Moshe Zadka writes:
Not good, for exactly the reason I outlined earlier: some bozo will try to write DocBook, just like this bozo tried to write LaTeX.
It's hard to predict what's needed for good documentation; I am *not* of a mind to avoid having support for very general documentation constructs. We want to have a single DTD to keep the learning curve and tool support under control, so we can't really be too stingy in designing the markup.
We'll need to extend DocBook anyway, for primitives like <class>, <function>, etc. Personally, I do not want anything like <chapter>, <section>, or any such cruft in /library docs/ (obviously, these are
There's more in the library documentation than module sections; this even gets me in trouble sometimes. But it is *very* important to keep in mind that library documentation can and should contain much more than basic reference material.
So, its better to roll our own, stealing from DocBook whatever we can. Thus, we get (as much as possible) easy conversion for both old Python-doccers, and old DocBook-heads.
That said, I think we need a completely different system for the rest of the docs:
1. The tutorial is simply a book about Python, and as such should be written like every other technical book. Moreover, Guido is (currently) the sole maintainer so he has last say.
Guido has the last say about everything he does, of course. On the other hand, he's not the only person who maintains the documentation. He's certainly not the one who does the most of the work on it. This makes it sound like a DocBook project.
2. The extending/embedding manual is similar.
DocBook, with appropriate OO extensions, would be a very good match for the extending & embedding manual as well.
3. The Python/C API needs a much better solution anyway: while the basic API is good, the documentation is pretty horrible. I do think we might need a specific XML DTD for that document, but once again, Guido has final say because he'll (probably) be writing it.
Guido is the author of the original version of the document, but he is not the maintainer. That seems to be my job (which I consider a good thing ;). This is very much a kind of document that DocBook was designed to handle. The OO support needs to be present, but that should be doable as a normal DocBook extension. The organizational and completeness problems with the API reference are orthagonal to the DTD issue; we just haven't had the time. I try to add to and enhance the document as specific questions come up, but can't seem to find enough time. (Things should get better once the conversion is done, but not by a whole lot!)
However, most module documentations will /not/ be written by Guido. In fact, the main goal should be that a module and the documentation are written by the same guy at the same time. Hence, the tool to write the library reference has the following design goals:
Yes; this is one of the two most important issues. The other (which is somewhat at odds with this) is that whatever DTD we select be usable for very high grade documentation that's much more elaborate than basic module documentation.
1. Low barrier for entry: not higher then for writing Python modules.
This is unattainable. The biggest barriers to entry for documentation writing are motivation and natural language. Few people are really good with their own native language, esp. in its written form. Explaining things to others through the written word is very difficult. Python is much easier to learn!
2. Tools to help with it: syntax checkers, and maybe even creators. I dream of a program which will turn the following code
This is relatively easy once you have a format, and I fully intend to do something like this. Konrad Hinsen has done some work with Daniel Larson's pythondoc to generate DocBook with his own Python extension; I'm sure something similar could be done with whatever form we choose.
3. A formidable array of 2XXX convertors: 2html, 2txt, 2man, 2windowshelp, 2info, 2docbook<0.5 wink>
Yes. Again, this is relatively easy. I'd like to point out that to make a switch, the only output we need to care about it HTML. All others will follow as they are needed, so a handful should be available quickly. To call the XML version of the documentation the reference version, I will require an HTML conversion and one typeset version.
I think a new Pythonic-one-way-to-do-it minimalistic DTD is the way to go.
A DTD that's too minimal will not be strong enough for writing the documentation. A good DTD that's workable for all the documents is my personal requirement: only one DTD. More than one increases the learning curve for all authors and maintainers. -Fred -- Fred L. Drake, Jr. <fdrake@acm.org> Corporation for National Research Initiatives