On Thu, Aug 26, 1999 at 05:14:29PM -0400, Fred L. Drake, Jr. wrote:
Last week I promised on the Python list to describe the current status of the conversion to SGML/XML. Here it is!
I'm currently able to parse all the LaTeX markup and generate either XML or SGML. The structure of the output is very similar to the input structure, but a number of minor improvements are made. The improvements are mostly very localized and have more to do with keeping the markup from getting to complex and disjointed, and eliminating some bogosities.
Excellent!
I am not at all decided on a DTD to use. I see three options:
1. DocBook -- this has been developed and heavily use-tested by a number of corporate users, and is known to be good for technical documentation. There are tools and stylesheets available to convert from DocBook to HTML and printed formats. We'd probably need to specialize it, but it's designed for that. Konrad Hinsen has already developed one customization that he's using to document Python modules, and there's an initiative to create a common extension for documenting OO constructs. I've asked Konrad for some sample documentation so I can see how it actually works out. My concern with DocBook is that the markup may be a bit on the "heavy" side; I don't want the document source to be so markup-heavy that I'm the only one to work on them.
I personally am not a fan of this, since it seems like it could limit the contributors to those willing to learn DocBook, which, at a glance, looks much more complicated than learning a standard way to produce python docs.
2. Create something similar to what we had in LaTeX, but with fewer warts. This is appealing because the conversion would be done sooner. However, new stylesheets would be needed, slowing down the usefulness of the result. It would also be the easiest to adopt for people already familiar with the current markup.
This sounds appealing. [...]
I'd like to see some discussion on what should be done and what needs to be done. From where I sit, the most important thing is to make sure we can maintain a high level of semantic markup (hopefully making further improvements over what we already have), with generation of hypertext (HTML, info, whatever) being the next most important thing. Typeset documents are a requirement, but aren't as high up the list.
From my perspective, what's most important is a *simple*, well-documented and authoritative documentation markup. The more people who can easily
produce docs for new code, the more documentation their will be, and a standard would facilitate sharing more documentation in everyone's favorite formats. With some kind of flexible-but-not-too-complex dtd, I'd probably work on producing python docs in all the formats that I'd like to see, such as vim tags and man pages (not that i liked the recent rant about the latter on c.l.p, but I would like and use and produce or help produce these formats if the dtd structure is simple and the authoritative text easy to parse) scott