[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]