[3.12] GH-101100: Fix reference warnings for ``gettext`` (GH-110115) (#110140)

GH-101100: Fix reference warnings for ``gettext`` (GH-110115)
(cherry picked from commit 0449fe999d56ba795a852d83380fe06514139935)

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

1 files changed, 26 insertions, 29 deletions

diff --git a/Doc/library/gettext.rst b/Doc/library/gettext.rst
index 88a65b9..7ebe91b 100644
--- a/Doc/library/gettext.rst
+++ b/Doc/library/gettext.rst
@@ -58,7 +58,7 @@ class-based API instead.
 
    Return the localized translation of *message*, based on the current global
    domain, language, and locale directory.  This function is usually aliased as
-   :func:`_` in the local namespace (see examples below).
+   :func:`!_` in the local namespace (see examples below).
 
 
 .. function:: dgettext(domain, message)
@@ -98,7 +98,7 @@ class-based API instead.
    .. versionadded:: 3.8
 
 
-Note that GNU :program:`gettext` also defines a :func:`dcgettext` method, but
+Note that GNU :program:`gettext` also defines a :func:`!dcgettext` method, but
 this was deemed not useful and so it is currently unimplemented.
 
 Here's an example of typical usage for this API::
@@ -119,7 +119,7 @@ greater convenience than the GNU :program:`gettext` API.  It is the recommended
 way of localizing your Python applications and modules.  :mod:`!gettext` defines
 a :class:`GNUTranslations` class which implements the parsing of GNU :file:`.mo` format
 files, and has methods for returning strings. Instances of this class can also
-install themselves in the built-in namespace as the function :func:`_`.
+install themselves in the built-in namespace as the function :func:`!_`.
 
 
 .. function:: find(domain, localedir=None, languages=None, all=False)
@@ -150,15 +150,12 @@ install themselves in the built-in namespace as the function :func:`_`.
 
 .. function:: translation(domain, localedir=None, languages=None, class_=None, fallback=False)
 
-   Return a :class:`*Translations` instance based on the *domain*, *localedir*,
+   Return a ``*Translations`` instance based on the *domain*, *localedir*,
    and *languages*, which are first passed to :func:`find` to get a list of the
    associated :file:`.mo` file paths.  Instances with identical :file:`.mo` file
    names are cached.  The actual class instantiated is *class_* if
    provided, otherwise :class:`GNUTranslations`.  The class's constructor must
-   take a single :term:`file object` argument.  If provided, *codeset* will change
-   the charset used to encode translated strings in the
-   :meth:`~NullTranslations.lgettext` and :meth:`~NullTranslations.lngettext`
-   methods.
+   take a single :term:`file object` argument.
 
    If multiple files are found, later files are used as fallbacks for earlier ones.
    To allow setting the fallback, :func:`copy.copy` is used to clone each
@@ -177,19 +174,19 @@ install themselves in the built-in namespace as the function :func:`_`.
 
 .. function:: install(domain, localedir=None, *, names=None)
 
-   This installs the function :func:`_` in Python's builtins namespace, based on
+   This installs the function :func:`!_` in Python's builtins namespace, based on
    *domain* and *localedir* which are passed to the function :func:`translation`.
 
    For the *names* parameter, please see the description of the translation
    object's :meth:`~NullTranslations.install` method.
 
    As seen below, you usually mark the strings in your application that are
-   candidates for translation, by wrapping them in a call to the :func:`_`
+   candidates for translation, by wrapping them in a call to the :func:`!_`
    function, like this::
 
       print(_('This string will be translated.'))
 
-   For convenience, you want the :func:`_` function to be installed in Python's
+   For convenience, you want the :func:`!_` function to be installed in Python's
    builtins namespace, so it is easily accessible in all modules of your
    application.
 
@@ -276,20 +273,20 @@ are the methods of :class:`!NullTranslations`:
 
       If the *names* parameter is given, it must be a sequence containing the
       names of functions you want to install in the builtins namespace in
-      addition to :func:`_`.  Supported names are ``'gettext'``, ``'ngettext'``,
-      ``'pgettext'``, ``'npgettext'``, ``'lgettext'``, and ``'lngettext'``.
+      addition to :func:`!_`.  Supported names are ``'gettext'``, ``'ngettext'``,
+      ``'pgettext'``, and ``'npgettext'``.
 
       Note that this is only one way, albeit the most convenient way, to make
-      the :func:`_` function available to your application.  Because it affects
+      the :func:`!_` function available to your application.  Because it affects
       the entire application globally, and specifically the built-in namespace,
-      localized modules should never install :func:`_`. Instead, they should use
-      this code to make :func:`_` available to their module::
+      localized modules should never install :func:`!_`. Instead, they should use
+      this code to make :func:`!_` available to their module::
 
          import gettext
          t = gettext.translation('mymodule', ...)
          _ = t.gettext
 
-      This puts :func:`_` only in the module's global namespace and so only
+      This puts :func:`!_` only in the module's global namespace and so only
       affects calls within this module.
 
       .. versionchanged:: 3.8
@@ -314,7 +311,7 @@ initialize the "protected" :attr:`_charset` instance variable, defaulting to
 ids and message strings read from the catalog are converted to Unicode using
 this encoding, else ASCII is assumed.
 
-Since message ids are read as Unicode strings too, all :meth:`*gettext` methods
+Since message ids are read as Unicode strings too, all ``*gettext()`` methods
 will assume message ids as Unicode strings, not byte strings.
 
 The entire set of key/value pairs are placed into a dictionary and set as the
@@ -404,7 +401,7 @@ version has a slightly different API.  Its documented usage was::
    _ = cat.gettext
    print(_('hello world'))
 
-For compatibility with this older module, the function :func:`Catalog` is an
+For compatibility with this older module, the function :func:`!Catalog` is an
 alias for the :func:`translation` function described above.
 
 One difference between this module and Henstridge's: his catalog objects
@@ -432,7 +429,7 @@ take the following steps:
 
 In order to prepare your code for I18N, you need to look at all the strings in
 your files.  Any string that needs to be translated should be marked by wrapping
-it in ``_('...')`` --- that is, a call to the function :func:`_`.  For example::
+it in ``_('...')`` --- that is, a call to the function :func:`_ <gettext>`.  For example::
 
    filename = 'mylog.txt'
    message = _('writing a log message')
@@ -504,7 +501,7 @@ module::
 Localizing your application
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If you are localizing your application, you can install the :func:`_` function
+If you are localizing your application, you can install the :func:`!_` function
 globally into the built-in namespace, usually in the main driver file of your
 application.  This will let all your application-specific files just use
 ``_('...')`` without having to explicitly install it in each file.
@@ -581,13 +578,13 @@ Here is one way you can handle this situation::
    for a in animals:
        print(_(a))
 
-This works because the dummy definition of :func:`_` simply returns the string
+This works because the dummy definition of :func:`!_` simply returns the string
 unchanged.  And this dummy definition will temporarily override any definition
-of :func:`_` in the built-in namespace (until the :keyword:`del` command). Take
-care, though if you have a previous definition of :func:`_` in the local
+of :func:`!_` in the built-in namespace (until the :keyword:`del` command). Take
+care, though if you have a previous definition of :func:`!_` in the local
 namespace.
 
-Note that the second use of :func:`_` will not identify "a" as being
+Note that the second use of :func:`!_` will not identify "a" as being
 translatable to the :program:`gettext` program, because the parameter
 is not a string literal.
 
@@ -606,13 +603,13 @@ Another way to handle this is with the following example::
        print(_(a))
 
 In this case, you are marking translatable strings with the function
-:func:`N_`, which won't conflict with any definition of :func:`_`.
+:func:`!N_`, which won't conflict with any definition of :func:`!_`.
 However, you will need to teach your message extraction program to
-look for translatable strings marked with :func:`N_`. :program:`xgettext`,
+look for translatable strings marked with :func:`!N_`. :program:`xgettext`,
 :program:`pygettext`, ``pybabel extract``, and :program:`xpot` all
 support this through the use of the :option:`!-k` command-line switch.
-The choice of :func:`N_` here is totally arbitrary; it could have just
-as easily been :func:`MarkThisStringForTranslation`.
+The choice of :func:`!N_` here is totally arbitrary; it could have just
+as easily been :func:`!MarkThisStringForTranslation`.
 
 
 Acknowledgements