[Doc-SIG] XML Conversion Update

[Moshe Zadka]

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):
		self.n=n

	def foo():
		print n

Into the following document

<class name="MyClass">
XXX Describe class here!
<methods>
<method name="__init__">
<arguments>
<argument name="n">
XXX Insert description here!
</arguments>
XXX Insert descritption here!
</method>
.
.
</class>
          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?

<hang-head-in-shame>
Where can I get the DTD? Only heard about it, never saw it...
</hang-head-in-shame>

--
Moshe Zadka <mzadka@geocities.com>. 
INTERNET: Learn what you know.
Share what you don't.