[Doc-SIG] XML Conversion Update
Moshe Zadka <email@example.com>
Fri, 27 Aug 1999 20:14:40 +0300 (GMT+0300)
On Fri, 27 Aug 1999, Skip Montanaro wrote:
> Moshe> I vote for a roll-our-own style.
> Well, how about we roll our own and it just happens to be a strict subset of
> docbook? You document it as the Pythonic Way To Write Documentation, and
> buried deep in some appendix it says (in six-point font):
> This DTD is a subset of DocBook.
Not good, for exactly the reason I outlined earlier: some bozo will try to
write DocBook, just like this bozo tried to write LaTeX.
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
needed for other kinds of docs: more on this later). So, the only thing we
will be left with from DocBook will be things like (don't know the exact
names, guessing...) <emph>, etc.
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
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.
2. The extending/embedding manual is similar.
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.
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:
1. Low barrier for entry: not higher then for writing Python modules.
2. Tools to help with it: syntax checkers, and maybe even creators. I
dream of a program which will turn the following code
def __init__(self, n):
Into the following document
XXX Describe class here!
XXX Insert description here!
XXX Insert descritption here!
3. A formidable array of 2XXX convertors: 2html, 2txt, 2man,
2windowshelp, 2info, 2docbook<0.5 wink>
I think a new Pythonic-one-way-to-do-it minimalistic DTD is the way
> That said, can you just start whacking useless appendages off of DocBook?
Where can I get the DTD? Only heard about it, never saw it...
Moshe Zadka <firstname.lastname@example.org>.
INTERNET: Learn what you know.
Share what you don't.