Documenting DTDs I: dtd2html (2/2) - exploring XML

Documenting DTDs I: dtd2html

dtd2html

A similar documentation tool has existed in the SGML world for years, as part of the perlSGML package: dtd2html. 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 perlSGML. You can download it from there, unpack it in any directory and call dtd2html on any DTD. An installer script optionally copies everything to the "right" place should you so desire.

Running dtd2html on HTML4 transitional produces a set of HTML pages to browse. 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 javadoc.
• 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: dtd2html generates 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.

Conclusion

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

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

URL: https://www.webreference.com/xml/column64/2.html
Created: Sep 16, 2002
Revised: Sep 16, 2002