Docs: reword dbm.ndbm introduction (#114549)

- add abbreviation directives for NDBM and GDBM
- consistently spell NDBM as NDBM
- silence broken ndbm class refs
- improve accuracy of dbm.ndbm.open() spec
- use replacement text for NDBM/GDBM file format incompatibility note

diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst
index 1a8e0158fcdbd5e3ea890b1b1aa5d1689940e966..bc5bb0cec0cef760f1454c823971ce7afc5ed53f 100644 (file)
--- a/Doc/library/dbm.rst
+++ b/Doc/library/dbm.rst
@@ -52,6 +52,10 @@ the Oracle Berkeley DB.
 .. |flag_n| replace::
    Always create a new, empty database, open for reading and writing.
 
+.. |incompat_note| replace::
+   The file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are incompatible
+   and can not be used interchangeably.
+
 .. function:: open(file, flag='r', mode=0o666)
 
    Open the database file *file* and return a corresponding object.
@@ -157,9 +161,7 @@ functionality like crash tolerance.
 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.
+.. note:: |incompat_note|
 
 .. exception:: error
 
@@ -253,29 +255,31 @@ and the :meth:`!items` and :meth:`!values` methods are not supported.
       .. versionadded:: 3.13
 
 
-:mod:`dbm.ndbm` --- Interface based on ndbm
--------------------------------------------
+:mod:`dbm.ndbm` --- New Database Manager
+----------------------------------------
 
 .. module:: dbm.ndbm
    :platform: Unix
-   :synopsis: The standard "database" interface, based on ndbm.
+   :synopsis: The New Database Manager
 
 **Source code:** :source:`Lib/dbm/ndbm.py`
 
 --------------
 
-The :mod:`dbm.ndbm` module provides an interface to the Unix "(n)dbm" library.
-Dbm objects behave like mappings (dictionaries), except that keys and values are
-always stored as bytes. Printing a ``dbm`` object doesn't print the keys and
-values, and the :meth:`items` and :meth:`values` methods are not supported.
+The :mod:`dbm.ndbm` module provides an interface to the
+:abbr:`NDBM (New Database Manager)` library.
+:class:`!ndbm` objects behave similar to :term:`mappings <mapping>`,
+except that keys and values are always stored as :class:`bytes`,
+and the :meth:`!items` and :meth:`!values` methods are not supported.
+
+This module can be used with the "classic" NDBM interface or the
+:abbr:`GDBM (GNU dbm)` compatibility interface.
 
-This module can be used with the "classic" ndbm 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.
+.. note:: |incompat_note|
 
 .. warning::
 
-   The ndbm library shipped as part of macOS has an undocumented limitation on the
+   The NDBM library shipped as part of macOS has an undocumented limitation on the
    size of values, which can result in corrupted database files
    when storing values larger than this limit. Reading such corrupted files can
    result in a hard crash (segmentation fault).
@@ -288,13 +292,14 @@ to locate the appropriate header file to simplify building this module.
 
 .. data:: library
 
-   Name of the ``ndbm`` implementation library used.
+   Name of the NDBM implementation library used.
 
 
-.. function:: open(filename[, flag[, mode]])
+.. function:: open(filename, flag="r", mode=0o666, /)
 
-   Open a dbm database and return a ``ndbm`` object.  The *filename* argument is the
-   name of the database file (without the :file:`.dir` or :file:`.pag` extensions).
+   Open an NDBM database and return an :class:`!ndbm` object.
+   The *filename* argument is the name of the database file
+   (without the :file:`.dir` or :file:`.pag` extensions).
 
    The optional *flag* argument must be one of these values:
 
@@ -310,7 +315,7 @@ to locate the appropriate header file to simplify building this module.
    database has to be created.  It defaults to octal ``0o666`` (and will be
    modified by the prevailing umask).
 
-   In addition to the dictionary-like methods, ``ndbm`` objects
+   In addition to the dictionary-like methods, :class:`!ndbm` objects
    provide the following method:
 
    .. versionchanged:: 3.11
@@ -318,11 +323,11 @@ to locate the appropriate header file to simplify building this module.
 
    .. method:: ndbm.close()
 
-      Close the ``ndbm`` database.
+      Close the NDBM database.
 
    .. method:: ndbm.clear()
 
-      Remove all items from the ``ndbm`` database.
+      Remove all items from the NDBM database.
 
       .. versionadded:: 3.13