Finish the docs.

6 files changed, 744 insertions, 27 deletions

diff --git a/doc/Config b/doc/Config
new file mode 100644
index 0000000..8bd4c7e
--- /dev/null
+++ b/doc/Config
@@ -0,0 +1,364 @@
+# Texi2html configuration for Gamma documentation. -*- perl -*-
+# Copyright (C) 2009, 2010 Sergey Poznyakoff
+#
+# Gamma is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3, or (at your option)
+# any later version.
+#
+# Gamma is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Gamma.  If not, see <http://www.gnu.org/licenses/>.
+
+$top_html_dir="/software/gamma";
+$graphics_dir="$top_html_dir/graphics";
+
+## texi2html configuration
+
+# Show TOC in place of the @contents directive.
+$INLINE_CONTENTS = 1;
+# Do not show Texinfo menus.
+$SHOW_MENU = 0;
+# Inhibit output of CSS lines in page headers.
+$CSS_LINES='';
+# Print footnotes at the end of each file (if the document is split).
+$SEPARATED_FOOTNOTES = 0;    
+
+$BODYTEXT = "";
+
+$EXTRA_HEAD=qq{
+  <link rev="made" href="mailto:gray@gnu.org.ua">
+  <link rel="stylesheet" type="text/css" href="${top_html_dir}/gray.css">
+  <link rel="stylesheet" type="text/css" href="${top_html_dir}/texi.css">
+  <link rel="icon" type="image/png" href="/graphics/gnu-head-icon.png">};
+
+$AFTER_BODY_OPEN=qq{
+<!--#include virtual="${top_html_dir}/inc/header.html" -->
+<ul class="tabs">
+  <li><a href="${top_html_dir}/gamma.html">Main</a></li>
+  <li><a href="${top_html_dir}/download.html">Downloads</a></li>
+  <li><a class="active" href="${top_html_dir}/manual.html">Documentation</a></li>
+</ul>};
+
+$PRE_BODY_CLOSE="Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.";
+    
+$format_map{'multitable'}='table class="multitable"';
+
+$SMALL_RULE = '';
+$DEFAULT_RULE = '';
+$MIDDLE_RULE = '';
+# This is output at the end of a section.
+$BIG_RULE = '';
+
+# Use navigation icons
+$ICONS = 1;
+%ACTIVE_ICONS =
+    (
+     'Top',         "$graphics_dir/top.png",
+     'Contents',    "$graphics_dir/ctx.png",
+     'Overview',    '',
+     'Index',       "$graphics_dir/idx.png",
+     'This',        '',
+     'Back',        "$graphics_dir/left.png",
+     'FastBack',    "$graphics_dir/bwd.png",
+     'Prev',        "",
+     'Up',          "$graphics_dir/up.png",
+     'Next',        "$graphics_dir/right.png",
+     'NodeUp',      "$graphics_dir/left.png", 
+     'NodeNext',    "$graphics_dir/up.png",   
+     'NodePrev',    "$graphics_dir/right.png",
+     'Following',   "$graphics_dir/right.png",
+     'Forward',     "$graphics_dir/right.png",
+     'FastForward', "$graphics_dir/fwd.png",
+     'About' ,      '',
+     'First',       '',
+     'Last',        '',
+     ' ',           ''
+    );
+
+@SECTION_BUTTONS =
+    (
+     \&gray_document_title,
+     \&gray_sec_ref,
+     'Back', 'Forward',
+     \&gray_chap_ref, 'FastBack', 'Up', 'FastForward',
+     \&gray_doc_ref,
+     'Contents', 'Index',
+     ' ','About',
+    );
+
+@SECTION_FOOTER_BUTTONS = @SECTION_BUTTONS;
+@NODE_FOOTER_BUTTONS = @SECTION_BUTTONS;
+
+# buttons for misc stuff
+@MISC_BUTTONS = (
+    \&gray_document_title,
+    'Contents',
+    'Index',
+    ' ',
+    'About'
+    );
+
+
+$print_section = \&gray_print_section;
+$print_navigation = \&gray_print_navigation;
+$print_head_navigation = \&gray_print_head_navigation;
+$print_foot_navigation = \&gray_print_foot_navigation;
+$print_About	      = \&gray_print_About;
+$cell = \&gray_multitable_cell;
+$print_page_foot = \&gray_print_page_foot;
+    
+sub gray_multitable_cell($$)
+{
+    my $text = shift;
+    my $row_macro = shift;
+
+    $text =~ s/<p>//;
+    $text =~ s/<\/p>//;
+    if ($row_macro eq 'headitem')
+    {
+        return '<th>' . $text . '</th>';
+    }
+    return '<td>' . $text . '</td>';
+}
+
+sub gray_print_About
+{
+    return &$print_misc(@_) if (!($SPLIT eq '') or $SECTION_NAVIGATION);
+}
+
+sub gray_split_status()
+{
+    if ($SPLIT eq '') {
+	return '';
+    } elsif ($SPLIT eq 'node') {
+	return ' <span class="splitstatus">(split by node)</span>';
+    } elsif ($SPLIT eq 'section') {
+	return ' <span class="splitstatus">(split by section)</span>';
+    } elsif ($SPLIT eq 'chapter') {
+	return ' <span class="splitstatus">(split by chapter)</span>';
+    }
+}
+
+sub gray_document_title($$)
+{
+    my $fh = shift;
+    my $vertical = shift;
+    my $status = gray_split_status();
+    print $fh qq{<td class="title">} . $Texi2HTML::THISDOC{title} . $status . ":</td>\n";
+}
+
+sub gray_node_ref($$)
+{
+    my $fh = shift;
+    my $vertical = shift;
+    print $fh qq{<span class="navtext">Node:</span>};
+}
+
+sub gray_sec_ref($$)
+{
+    my $fh = shift;
+    my $vertical = shift;
+    print $fh qq{<span class="navtext">Section:</span>};
+}
+
+sub gray_chap_ref($$)
+{
+    my $fh = shift;
+    my $vertical = shift;
+    print $fh qq{<span class="navtext">Chapter:</span>};
+}
+
+sub gray_doc_ref($$)
+{
+    my $fh = shift;
+    my $vertical = shift;
+    print $fh qq{<span class="navtext">Doc:</span>};
+}
+
+sub gray_print_navigation
+{
+    my $fh = shift;
+    my $buttons = shift;
+    my $vertical = shift;
+    my $spacing = 1;
+    my $class="nav";
+
+    print $fh qq{<table class="nav">\n};
+
+    print $fh "<tr>" unless $vertical;
+    for my $button (@$buttons)
+    {
+	if ($button =~ /^\@class=(.*)/) {
+	    $class = "$class $1";
+	    next;
+	}
+        print $fh "<tr>\n" if $vertical;
+        print $fh qq{<td class="$class">};
+
+        if (ref($button) eq 'CODE')
+        {
+            &$button($fh, $vertical);
+        }
+        elsif (ref($button) eq 'SCALAR')
+        {
+            print $fh "$$button" if defined($$button);
+        }
+        elsif (ref($button) eq 'ARRAY')
+        {
+            my $text = $button->[1];
+            my $button_href = $button->[0];
+            # verify that $button_href is simple text and text is a reference
+            if (defined($button_href) and !ref($button_href) 
+               and defined($text) and (ref($text) eq 'SCALAR') and defined($$text))
+            {             # use given text
+                if ($Texi2HTML::HREF{$button_href})
+                {
+                  print $fh "" .
+                        &$anchor('',
+                                    $Texi2HTML::HREF{$button_href},
+                                    $$text
+                                   ) 
+                                    ;
+                }
+                else
+                {
+                  print $fh $$text;
+                }
+            }
+        }
+        elsif ($button eq ' ')
+        {                       # handle space button
+            print $fh
+                ($ICONS && $ACTIVE_ICONS{' '}) ?
+                    &$button_icon_img($BUTTONS_NAME{$button}, $ACTIVE_ICONS{' '}) :
+                        $NAVIGATION_TEXT{' '};
+            #next;
+        }
+        elsif ($Texi2HTML::HREF{$button})
+        {                       # button is active
+            my $btitle = $BUTTONS_GOTO{$button} ?
+                'title="' . $BUTTONS_GOTO{$button} . '"' : '';
+            if ($ICONS && $ACTIVE_ICONS{$button})
+            {                   # use icon
+                print $fh '' .
+                    &$anchor('',
+                        $Texi2HTML::HREF{$button},
+                        &$button_icon_img($BUTTONS_NAME{$button},
+                                   $ACTIVE_ICONS{$button},
+                                   $Texi2HTML::SIMPLE_TEXT{$button}),
+                        $btitle
+                      );
+            }
+            else
+            {                   # use text
+                print $fh
+                    '' .
+                        &$anchor('',
+                                    $Texi2HTML::HREF{$button},
+                                    $NAVIGATION_TEXT{$button},
+                                    $btitle
+                                   );
+            }
+        }
+        else {                       # button is passive
+            print $fh '<span class="passive">' .
+                ($ICONS && $PASSIVE_ICONS{$button} ?
+                    &$button_icon_img($BUTTONS_NAME{$button},
+                                          $PASSIVE_ICONS{$button},
+                                          $Texi2HTML::SIMPLE_TEXT{$button}) :
+
+                                          $NAVIGATION_TEXT{$button}) . '</span>';
+        }
+        print $fh "</td>\n";
+        print $fh "</tr>\n" if $vertical;
+	$class = "nav";
+    }
+    print $fh "</tr>" unless $vertical;
+    print $fh "</table>\n";
+}
+
+sub gray_print_head_navigation($$)
+{
+    my $fh = shift;
+    my $buttons = shift;
+
+    return if ($SPLIT eq '');
+    if ($VERTICAL_HEAD_NAVIGATION)
+    {
+        print $fh <<EOT;
+<table class='nav'>
+<tr>
+<td>
+EOT
+    }
+    main::print_lines($fh, $Texi2HTML::THIS_HEADER);
+    &$print_navigation($fh, $buttons, $VERTICAL_HEAD_NAVIGATION);
+    if ($VERTICAL_HEAD_NAVIGATION)
+    {
+        print $fh <<EOT;
+</td>
+<td>
+EOT
+    }
+}
+
+sub gray_print_foot_navigation
+{
+    my $fh = shift;
+
+    return if ($SPLIT eq '');
+    if ($VERTICAL_HEAD_NAVIGATION)
+    {
+        print $fh <<EOT;
+</td>
+</tr>
+</table>
+EOT
+    }
+}
+
+sub gray_print_page_foot($)
+{
+    my $fh = shift;
+    my $program_string = program_string();
+    print $fh <<EOT;
+<div class="copyright">
+$program_string
+EOT
+    if (defined($PRE_BODY_CLOSE) && $PRE_BODY_CLOSE) {
+	print $fh "<p>$PRE_BODY_CLOSE</p>";
+    }
+    print $fh <<EOT;
+</div>
+</body>
+</html>
+EOT
+}
+
+sub gray_print_section
+{
+    my $fh = shift;
+    my $first_in_page = shift;
+    my $previous_is_top = shift;
+    my $buttons = \@SECTION_BUTTONS;
+
+    if ($first_in_page) {
+	&$print_head_navigation($fh, $buttons)
+    } else {
+	main::print_lines($fh, $Texi2HTML::THIS_HEADER);
+    }
+    my $nw = main::print_lines($fh);
+    if (defined $SPLIT
+        and ($SPLIT eq 'node')) {
+        &$print_foot_navigation($fh);
+        print $fh "$SMALL_RULE\n";
+        &$print_navigation($fh, \@NODE_FOOTER_BUTTONS) if (!defined($WORDS_IN_PAGE) or (defined ($nw)
+                                    and $nw >= $WORDS_IN_PAGE));
+    }
+}
+
diff --git a/doc/expat.texi b/doc/expat.texi
index 08b4137..993c1f2 100644
--- a/doc/expat.texi
+++ b/doc/expat.texi
@@ -2,8 +2,9 @@
 @c Copyright (C) 2010 Sergey Poznyakoff
 @c See gamma.texi for copying conditions.
 @c *******************************************************************
