documented default flag, mode; changed gdbm into a pointer to dbm

4 files changed, 54 insertions, 78 deletions

diff --git a/Doc/lib/libdbm.tex b/Doc/lib/libdbm.tex
index 7e004d2..ee2d39f 100644
--- a/Doc/lib/libdbm.tex
+++ b/Doc/lib/libdbm.tex
@@ -1,11 +1,15 @@
 \section{Built-in Module \sectcode{dbm}}
 \bimodindex{dbm}
 
-Dbm provides python programs with an interface to the unix \code{ndbm}
-database library.  Dbm objects are of the mapping type, so they can be
-handled just like objects of the built-in \dfn{dictionary} type,
-except that keys and values are always strings, and printing a dbm
-object doesn't print the keys and values.
+The \code{dbm} module provides an interface to the {\UNIX}
+\code{(n)dbm} library.  Dbm objects behave like mappings
+(dictionaries), except that keys and values are always strings.
+Printing a dbm object doesn't print the keys and values, and the
+\code{items()} and \code{values()} methods are not supported.
+
+See also the \code{gdbm} module, which provides a similar interface
+using the GNU GDBM library.
+\bimodindex{gdbm}
 
 The module defines the following constant and functions:
 
@@ -15,11 +19,18 @@ 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\, rwmode\, filemode}
-Open a dbm database and return a mapping object.  \var{filename} is
-the name of the database file (without the \file{.dir} or \file{.pag}
-extensions), \var{rwmode} is \code{'r'}, \code{'w'} or \code{'rw'} to
-open the database fore reading, writing or both respectively,
-and \var{filemode} is the \UNIX{} mode of the file, used only
-when the database has to be created (but to be supplied at all times).
+\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).
+
+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}
diff --git a/Doc/lib/libgdbm.tex b/Doc/lib/libgdbm.tex
index f353b5e..96be165 100644
--- a/Doc/lib/libgdbm.tex
+++ b/Doc/lib/libgdbm.tex
@@ -1,31 +1,8 @@
 \section{Built-in Module \sectcode{gdbm}}
 \bimodindex{gdbm}
 
-Gdbm provides python programs with an interface to the GNU \code{gdbm}
-database library.  Gdbm objects are of the mapping type, so they can be
-handled just like objects of the built-in \dfn{dictionary} type,
-except that keys and values are always strings, and printing a gdbm
-object doesn't print the keys and values.
+This module is nearly identical to the \code{dbm} module, but uses
+GDBM instead.  Its interface is identical, and not repeated here.
 
-The module is based on the Dbm module, modified to use GDBM instead.
-
-The module defines the following constant and functions:
-
-\renewcommand{\indexsubitem}{(in module gdbm)}
-\begin{excdesc}{error}
-Raised on gdbm-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\, rwmode\, filemode}
-Open a gdbm database and return a mapping object.  \var{filename} is
-the name of the database file, \var{rwmode} is \code{'r'}, \code{'w'},
-\code{'c'}, or \code{'n'} for reader, writer (this also gives read
-access), create (writer, but create the database if it doesn't already
-exist) and newdb (which will always create a new database).  Only one
-writer may open a gdbm file and many readers may open the file.  Readers
-and writers cannot open the gdbm file at the same time.  Note that the
-\code{GDBM_FAST} mode of opening the database is not supported.
-\var{filemode} is the \UNIX\ mode of the file, used only when a
-database is created (but to be supplied at all times).
-\end{funcdesc}
+Warning: the file formats created by gdbm and dbm are incompatible.
+\bimodindex{dbm}
diff --git a/Doc/libdbm.tex b/Doc/libdbm.tex
index 7e004d2..ee2d39f 100644
--- a/Doc/libdbm.tex
+++ b/Doc/libdbm.tex
@@ -1,11 +1,15 @@
 \section{Built-in Module \sectcode{dbm}}
 \bimodindex{dbm}
 
-Dbm provides python programs with an interface to the unix \code{ndbm}
-database library.  Dbm objects are of the mapping type, so they can be
-handled just like objects of the built-in \dfn{dictionary} type,
-except that keys and values are always strings, and printing a dbm
-object doesn't print the keys and values.
+The \code{dbm} module provides an interface to the {\UNIX}
+\code{(n)dbm} library.  Dbm objects behave like mappings
+(dictionaries), except that keys and values are always strings.
+Printing a dbm object doesn't print the keys and values, and the
+\code{items()} and \code{values()} methods are not supported.
+
+See also the \code{gdbm} module, which provides a similar interface
+using the GNU GDBM library.
+\bimodindex{gdbm}
 
 The module defines the following constant and functions:
 
@@ -15,11 +19,18 @@ 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\, rwmode\, filemode}
-Open a dbm database and return a mapping object.  \var{filename} is
-the name of the database file (without the \file{.dir} or \file{.pag}
-extensions), \var{rwmode} is \code{'r'}, \code{'w'} or \code{'rw'} to
-open the database fore reading, writing or both respectively,
-and \var{filemode} is the \UNIX{} mode of the file, used only
-when the database has to be created (but to be supplied at all times).
+\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).
+
+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}
diff --git a/Doc/libgdbm.tex b/Doc/libgdbm.tex
index f353b5e..96be165 100644
--- a/Doc/libgdbm.tex
+++ b/Doc/libgdbm.tex
@@ -1,31 +1,8 @@
 \section{Built-in Module \sectcode{gdbm}}
 \bimodindex{gdbm}
 
-Gdbm provides python programs with an interface to the GNU \code{gdbm}
-database library.  Gdbm objects are of the mapping type, so they can be
-handled just like objects of the built-in \dfn{dictionary} type,
-except that keys and values are always strings, and printing a gdbm
-object doesn't print the keys and values.
+This module is nearly identical to the \code{dbm} module, but uses
+GDBM instead.  Its interface is identical, and not repeated here.
 
-The module is based on the Dbm module, modified to use GDBM instead.
-
-The module defines the following constant and functions:
-
-\renewcommand{\indexsubitem}{(in module gdbm)}
-\begin{excdesc}{error}
-Raised on gdbm-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\, rwmode\, filemode}
-Open a gdbm database and return a mapping object.  \var{filename} is
-the name of the database file, \var{rwmode} is \code{'r'}, \code{'w'},
-\code{'c'}, or \code{'n'} for reader, writer (this also gives read
-access), create (writer, but create the database if it doesn't already
-exist) and newdb (which will always create a new database).  Only one
-writer may open a gdbm file and many readers may open the file.  Readers
-and writers cannot open the gdbm file at the same time.  Note that the
-\code{GDBM_FAST} mode of opening the database is not supported.
-\var{filemode} is the \UNIX\ mode of the file, used only when a
-database is created (but to be supplied at all times).
-\end{funcdesc}
+Warning: the file formats created by gdbm and dbm are incompatible.
+\bimodindex{dbm}