Doco update from Sjoerd Mullender.

2 files changed, 29 insertions, 23 deletions

diff --git a/Doc/lib/libchunk.tex b/Doc/lib/libchunk.tex
index 770b525..0825a25 100644
--- a/Doc/lib/libchunk.tex
+++ b/Doc/lib/libchunk.tex
@@ -13,16 +13,15 @@ chunks.\footnote{``EA IFF 85'' Standard for Interchange Format Files,
 Jerry Morrison, Electronic Arts, January 1985.}  This format is used
 in at least the Audio\index{Audio Interchange File
 Format}\index{AIFF}\index{AIFF-C} Interchange File Format
-(AIFF/AIFF-C), the Real\index{Real Media File Format} Media File
-Format\index{RMFF} (RMFF), and the
-Tagged\index{Tagged Image File Format} Image File Format\index{TIFF}
-(TIFF).
+(AIFF/AIFF-C) and the Real\index{Real Media File Format} Media File
+Format\index{RMFF} (RMFF).  The WAVE audio file format is closely
+related and can also be read using this module.
 
 A chunk has the following structure:
 
 \begin{tableiii}{c|c|l}{textrm}{Offset}{Length}{Contents}
   \lineiii{0}{4}{Chunk ID}
-  \lineiii{4}{4}{Size of chunk in big-endian byte order, including the 
+  \lineiii{4}{4}{Size of chunk in big-endian byte order, not including the 
                  header}
   \lineiii{8}{\var{n}}{Data bytes, where \var{n} is the size given in
                        the preceeding field}
@@ -33,7 +32,7 @@ A chunk has the following structure:
 The ID is a 4-byte string which identifies the type of chunk.
 
 The size field (a 32-bit value, encoded using big-endian byte order)
-gives the size of the whole chunk, including the 8-byte header.
+gives the size of the chunk data, not including the 8-byte header.
 
 Usually an IFF-type file consists of one or more chunks.  The proposed
 usage of the \class{Chunk} class defined here is to instantiate an
@@ -42,7 +41,7 @@ it reaches the end, after which a new instance can be instantiated.
 At the end of the file, creating a new instance will fail with a
 \exception{EOFError} exception.
 
-\begin{classdesc}{Chunk}{file\optional{, align}}
+\begin{classdesc}{Chunk}{file\optional{, align, bigendian, inclheader}}
 Class which represents a chunk.  The \var{file} argument is expected
 to be a file-like object.  An instance of this class is specifically
 allowed.  The only method that is needed is \method{read()}.  If the
@@ -51,7 +50,12 @@ raise an exception, they are also used.  If these methods are present
 and raise an exception, they are expected to not have altered the
 object.  If the optional argument \var{align} is true, chunks are
 assumed to be aligned on 2-byte boundaries.  If \var{align} is
-false, no alignment is assumed.  The default value is true.
+false, no alignment is assumed.  The default value is true.  If the
+optional argument \var{bigendian} is false, the chunk size is assumed
+to be in little-endian order.  This is needed for WAVE audio files.
+The default value is true.  If the optional argument \var{inclheader}
+is true, the size given in the chunk header includes the size of the
+header.  The default value is false.
 \end{classdesc}
 
 A \class{Chunk} object supports the following methods:
@@ -61,6 +65,10 @@ Returns the name (ID) of the chunk.  This is the first 4 bytes of the
 chunk.
 \end{methoddesc}
 
+\begin{methoddesc}{getsize}{}
+Returns the size of the chunk.
+\end{methoddesc}
+
 \begin{methoddesc}{close}{}
 Close and skip to the end of the chunk.  This does not close the
 underlying file.
diff --git a/Doc/lib/libxmllib.tex b/Doc/lib/libxmllib.tex
index 7b87219..c407629 100644
--- a/Doc/lib/libxmllib.tex
+++ b/Doc/lib/libxmllib.tex
@@ -16,7 +16,18 @@ This module defines a class \class{XMLParser} which serves as the basis
 for parsing text files formatted in XML (Extensible Markup Language).
 
 \begin{classdesc}{XMLParser}{}
-The \class{XMLParser} class must be instantiated without arguments.
+The \class{XMLParser} class must be instantiated without
+arguments.\footnote{Actually, a number of keyword arguments are
+recognized which influence the parser to accept certain non-standard
+constructs.  The following keyword arguments are currently
+recognized.  The defaults for all of these is \code{0} (false).
+\var{accept_unquoted_attributes} (accept certain attribute values
+without requiring quotes), \var{accept_missing_endtag_name} (accept
+end tags that look like \code{</>}), \var{map_case} (map upper case to
+lower case in tags and attributes), \var{accept_utf8} (allow UTF-8
+characters in input; this is required according to the XML standard,
+but Python does not as yet deal properly with these characters, so
+this is not the default).}
 \end{classdesc}
 
 This class provides the following interface methods and instance variables:
@@ -140,19 +151,6 @@ subclass must override this method to provide support for character
 references outside of the \ASCII{} range.
 \end{methoddesc}
 
-\begin{methoddesc}{handle_entityref}{ref}
-This method is called to process a general entity reference of the
-form \samp{\&\var{ref};} where \var{ref} is an general entity
-reference.  It looks for \var{ref} in the instance (or class)
-variable \member{entitydefs} which should be a mapping from entity
-names to corresponding translations.
-If a translation is found, it calls the method \method{handle_data()}
-with the translation; otherwise, it calls the method
-\code{unknown_entityref(\var{ref})}.  The default \member{entitydefs}
-defines translations for \code{\&amp;}, \code{\&apos}, \code{\&gt;},
-\code{\&lt;}, and \code{\&quot;}.
-\end{methoddesc}
-
 \begin{methoddesc}{handle_comment}{comment}
 This method is called when a comment is encountered.  The
 \var{comment} argument is a string containing the text between the
@@ -223,7 +221,7 @@ base class implementation does nothing.
 \begin{methoddesc}{unknown_entityref}{ref}
 This method is called to process an unknown entity reference.  It is
 intended to be overridden by a derived class; the base class
-implementation does nothing.
+implementation calls \method{syntax_error()} to signal an error.
 \end{methoddesc}