traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Update the instructions slightly. 

Add a new section describing what each of the tools does, in general
terms.
This commit is contained in:
Fred Drake 1999-08-26 18:08:13 +00:00
parent 4f0279f439
commit 0ee4891c82
1 changed files with 44 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
Doc/tools/sgmlconv/README
View File

@ -11,23 +11,63 @@ 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 SGML:
To convert all documents to XML:
cd Doc/
make -f tools/sgmlconv/Makefile sgml
To convert a document to SGML:
To convert one document to XML:
cd Doc/<document-dir>
make -f ../tools/sgmlconv/make.rules TOOLSDIR=../tools
To generate XML instead, use:
To generate SGML instead, use:
cd Doc/<document-dir>
make -f ../tools/sgmlconv/make.rules TOOLSDIR=../tools xml
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.