| These scripts and Makefile fragment are used to convert the Python |
| documentation in LaTeX format to SGML or XML. Though I originally |
| thought that the XML was unlikely to be used, tool support for XML |
| is increasing quickly enough that it may well be the final format. |
| (It is the default output format when using the makefiles included |
| here.) |
| |
| This material is preliminary and incomplete. The XML omnibus package |
| developed by the Python XML-SIG is required; specifically, the version |
| available in the public CVS repository. See |
| http://www.python.org/sigs/xml-sig/ for more information on the |
| package. |
| |
| To convert all documents to XML: |
| |
| cd Doc/ |
| make -f tools/sgmlconv/Makefile sgml |
| |
| To convert one document to XML: |
| |
| cd Doc/<document-dir> |
| make -f ../tools/sgmlconv/make.rules TOOLSDIR=../tools |
| |
| To generate SGML instead, use: |
| |
| cd Doc/<document-dir> |
| make -f ../tools/sgmlconv/make.rules TOOLSDIR=../tools sgml |
| |
| Note that building the second target format is fast because both |
| conversions use the same intermediate format (an ESIS event stream). |
| This is true regardless of whether you build SGML or XML first. |
| |
| Please send comments and bug reports to python-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. |
| |
| 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. |