MHonArc v2.5.0b2 -->
dita message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: DTD Formatting: Comments
Would suggest consideration of the following comment types
for each module:
------------------------------------
1) Closing comment on each physical module, e.g.
<!-- ================== End Journal Archiving and Interchange DTD -->
------------------------------------
2) Opening comment on each module that states some or all
of the following:
- module name
- larger system module is part of
- initial creation date
- version number and latest update date
- fpi
- purpose of module
- maybe the module contents
------------------------------------
3) Change history comment (who, when, and particularly why)
------------------------------------
4) Comments that separate logical groupings of element, entity,
or attribute list declarations, for example:
<!-- ============================================================= -->
<!-- PARAMETER ENTITIES FOR ATTRIBUTE LISTS -->
<!-- ============================================================= -->
------------------------------------
5) Element-specific Comments
Naming Comment for each element. In theory elements have two names:
- the element type name (used by DTD and schema)
- the human readable name, which may be a word or phrase
Suggest giving each element a full name in the comments, for example:
<!-- COLLABORATIVE (GROUP) AUTHOR -->
<!ELEMENT collab (#PCDATA | %collab-elements;)* >
------------------------------------
Definition comment for each element (because people don't read
documentation as they should!), for example:
<!-- COLLABORATIVE (GROUP) AUTHOR -->
<!-- Used for groups of authors credited under
one name, either as a collaboration in the
strictest sense, or when an organization,
institution, or corporation is the group. -->
<!ELEMENT collab (#PCDATA | %collab-elements;)* >
------------------------------------
--
======================================================================
Deborah Aleyne Lapeyre mailto:dalapeyre@mulberrytech.com
Mulberry Technologies, Inc. http://www.mulberrytech.com
17 West Jefferson Street Direct Phone: 301/315-9633
Suite 207 Phone: 301/315-9631
Rockville, MD 20850 Fax: 301/315-8285
----------------------------------------------------------------------
Mulberry Technologies: A Consultancy Specializing in XML and SGML
======================================================================
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]