Item 5. Comment DTDs Liberally

DTDs can be as obfuscated as C++ code written by a first-year undergrad. You should use lots of comments to explain exactly what's going on. Well-written DTDs such as the modular XHTML DTD often contain more than twice as many lines of comments as actual code. The list that follows shows some of the information you should include in a DTD.

• Who wrote it and how to contact them

• The copyright and use conditions that apply to the DTD

• The version of the DTD

• The namespace URI

• The PUBLIC and SYSTEM identifiers for the DTD

• The root elements

• A brief description of the application the DTD models

• The purpose and content of each parameter entity defined

• The purpose and content of each general entity defined

• The meaning of each element declared by an ELEMENT declaration

• The meaning of each attribute declared in an ATTLIST declaration

• The meaning of each notation declared in a NOTATION declaration

• Additional constraints on elements and attributes that cannot be specified in a DTD, for example, that a length attribute must contain a positive integer

For example, let's consider a DTD designed for bank statements like the ones your bank sends you at the end of every month. If the account isn't very active a typical document might look like this:

 <?xml version="1.0"?> <!DOCTYPE Statement PUBLIC "-//MegaBank//DTD Statement//EN"                            "statement.dtd"> <Statement xmlns="http://namespaces.megabank.com/">   <Bank>MegaBank</Bank>   <Account>     <Number>00003145298</Number>     <Type>Savings</Type>     <Owner>John Doe</Owner>   </Account>   <Date>2003-30-02</Date>   <OpeningBalance>5266.34</OpeningBalance>   <Transaction type="deposit">     <Date>2003-02-07</Date>     <Amount>300.00</Amount>   </Transaction>   <Transaction type="transfer">     <Account>       <Number>0000271828</Number>       <Type>Checking</Type>       <Owner>John Doe</Owner>     </Account>     <Date>2003-02-07</Date>     <Amount>200.00</Amount>   </Transaction>   <Transaction type="deposit">     <Date>2003-02-15</Date>     <Amount>512.32</Amount>   </Transaction>   <Transaction type="withdrawal">     <Date>2003-02-15</Date>     <Amount>200.00</Amount>   </Transaction>   <Transaction type="withdrawal">     <Date>2003-02-25</Date>     <Amount>200.00</Amount>   </Transaction>   <ClosingBalance>5478.64</ClosingBalance> </Statement> 

You already saw this example in French in Item 2. We'll be looking at different aspects of it in several later items too, but for now let's think about what's appropriate for the DTD.