-@WRITEME
-
+@cindex XML
+@cindex Expat
+@cindex libexpat
 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
@@ -21,11 +22,14 @@ Usage:
 * parsing::
 * errors::
 * handlers::
+* miscellaneous functions::
 @end menu
 
 @node expat basics
 @section Expat Basics
-
+@cindex expat, basics
+@cindex callback, expat
+@cindex handlers, expat
 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
@@ -35,6 +39,7 @@ 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.
 
+@cindex parser, creating
 Parsers are created using @code{xml-make-parser} function.  In the
 simplest case, it takes no arguments, e.g.:
 
@@ -47,6 +52,8 @@ 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:
 
+@flindex xmlck.scm, example
+@anchor{xmlck.scm}
 @lisp
 (use-modules ((gamma expat)))
 (xml-parse (xml-make-parser))
@@ -58,6 +65,7 @@ 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.
 
+@cindex handlers, expat
 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
@@ -133,11 +141,15 @@ Finally, create a parser and parse the input:
                             #:end-element-handler elt-end))
 @end lisp
 
-
-
 @node creating parsers
 @section Creating XML Parsers
-@WRITEME
+@cindex parsers, XML, creating
+Gamma provides several functions for creating and modifying
+@acronym{XML} parsers.  The @code{xml-primitive-make-parser} and
+@code{xml-primitive-set-handler} are lower level interfaces, provided
+for those who wish to further extend Gamma functionality. Higher level
+interfaces are @code{xml-make-parser} and @code{xml-set-handler} which
+we recommend for regular users.
 
 @anchor{xml-primitive-make-parser}
 @deffn {Scheme procedure} xml-primitive-make-parser enc sep
