[Python-Dev] PEP 287: reStructuredText Standard Docstring Format

[Tom Emerson]

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"