DTD Formatting: Comments

[Deborah Aleyne Lapeyre <dalapeyre@mulberrytech.com>]

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
======================================================================