Further improvements in expat.

* src/expat.sci (xml-make-parser): Fix definition.
(xml-error-descr): New syntax.
* src/gamma-expat.c (xml-expat-version-string)
(xml-expat-version)
(xml-default-current)
(xml-error-string)
(xml-current-line-number)
(xml-current-byte-count): New functions.
(xml-primitive-make-parser): Include context data int the
error information.
(generic_xml_decl_handler): Account for possible NULLs.

* examples/xml-check.scm: New file.
* examples/xml-struct.scm: New file.
* examples/xmlck.scm: New file.
* examples/expat-info.scm: New file.
* examples/Makefile.am, examples/README: Update.

* doc/expat.texi: Update.

10 files changed, 865 insertions, 145 deletions

diff --git a/doc/expat.texi b/doc/expat.texi
index e52a636..08b4137 100644
--- a/doc/expat.texi
+++ b/doc/expat.texi
@@ -4,8 +4,10 @@
 @c *******************************************************************
 @WRITEME
 
-The @samp{(gamma expat)} module provides interface with
+The @samp{(gamma expat)} module provides interface to
 @command{libexpat}, a library for parsing @acronym{XML} documents.
+See @uref{http://expat.sourceforge.net}, for a description of the
+library.
 
 Usage:
 
@@ -14,14 +16,130 @@ Usage:
 @end lisp
 
 @menu
-* primitives::             Expat Primitives
+* expat basics::
+* creating parsers::
+* parsing::
+* errors::
 * handlers::
 @end menu
 
-@node primitives
-@section Expat Primitives
+@node expat basics
+@section Expat Basics
+
+Parsing of @acronym{XML} documents using Expat is based on
+user-defined callback functions.  You create a @dfn{parser}
+object, and associate @dfn{callback} (or @dfn{handler}) functions with
+the events he is interested in.  Such events may be, for instance,
+encountering of a open or closing tag, encountering of a comment
+block, etc.  Once the parser object is ready, you start feeding the
+document to it.  As the parser recognizes @acronym{XML} constructs, it
+calls the callbacks that are registered for them.
+
+Parsers are created using @code{xml-make-parser} function.  In the
+simplest case, it takes no arguments, e.g.:
+
+@lisp
+(let ((parser (xml-make-parser)))
+  @dots{}
+@end lisp
+
+The function @code{xml-parse} takes the parser as its argument, reads
+the document from the current input stream and feeds it to the parser.
+Thus, the simplest program for parsing @acronym{XML} documents is:
+
+@lisp
+(use-modules ((gamma expat)))
+(xml-parse (xml-make-parser))
+@end lisp
+
+This program is perhaps not so useful, but you may already use it to
+check whether its input is a correctly formed @acronym{XML} document.
+If @code{xml-parse} encounters an error, it signals the
+@code{gamma-xml-error} error.  @xref{errors, error handling}, for a
+discussion on how to handle it.
+
+The @code{xml-make-parser} function takes optional arguments, which
+allow to set callback functions for the new parser.  For example, the
+following code sets function @samp{elt-start} as a handler for
+start elements:
+
+@lisp
+(xml-make-parser #:start-element-handler elt-start)
+@end lisp
+
+The @code{#:start-element-handler} keyword informs the function that
+the argument following it is a handler for start @acronym{XML} documents.
+Any number of handlers may be set this way, e.g.:
+
+@lisp
+(xml-make-parser #:start-element-handler elt-start
+                 #:end-element-handler elt-end
+                 #:comment-handler comment)
+@end lisp
+
+Definitions of particular handler functions differ depending on their
+purpose, i.e. on the event they are defined to handle.  For example,
+a start element handler must be defined as having two arguments.
+First of them is the name of the tag, and the second one is a list of
+attributes supplied for that tag.  Thus, for example, the following
+start handler prints the tag and the number of attributes:
+
+@lisp
+(define (elt-start name attrs)
+  (format #t "~A (~A)~%" name (length attrs)))
+@end lisp
+
+For a detailed description of all available handlers and handler
+keywords, see @ref{handlers}.
+
+To further improve our example, suppose you need a program that will
+take an @acronym{XML} document as its input and create a description
+of its structure on output, showing element nesting levels by
+indenting their description.  Here is how to write it.
+
+First, define handlers for start and end elements.  Start element
+handler will print two indenting spaces for each level of ancestor
+elements, followed by the element name and its attributes and a
+newline.  It will then increase the global level variable:
+
+@lisp
+(define level 0)
+
+(define (elt-start name attrs)
+  (display (make-string (* 2 level) #\space))
+  (display name)
+  (for-each
+   (lambda (x)
+    (display " ")
+    (display (car x))
+    (display "=")
+    (display (cdr x)))
+   attrs)
+  (newline)
+  (set! level (1+ level)))
+@end lisp
+
+The handler for end tags is simpler: it must only decrease the level:
+
+@lisp
+(define (elt-end name)
+  (set! level (1- level)))
+@end lisp
+  
+Finally, create a parser and parse the input:
+
+@lisp
+(xml-parse (xml-make-parser #:start-element-handler elt-start
+                            #:end-element-handler elt-end))
+@end lisp
+
+
+
+@node creating parsers
+@section Creating XML Parsers
 @WRITEME
 
+@anchor{xml-primitive-make-parser}
 @deffn {Scheme procedure} xml-primitive-make-parser enc sep
 Return a new @acronym{XML} parser. If @var{enc} is given, it must be one of:
 @samp{US-ASCII}, @samp{UTF-8}, @samp{UTF-16}, @samp{ISO-8859-1}.  If @var{sep}
@@ -63,23 +181,6 @@ and to:
 @end lisp
 @end deffn
 
-@deffn {Scheme procedure} xml-primitive-parse parser input isfinal
-Parse next piece of input.  Arguments are:
-
-@table @var
-@item parser
-A parser returned from a previous call to
-@code{xml-primitive-make-parser} or @code{xml-make-parser}.
-
-@item input
-A piece of input text.
-
-@item isfinal
-Boolean value indicating whether @var{input} is the last part of
-input.
-@end table
-@end deffn
-
 @deffn {Scheme procedure} xml-primitive-set-handler parser key handler
 Set @acronym{XML} handler for an event.  Arguments are:
 
@@ -87,90 +188,77 @@ Set @acronym{XML} handler for an event.  Arguments are:
 @item parser
 A valid @acronym{XML} parser
 
+@anchor{handler-keyword}
 @item key
-A key, identifying an event.
-
-@table @asis
-@kwindex start-element-handler
-@item #:start-element-handler
-
-@kwindex end-element-handler
-@item #:end-element-handler
-
-@kwindex character-data-handler
-@item #:character-data-handler
-
-@kwindex processing-instruction-handler
-@item #:processing-instruction-handler
-
-@kwindex comment-handler
-@item #:comment-handler
-
-@kwindex start-cdata-section-handler
-@item #:start-cdata-section-handler
+A key, identifying the event.  For example,
+@samp{#:start-element-handler} sets handler which is called for start
+tags.
 
-@kwindex end-cdata-section-handler
-@item #:end-cdata-section-handler
+@xref{handlers}, for its values and their meaning.
 
-@kwindex default-handler
-@item #:default-handler
-
-@kwindex default-handler-expand
-@item #:default-handler-expand
-
-@kwindex external-entity-ref-handler
-@item #:external-entity-ref-handler
-
+@item handler
+Handler procedure.
+@end table