[Doc-SIG] SGML Python docs
Wed, 09 Sep 1998 14:18:31 +0100
In message <firstname.lastname@example.org>
"Fred L. Drake" <email@example.com> wrote:
>> A while ago (around Easter time), it was said that the Python documentation
>> (manual reference, etc) would at some point be converted to SGML.
> This is still planned. The preliminary conversion script I'd been
> working on has been massively broken due to the changes in the LaTeX
> markup, and I think the breakage is permanent: at this point, I'm
> more likely to start a conversion script from scratch than try to
> revive the old one yet again.
This is basically what happened to my LaTeX -> x converter...
> On the other hand, the LaTeX markup has become much more logical,
> which reduces the immediacy of the need for a conversion. While I
> still think SGML/XML will be the final form of the documentation, I
> don't see a compelling need for a conversion at this time. No matter
> how we do things, there is no trivial conversion of the documentation
> and related tools that gives us any benefits over the current
> situation that I'm aware of; feel free to enlighten me on this one.
My personal opinion is that the format that the documentation is written in
is irrelevant: whatever is decided upon needs to have a converter written for
it which can then be used to convert into varying types of documentation. My
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
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'd also be very interested in seeing alternate DTDs that are
> targeted more tightly for these sorts of documents, possibly specific
> to this particular documentation set.
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
an attribute in an RE object). I don't believe in reinventing the wheel when
it's not necessary, but I would imagine we would be trying to mangle two
different wheels together if we used a non-specific DTD.