To convert all documents to XML:

To convert one document to XML:

To generate SGML instead, use:

make -f ../tools/sgmlconv/make.rules TOOLSDIR=../tools sgml

What do the tools do?

---------------------

latex2esis.py

Reads in a conversion specification written in XML

(conversion.xml), reads a LaTeX document fragment, and interprets

the markup according to the specification. The output is a stream

of ESIS events like those created by the nsgmls SGML parser, but

is *not* guaranteed to represent a single tree! This is done to

allow conversion per entity rather than per document. Since many

of the LaTeX files for the Python documentation contain two

sections on closely related modules, it is important to allow both

of the resulting <section> elements to exist in the same output

stream. Additionally, since comments are not supported in ESIS,

comments are converted to <COMMENT> elements, which might exist at

the same level as the top-level content elements.

docfixer.py

This is the really painful part of the conversion. Well, it's the

second really painful part, but more of the pain is specific to

the structure of the Python documentation and desired output

rather than to the parsing of LaTeX markup.

This script loads the ESIS data created by latex2esis.py into a

DOM document *fragment* (remember, the latex2esis.py output may

not be well-formed). Once loaded, it walks over the tree many

times looking for a variety of possible specific

micro-conversions. Most of the code is not in any way "general".

After processing the fragment, a new ESIS data stream is written

out. Like the input, it may not represent a well-formed

document.

The output of docfixer.py is what gets saved in <filename>.esis.

esis2sgml.py

Reads an ESIS stream and convert to SGML or XML. This also

converts <COMMENT> elements to real comments. This works quickly

because there's not much to actually do.