[Doc-SIG] RE: Python 2.0 quick reference...

[Fred L. Drake, Jr.]

Simon Brunning writes:
 > The new version of the Python Quick Reference is at
 > <http://www.brunningonline.net/simon/python/PQR.html>. It occurs to me that
 > members of this list would be best placed to advise me as to future
 > directions...

  I'm not sure what you mean by "future directions" -- changes in
organization? content?

 > > I'm not going to make any further changes to the 2.0 version, but I'm
 > > planning to extensively revamp the whole document for the 2.1 version. At
 > > very least, I'm going to get rid of nearly every <pre> tag, and to
 > > externalise the formatting into a css. That would allow people download
 > > the
 > > document and to muck about with the format to their heart's content.

  I agree that moving the styling into CSS is a laudable goal, but I
don't think that means getting rid of PRE sections (assuming those are
code examples or interactive sessions).

 > > But I'm actually thinking of going one step further, and keeping the
 > > master
 > > document in XML format (possibly using DocBook?) and transforming to HTML
 > > as
 > > required. And indeed into PDF using your own wonderful ReportLab tool.
...
 > Any suggestions? In what format are the master versions of the Python
 > Documentation? Any good tools knocking around?

  The Python docs are in LaTeX using fairly extensive custom markup.
I don't expect that would be appropriate for the QuickRef, but perhaps
if you wrote it using the "howto" document class and formatted it to
use a single HTML page.  You'd also get PostScript and PDF formatting
for free that way.  Information on the LaTeX markup for Python
documentation is available at:

	http://www.python.org/doc/current/doc/doc.html


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Digital Creations