Doc/tools/sgmlconv/README

   1 These scripts and Makefile fragment are used to convert the Python
   2 documentation in LaTeX format to SGML or XML.  Though I originally
   3 thought that the XML was unlikely to be used, tool support for XML
   4 is increasing quickly enough that it may well be the final format.
   5 (It is the default output format when using the makefiles included
   6 here.)
   7
   8 This material is preliminary and incomplete.  The XML omnibus package
   9 developed by the Python XML-SIG is required; specifically, the version
  10 available in the public CVS repository.  See
  11 http://www.python.org/sigs/xml-sig/ for more information on the
  12 package.
  13
  14 To convert all documents to XML:
  15
  16         cd Doc/
  17         make -f tools/sgmlconv/Makefile sgml
  18
  19 To convert one document to XML:
  20
  21         cd Doc/<document-dir>
  22         make -f ../tools/sgmlconv/make.rules TOOLSDIR=../tools
  23
  24 To generate SGML instead, use:
  25
  26         cd Doc/<document-dir>
  27         make -f ../tools/sgmlconv/make.rules TOOLSDIR=../tools sgml
  28
  29 Note that building the second target format is fast because both
  30 conversions use the same intermediate format (an ESIS event stream).
  31 This is true regardless of whether you build SGML or XML first.
  32
  33 Please send comments and bug reports to python-docs@python.org.
  34
  35
  36 What do the tools do?
  37 ---------------------
  38
  39 latex2esis.py
  40     Reads in a conversion specification written in XML
  41     (conversion.xml), reads a LaTeX document fragment, and interprets
  42     the markup according to the specification.  The output is a stream
  43     of ESIS events like those created by the nsgmls SGML parser, but
  44     is *not* guaranteed to represent a single tree!  This is done to
  45     allow conversion per entity rather than per document.  Since many
  46     of the LaTeX files for the Python documentation contain two
  47     sections on closely related modules, it is important to allow both
  48     of the resulting <section> elements to exist in the same output
  49     stream.  Additionally, since comments are not supported in ESIS,
  50     comments are converted to <COMMENT> elements, which might exist at
  51     the same level as the top-level content elements.
  52
  53 docfixer.py
  54     This is the really painful part of the conversion.  Well, it's the
  55     second really painful part, but more of the pain is specific to
  56     the structure of the Python documentation and desired output
  57     rather than to the parsing of LaTeX markup.
  58
  59     This script loads the ESIS data created by latex2esis.py into a
  60     DOM document *fragment* (remember, the latex2esis.py output may
  61     not be well-formed).  Once loaded, it walks over the tree many
  62     times looking for a variety of possible specific
  63     micro-conversions.  Most of the code is not in any way "general".
  64     After processing the fragment, a new ESIS data stream is written
  65     out.  Like the input, it may not represent a well-formed
  66     document.
  67
  68     The output of docfixer.py is what gets saved in <filename>.esis.
  69
  70 esis2sgml.py
  71     Reads an ESIS stream and convert to SGML or XML.  This also
  72     converts <COMMENT> elements to real comments.  This works quickly
  73     because there's not much to actually do.