Item 5. Comment DTDs Liberally

The Header Comment

The DTD should start with one long comment that lists lots of metadata about the DTD. Generally, this would start with a title specifying the XML application the DTD describes. For example:

MegaBank Account Statement DTD, Version 1.1.2

This would normally be followed with some copyright notice. For example:

Copyright 2003 MegaBank

Alternately, you could use the copyright symbol:

2003 MegaBank

Do not use a c inside parentheses:

(c) 2003 MegaBank

This is not recognized by the international treaty that establishes copyright law in most countries . For similar reasons do not use both the word Copyright and the symbol like this:

Copyright 2003 MegaBank

Neither of these forms is legally binding. I wouldn't want to rely on the difference between and (c) in a defense against a claim of copyright infringement, but as a copyright owner I wouldn't want to count on them being considered the same either. If the genuine symbol is too hard to type because you're restricted to ASCII, just use the word Copyright with a capital C instead.

Now that the DTD has been copyrighted , the next question is, who do you want to allow to use the DTD and under what conditions? If the DTD is purely for internal use and you don't want to allow anyone else to use it, a simple 2003 MegaBank statement may be all you need. However, by default such a statement makes the DTD at least technically illegal for anyone else to use, copy, or distribute without explicit permission from the copyright owner. If it is your intention that this DTD be used by multiple parties, you should include language explicitly stating that. For example, this statement would allow third parties to reuse the DTD but not to modify it:

This DTD may be freely copied and redistributed.

If you want to go a little further, you can allow other parties to modify the DTD. For example, one of the most liberal licenses common among DTDs is the W3C's, which states:

Permission to use, copy, modify and distribute the XHTML
Basic DTD and its accompanying documentation for any purpose
and without fee is hereby granted in perpetuity, provided
that the above copyright notice and this paragraph appear in 
all copies. The copyright holders make no representation 
about the suitability of the DTD for any purpose.

Often some authorship information is also included. As well as giving credit where credit is due (or assigning blame), this is important so that users know who they can ask questions of or report bugs to. Depending on circumstances the contact information may take different forms. For instance, a private DTD inside a small company might use a personal name and a phone extension while a large public DTD might provide the name and URL of a committee. Whichever form it takes, there should be some means of contacting a party responsible for the DTD. For example:

Prepared by the MegaBank Interdepartment XML Committee
Joseph Quackenbush, editor <jquackenbush@megabank.com>
http://xml.megabank.com/

If you modify the DTD, you should add your name and contact information and indicate how the DTD has been modified. However, you should also retain the name of the original author. For example:

International Statement DTD prepared for MegaBank France to
satisfy EEC banking regulations by Stefan Hilly 
<shilly@megabank.fr>

Original prepared by the MegaBank Interdepartment XML Committee
Joseph Quackenbush, editor <jquackenbush@megabank.com>
http://xml.megabank.com/

Following the copyright and authorship information, the next thing is normally a brief description of the XML application the DTD describes. For example, the bank statement application might include something like this:

This is the DTD for MBSML, the MegaBank Statement Markup 
Language. It is used for account statements sent to both
business and consumer customers at the end of each month.
Each document represents a complete statement for a single 
account. It handles savings, checking, CD, and money market
accounts. However, it is not used for credit cards or loans.

This is often followed by useful information about the DTD that is not part of the DTD grammar itself. For example, the following comment describes the namespace URI, the root element, the public ID, and the customary system ID for this DTD.

All elements declared by this DTD are in the 
http://namespaces.megabank.com/statement namespace.

Documents adhering to this DTD should have the root element
Statement.

This DTD is identified by these PUBLIC and SYSTEM identifiers:

   PUBLIC "-//MegaBank//DTD Statement//EN"
   SYSTEM "http://dtds.megabank.com/statement.dtd"
The system ID may be pointed at a local copy of the DTD 
instead. For example,

<!DOCTYPE Statement PUBLIC "-//MegaBank//DTD Statement//EN"
                           "statement.dtd">

The internal DTD subset should *not* be used to customize 
the DTD.

Some DTDs also include usage instructions or detailed lists of changes in the current version. There's certainly nothing wrong with this, but I normally prefer to point to some canonical source of documentation for the application. For example:

For more information see http://xml.megabank.com/statement/

This pretty much exhausts the information that's customarily stored in the header.