[Doc-SIG] XML Conversion Update

Moshe Zadka Moshe Zadka <mzadka@geocities.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
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.

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

class MyClass:

	def __init__(self, n):

	def foo():
		print n

Into the following document

<class name="MyClass">
XXX Describe class here!
<method name="__init__">
<argument name="n">
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
to go.

> 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 <mzadka@geocities.com>. 
INTERNET: Learn what you know.
Share what you don't.