[Doc-SIG] SGML Python docs

[Laurence Tratt]

In message <13813.39671.3295.188971@weyr.cnri.reston.va.us>
          "Fred L. Drake" <fdrake@cnri.reston.va.us> 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.


Laurie