Doc/tools/sgmlconv/README

   1 These scripts and Makefile fragment are used to convert the Python
   2 documentation in LaTeX format to XML.
   3
   4 This material is preliminary and incomplete.  Python 2.0 is required.
   5
   6 To convert all documents to XML:
   7
   8         cd Doc/
   9         make -f tools/sgmlconv/Makefile
  10
  11 To convert one document to XML:
  12
  13         cd Doc/<document-dir>
  14         make -f ../tools/sgmlconv/make.rules TOOLSDIR=../tools
  15
  16 Please send comments and bug reports to docs@python.org.
  17
  18
  19 What do the tools do?
  20 ---------------------
  21
  22 latex2esis.py
  23     Reads in a conversion specification written in XML
  24     (conversion.xml), reads a LaTeX document fragment, and interprets
  25     the markup according to the specification.  The output is a stream
  26     of ESIS events like those created by the nsgmls SGML parser, but
  27     is *not* guaranteed to represent a single tree!  This is done to
  28     allow conversion per entity rather than per document.  Since many
  29     of the LaTeX files for the Python documentation contain two
  30     sections on closely related modules, it is important to allow both
  31     of the resulting <section> elements to exist in the same output
  32     stream.  Additionally, since comments are not supported in ESIS,
  33     comments are converted to <COMMENT> elements, which might exist at
  34     the same level as the top-level content elements.
  35
  36     The output of latex2esis.py gets saved as <filename>.esis1.
  37
  38 docfixer.py
  39     This is the really painful part of the conversion.  Well, it's the
  40     second really painful part, but more of the pain is specific to
  41     the structure of the Python documentation and desired output
  42     rather than to the parsing of LaTeX markup.
  43
  44     This script loads the ESIS data created by latex2esis.py into a
  45     DOM document *fragment* (remember, the latex2esis.py output may
  46     not be well-formed).  Once loaded, it walks over the tree many
  47     times looking for a variety of possible specific
  48     micro-conversions.  Most of the code is not in any way "general".
  49     After processing the fragment, a new ESIS data stream is written
  50     out.  Like the input, it may not represent a well-formed
  51     document, but does represent a parsed entity.
  52
  53     The output of docfixer.py is what gets saved in <filename>.esis.
  54
  55 esis2sgml.py
  56     Reads an ESIS stream and convert to SGML or XML.  This also
  57     converts <COMMENT> elements to real comments.  This works quickly
  58     because there's not much to actually do.