Mailman 3 August 1999 - Doc-SIG

XML Conversion Update
by Fred L. Drake, Jr. Dec. 3, 1999

Dec. 3, 1999

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. 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. 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. 3. Create something entirely new and specific to Python. Clearly, this offers a lot of work to all the volunteers. We'd need requirements analysis, DTD design, stylesheets, and probably lots of things I haven't thought of. However, it also means we can limit the weight of the markup in the source, which might be a major advantage in getting people to use it. But *everyone* would have to learn it (well, everyone that writes documentation at any rate). This offers a great deal of opportunity to "get it right" for Python, but also a lot of rope. (You know what rope is used for, right?) 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. I'm not terribly concerned about how XML/SGML-->foo conversion processes are implemented, with the caveat being that I need to be able to understand them without a massive learning curve. Clearly, Python code is a major option for tools (surprised?), but I can easily deal with using Java tools (with or without JPython), DSSSL processors (just don't expect me to maintain Jade/OpenJade!), XSL, CSS, and whatnot. I'd like to get away from having any Perl scripts involved, not because I think Perl is Evil, but because I'm not a Perl hacker. (Don't get me wrong; I make no claim that Perl is not Evil! ;) Comments, suggestions, volunteers? -Fred -- Fred L. Drake, Jr. <fdrake(a)acm.org> Corporation for National Research Initiatives

9 16

Re: [Doc-SIG] XML Conversion Update
by Jack Jansen Dec. 3, 1999

Dec. 3, 1999

While I agree with Sean (and others) that small DTDs are a lot better suited to documenting Python modules there's various standard-formatting things that you'd like to borrow from existing DTDs (emphasis, references to other manuals/sections, footnotes, etc). Is there a way that that could be done, without dragging in the whole of the (apparently huge and hairy, from the reports here) docbook DTD? -- Jack Jansen | ++++ stop the execution of Mumia Abu-Jamal ++++ Jack.Jansen(a)oratrix.com | ++++ if you agree copy these lines to your sig ++++ www.oratrix.nl/~jack | see http://www.xs4all.nl/~tank/spg-l/sigaction.htm

6 8

RE: [Doc-SIG] XML Conversion Update
by hinsen＠cnrs-orleans.fr Aug. 27, 1999

Aug. 27, 1999

> > I am not at all decided on a DTD to use. I see three options: > > Im pretty ignorant about this. I did look into the docbook DTD, and it is > indeed complex. However, it also appears that much of it is optional. > > It seems that if a reasonable subset of the docbook features could be used > and documented for use in Python it would be simpler to use, and save > reinventing the wheel. I did use DocBook, and I certainly had lots of problems with it. However, the real problem is not the complexity (for any given project, most of DocBook markup is irrelevant), but the lack of decent documentation. This might change when the O'Reilly book by Norman Walsh is out. The second problem I wasted a lot of time with is Jade plus JadeTeX; I just couldn't get decent paper output with it. And I didn't really want to learn DSSSL either. In the end I wrote my own special-purpose converter using PyDOM, which was finished in a day! So my suggestions are: - Use DocBook-XML, or perhaps Norman Walsh's simplified DocBook, or something intermediate. Maybe some modifications must be made, but that is relatively simple. - Use Python tools for conversion, that's what we are all most familiar with. Konrad. -- ------------------------------------------------------------------------------- Konrad Hinsen | E-Mail: hinsen(a)cnrs-orleans.fr Centre de Biophysique Moleculaire (CNRS) | Tel.: +33-2.38.25.55.69 Rue Charles Sadron | Fax: +33-2.38.63.15.17 45071 Orleans Cedex 2 | Deutsch/Esperanto/English/ France | Nederlands/Francais -------------------------------------------------------------------------------

1 0

Python XML Documents
by Fred L. Drake, Jr. Aug. 26, 1999

Aug. 26, 1999

Just as a discussion item, I've tossed out a copy of the XML produced by tools currently checked into CVS (Doc/tools/sgmlconv/). The file is: ftp://ftp.python.org/pub/python/doc/1.5.2p1/test/xml-1.5.2p1+.tgz That might be easier than pulling the stuff out of CVS and generating it, especially if you have a slow connection or a slow machine. ;-) -Fred -- Fred L. Drake, Jr. <fdrake(a)acm.org> Corporation for National Research Initiatives

1 0

Python PODs?
by Moshe Zadka Aug. 21, 1999

Aug. 21, 1999

Hi. The recent flamewar on c.l.py about lack of man pages got me thinking about a new "backend" for Python documentation, which would reflect Python's nature, while being amenable for auto-processing. The basic format would be POD (Perl's plain old documentation format), which is quite easy to parse. The Pythonic namespace hierarchy (package->module->object->methods) could be reflected in directory structure I.e., urllib/ ---.pod (general information about the module) urlopen.pod URLOpener/ ---.pod (general information about the class) __init__.pod (description of init method) Then, use of pod2man/pod2text with appropriate wrapping would mean I could have pythondoc urllib (show urllib/---.pod) pythondoc urllib.URLOpener.__init__ (show urllib/URLOpener/__init__.pod) I would be all-to-happy in helping to write such a back-end, we just need to make sure 1. The front-end is stable, and easily parsable (SGML ain't, XML is) 2. The front-end has enough information to do that easily (not really sure) What do you think? A preliminary module to make genereating PODS look just like generating XML (so the convertor would be written the way XML->XML translators are written) is in http://starship.python.net/crew/moshez/POD.py (It's not thoroughly debugged, but it passed the simple _test() well enough) -- Moshe Zadka <mzadka(a)geocities.com>. I'm not anti-Microsoft -- Microsoft is anti-me (Anonymous Coward on /.)

2 2