| 1 | These scripts and Makefile fragment are used to convert the Python
|
|---|
| 2 | documentation in LaTeX format to XML.
|
|---|
| 3 |
|
|---|
| 4 | This material is preliminary and incomplete. Python 2.0 is required.
|
|---|
| 5 |
|
|---|
| 6 | To convert all documents to XML:
|
|---|
| 7 |
|
|---|
| 8 | cd Doc/
|
|---|
| 9 | make -f tools/sgmlconv/Makefile
|
|---|
| 10 |
|
|---|
| 11 | To convert one document to XML:
|
|---|
| 12 |
|
|---|
| 13 | cd Doc/<document-dir>
|
|---|
| 14 | make -f ../tools/sgmlconv/make.rules TOOLSDIR=../tools
|
|---|
| 15 |
|
|---|
| 16 | Please send comments and bug reports to [email protected].
|
|---|
| 17 |
|
|---|
| 18 |
|
|---|
| 19 | What do the tools do?
|
|---|
| 20 | ---------------------
|
|---|
| 21 |
|
|---|
| 22 | latex2esis.py
|
|---|
| 23 | Reads in a conversion specification written in XML
|
|---|
| 24 | (conversion.xml), reads a LaTeX document fragment, and interprets
|
|---|
| 25 | the markup according to the specification. The output is a stream
|
|---|
| 26 | of ESIS events like those created by the nsgmls SGML parser, but
|
|---|
| 27 | is *not* guaranteed to represent a single tree! This is done to
|
|---|
| 28 | allow conversion per entity rather than per document. Since many
|
|---|
| 29 | of the LaTeX files for the Python documentation contain two
|
|---|
| 30 | sections on closely related modules, it is important to allow both
|
|---|
| 31 | of the resulting <section> elements to exist in the same output
|
|---|
| 32 | stream. Additionally, since comments are not supported in ESIS,
|
|---|
| 33 | comments are converted to <COMMENT> elements, which might exist at
|
|---|
| 34 | the same level as the top-level content elements.
|
|---|
| 35 |
|
|---|
| 36 | The output of latex2esis.py gets saved as <filename>.esis1.
|
|---|
| 37 |
|
|---|
| 38 | docfixer.py
|
|---|
| 39 | This is the really painful part of the conversion. Well, it's the
|
|---|
| 40 | second really painful part, but more of the pain is specific to
|
|---|
| 41 | the structure of the Python documentation and desired output
|
|---|
| 42 | rather than to the parsing of LaTeX markup.
|
|---|
| 43 |
|
|---|
| 44 | This script loads the ESIS data created by latex2esis.py into a
|
|---|
| 45 | DOM document *fragment* (remember, the latex2esis.py output may
|
|---|
| 46 | not be well-formed). Once loaded, it walks over the tree many
|
|---|
| 47 | times looking for a variety of possible specific
|
|---|
| 48 | micro-conversions. Most of the code is not in any way "general".
|
|---|
| 49 | After processing the fragment, a new ESIS data stream is written
|
|---|
| 50 | out. Like the input, it may not represent a well-formed
|
|---|
| 51 | document, but does represent a parsed entity.
|
|---|
| 52 |
|
|---|
| 53 | The output of docfixer.py is what gets saved in <filename>.esis.
|
|---|
| 54 |
|
|---|
| 55 | esis2sgml.py
|
|---|
| 56 | Reads an ESIS stream and convert to SGML or XML. This also
|
|---|
| 57 | converts <COMMENT> elements to real comments. This works quickly
|
|---|
| 58 | because there's not much to actually do.
|
|---|
