[DOC-SIG] Comparing SGML DTDs

[Andrew Kuchling]

Paul Prescod <papresco@technologist.com> wrote:
> * The title of the thread is "notes on the tutorial's markup" -- isn't
>the tutorial then the task at hand? I'm having trouble reconstructing
>the thread. I thought that was proposed as a test case by Andrew
>Kuchling. 

	The tutorial, "Extending & Embedding", and API documents are
simpler than the LibRef, because they just need some simple
typesetting capability: chapters, sections, and code.  They're a lot
simpler than the library reference, so I chickened out from
considering the latter.

	For an example of the problems to be confronted in the LibRef,
look at the documentation for SocketServer.py, at
http://grail.cnri.reston.va.us/python/1.5a4/lib/node176.html; note the
several ad hoc sections for instance variables, class variables,
external methods, overridable internal methods, and utility methods.
The LaTeX setup, as it currently stands, can't document a complex
framework well; it's more suited to modules that are simply
collections of functions with an object or two.  (Even that's getting
tough; there's no typographical indication for default arguments or
keyword arguments.)  

	This can probably be solved by thinking up a typographical
notation for these features and adding LaTeX macros for them.  Perhaps
that band-aid solution would be good enough, though I don't know where
that leaves people who want to produce WinHelp, or OS/2 help, or
WhateverHelp files.

> I also thought that Andrew was the tutorial maintainer (from 
>some old messages in the thread). You can see how I came to the
>conclusion that he had the (moral) authority to move it to SGML.

	No, and I'm sorry if I gave that impression.  While I'm
tweaking the tutorial for 1.5, I haven't taken it over permanently.

> * Does it makes sense to think about the library reference in
>isolation? Do we really plan to keep the two docs in different formats

	The language reference is already in FrameMaker, but document
formats shouldn't be multiplied.  If GvR rules SGML/XML out, that's
that, and we have to consider the other options: just add some LaTeX
macros, or use TIM (which is built on top of Texinfo, a format which I
quite like), or invent some pod-like format.


	Andrew Kuchling
	amk@magnet.com
	http://starship.skyport.net/crew/amk/

_______________
DOC-SIG  - SIG for the Python Documentation Project

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