[3.12] Docs: reword dbm.ndbm introduction (#114549) (#114599)

(cherry picked from commit 4cf068ed08)

- 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

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::
+.. note:: |incompat_note|
-   The file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are
-   incompatible and can not be used interchangeably.
 
 .. exception:: error
 
@@ -246,29 +248,32 @@ and the :meth:`!items` and :meth:`!values` methods are not supported.
 
       Close the GDBM database.
 
-: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.
+The :mod:`dbm.ndbm` module provides an interface to the
-Dbm objects behave like mappings (dictionaries), except that keys and values are
+:abbr:`NDBM (New Database Manager)` library.
-always stored as bytes. Printing a ``dbm`` object doesn't print the keys and
+:class:`!ndbm` objects behave similar to :term:`mappings <mapping>`,
-values, and the :meth:`items` and :meth:`values` methods are not supported.
+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 GNU GDBM
+This module can be used with the "classic" NDBM interface or the
-compatibility interface. On Unix, the :program:`configure` script will attempt
+:abbr:`GDBM (GNU dbm)` compatibility interface.
-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).
@@ -281,13 +286,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
+   Open an NDBM database and return an :class:`!ndbm` object.
-   name of the database file (without the :file:`.dir` or :file:`.pag` extensions).
+   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:
 
@@ -303,7 +309,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
@@ -311,7 +317,7 @@ to locate the appropriate header file to simplify building this module.
 
    .. method:: ndbm.close()
 
-      Close the ``ndbm`` database.
+      Close the NDBM database.
 
 
 :mod:`dbm.dumb` --- Portable DBM implementation