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.