mirror of
https://github.com/python/cpython.git
synced 2026-05-12 23:49:15 -04:00
Fred Drake
74 lines
3.0 KiB
Plaintext
74 lines
3.0 KiB
Plaintext
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.
|