First cut at documentation for the xml.sax package (not including any

sub-modules).

1 files changed, 108 insertions, 0 deletions

diff --git a/Doc/lib/xmlsax.tex b/Doc/lib/xmlsax.tex
new file mode 100644
index 0000000000..d09777fea2
--- /dev/null
+++ b/Doc/lib/xmlsax.tex
@@ -0,0 +1,108 @@
+\section{\module{xml.sax} ---
+         Support for SAX2 parsers}
+
+\declaremodule{standard}{xml.sax}
+\modulesynopsis{Package containing SAX2 base classes and convenience
+                functions.}
+\moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no}
+\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
+
+\versionadded{2.0}
+
+
+The \module{xml.sax} package provides a number of modules which
+implement the Simple API for XML (SAX) interface for Python.  The
+package itself provides the SAX exceptions and the convenience
+functions which will be most used by users of the SAX API.
+
+The convenience functions are:
+
+\begin{funcdesc}{make_parser}{\optional{parser_list}}
+  Create and return a SAX \class{XMLReader} object.  The first parser
+  found will be used.  If \var{parser_list} is provided, it must be a
+  sequence of strings which name modules that have a function named
+  \function{create_parser()}.  Modules listed in \var{parser_list}
+  will be used before modules in the default list of parsers.
+\end{funcdesc}
+
+\begin{funcdesc}{parse}{filename_or_stream, handler\optional{, error_handler}}
+  Create a SAX parser and use it to parse a document.  The document,
+  passed in as \var{filename_or_stream}, can be a filename or a file
+  object.  The \var{handler} parameter needs to be a SAX
+  \class{ContentHandler} instance.  If \var{error_handler} is given,
+  it must be a SAX \class{ErrorHandler} instance; if omitted, 
+  \exception{SAXParseException} will be raised on all errors.  There
+  is no return value; all work must be done by the \var{handler}
+  passed in.
+\end{funcdesc}
+
+\begin{funcdesc}{parseString}{string, handler\optional{, error_handler}}
+  Similar to \function{parse()}, but parses from a buffer \var{string}
+  received as a parameter.
+\end{funcdesc}
+
+
+The SAX exceptions are also provided here:
+
+\begin{excclassdesc}{SAXException}{msg\optional{, exception}}
+  Encapsulate an XML error or warning.  This class can contain basic
+  error or warning information from either the XML parser or the
+  application: it can be subclassed to provide additional
+  functionality or to add localization.  Note that although the
+  handlers defined in the \class{ErrorHandler} interface receive
+  instances of this exception, it is not required to actually raise
+  the exception --- it is also useful as a container for information.
+
+  When instantiated, \var{msg} should be a human-readable description
+  of the error.  The optional \var{exception} parameter, if given,
+  should be \code{None} or an exception that was caught by the parsing
+  code and is being passed along as information.
+
+  This is the base class for the other SAX exception classes.
+\end{excclassdesc}
+
+\begin{excclassdesc}{SAXParseException}{msg, exception, locator}
+  Subclass of \exception{SAXException} raised on parse errors.
+  Instances of this class are passed to the methods of the SAX
+  \class{ErrorHandler} interface to provide information about the
+  parse error.  This class supports the SAX \class{Locator} interface
+  as well as the \class{SAXException} interface.
+\end{excclassdesc}
+
+\begin{excclassdesc}{SAXNotRecognizedException}{msg\optional{, exception}}
+  Subclass of \exception{SAXException} raised when a SAX
+  \class{XMLReader} is confronted with an unrecognized feature or
+  property.  SAX applications and extensions may use this class for
+  similar purposes.
+\end{excclassdesc}
+
+\begin{excclassdesc}{SAXNotSupportedException}{msg\optional{, exception}}
+  Subclass of \exception{SAXException} raised when a SAX
+  \class{XMLReader} is asked to enable a feature that is not
+  supported, or to set a property to a value that the implementation
+  does not support.  SAX applications and extensions may use this
+  class for similar purposes.
+\end{excclassdesc}
+
+
+\begin{seealso}
+  \seetitle[http://www.megginson.com/SAX/]{SAX: The Simple API for
+            XML}{This site is the focal point for the definition of
+            the SAX API.  It provides a Java implementation and online
+            documentation.  Links to implementations and historical
+            information are also available.}
+\end{seealso}
+
+
+\subsection{SAXException Objects \label{saxexception-objects}}
+
+The \class{SAXException} exception class supports the following
+methods:
+
+\begin{methoddesc}[SAXException]{getMessage}{}
+  Return a human-readable message describing the error condition.
+\end{methoddesc}
+
+\begin{methoddesc}[SAXException]{getException}{}
+  Return an encapsulated exception object, or \code{None}.
+\end{methoddesc}