[Doc-SIG] SGML Python docs

[Fred L. Drake]

Laurence Tratt writes:
 > only problem with LaTeX is that it's pretty hard to write a reliable parser
 > for, and that at the push of a button any program which relies on parts of

  Yes, this is a real problem.  Perhaps there should be a LaTeXParser
class available for Python, similar to sgmllib.SGMLParser?  ;-)  I
don't know when I'll fit that in, but I'll probably have to whenever I 
get around to the next shot at a conversion script!

 > the markup staying roughly the same dies horribly. If there could be a
 > guarantee that the LaTeX markup wasn't going to change then I think it would
 > be OK to use the LaTeX as the base converter. However - from experience - the
 > temptation with LaTeX is always to have a quick fiddle to tidy things up, and
 > that breaks things very easily :)

  I don't know that this will change substantially if we use a Python- 
specific DTD.  There are a couple of issues here:

	-  Requirements change, even if slowly.  The most substantial
	   recent changes for the Python docs have been the
	   introduction of the API document and the howto document
	   class.

	-  When new markup structures are identified which better
	   serve existing requirements.  For example, we're now coding 
	   the short "module synopsis" provided in chapter
	   introductions in the module section, which improves the
	   maintainability and flexibility of the documents.

 > I would imagine this is the only way to reliably retain all the information
 > that the LaTeX now holds (eg about when "string" is a module, and when it's

  I think the DocBook ROLE attribute could be used to help make these
distinctions, but that brings back up the authoring issue again:
who's going to type all that stuff?  For the contributed
documentation, we still receive more sections that use \code for
everything that should be typeset in Courier than anything else
(though some authors are using the "logical" markup; thanks!).  What
happens is that I have to spend a fair amount of time adjusting the
markup to us \module, \function, \method, or whatever is called for.
This is time consuming and prevents me from spending much time writing 
(as do other things, like needing to get things done!).
  Perhaps it's time to dust off the DTD I was writing as the target
for the old conversion script and bring that somewhat up to date and
add comments on the semantic interpretation of the elements and
attributes, perhaps with notes on processing expectations for the
current output formats.


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives
1895 Preston White Dr.	    Reston, VA  20191