| These scripts and Makefile fragment are used to convert the Python |
| documentation in LaTeX format to XML. |
| |
| This material is preliminary and incomplete. Python 2.0 is required. |
| |
| To convert all documents to XML: |
| |
| cd Doc/ |
| make -f tools/sgmlconv/Makefile |
| |
| To convert one document to XML: |
| |
| cd Doc/<document-dir> |
| make -f ../tools/sgmlconv/make.rules TOOLSDIR=../tools |
| |
| Please send comments and bug reports to docs@python.org. |
| |
| |
| 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. |
| |
| The output of latex2esis.py gets saved as <filename>.esis1. |
| |
| 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, but does represent a parsed entity. |
| |
| 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. |