mirror of
https://github.com/python/cpython.git
synced 2025-11-03 19:34:08 +00:00
58 lines
2.3 KiB
Text
58 lines
2.3 KiB
Text
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.
|