Notice that the DTD above follows the four groupings mentioned earlier: elements of the same document structure, elements used only in one place, elements used anywhere, and any special processing elements. Each of the groups above has a comment explaining what elements are in the group and how they are used.

When you must deal with an odd element, put it in the most logical place in your DTD—which might even be by itself.

Declaring Elements After Their First Content Model

Grouping element declarations by type is important for formatting your DTDs properly. Within groups, it makes sense to declare elements the first time they are modeled. That way, whenever you see elements as part of a model group, you know that they are already defined or the current model group is the first model group. For example:

 <!ELEMENT stuff      O O (bigstuff|littlestuf) --gag me-->
 <!--               STUFF ELEMENTS                      -->
 <!ELEMENT bigstuff   O O (tinystuff?, morestuff+)        >
 <!ELEMENT littlestuf O O (%stuffies;)                    >

In this example, tinystuff and morestuff have already been defined. Otherwise, you would define them immediately after the bigstuff element. %stuffies; was also defined previously—probably with the parameter entities at the beginning of the DTD.

Note the comment line immediately after the stuff element declaration. It helps you understand the elements when their names do not make sense. Names are often cryptic, so comments really help. For example:

 <!--**********************************************-->
 <!--               IPL ELEMENTS                   -->
 <!--          (Illustrated Parts List)            -->
 <!--**********************************************-->
 <!--                                              -->
 <!--         INTERLEAF 5.3.1 STYLE COMPONENT      -->
 <!ELEMENT   line10  - - (inum, partn, pardes, qty)  >
 <!--                 INDEX NUMBER                 -->
 <!ELEMENT   inum    - - (#PCDATA)                   >
 <!--                 PART NUMBER                  -->
 <!ELEMENT   partn   - - (#PCDATA)                   >
 <!--                 PART DESCRIPTION             -->
 <!ELEMENT   pardes  - - (#PCDATA)                   >
 <!--                 QUANTITY PER ASSEMBLY        -->
 <!ELEMENT   qty     - - (#PCDATA)                   >
 <!--**********************************************-->

Sometimes you must provide extra comments just to make sense of the element names, especially with specialized document types. For instance, the illustrated parts list in the previous example is a highly defined document type, but it can be confusing to someone who has not worked with it before. Many such document types exist, and they need extra comments to describe their elements.

In the previous example, the elements are declared in the same order as they were first modeled, which makes each grouping of elements more coherent and easier to follow. For instance, because the sequence is line10, inum, partn pardes, and qty, that is the order in which the elements are declared.

Where To Define Attributes

Machines don’t care how attributes and their elements look. A machine doesn’t care whether you place the ATTLIST declaration a page away from its element. Doing so, however, makes it harder for you—and others—to understand the DTD. It’s far better to make attribute declarations either immediately after the elements to which the attributes apply or in their own group in the DTD.

In the following example, artfig is defined for the first time, and all its attributes are defined as well. You could put the ATTLIST elsewhere in the DTD after you have declared more elements, but that makes it difficult to find. It’s much better to declare attributes directly after the elements to which they apply.

 <!ELEMENT  artfig   - O EMPTY                           >
 <!ATTLIST  artfig
       artno        ID      #IMPLIED  -- art file number--
       artsz        NUTOKEN #IMPLIED  -- size of frame  --
       artrv        CDATA   #IMPLIED  -- art revision   --
       stdart       (y|n)   #IMPLIED  -- standard art   -->

In this excerpt from listing 12.2, the attributes are grouped separately in the DTD:

 <!--       ELEMENTS    NAME     VALUE   DEFAULT -->
 <!ATTLIST  %doctype;   security CDATA   #IMPLIED
                        status   CDATA   ""
                        version  CDATA   #IMPLIED>
 <!ATTLIST title        stitle   CDATA   #IMPLIED>
 <!ATTLIST (h0|h1|h2|%bm.d;|%fm.d;)
                        id       ID      #IMPLIED
                        stitle  CDATA    #IMPLIED>
 <!ATTLIST (h3|h4)      id       ID      #IMPLIED>
 <!ATTLIST artwork      sizex    NMTOKEN textsize
           -- Default is current text width in column. --
                        sizey    NUTOKEN #REQUIRED
           -- (Sizes are specified in the units supported by the
              application in which this declaration appears;
              for sizex, the keyword "textsize" can be used
              to mean "the width at which previous text was set").
           -->