@@ -275,18 +287,192 @@ is equivalent to:
 @end lisp
 @end deffn
 
-@deffn {Scheme function} xml-parse parser
-Reads @acronym{XML} input from the standard input port and parses it
-using @code{xml-primitive-parse}.
+@deffn {Scheme function} xml-parse parser [port]
+Reads @acronym{XML} input from @var{port} (or the standard input port,
+if it is not given) and parses it using @code{xml-primitive-parse}.
 @end deffn
 
 @node errors
 @section Error Handling
-@WRITEME
+@cindex xml error handling
+@cindex error handling, @acronym{XML}
+When encountering an error. the @samp{gamma xml} functions use
+Guile error reporting mechanism (@pxref{Error Reporting,
+Procedures for Signaling Errors,,guile,The Guile Reference Manual}).
+The @dfn{error key} indicates what type of error it was, and the
+rest of arguments supply additional information about the error.
+Recommended ways for handling errors in Guile are described in
+@ref{Handling Errors, How to Handle Errors,,guile,The Guile Reference
+Manual}). In this chapter we will describe how to handle errors
+in @acronym{XML} input and other errors reported by the underlying
+@file{libexpat} library.
+
+@defvr {Error Key} gamma-xml-error
+An error of this type is signalled when a of @samp{gamma xml}
+functions encounters an @acronym{XML}-related error.
+@end defvr
+
+The arguments supplied with this error are:
+
+@table @asis
+@item key
+The error key (@code{gamma-xml-error}).
+
+@item func
+Name of the function that generated the error.
+
+@item fmt
+Format string
+
+@item fmt-args
+Arguments for @samp{fmt}.
+
+@item descr
+Error description.  If there are no additional information, it is
+@code{#f}.  Otherwise it is a list of 5 elements which describes the
+error and its location in the input stream:
+
+@enumerate 0
+@item
+Error code (number).
+
+@item
+Line number (starts at 1).
+
+@item
+Column number (starts at 0).
+
+@item
+Context in which the error occured, i.e. a part of the input text
+which was found to contain the error.
+
+@item
+Offset of point that caused the error within the context.
+@end enumerate
+@end table
+
+A special syntax is provided to extract parts of the @samp{descr}
+list:
+
+@deffn {Gamma Syntax} xml-error-descr descr key
+Extract from @var{descr} the part identified by @var{key}.  Use
+this macro in the error handlers.  Valid values for @var{key} are:
+
+@defvr {xml-error-descr key} #:error-code
+Return the error code.
+@end defvr
+
+@defvr {xml-error-descr key} #:line
+Return line number.
+@end defvr
+
+@defvr {xml-error-descr key} #:column
+Return column number.
+@end defvr
+
+@defvr {xml-error-descr key} #:has-context?
+Return @code{#t} if the description has context part.  Use the two
+keywords below only if
+
+@lisp
+(xml-error-descr d #:has-context?
+@end lisp
+
+@noindent
+returned @code{#t}.
+@end defvr
+
+@defvr {xml-error-descr key} #:context
+Return context string.
+@end defvr
+
+@defvr {xml-error-descr key} #:error-offset
+Return the location within @code{#:context} where the error occurred.
+@end defvr
+@end deffn
+
+If no special handler is set, the default @command{guile} error
+handler displays the error and its approximate location on the
+standard error port.  For example, given the following input file:
+
+@example
+@group
+$ cat input.xml
+<input>
+ <ref a=1/>
+</input>
+@end group
+@end example
+
+@noindent
+the @file{xmlck.scm} (@pxref{xmlck.scm}) produces:
+
+@example
+@group
+$ guile -s examples/xmlck.scm < input.xml
+ERROR: In procedure xml-primitive-parse:
+ERROR: not well-formed (invalid token) near line 2
+@end group
+@end example
+
+@anchor{catching gamma-xml-error}
+To provide a more detailed diagnostics, catch the
+@code{gamma-xml-error} code and use information from the @samp{descr}
+list.  For example:
+
+@lisp
+(catch 'gamma-xml-error
+       (lambda ()
+	 (xml-parse (xml-make-parser)))
+       (lambda (key func fmt args descr)
+	 (with-output-to-port
+	     (current-error-port)
+	   (lambda ()
+	     (cond
+	      ((not descr)
+	       (apply format #t fmt args)
+	       (newline))
+	      (else
+	       (format #t
+		       "~A:~A: ~A~%"
+		       (xml-error-descr descr #:line)
+		       (xml-error-descr descr #:column)
+		       (xml-error-string (xml-error-descr descr #:error-code)))
+	       (if (xml-error-descr descr #:has-context?)
+		   (let ((ctx-text (xml-error-descr descr #:context))
+			 (ctx-pos  (xml-error-descr descr #:error-offset)))
+		     (format #t
+			     "Context (^ marks the point): ~A^~A~%"
+			     (substring ctx-text 0 ctx-pos)
+			     (substring ctx-text ctx-pos))))
+	       (exit 1)))))))
+@end lisp
+
+When applied to the same input document as in the previous example,
+this code produces:
+
+@example
+@group
+$ guile -s examples/xml-check.scm < input.xml
+2:8: not well-formed (invalid token)
+Context (^ marks the point): <input>
+ <ref a=^1/>
+
+@end group
+@end example
 
 @node handlers
 @section Expat Handlers
-@WRITEME
+@cindex handlers, expat
+@cindex callbacks, expat
+This section describes all available element handlers.  For clarity,
+each handler is described in its own subsection.  For each handler, we
+indicate a @dfn{keyword} that is used when registering this
+handler and the @dfn{handler prototype}.
+
+To register handlers, use @code{xml-make-parser} or
+@code{xml-set-handler} functions.  @xref{creating parsers}, for a
+detailed discussion of these functions.
 
 @menu
 * start-element-handler::
@@ -312,7 +498,8 @@ using @code{xml-primitive-parse}.
 
 @node start-element-handler
 @subsection start-element-handler
-
+@cindex start element handler
+@cindex handler, start element
 @defvr {Handler Keyword} #:start-element-handler
 Sets handler for start (and empty) tags. 
 @end defvr
@@ -334,7 +521,8 @@ A list of element attributes.  Each attribute is represented by a cons
 
 @node end-element-handler
 @subsection end-element-handler
-
+@cindex end element handler
+@cindex handler, end element
 @defvr {Handler Keyword} #:end-element-handler
 Sets handler for end (and empty) tags.  An empty tag generates a call
 to both start and end handlers (in that order).
@@ -353,7 +541,8 @@ Element name
 
 @node character-data-handler
 @subsection character-data-handler
-
+@cindex character data handler
+@cindex handler, character data
 @defvr {Handler Keyword} #:character-data-handler
 Sets a text handler. A single block of contiguous text free of markup
 may result in a sequence of calls to this handler. So, if you are
@@ -374,6 +563,8 @@ The text.
 
 @node processing-instruction-handler
 @subsection processing-instruction-handler
+@cindex processing instruction handler
+@cindex handler, processing instruction
 
 @defvr {Handler Keyword} #:processing-instruction-handler
 Set a handler for @dfn{processing instructions}.
@@ -408,6 +599,8 @@ The text inside the comment delimiters.
 
 @node start-cdata-section-handler
 @subsection start-cdata-section-handler
+@cindex start cdata section handler
+@cindex handler, start cdata section
 
 @defvr {Handler Keyword} #:start-cdata-section-handler
 Sets a handler that gets called at the beginning of a CDATA section.
@@ -420,6 +613,8 @@ The handler is defined as follows:
 
 @node end-cdata-section-handler
 @subsection end-cdata-section-handler
+@cindex end cdata section handler
+@cindex handler, end cdata section
 
 @defvr {Handler Keyword} #:end-cdata-section-handler
 Sets a handler that gets called at the end of a CDATA section.
@@ -432,6 +627,8 @@ The handler is defined as:
 
 @node default-handler
 @subsection default-handler
+@cindex default handler
+@cindex handler, default
 
 @defvr {Handler Keyword} #:default-handler
 Sets a handler for any characters in the document which wouldn't
@@ -458,6 +655,8 @@ are passed to the default handler verbatim.
 
 @node default-handler-expand
 @subsection default-handler-expand
+@cindex default handler, with expansion
+@cindex handler, default, with expansion
 
 @defvr {Handler Keyword} #:default-handler-expand
 This sets a default handler as above, but does not inhibit the
@@ -469,6 +668,8 @@ The handler prototype is the same as in @ref{default-handler}.
 
 @node skipped-entity-handler
 @subsection skipped-entity-handler
+@cindex skipped entity handler
+@cindex handler, skipped entity
 
 @defvr {Handler Keyword} #:skipped-entity-handler
 Set a skipped entity handler, i.e. a handler which is called if:
@@ -496,6 +697,8 @@ otherwise.
 
 @node start-namespace-decl-handler
 @subsection start-namespace-decl-handler
+@cindex start namespace declaration handler
+@cindex handler, start namespace declaration
 
 @defvr {Handler Keyword} #:start-namespace-decl-handler
 Set a handler to be called when a namespace is declared.
@@ -515,6 +718,8 @@ Namespace @acronym{URI}.
 
 @node end-namespace-decl-handler
 @subsection end-namespace-decl-handler
+@cindex end namespace declaration handler
+@cindex handler, end namespace declaration
 
 @defvr {Handler Keyword} #:end-namespace-decl-handler
 Set a handler to be called when leaving the scope of a namespace
@@ -530,6 +735,8 @@ The handler prototype is:
 
 @node xml-decl-handler
 @subsection xml-decl-handler
+@cindex @acronym{XML} declaration handler
+@cindex handler, @acronym{XML} declaration
 
 @defvr {Handler Keyword} #:xml-decl-handler
 Sets a handler that is called for @acronym{XML} declarations and also
@@ -555,6 +762,8 @@ it was given as @samp{yes} or @samp{no}.
 
 @node start-doctype-decl-handler
 @subsection start-doctype-decl-handler
+@cindex start doctype declaration handler
+@cindex handler, start doctype declaration
 
 @defvr {Handler Keyword} #:start-doctype-decl-handler
 Set a handler that is called at the start of a @samp{DOCTYPE} declaration,
@@ -583,6 +792,8 @@ Public @acronym{ID}.  May be @code{#f}.
 
 @node end-doctype-decl-handler
 @subsection end-doctype-decl-handler
+@cindex end doctype declaration handler
+@cindex handler, end doctype declaration
 
 @defvr {Handler Keyword} #:end-doctype-decl-handler
 Set a handler that is called at the end of a @samp{DOCTYPE}
@@ -596,6 +807,8 @@ The handler takes no arguments:
 
 @node attlist-decl-handler
 @subsection attlist-decl-handler
+@cindex attlist declaration handler
+@cindex handler, attlist declaration
 
 @defvr {Handler Keyword} #:attlist-decl-handler
 Sets a handler for @samp{attlist} declarations in the
@@ -625,6 +838,8 @@ is a @samp{#IMPLIED} attribute.
 
 @node entity-decl-handler
 @subsection entity-decl-handler
+@cindex entity declaration handler
+@cindex handler, entity declaration
 
 @defvr {Handler Keyword} #:entity-decl-handler
 Sets a handler that will be called for all entity declarations.
@@ -668,6 +883,8 @@ Notation name, for unparsed entity declarations.  Otherwise,
 
 @node notation-decl-handler
 @subsection notation-decl-handler
+@cindex notation declaration handler
+@cindex handler, notation declaration
 
 @defvr {Handler Keyword} #:notation-decl-handler
 Sets a handler that receives notation declarations.
@@ -681,6 +898,8 @@ Handler prototype is:
 
 @node not-standalone-handler
 @subsection not-standalone-handler
+@cindex not standalone document handler
+@cindex handler, not standalone document
 
 @defvr {Handler Keyword} #:not-standalone-handler
 Sets a handler that is called if the document is not @dfn{standalone}, i.e.
@@ -694,3 +913,53 @@ The handler takes no arguments:
 @deffn {Handler prototype} not-standalone 
 @end deffn
 
+@node miscellaneous functions
+@section miscellaneous functions
+
+@deffn {Scheme function} xml-expat-version-string
+Return the version of the expat library as a string.
+
+For example:
+
+@lisp
+(xml-expat-version-string) @result{} "expat_2.0.1"
+@end lisp
+@end deffn
+
+@deffn {Scheme function} xml-expat-version
+Return the version of the expat library as a triplet: @samp{(major
+minor micro)}.
+
+For example:
+@lisp
+(xml-expat-version) @result{} (2 0 1)
+@end lisp
+@end deffn
+
+@deffn {Scheme function} xml-default-current
+Pass current markup to the default handler (@pxref{default-handler}).
+This function may be called only from a callback handler.
+@end deffn
+
+@deffn {Scheme function} xml-error-string code)
+Return a textual description corresponding to the @var{code} argument.
+@xref{catching gamma-xml-error}, for an example of using this
+function.
+@end deffn
+
+@deffn {Scheme function} xml-current-line-number parser
+Return number of the current input line in @var{parser}.  Input lines
+are numbered from @samp{1}.
+@end deffn
+
+@deffn {Scheme function} xml-current-column-number parser
+Return number of column in the current input line.
+@end deffn
+
+@deffn {Scheme function} xml-current-byte-count parser
+Return the number of bytes in the current event.  Returns @samp{0} if
+the event is inside a reference to an internal entity and for the
+end-tag event for empty element tags (the later can be used to
+distinguish empty-element tags from empty elements using separate
+start and end tags).  
+@end deffn
diff --git a/doc/gamma.texi b/doc/gamma.texi
index 8f5b67e..79c53d4 100644
--- a/doc/gamma.texi
+++ b/doc/gamma.texi
@@ -12,10 +12,12 @@
 
 @defcodeindex op
 @defcodeindex kw
+@defcodeindex fl
 @syncodeindex fn cp
 @syncodeindex pg cp
 @syncodeindex op cp
 @syncodeindex kw cp
+@syncodeindex fl cp
 
 @ifinfo
 @dircategory Guile modules
@@ -74,15 +76,50 @@ Appendices
 * Copying This Manual::  The GNU Free Documentation License.
 * Concept Index::        Index of Concepts.
 
-@c @detailmenu
-@c  --- The Detailed Node Listing ---
-@c @end detailmenu
-
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Expat Interface
+
+* expat basics::
+* creating parsers::
+* parsing::
+* errors::
+* handlers::
+* miscellaneous functions::
+
+Expat Handlers
+
+* start-element-handler::
+* end-element-handler::
+* character-data-handler::
+* processing-instruction-handler::
+* comment-handler::
+* start-cdata-section-handler::
+* end-cdata-section-handler::
+* default-handler::
+* default-handler-expand::
+* skipped-entity-handler::
+* start-namespace-decl-handler::
+* end-namespace-decl-handler::
+* xml-decl-handler::
+* start-doctype-decl-handler::
+* end-doctype-decl-handler::
+* attlist-decl-handler::
+* entity-decl-handler::
+* notation-decl-handler::
+* not-standalone-handler::
+
+@end detailmenu
 @end menu
 
 @node Overview
 @chapter Overview
-@WRITEME
+
+@GAMMA{} is a collection of assorted Guile modules.  Version
+@value{VERSION} provides a @samp{syslog} interface, a module for
+interfacing with @acronym{SQL} (more precisely: MySQL and PostgreSQL)
+databases and a module for writing @acronym{XML} parsers,
 
 @node Syslog
 @chapter Syslog Interface
diff --git a/doc/sql.texi b/doc/sql.texi
index 5a35fdd..bca15a0 100644
--- a/doc/sql.texi
+++ b/doc/sql.texi
@@ -2,7 +2,9 @@
 @c Copyright (C) 2010 Sergey Poznyakoff
 @c See gamma.texi for copying conditions.
 @c *******************************************************************
-
+@cindex SQL
+@cindex MySQL
+@cindex PostgreSQL
 The @samp{(gamma sql)} module provides interface with MySQL and
 PostfeSQL database management systems. 
 
@@ -13,6 +15,7 @@ Usage:
 @end lisp
 
 @deffn {Scheme procedure} sql-open-connection params
+@cindex connection to @acronym{SQL}, opening
 This function opens a connection to the @acronym{SQL}
 server and returns a connection object. This object is
 then used as argument to @code{sql-query} and
@@ -58,6 +61,7 @@ Sets the database name.
 @end defvr
 
 @defvr {Keyword} #:ssl-cert
+@cindex @acronym{SSL}, using with @acronym{SQL}
 Defines full pathname of the @acronym{SSL} certificate to use.  If
 this keyword is present, the connection with the server will be
 encrypted using @acronym{SSL}.
@@ -66,6 +70,8 @@ Currently it is implemented only for MySQL connections.
 @end defvr
 
 @defvr {Keyword} #:config-file
+@cindex config file, MySQL
+@cindex option file, MySQL
 Use the specified MySQL configuration file to obtain missing parameters.
 @end defvr
 
@@ -73,16 +79,17 @@ Use the specified MySQL configuration file to obtain missing parameters.
 Obtain missing parameters from the specified group in the MySQL
 configuration file (see @samp{#:config-file}, above).
 @end defvr
-
 @end deffn
 
 @deffn {Scheme procedure} sql-close-connection conn
+@cindex connection to @acronym{SQL}, closing
 Close the @acronym{SQL} connection.  The @var{conn} must be a
 connection descriptor returned from a previous call to
 @code{sql-open-connection}.
 @end deffn
 
 @deffn {Scheme procedure} sql-query conn query
+@cindex query, @acronym{SQL}
 @var{Conn} is a connection descriptor returned from a previous call to
 @code{sql-open-connection}, and @var{query} is a valid @acronym{SQL}
 query.  This function executes the query and returns its results.
diff --git a/doc/syslog.texi b/doc/syslog.texi
index 879ea04..ad9e657 100644
--- a/doc/syslog.texi
+++ b/doc/syslog.texi
@@ -2,7 +2,7 @@
 @c Copyright (C) 2010 Sergey Poznyakoff
 @c See gamma.texi for copying conditions.
 @c *******************************************************************
-
+@cindex syslog
 The @samp{(gamma syslog)} module provides bindings for @samp{syslog}
 functions:
 
@@ -23,47 +23,74 @@ Flags that control the operation.  A logical or (@code{logior}) of
 one or more of the following:
 
 @table @asis
+@kwindex LOG_CONS
 @item LOG_CONS
 Write directly to system console if there is an error while sending to
 system logger.
 
+@kwindex LOG_NDELAY
 @item LOG_NDELAY
 Open the connection immediately (normally, the opening is delayed
 until when the first message is logged).
 
+@kwindex LOG_NOWAIT
 @item LOG_NOWAIT
 Don't wait for child processes that may have been created while
 logging the message.
 
+@kwindex LOG_ODELAY
 @item LOG_ODELAY
 The converse of @samp{LOG_NDELAY}; opening of the connection is
 delayed until @code{syslog} is called.  This is the default.
 
+@kwindex LOG_PERROR
 @item LOG_PERROR
 Print to stderr as well.  This constant may be absent if the
 underlying implementation does not support it.
 
+@kwindex LOG_PID
 @item LOG_PID
 Include PID with each message.
 @end table
 
+@cindex facility, syslog
+@cindex syslog facility
 @item facility
 Specifies what type of program is logging  the  message.
 The facility must be one of:
 
 @multitable @columnfractions 0.3 0.7
 @headitem Facility @tab Meaning
+@kwindex LOG_AUTH
 @item LOG_AUTH      @tab Security/authorization messages.
+@kwindex LOG_AUTHPRIV
 @item LOG_AUTHPRIV  @tab Same as @code{LOG_AUTH}.
+@kwindex LOG_CRON
 @item LOG_CRON      @tab Clock daemon.
+@kwindex LOG_DAEMON
 @item LOG_DAEMON    @tab System daemons without separate facility value.
+@kwindex LOG_FTP
 @item LOG_FTP       @tab @acronym{FTP} daemon.
+@kwindex LOG_LOCAL0
+@kwindex LOG_LOCAL1
+@kwindex LOG_LOCAL2
+@kwindex LOG_LOCAL3
+@kwindex LOG_LOCAL4
+@kwindex LOG_LOCAL5
+@kwindex LOG_LOCAL6
+@kwindex LOG_LOCAL7
 @item LOG_LOCAL0 through LOG_LOCAL7 @tab Reserved for local use.
+@kwindex LOG_LPR
 @item LOG_LPR       @tab Line printer subsystem.
+@kwindex LOG_MAIL
 @item LOG_MAIL      @tab Mail subsystem.
+@kwindex LOG_NEWS
 @item LOG_NEWS      @tab @acronym{USENET} news subsystem.
+@kwindex LOG_SYSLOG
 @item LOG_SYSLOG    @tab Messages generated internally by @command{syslogd}.
+@kwindex LOG_USER
 @item LOG_USER      @tab Generic user-level messages.  This is the default.