From 7c25f3df855b57d1d8fdb64f5361932608187bd5 Mon Sep 17 00:00:00 2001
From: Fred Drake <fdrake@acm.org>
Date: Fri, 15 Sep 2000 21:31:31 +0000
Subject: [PATCH] Add some comments on the available implementations that this
 module can use.

Change the list of flag values for open() to a table.

Markup consistency nits.
---
 Doc/lib/libdbm.tex | 36 +++++++++++++++++++++++++-----------
 1 file changed, 25 insertions(+), 11 deletions(-)

diff --git a/Doc/lib/libdbm.tex b/Doc/lib/libdbm.tex
index a84f987645c..e08af998983 100644
--- a/Doc/lib/libdbm.tex
+++ b/Doc/lib/libdbm.tex
@@ -7,15 +7,17 @@
 
 
 The \module{dbm} module provides an interface to the \UNIX{}
-\code{(n)dbm} library.  Dbm objects behave like mappings
+(\code{n})\code{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
 \method{items()} and \method{values()} methods are not supported.
 
-See also the \refmodule{gdbm}\refbimodindex{gdbm} module, which
-provides a similar interface using the GNU GDBM library.
+This module can be used with the ``classic'' ndbm interface, the BSD
+DB compatibility interface, or the GNU GDBM compatibility interface.
+On \UNIX, the \program{configure} script will attempt to locate the
+appropriate header file to simplify building this module.
 
-The module defines the following constant and functions:
+The module defines the following:
 
 \begin{excdesc}{error}
 Raised on dbm-specific errors, such as I/O errors.
@@ -23,16 +25,27 @@ Raised on dbm-specific errors, such as I/O errors.
 specifying an incorrect key.
 \end{excdesc}
 
-\begin{funcdesc}{open}{filename, \optional{flag, \optional{mode}}}
+\begin{datadesc}{library}
+Name of the \code{ndbm} implementation library used.
+\end{datadesc}
+
+\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).
+\file{.pag} extensions; note that the BSD DB implementation of the
+interface will append the extension \file{.db} and only create one
+file).
 
-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{flag} argument must be one of these values:
+
+\begin{tableii}{c|l}{code}{Value}{Meaning}
+  \lineii{'r'}{Open existing database for reading only (default)}
+  \lineii{'w'}{Open existing database for reading and writing}
+  \lineii{'c'}{Open database for reading and writing, creating it if
+               it doesn't exist}
+  \lineii{'n'}{Always create a new, empty database, open for reading
+               and writing}
+\end{tableii}
 
 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
@@ -42,6 +55,7 @@ only when the database has to be created.  It defaults to octal
 
 \begin{seealso}
   \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
+  \seemodule{gdbm}{Similar interface to the GNU GDBM library.}
   \seemodule{whichdb}{Utility module used to determine the type of an
                       existing database.}
 \end{seealso}