Documentation for Human Consumption DDML provided one demonstration of how you can use an HTML vocabulary to add human-readable information to an XML document, but the need for such notation often goes well beyond the rather formal situation of standards and schema creation. Although XML provides a mechanism for adding notes, which are intended to allow human-readable information in XML documents that will be ignored by the application (comments), the limits of that mechanism give HTML another good area for enriching XML work. Comments (the ubiquitous <!-- and -->) are very useful in some situations, but they have some distinct disadvantages. Comments may or may not be transmitted to the application from the XML parsing process, and many XML applications will disregard their contents even if they receive the information. XML parsers treat the information stored within comments as plain text and HTML browsers typically ignore it even if it happens to contain HTML.

Developers who want or need to include human-readable documentation within their document structures (as opposed to floating in comments) need to create places where document authors can generate sophisticated human-readable information. While you can create your own format for doing this (or use an XML format such as DocArticle), XHTML provides a well known and well supported vocabulary for doing such work. You might need to modify XHTML, as described in the previous article, to support the use of your own custom markup within the XHTML. However, XHTML can provide a simple framework for doing such work.

For example, an invoice meant for mostly automated processing might include a Comments section. Rather than develop a formal vocabulary for a relatively freeform area, let users include XHTML in this area. That enables them to handle some critical possibilities such as:

- Adding extra emphasis to an order that absolutely must be delivered overnight

- Providing tables, charts, and diagrams explaining what the contents of the order will be used for (for cases in which technical assistance may be necessary)

- Extra pleading to send the shipment even though the last three payments didn't clear

- Requests for extra discounts

- Thanks for previous excellent service

Some of these may seem frivolous, but all of them represent exceptional circumstances that happen fairly frequently in the real world. None of them are easily captured by the formal structures most document designers use to capture the "core" information on an invoice, such as shipping addresses and mechanisms, billing information, and the requested materials. Automated ordering systems are similarly poor at handling this kind of information. On the other hand, these are all circumstances that happen on a fairly regular basis when paper forms are used – people are very good at scribbling such things in the margins or on the invoice, expecting other people to read and act on them. Because the information is really meant to represent human-to-human contact, it's a very good candidate for XHTML. XHTML provides the structures people need to communicate this kind of information, supplying tables, pictures, and emphasis. Programs meant to support human creation of these forms can use an XHTML editor component to write the XHTML, while the recipient end can show the comment contents on paper or onscreen using HTML or XHTML browser components. While some of it may be machine-interpreted, much of it probably represents situations that demand some level of human intervention.

Document containers XML can be very useful as a container format, enabling developers to package and distribute sets of information. In this case, XHTML provides a format for the "real" content of the documents – its XML structures allow it to get through the XML processing infrastructure and be a part of the package; but its HTML vocabulary is only relevant to its final recipient, not to processing along the way. Document sets can be assembled as a single, large XML document, complete with headers describing the set and the individual documents they contain. You can use this for simple projects like snapshots of Web sites, or more complex projects like selling and trading documents among sites.

Note The use of binary formats for images and other Web site content does limit the usefulness of this technique to some extent, but it may be appropriate for situations in which the text is central or graphics are represented using textual formats such as Scalable Vector Graphics (SVG). The container document can use a prefix for its own elements and leave the default namespace undeclared, letting all of the contained documents declare it for themselves. This provides maximum flexibility while making clear the distinction between the XML elements that are part of the container and the (XHTML or other) documents being contained. For example, a simple container might look like this:

   <?xml  version="1.0"?>
   <docpac:documents  xmlns:docpac="http://www.simonstl.com/xhtml/code/chap17/docpac">
   <docpac:info>
   <docpac:docsetname>Discarded  Files</docpac:docsetname>
   <docpac:owner>Simon  St.Laurent</docpac:owner>
   </docpac:info>
   <docpac:document>
   <docpac:author>Simon  St.Laurent</docpac:author>
   <docpac:name>Revolutionary  Traditions</docpac:name>
   <docpac:daterevised>04202000</docpac:daterevised>
   <docpac:content>
   <html  xmlns="http://www.w3.org/1999/xhtml" lang="en-US"  xml:lang="en-US">
   document content
   </html>
   </docpac:content>
   </docpac:document>
   <docpac:document>
   <docpac:author>Spring the Friendly  Dog</docpac:author>
   <docpac:name>Kibble  Revisited</docpac:name>
   <docpac:daterevised>04202000</docpac:daterevised>
   <docpac:content>
   <html xmlns="http://www.w3.org/1999/xhtml"  lang="en-US" xml:lang="en-US">
   document content
   </html>
   </docpac:content>
   </docpac:document>
   <docpac:document>
   <docpac:author>Simon  St.Laurent</docpac:author>
   <docpac:name>Traditional  Revolutions</docpac:name>
   <docpac:daterevised>04202000</docpac:daterevised>
   <docpac:content>
   <html  xmlns="http://www.w3.org/1999/xhtml" lang="en-US"  xml:lang="en-US">
   document content
   </html>
   </docpac:content>
   </docpac:document>
 </docpac:documents>

Commercial document packaging systems provide more sophisticated metadata and content management, but the basic structure likely is similar. One sizable problem arises with this approach, however. DOCTYPE declarations can only appear at the top of an XML document, not in the middle, so you can't transmit fully conforming XHTML documents this way. A lightweight transfor-mation that converts the DOCTYPE declaration into elements and then back to a DOCTYPE declaration might be capable of fixing this, but for now it's a complicating factor.

Tip XML Schemas don't use DOCTYPE declarations. When they appear, Schemas may be a way around this issue because XHTML documents that are fully conformant to the set of XML Schema modules may not have to use DOCTYPE declarations. The XHTML specification may require them, however — it's too early to know.