[3.12] Docs: reword dbm.gnu introduction (#114548) (#114588)

(cherry picked from commit 06c5de36f222b926bbc94831536096b974bd5e77)

Also...
- consistently spell GDBM as GDBM
- silence gdbm class refs
- improve accuracy of dbm.gdbm.open() spec

diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst
index bc72f0f76ac2e23d4958c1b35a6c1672c372705a..1e8e2bb1e353fe6fa8289462507db5424ebb482b 100644 (file)
--- a/Doc/library/dbm.rst
+++ b/Doc/library/dbm.rst
@@ -137,27 +137,28 @@ then prints out the contents of the database::
 The individual submodules are described in the following sections.
 
 
-:mod:`dbm.gnu` --- GNU's reinterpretation of dbm
-------------------------------------------------
+:mod:`dbm.gnu` --- GNU database manager
+---------------------------------------
 
 .. module:: dbm.gnu
    :platform: Unix
-   :synopsis: GNU's reinterpretation of dbm.
+   :synopsis: GNU database manager
 
 **Source code:** :source:`Lib/dbm/gnu.py`
 
 --------------
 
-This module is quite similar to the :mod:`dbm` module, but uses the GNU library
-``gdbm`` instead to provide some additional functionality.  Please note that the
-file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are incompatible.
+The :mod:`dbm.gnu` module provides an interface to the :abbr:`GDBM (GNU dbm)`
+library, similar to the :mod:`dbm.ndbm` module, but with additional
+functionality like crash tolerance.
 
-The :mod:`dbm.gnu` module provides an interface to the GNU DBM library.
-``dbm.gnu.gdbm`` objects behave like mappings (dictionaries), except that keys and
-values are always converted to bytes before storing.  Printing a ``gdbm``
-object doesn't print the
-keys and values, and the :meth:`items` and :meth:`values` methods are not
-supported.
+:class:`!gdbm` objects behave similar to :term:`mappings <mapping>`,
+except that keys and values are always converted to :class:`bytes` before storing,
+and the :meth:`!items` and :meth:`!values` methods are not supported.
+
+.. note::
+   The file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are
+   incompatible and can not be used interchangeably.
 
 .. exception:: error
 
@@ -165,9 +166,9 @@ supported.
    raised for general mapping errors like specifying an incorrect key.
 
 
-.. function:: open(filename[, flag[, mode]])
+.. function:: open(filename, flag="r", mode=0o666, /)
 
-   Open a ``gdbm`` database and return a :class:`gdbm` object.  The *filename*
+   Open a GDBM database and return a :class:`!gdbm` object.  The *filename*
    argument is the name of the database file.
 
    The optional *flag* argument can be:
@@ -196,14 +197,14 @@ supported.
    | ``'u'`` | Do not lock database.                      |
    +---------+--------------------------------------------+
 
-   Not all flags are valid for all versions of ``gdbm``.  The module constant
+   Not all flags are valid for all versions of GDBM.  The module constant
    :const:`open_flags` is a string of supported flag characters.  The exception
    :exc:`error` is raised if an invalid flag is specified.
 
    The optional *mode* argument is the Unix mode of the file, used only when the
    database has to be created.  It defaults to octal ``0o666``.
 
-   In addition to the dictionary-like methods, ``gdbm`` objects have the
+   In addition to the dictionary-like methods, :class:`gdbm` objects have the
    following methods:
 
    .. versionchanged:: 3.11
@@ -212,7 +213,7 @@ supported.
    .. method:: gdbm.firstkey()
 
       It's possible to loop over every key in the database using this method  and the
-      :meth:`nextkey` method.  The traversal is ordered by ``gdbm``'s internal
+      :meth:`nextkey` method.  The traversal is ordered by GDBM's internal
       hash values, and won't be sorted by the key values.  This method returns
       the starting key.
 
@@ -230,7 +231,7 @@ supported.
    .. method:: gdbm.reorganize()
 
       If you have carried out a lot of deletions and would like to shrink the space
-      used by the ``gdbm`` file, this routine will reorganize the database.  ``gdbm``
+      used by the GDBM file, this routine will reorganize the database.  :class:`!gdbm`
       objects 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.
@@ -242,7 +243,7 @@ supported.
 
    .. method:: gdbm.close()
 
-      Close the ``gdbm`` database.
+      Close the GDBM database.
 
 :mod:`dbm.ndbm` --- Interface based on ndbm
 -------------------------------------------