[Doc-SIG] SGML Python docs
Wed, 09 Sep 1998 22:30:37 +0100
In message <email@example.com>
"Fred L. Drake" <firstname.lastname@example.org> wrote:
>> only problem with LaTeX is that it's pretty hard to write a reliable parser
> 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
> - 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.