The Common DTD

Another reason to keep your DTDs easy to follow is because of the common DTD. SGML installations usually share DTDs. Element modules make it possible to fix or change DTDs in one place and have those improvements ripple throughout the entire installation.

Listing 12.3 shows what a common DTD looks like. Elements are organized by logical group, and tags are grouped by type. Comments guide users easily through the DTD. All the declarations are aligned.

Listing 12.3 A Common DTD

Notice revision tracking and background info for future users of in-house DTD.

<!--*****************************************************************-->
<!--   AnyCorp, a BIG Corp company                                   -->
<!--                                                                 -->
<!--   Name:   Common DTD                                            -->
<!--   Purpose:   Define common elements shared by documents         -->
<!--   Project:   Electronic Document Project                        -->
<!--              AnyCorp electronic document project                -->
<!--   Version:   1.25                                               -->
<!--   Date:      Today’s Date, 199?                                 -->
<!--   Public Identifier:                                            -->
<!--   "-//ANYCORP//DTD Common Shared Elements//EN"                  -->
<!--                                                                 -->
<!--*****************************************************************-->
<!--*****************************************************************-->
<!--                    Revision History                             -->
<!--                                                                 -->
<!--   Author          Date           Reason                         -->
<!--   ======          ====           ============================== -->
<!--                                                                 -->
<!--   ABC             Today, 199?    Needed to add <eqnnew> element -->
<!--                                                                 -->
<!--*****************************************************************-->

These content modules are shared as entities among several DTDs. This avoids tedious duplication of identical content models.

 <!--           Content Model Modules  -->
 <!ENTITY % parent       "para|texeqn|eqnsec|stdeqn|blist|
                          nlist|dlist|table|illus|note|caut|warn">
 <!ENTITY % miscstr      "(((%parent;)+, SubSec*)|SubSec+)">
 <!ENTITY % minmum      "#PCDATA|emph|rdi|partno|
                         partname|manufact|product">
 <!ENTITY % data        "(%minmum;|xref|eref|appref)+">

 <!--           Attribute Modules  -->

These attribute models can now be shared by several DTDs without having to declare the same attributes again and again.

 <!ENTITY % mattrib      "id           CDATA                  #IMPLIED
                        addinfo        CDATA                  #IMPLIED
                        securOwn       CDATA                  #IMPLIED
                        securLvl    (public|iuo|coconf|critical) #IMPLIED
                        %mattrib;">
 <!ENTITY % stanat      "Custno        NUMBER                 #IMPLIED
                         customer      CDATA                  #IMPLIED
                         pubdate       cdata                  #IMPLIED
                        %mattrib;">

 <!ENTITY % sattrib     "">

 <!--   Subsections, Title Paragraphs, Equations, Lists           -->

 <!ELEMENT SubSec  - -  (title, (%miscstr;)?)>
 <!ATTLIST               %sattrib;
                         %stanat;>
 <!ELEMENT title   - -  (%minmum;|xref)+>

 <!ELEMENT para    - -  %data;>
 <!ATTLIST para          wrap       (n)   #IMPLIED
                         indent     (y)   #IMPLIED
                         %stanat;>
 <!ELEMENT eqnsec  - - (para|txteqn|stdeqn)+>
 <!ELEMENT txteqn  - - (#PCDATA|emph)+>
 <!ATTLIST txteqn      %stanat;>
 <!ELEMENT stdeqn  - - CDATA       -- Pull ISO DTD here -->
 <!ATTLIST stdeqn       %stanat;>
 <!ELEMENT blist   - - (item+)     -(nlist)>
 <!ATTLIST blist        %stanat;>
 <!ELEMENT nlist   - - (item+)>
 <!ATTLIST nlist        %stanat;>
 <!ELEMENT dlist   - - (def+)>
 <!ATTLIST dlist        %stanat;>
 <!ELEMENT def     - - (term,item)>
 <!ATTLIST def          %stanat;>
 <!ELEMENT term    - - %data;>
 <!ATTLIST def         %stanat;>
 <!ELEMENT item    - - (para|blist|nlist|dlist|
                       note|caut|warn|table|illus)+>
 <!ATTLIST item        %stanat;>