Doc: clarify description of regexp fields in pg_ident.conf.

The grammar was a little shaky and confusing here, so word-smith it
a bit.  Also, adjust the comments in pg_ident.conf.sample to use the
same terminology as the SGML docs, in particular "DATABASE-USERNAME"
not "PG-USERNAME".

Back-patch appropriate subsets.  I did not risk changing
pg_ident.conf.sample in released branches, but it still seems OK
to change it in v18.

Reported-by: Alexey Shishkin <[email protected]>
Author: Tom Lane <[email protected]>
Reviewed-by: David G. Johnston <[email protected]>
Discussion: https://postgr.es/m/175206279327.3157504.12519088928605422253@wrigleys.postgresql.org
Backpatch-through: 13

diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 37ded4ba8793375d2359fb7edc3d6fc5de25dbb6..661a25790f4c99e34895e05adfaaa3fc67412578 100644 (file)
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -962,8 +962,9 @@ local   db1,db2,@demodbs  all                                   md5
    the remainder of the field is treated as a regular expression.
    (See <xref linkend="posix-syntax-details"/> for details of
    <productname>PostgreSQL</productname>'s regular expression syntax.)  The regular
-   expression can include a single capture, or parenthesized subexpression,
-   which can then be referenced in the <replaceable>database-username</replaceable>
+   expression can include a single capture, or parenthesized subexpression.
+   The portion of the system user name that matched the capture can then
+   be referenced in the <replaceable>database-username</replaceable>
    field as <literal>\1</literal> (backslash-one).  This allows the mapping of
    multiple user names in a single line, which is particularly useful for
    simple syntax substitutions.  For example, these entries
@@ -981,12 +982,11 @@ mymap   /^(.*)@otherdomain\.com$   guest
   <para>
    If the <replaceable>database-username</replaceable> field starts with
    a slash (<literal>/</literal>), the remainder of the field is treated
-   as a regular expression (see <xref linkend="posix-syntax-details"/>
-   for details of <productname>PostgreSQL</productname>'s regular
-   expression syntax). It is not possible to use <literal>\1</literal>
-   to use a capture from regular expression on
-   <replaceable>system-username</replaceable> for a regular expression
-   on <replaceable>database-username</replaceable>.
+   as a regular expression.
+   When the <replaceable>database-username</replaceable> field is a regular
+   expression, it is not possible to use <literal>\1</literal> within it to
+   refer to a capture from the <replaceable>system-username</replaceable>
+   field.
   </para>
 
   <tip>