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 ...

Get Effective XML: 50 Specific Ways to Improve Your XML now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial