[DOC-SIG] Library reference SGML plan

[Paul Prescod]

Before I start -- how is all of this going to play out with 1.5 and
updates and so forth. Is now the right time to do a documentation
changeover?

If so, let me propose a reorganization of Fredrik's steps:

1. Hack the conversion from TeX to PyLibRef-SGML. Don't worry about
DocBook yet. We'll see how far PyLibRefSGML is from DocBook once we've
got an SGML document. (I can do this, but not for a few days)

2. Write the DTD (or at least a first draft) based on our observations
from 1. Work towards DocBook compatibility if possible because of the
benefits of standardization and code reuse. (I can do this after I
finish step 1).

3. Do the conversions to Print and HTML for our "demo".

4. Write a "howto" document on the entire system.

As for these:

> 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!)

I don't know that we need these two steps. I like XML, but it doesn't
seem relevant to the task at hand. Also, why don't we have a single
parser for sgml/xml? Then we're agnostic. (I'm defining SGML here as XML
plus a few minimizations).

> 7. write an XML to HTML tool based on (6) and a "Python style
>    sheet" (almost done!)

This step makes a lot of sense, but I would say that we could be
SGML/XML agnostic here too.

> 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?)

This is where I get worried. You'll have to tell me more about edroff to
convince me that we're not taking on a humungous job here. I can't find
anything about it on the Web! Even if edroff is the easist tool in the
world to connect to, we should note that PostScript is not necessarily
the best print delivery format in the world. I much prefer to receive a
PDF or RTF file. With Jade, it seems we can deliver any of these -- PS,
PDF, RTF or TeX (not to mention MIF and whatever else someone adds
next). I'm reluctant to throw away the amazing job James has done
unifying those output formats so that support for any of them gives you
support for all of them. We would also be wasting the effort the
typesetting/wordprocessing tool vendors have put into line breaking
algorithms, etc. 

I'm not convinced that we should get hung up about the entire printing
process being in Python. If anyone doesn't want to install Jade, then
they can just view the HTML output for proofing purposes. Why should
every author's desktop be able to serve as a publishing hub?

Also, I would rather spend effort integrating Jade and Python to make a
more powerful, flexible publishing solution than currently exists,
rather than replacing Jade with a less powerful copycat written in a
hurry.

> 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...

So could an SGML parser that does XML plus a few minimization
conventions.
 
 Paul Prescod



_______________
DOC-SIG  - SIG for the Python Documentation Project

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