[Doc-SIG] SGML Python docs

[Laurence Tratt]

In message <13814.40453.748852.965008@weyr.cnri.reston.va.us>
          "Fred L. Drake" <fdrake@cnri.reston.va.us> wrote:

>> only problem with LaTeX is that it's pretty hard to write a reliable parser
>> for
> 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

Quit your day job :)

> but I'll probably have to whenever I get around to the next shot at a
> conversion script!

I don't think one needs to make a general parser, and writing a hard-coded-to-
one-style parser is definitely a lot easier. But that's what I mean about
breaking: a hard-coded parser is totally at the mercy of the LaTeX style
staying the same.

>   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.

It's a bit easier to update things in a conversion program with a more, er,
strict layout like XML than LaTeX: with LaTeX, if you write a conversion
script, you pretty much have to stipulate that if the style changes, the
program gets rewritten. With XML/SGML/whatever, you have a fighting chance :)

Personally I'm not a great fan of XML, but I would like to be able to
generate different types of output from the documentation - which contains
all the information I need, but in a very hard to digest format.

Something like XML won't really solve any problems for the people writing the
documentation as far as I can see, but it will solve the output problem. Does
this sound like a fair comment?

>   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.

That sounds like a good idea.


Laurie