[3.11] Docs: use placeholders in dbm flag param docs (GH-114482) (#114498)

Also correct the default flag param for dbm.dumb.open();
it's 'c', not 'r'.
(cherry picked from commit 8c265408c51609c6b4a6788cac9cc5fea7a14888)

Co-authored-by: Erlend E. Aasland <erlend@python.org>

diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst
index 8b799ad6cb57fd9c128bb49e264ef97f4f108f91..bc72f0f76ac2e23d4958c1b35a6c1672c372705a 100644 (file)
--- a/Doc/library/dbm.rst
+++ b/Doc/library/dbm.rst
@@ -36,6 +36,21 @@ the Oracle Berkeley DB.
 .. versionchanged:: 3.11
    Accepts :term:`path-like object` for filename.
 
+.. Substitutions for the open() flag param docs;
+   all submodules use the same text.
+
+.. |flag_r| replace::
+   Open existing database for reading only.
+
+.. |flag_w| replace::
+   Open existing database for reading and writing.
+
+.. |flag_c| replace::
+   Open database for reading and writing, creating it if it doesn't exist.
+
+.. |flag_n| replace::
+   Always create a new, empty database, open for reading and writing.
+
 .. function:: open(file, flag='r', mode=0o666)
 
    Open the database file *file* and return a corresponding object.
@@ -46,21 +61,13 @@ the Oracle Berkeley DB.
 
    The optional *flag* argument can be:
 
-   +---------+-------------------------------------------+
-   | Value   | Meaning                                   |
-   +=========+===========================================+
-   | ``'r'`` | Open existing database for reading only   |
-   |         | (default)                                 |
-   +---------+-------------------------------------------+
-   | ``'w'`` | Open existing database for reading and    |
-   |         | writing                                   |
-   +---------+-------------------------------------------+
-   | ``'c'`` | Open database for reading and writing,    |
-   |         | creating it if it doesn't exist           |
-   +---------+-------------------------------------------+
-   | ``'n'`` | Always create a new, empty database, open |
-   |         | for reading and writing                   |
-   +---------+-------------------------------------------+
+   .. csv-table::
+      :header: "Value", "Meaning"
+
+      ``'r'`` (default), |flag_r|
+      ``'w'``, |flag_w|
+      ``'c'``, |flag_c|
+      ``'n'``, |flag_n|
 
    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`` (and will be
@@ -165,21 +172,13 @@ supported.
 
    The optional *flag* argument can be:
 
-   +---------+-------------------------------------------+
-   | Value   | Meaning                                   |
-   +=========+===========================================+
-   | ``'r'`` | Open existing database for reading only   |
-   |         | (default)                                 |
-   +---------+-------------------------------------------+
-   | ``'w'`` | Open existing database for reading and    |
-   |         | writing                                   |
-   +---------+-------------------------------------------+
-   | ``'c'`` | Open database for reading and writing,    |
-   |         | creating it if it doesn't exist           |
-   +---------+-------------------------------------------+
-   | ``'n'`` | Always create a new, empty database, open |
-   |         | for reading and writing                   |
-   +---------+-------------------------------------------+
+   .. csv-table::
+      :header: "Value", "Meaning"
+
+      ``'r'`` (default), |flag_r|
+      ``'w'``, |flag_w|
+      ``'c'``, |flag_c|
+      ``'n'``, |flag_n|
 
    The following additional characters may be appended to the flag to control
    how the database is opened:
@@ -290,21 +289,13 @@ to locate the appropriate header file to simplify building this module.
 
    The optional *flag* argument must be one of these values:
 
-   +---------+-------------------------------------------+
-   | Value   | Meaning                                   |
-   +=========+===========================================+
-   | ``'r'`` | Open existing database for reading only   |
-   |         | (default)                                 |
-   +---------+-------------------------------------------+
-   | ``'w'`` | Open existing database for reading and    |
-   |         | writing                                   |
-   +---------+-------------------------------------------+
-   | ``'c'`` | Open database for reading and writing,    |
-   |         | creating it if it doesn't exist           |
-   +---------+-------------------------------------------+
-   | ``'n'`` | Always create a new, empty database, open |
-   |         | for reading and writing                   |
-   +---------+-------------------------------------------+
+   .. csv-table::
+      :header: "Value", "Meaning"
+
+      ``'r'`` (default), |flag_r|
+      ``'w'``, |flag_w|
+      ``'c'``, |flag_c|
+      ``'n'``, |flag_n|
 
    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`` (and will be
@@ -363,21 +354,13 @@ The module defines the following:
 
    The optional *flag* argument can be:
 
-   +---------+-------------------------------------------+
-   | Value   | Meaning                                   |
-   +=========+===========================================+
-   | ``'r'`` | Open existing database for reading only   |
-   |         | (default)                                 |
-   +---------+-------------------------------------------+
-   | ``'w'`` | Open existing database for reading and    |
-   |         | writing                                   |
-   +---------+-------------------------------------------+
-   | ``'c'`` | Open database for reading and writing,    |
-   |         | creating it if it doesn't exist           |
-   +---------+-------------------------------------------+
-   | ``'n'`` | Always create a new, empty database, open |
-   |         | for reading and writing                   |
-   +---------+-------------------------------------------+
+   .. csv-table::
+      :header: "Value", "Meaning"
+
+      ``'r'``, |flag_r|
+      ``'w'``, |flag_w|
+      ``'c'`` (default), |flag_c|
+      ``'n'``, |flag_n|
 
    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`` (and will be modified