Item 5. Comment DTDs Liberally
DTDs can be as
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.
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:
Do not use a c inside parentheses:
(c) 2003 MegaBank
This is not recognized by the international treaty that establishes copyright law in most
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
Now that the DTD has been
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
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
Prepared by the MegaBank Interdepartment XML Committee Joseph Quackenbush, editor <firstname.lastname@example.org> http://xml.megabank.com/
If you modify the DTD, you should add your name and contact information and
International Statement DTD prepared for MegaBank France to satisfy EEC banking regulations by Stefan Hilly <email@example.com> Original prepared by the MegaBank Interdepartment XML Committee Joseph Quackenbush, editor <firstname.lastname@example.org> 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
For more information see http://xml.megabank.com/statement/
This pretty much exhausts the information that's customarily stored in the header.