David Goodger writes: [...]
Proposed alternatives have included:
- XML [3]_, SGML [4]_, DocBook [5]_, HTML [6]_, XHTML [7]_
XML and SGML are explicit, well-formed meta-languages suitable for all kinds of documentation. XML is a variant of SGML. They are best used behind the scenes, because they are verbose, difficult to type, and too cluttered to read comfortably as source. DocBook, HTML, and XHTML are all applications of SGML and/or XML, and all share the same basic syntax and the same shortcomings.
And how much of HTML is required for marking up documentation? JavaDoc doesn't appear to suffer from this problem. I've never heard this argument given by programmers who are writing documentation. I use HTML in my JavaDoc comments. I use HTML in my Doxygen comments (in C++). Why not use HTML in my Python comments? DocBook is much more verbose, as it concentrates almost exclusively on semantics, not display. It is overkill for this. XML and SGML are by themselves not an alternative: they are a means to the end. XML is an SGML application. DocBook is an XML and/or SGML application. HTML is an SGML application. XHTML is an XML application.
- JavaDoc [10]_
Special comments before Java classes and functions serve to document the code. A program to extract these, and turn them into HTML documentation is called javadoc, and is part of the standard Java distribution. However, the only output format that is supported is HTML, and JavaDoc has a very intimate relationship with HTML, using HTML tags for most markup.
[...] This is patently false: there are Doclets available that convert to a wide variety of formats. Sun provides a MIF doclet, and third parties have provided doclets for RTF, TexInfo, LaTeX, and DocBook. There is very little that cannot be marked up in HTML that cannot be converted to other formats in a straight forward way. I'll raise Doxygen as another example: the comments utilize HTML (though you can escape for specific processor features (e.g., TeX equations) if necessary) and documentation can be generated in HTML, RTF, PostScript, Hyperlinked PDF, compressed HTML, and Unix man page format. You also forget to mention TexInfo, one of the older and more widely used documentation format for programmer docs. I don't have a vote, but if I did, -1. -tree -- Tom Emerson Basis Technology Corp. Sr. Computational Linguist http://www.basistech.com "Beware the lollipop of mediocrity: lick it once and you suck forever"