[DOC-SIG] Library reference manual debate

[Scott]

Seems like there's a lot of great works getting underway here.  I'm certain
they would/will add alot to what python can do.

As far as my own opinion for what what format the library reference should
take,  I have two major concerns.  First is that the first beta release of
python 1.5 is not significantly delayed for whatever is decided should be done
to change the current docs.  There's alot of work in 1.4 out there that would
benefit greatly from a public 1.5 release (and I'm tired of wanting to write
code that will only work in 1.5 when in production it will have to in 1.4).

Second is that html be really easy to access.  For the library reference in
particular, I find that I'd much rather click search a couple of times than
page through sheet after sheet of hardcopy.

Finally, though I'm not all that familiar with the particulars of parsing
tim/sgml/xml/latex, I would like to point out that I've made some progress 
towards easily producing generally efficient parsers in python (Lex/Yacc/Bison
style). Should anyone working on any python documentation projects want such a
tool before it's ready for its first public release, there is pre release info
on the string sig and under
http://starship.skyport.net/crew/scott/projects.html.  Using the prelease code
toward this end, or offering suggestions as to how it could better accomodate
this end is most welcome.

scott   


On Sun, Nov 16, 1997 at 09:08:11PM +0100, Fredrik Lundh wrote:
| > 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
| _______________

_______________
DOC-SIG  - SIG for the Python Documentation Project

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