cpython/Doc/tools/sgmlconv
Fred Drake c81d470648 Allow the <author/> element to appear before a paragraph without being
made a part of the paragraph.
2001-03-29 23:31:22 +00:00
..
Makefile Update the rules to separate the two phases for the ESIS generation, 2000-11-22 16:54:20 +00:00
README Update to reflect the process changes. 2000-11-22 16:58:25 +00:00
conversion.xml Add conversions for more of the markup -- not all of this was around when 2001-03-23 16:29:06 +00:00
docfixer.py Allow the <author/> element to appear before a paragraph without being 2001-03-29 23:31:22 +00:00
esis2sgml.py Remove the annoying __version__ definitions. 2001-03-23 17:09:02 +00:00
esistools.py Remove the annoying __version__ definitions. 2001-03-23 17:09:02 +00:00
latex2esis.py Pick up the "encode" function from esistools instead of defining our own 2001-03-23 16:53:34 +00:00
make.rules Update the rules to separate the two phases for the ESIS generation, 2000-11-22 16:54:20 +00:00

README

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 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.

    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.