Massive addition of SAX documentation from Martin von Loewis

<loewis@informatik.hu-berlin.de>.

Reorganized to be more like other parts of the documentation in its
arrangement, but with few content changes.

This closes SourceForge patch #101850.

Doc/lib/xmlsax.tex

@@ -6,6 +6,7 @@
                 functions.}
 \moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no}
 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
+\sectionauthor{Martin v. L\"owis}{loewis@informatik.hu-berlin.de}
 
 \versionadded{2.0}
 
@@ -41,8 +42,29 @@ The convenience functions are:
   received as a parameter.
 \end{funcdesc}
 
-
-The SAX exceptions are also provided here:
+A typical SAX application uses three kinds of objects: readers,
+handlers and input sources. ``Reader'' in this context is another term
+for parser, ie. some piece of code that reads the bytes or characters
+from the input source, and produces a sequence of events. The events
+then get distributed to the handler objects, ie. the reader invokes a
+method on the handler. A SAX application must therefore obtain a
+handler object, create or open the input sources, create the handlers,
+and connect these objects all together. As the final step, parsing is
+invoked. During parsing
+
+For these objects, only the interfaces are relevant; they are normally
+not instantiated by the application itself. Since Python does not have
+an explicit notion of interface, they are formally introduced as
+classes. The \class{InputSource}, \class{Locator},
+\class{AttributesImpl}, and \class{XMLReader} interfaces are defined
+in the module \refmodule{xml.sax.xmlreader}. The handler interfaces
+are defined in \refmodule{xml.sax.handler}. For convenience,
+\class{InputSource} (which is often instantiated directly) and the
+handler classes are also available from \module{xml.sax}.  These
+classes are described below.
+
+In addition to these classes, \module{xml.sax} provides the following
+exception classes.
 
 \begin{excclassdesc}{SAXException}{msg\optional{, exception}}
   Encapsulate an XML error or warning.  This class can contain basic
@@ -94,7 +116,7 @@ The SAX exceptions are also provided here:
 \end{seealso}
 
 
-\subsection{SAXException Objects \label{saxexception-objects}}
+\subsection{SAXException Objects \label{sax-exception-objects}}
 
 The \class{SAXException} exception class supports the following
 methods:

Doc/lib/xmlsaxutils.tex

+\section{\module{xml.sax.saxutils} ---
+         SAX Utilities}
+
+\declaremodule{standard}{xml.sax.saxutils}
+\modulesynopsis{Convenience functions and classes for use with SAX.}
+\sectionauthor{Martin v. L\"owis}{loewis@informatik.hu-berlin.de}
+\moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no}
+
+\versionadded{2.0}
+
+
+The module \module{xml.sax.saxutils} contains a number of classes and
+functions that are commonly useful when creating SAX applications,
+either in direct use, or as base classes.
+
+\begin{funcdesc}{escape}{data\optional{, entities}}
+  Escape \&, <, and > in a string of data.
+
+  You can escape other strings of data by passing a dictionary as the
+  optional entities parameter.  The keys and values must all be
+  strings; each key will be replaced with its corresponding value.
+\end{funcdesc}
+
+\begin{classdesc}{XMLGenerator}{\optional{out\optional{, encoding}}}
+  This class implements the \class{ContentHandler} interface by
+  writing SAX events back into an XML document. In other words, using
+  an \class{XMLGenerator} as the content handler will reproduce the
+  original document being parsed. \var{out} should be a file-like
+  object which will default to \var{sys.stdout}. \var{encoding} is the
+  encoding of the output stream which defaults to \code{'iso-8859-1'}.
+\end{classdesc}
+
+\begin{classdesc}{XMLFilterBase}{base}
+  This class is designed to sit between an \class{XMLReader} and the
+  client application's event handlers.  By default, it does nothing
+  but pass requests up to the reader and events on to the handlers
+  unmodified, but subclasses can override specific methods to modify
+  the event stream or the configuration requests as they pass through.
+\end{classdesc}
+
+\begin{funcdesc}{prepare_input_source}{source\optional{, base}}
+  This function takes an input source and an optional base URL and
+  returns a fully resolved \class{InputSource} object ready for
+  reading.  The input source can be given as a string, a file-like
+  object, or an \class{InputSource} object; parsers will use this
+  function to implement the polymorphic \var{source} argument to their
+  \method{parse()} method.
+\end{funcdesc}