From 0ee4891c82bbec210b7e13ea3e2b76afb5d078f9 Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Thu, 26 Aug 1999 18:08:13 +0000 Subject: Update the instructions slightly. Add a new section describing what each of the tools does, in general terms. --- Doc/tools/sgmlconv/README | 48 +++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 44 insertions(+), 4 deletions(-) diff --git a/Doc/tools/sgmlconv/README b/Doc/tools/sgmlconv/README index 7b22acb..e19f621 100644 --- a/Doc/tools/sgmlconv/README +++ b/Doc/tools/sgmlconv/README @@ -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/ make -f ../tools/sgmlconv/make.rules TOOLSDIR=../tools -To generate XML instead, use: +To generate SGML instead, use: cd Doc/ - 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
elements to exist in the same output + stream. Additionally, since comments are not supported in ESIS, + comments are converted to 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 .esis. + +esis2sgml.py + Reads an ESIS stream and convert to SGML or XML. This also + converts elements to real comments. This works quickly + because there's not much to actually do. -- cgit v0.12