Aligning Declarations

The key to making your DTDs clear is aligning all the element declarations and model groups. Even if you get everything else right, improperly aligned declarations make it difficult to find components. Aligning similar components is at the heart of a visually pleasing DTD. Listing 12.5 shows a DTD that is properly grouped and that has attributes called separately and clearly. Its first part is difficult to follow because the entity declarations, models, and comments are not aligned. The last part of the DTD is easy to follow because it is aligned.

Listing 12.5 DTD with Partly Aligned Declarations, Partly Not

 <!-- Public document type declaration subset. Typical invocation:
 <!DOCTYPE book PUBLIC "-//USA/AAP//DTD BK-1//EN"
  [<!ENTITY % ISOnum PUBLIC "ISO 8879-1986//ENTITIES Numeric and
           Special Graphic//EN" >
   <!ENTITY % ISOpub PUBLIC "ISO 8879-1986//ENTITITES
           Publishing//EN" >
   %ISOnum;  %ISOpub;
   <!ENTITY % srmaps PUBLIC "-//USA/AAP//SHORTREF SR-1//EN" >
   %srmaps;
 ]>
 -->
 <!--This is the AAP’s document type declaration for a book/monograph.
 It contains the necessary elements for use as a technical report,
 conference proceedings, or a thesis or dissertation.  It is also suitable
 for textbooks. -->

             <!-- Entity Naming Conventions -->
 <!--
                    Prefix = where used:
      p.  = in paragraphs (also in phrases if .ph suffix)
      s.  = in sections (i.e., among paragraphs)
      i.  = where allowed by inclusion exceptions
      m.  = content model or declared content
      a.  = attribute definition
      NONE= specific use defined in models
                  Suffix = allowed content:
      .ph = elements whose content is %m.ph;
      .d  = elements whose content has same model as defaults
      NONE= individually defined elements
 -->
 <!ENTITY % book   "book" -- default document type generic identifier -->

                <!-- Specialized Elements -->

Notice that the content models for these entity declarations are not aligned, and it does make them harder to read.

 <!ENTITY % ade.ph "str|cty|sbd|cny|pc|san|ead"  -- address elements -->
 <!ENTITY % bib "au|cau|msn|srt|loc|pdt|pp|atl|sct|obi" -- bibliographic-->
 <!ENTITY % bmcps.d "vt" -- back matter cps elements -->
 <!ENTITY % bmsec.d "awd|bib|notes" -- back matter sections -->
 <!ENTITY % bmsec.i "gl|idx" -- indexes and glossary -->
 <!ENTITY % fmcps.d "ack|ded|abs|smtl" -- front matter cps elements -->
 <!ENTITY % fmsec.d "fwd|pf" -- front matter sections -->
 <!ENTITY % pub  "cgs|cgn|rps|crt|pdt|pnm|loc|cng|avl" -- pubfm -->
 <!ENTITY % pub.ph  "cdn|aon|isbn|lcn|rid|ed|vid|cip|phi|prc|ext|pkg|pid" >

              <!-- Basic Document Elements -->
 <!ENTITY % i.float "fig|fn|nit" -- floating elements -->
 <!ENTITY % p.e1 "dl|oad|iad|art|bq|lit|pdt|bb|bibl|itml|au|cau"
                                                         -- general -->
 <!ENTITY % p.em.ph "it|b|bi|rm|scp|e1|e2|e3" -- emphasis -->
 <!ENTITY % p.lst.d "l|l1|l2|l3|l4|l5" -- list, types 1 thru 5 -->
 <!ENTITY % p.rf.ph "ntr|fnr|fgr|tbr|artr|apr|srr|rb" -- references -->
 <!ENTITY % p.tbl "tbl" -- table matter -- >
 <!ENTITY % p.zz "(%p.e1;)|(%p.tbl;)|(%p.lst.d;)"
                                           -- paragraph subelements -->
 <!ENTITY % p.zz.ph "q |pp|(%p.em.ph;)|(%p.rf.ph;)|gk|cyr|emq"
                                                         -- phrases -->
 <!ENTITY % s.h.ph "h|h1|h2|h3|h4" -- headings -->
 <!ENTITY % s.top.d "top1|top2|top3|top4" -- topics -->
 <!ENTITY % s.zz "p|(%p.zz;)|(%s.h.ph;)|(%s.top.d;)"
                                             -- section subelements -->

                       <!-- Models -->
 <!ENTITY % m.addr  "(%ade.ph;)*" -- address (no name) -->
 <!ENTITY % m.bib "(no?, ti, (%bib;)*)" -- bibliographic entry -->
 <!ENTITY % m.copy  "(crd|crn|cci)+" -- copyright notice data -->
 <!ENTITY % m.cps "(h?, p, (%s.zz;)*)" -- captioned par seq -->
 <!ENTITY % m.date "(mo?, day?, yr)" -- date components -->
 <!ENTITY % m.fig "EMPTY" -- default FIG content -->
 <!ENTITY % m.name"(fnm?, snm, (deg|sch)*, role*, (%ade.ph;)*, aff?)" >
 <!ENTITY % m.org  "(onm, odv*, %m.addr;)" -- organization name -->
 <!ENTITY % m.p "(#PCDATA|(%p.zz.ph;)|(%p.zz;))*" -- paragraph text -->
 <!ENTITY % m.ph "(#PCDATA|(%p.zz.ph;))*" -- phrase model -->
 <!ENTITY % m.pseq  "(p, (p|(%p.zz;))*)" -- P with sequence -->
 <!ENTITY % m.rep "(rep1, (rep2, rep3?)?)?"  -- repeating information -->
 <!ENTITY % m.rep1  "(ti)" -- repeating identifier 1 -->
 <!ENTITY % m.rep2  "(pdt)" -- repeating identifier 2 -->
 <!ENTITY % m.rep3  "(vid)" -- repeating identifier 3 -->
 <!ENTITY % m.sec "(st, (%s.zz;)*, ss1*)" -- section -->
 <!ENTITY % m.tcchp "(no?, ct, pp*, tcsec*)" -- TOC chp model -->
 <!ENTITY % m.tcpt  "(no?, pt, pp*, tcchp*)" -- TOC part model -->
 <!ENTITY % m.tcsec "(no?, st, pp*, tcss1*)" -- TOC sec model -->
 <!ENTITY % m.tcss1 "(no?, st, pp*, tcss2*)" -- TOC ss1 model -->
 <!ENTITY % m.tcss2 "(no?, st, pp*, tcss3*)" -- TOC ss2 model -->
 <!ENTITY % m.tcss3 "(no?, st, pp*)"         -- TOC ss3 model -->
 <!ENTITY % m.toc "(tcpt+|tcchp+)?"        -- TOC elements -->
 <!ENTITY % m.idx "(%m.sec;|itml|((idxn|idxs)*,pp*))" --model for
                          indexes and glossary -->

               <!-- Attribute Definitions -->
 <!ENTITY % a.id  "id ID #IMPLIED" -- ID attribute definition -->
 <!ENTITY % a.rid   "rid IDREF #IMPLIED" -- IDREF attribute definition:
                     content must be empty if IDREF is specified. -->
 <!ENTITY % a.sizes "sizex NUTOKEN #IMPLIED sizey NUTOKEN #IMPLIED
                                                     unit CDATA #IMPLIED"
                     -- unit must be specified if sizex or sizey are. -->