From 4cf068ed0879cccf86a45f06fb274b350b89e911 Mon Sep 17 00:00:00 2001
From: "Erlend E. Aasland" <erlend@python.org>
Date: Fri, 26 Jan 2024 13:35:56 +0100
Subject: [PATCH] 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
---
 Doc/library/dbm.rst | 47 +++++++++++++++++++++++++--------------------
 1 file changed, 26 insertions(+), 21 deletions(-)

diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst
index 1a8e0158fcd..bc5bb0cec0c 100644
--- 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 GNU GDBM
-compatibility interface. On Unix, the :program:`configure` script will attempt
-to locate the appropriate header file to simplify building this module.
+This module can be used with the "classic" NDBM interface or the
+:abbr:`GDBM (GNU dbm)` compatibility interface.
+
+.. 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