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

tglsfdc · tglsfdc · commit ff6783ce5260 · 2025-07-15T18:53:00.000-04:00
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 <alexey.shishkin@enterprisedb.com> Author: Tom Lane <tgl@sss.pgh.pa.us> Reviewed-by: David G. Johnston <david.g.johnston@gmail.com> 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
@@ -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>
