[PYTHON DOC-SIG] SGML-Tools

[Fred L. Drake]

Guido van Rossum wrote:
> 
> > FYI:  The Linux Documentation Project has recently changed
> > the name of their tool suite to SGML-Tools.  I'd recommend
> > that we at least consider it as a possibility, just to leverage
> > off of their efforts.  

> Seriously, it looks like they used the LaTeX document structure and
> command set as a model, which could be an advantage for the Library
> reference manual and the (yet to write :-) Python-C API manual.

  Their document type definition is based on an old DTD called
"QWERTZ" which was intended to be almost a direct translation of
LaTeX.  Other than allowing documents to be validated against a DTD
and being able to use their software, there don't appear to be any
particular advantages to linuxdox/sgml-tools.

> On the other hand, the list of software that is *required* to make it
> work is rather impressive, and I wonder how easy it would be to do

  Windows NT is probably pretty straightforward, especially if you can
get a bourne shell and perl pre-built.  The shell might be the hardest
thing in the freeware market.  (I haven't heard of bash being ported
to NT, and I'd guess that's unlikely.)  The SGML parser should be
readily available.

> > PS: I may convert my Numeric tutorial to it to see how painful it is.
> > It might make sense for someone to convert one of the existing .tex
> > files to .sgml to see how painful that is.  
> 
> If someone steps forward and converts the library manual (or a single
> chapter or even section) to SGML, that would be great.  I expect that
> the fastest approach is to develop a flexible latex-to-anything
> converter...  I'd also be interested in conversion results to TIM, and
> would like to consider a comparison of the quality of the restulting
> Postscript and HTML (being probably the most useful output formats).

  I'd be quite glad to do the work if we could decide on a usable DTD,
but I don't think QWERTZ-derived DTDs really qualify.  There are
others (DocBook springs to mind;
http://www.ora.com/davenport/index.html), but they get complex if
they're actually much good, and are probably hard to deal with in the
fairly open Python community.  I don't think it would be hard to
derive or create something useful or even write the tools, but it
would take a little doing.  There is an early DSSSL (SGML style sheet)
implementation available that supports output in HTML, RTF, and TeX,
but the style sheet and some support would need to be written.


  -Fred

--
Fred L. Drake, Jr.
fdrake@cnri.reston.va.us
Corporation for National Research Initiatives
1895 Preston White Drive
Reston, VA    20191-5434

_______________
DOC-SIG  - SIG for the Python Documentation Project

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