Extensive changes by AMK.

Doc/lib/libgdbm.tex

@@ -1,8 +1,81 @@
 \section{Built-in Module \sectcode{gdbm}}
+\label{module-gdbm}
 \bimodindex{gdbm}
 
-This module is nearly identical to the \code{dbm} module, but uses
-GDBM instead.  Its interface is identical, and not repeated here.
-
-Warning: the file formats created by gdbm and dbm are incompatible.
+This module is quite similar to the \code{dbm} module, but uses {\sc gdbm}
+instead to provide some additional functionality.  Please note that
+the file formats created by {\sc gdbm} and dbm are incompatible.
 \bimodindex{dbm}
+
+The \code{gdbm} module provides an interface to the GNU DBM
+library.  {\sc gdbm} objects behave like mappings
+(dictionaries), except that keys and values are always strings.
+Printing a {\sc gdbm} object doesn't print the keys and values, and the
+\code{items()} and \code{values()} methods are not supported.
+
+The module defines the following constant and functions:
+
+\renewcommand{\indexsubitem}{(in module dbm)}
+\begin{excdesc}{error}
+Raised on dbm-specific errors, such as I/O errors. \code{KeyError} is
+raised for general mapping errors like specifying an incorrect key.
+\end{excdesc}
+
+\begin{funcdesc}{open}{filename\, \optional{flag\, \optional{mode}}}
+Open a dbm database and return a dbm object.  The \var{filename}
+argument is the name of the database file (without the \file{.dir} or
+\file{.pag} extensions).
+
+The optional \var{flag} argument can be
+\code{'r'} (to open an existing database for reading only --- default),
+\code{'w'} (to open an existing database for reading and writing),
+\code{'c'} (which creates the database if it doesn't exist), or
+\code{'n'} (which always creates a new empty database).
+
+Appending \code{f} to the flag opens the database in fast mode;
+altered data will not automatically be written to the disk after every
+change.  This results in faster writes to the database, but may result
+in an inconsistent database if the program crashes while the database
+is still open.  Use the \code{sync()} method to force any unwritten
+data to be written to the disk.
+
+The optional \var{mode} argument is the \UNIX{} mode of the file, used
+only when the database has to be created.  It defaults to octal
+\code{0666}.
+\end{funcdesc}
+
+In addition to the dictionary-like methods, {\sc gdbm} objects have the
+following methods:
+
+\begin{funcdesc}{firstkey}{}
+It's possible to loop over every key in the database using this method
+and the \code{nextkey()} method.  The traversal is ordered by {\sc gdbm}'s
+internal hash values, and won't be sorted by the key values.  This
+method returns the starting key.
+\end{funcdesc}
+
+\begin{funcdesc}{nextkey}{key}
+Returns the key that follows \var{key} in the traversal.  The
+following code prints every key in the database \code{db}, without having to
+create a list in memory that contains them all:
+\bcode\begin{verbatim}
+k=db.firstkey()
+while k!=None:
+    print k
+    k=db.nextkey(k)
+\end{verbatim}\ecode
+\end{funcdesc}
+
+\begin{funcdesc}{reorganize}{}
+If you have carried out a lot of deletions and would like to shrink
+the space used by the {\sc gdbm} file, this routine will reorganize the
+database.  {\sc gdbm} will not shorten the length of a database file except
+by using this reorganization; otherwise, deleted file space will be
+kept and reused as new (key,value) pairs are added.
+\end{funcdesc}
+
+\begin{funcdesc}{sync}{}
+When the database has been opened in fast mode, this method forces any
+unwritten data to be written to the disk.
+\end{funcdesc}
+