[Doc-SIG] XML Conversion Update

[Fred L. Drake, Jr.]

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