[DOC-SIG] Library reference manual debate

[Fredrik Lundh]

> Otherwise, I'd challenge you to get started -- I'm sure you'd do a
> great job.

Well, the thing is that I have to do this anyway (not that bad,
since I get paid to do it); if I can get you on the "right track",
I might be able to contribute without having to work extra
shifts ;-)

> I'm more interested in hearing from people who have done some-
> thing that I (and the rest of the Python community) can use.  "Use
> SGML" is not a productive approach; "this is what I did using SGML"
> is.

Okay, folks.  Time to:

1. Settle on a DTD.  Can we use DocBook as is?  What extensions
   are needed?  (Paul?  Fred?)

2. Write a small "howto" document; maybe just a sample page
   showing how to format a typical libref chapter.   maybe also
   a "howto" on how to efficiently use emacs' SGML mode.

3. Hack a customized Tex to SGML converter (anyone has any
   code for this?)

4. (initially) use Jade for the initial conversions to RTF/PS and
   HTML, using Norm Walsh's DSSSL stylesheets (Paul?)

Now, since learning scheme (DSSSL) is more than I have time
for, I'll also propose the following projects:

5. write an SGML to XML converter using Grail's SGMLparser
   (in the meantime, we can use James Clark's "sx" tool)
6. write an XML parser (at least a tokenizer) that some day
   could be included in the standard Python distribution (almost
   done!)
7. write an XML to HTML tool based on (6) and a "Python style
   sheet" (almost done!)
8. write an XML to PostScript tool based on (6), the printer
   formatter from edroff, and PIL's PSDraw (or maybe we could
   use html2ps?)
9. write an XSL stylesheet for XML-aware browsers.
10. etc.
11. etc.
12. etc.

Or maybe fuse 5 and 6.  But dealing with XML is much easier;
an XML parser written in C could be added to Python without
anyone noticing...

And given modules 5-7, we'll end up with the 100% pure python
solution that I guess we all would prefer...

So, what do you think?

Cheers	/F


_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________