Documenting DTDs I: dtd2html (2/2) - exploring XML
Documenting DTDs I: dtd2html
A similar documentation tool has existed in the SGML world for years,
as part of the perlSGML package:
dtd2html takes a DTD,
plus an optional description file, and generates a set of HTML pages
following the structure of the content model that the DTD describes.
It is also capable of generating tree views and quick reference formats.
Download and install
dtd2html is part of the Perl package
You can download it from there, unpack it in any directory and
dtd2html on any DTD. An installer script optionally
copies everything to the "right" place should you so desire.
dtd2html on HTML4 transitional produces a set of HTML pages
This can naturally only be a visualization of the content
model's structure, but with the addition of a
description file meaningful documentation is produced.
While it is a neat tool, things could be better:
- Not widespread: Not many people seem to use it, and consequently not much documentation is produced that way.
- Not "inline": The odds of an external file being in sync with the
described entity is rather slim, better would be an inlined form of
documentation, even within comments, as it is in
- Not easily customizable: As a developer tool, developers want to fiddle with it. Javadoc sports an extensible doclet mechanism, a plugin interface for controlling document generation. This way, different documentation formats are easily accomplished, and the approach has even been pushed to the limit by creating non-documentation content: XDoclet generates bean descriptors for Enterprise Java Beans straight out of the source code.
- Not concise:
dtd2htmlgenerates too many pages. One page per element, containing all information pertaining to this element, should be sufficient. Instead, the tool generates separate pages for attributes and content model.
- Not extensible: As the name applies, only DTDs are supported.
While not all is great with dtd2html, it is so far one of the few documentation tools available for describing XML document types. I encourage you to use it, should you create DTDs for the rest of us to work with.
In the following installments, we will look at developing a
documentation tool for XML document type definitions that should do away
with the current limitations of
Hopefully this will lead to more documentation being produced in a standardized, concise format that is easy to consume for both man and machine.
Should you know about other tools I might have missed, as well as feature requests for such a tool, please let me know.
Produced by Michael Claßen
Created: Sep 16, 2002
Revised: Sep 16, 2002