Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps  (TLS1.3) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.94.2)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1uZaUc-005Wtb-Mx
	for pgsql-docs@arkaria.postgresql.org; Wed, 09 Jul 2025 19:30:10 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.94.2)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1uZaUa-003PaI-Q6
	for pgsql-docs@arkaria.postgresql.org; Wed, 09 Jul 2025 19:30:09 +0000
Received: from makus.postgresql.org ([2001:4800:3e1:1::229])
	by malur.postgresql.org with esmtps  (TLS1.3) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.94.2)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1uZaUa-003PZD-Ic
	for pgsql-docs@lists.postgresql.org; Wed, 09 Jul 2025 19:30:09 +0000
Received: from sss.pgh.pa.us ([68.162.161.243])
	by makus.postgresql.org with esmtps  (TLS1.3) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.96)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1uZaUZ-006S43-1b
	for pgsql-docs@lists.postgresql.org;
	Wed, 09 Jul 2025 19:30:08 +0000
Received: from sss1.sss.pgh.pa.us (localhost [127.0.0.1])
	by sss.pgh.pa.us (8.15.2/8.15.2) with ESMTP id 569JU4NP1341071;
	Wed, 9 Jul 2025 15:30:04 -0400
From: Tom Lane <tgl@sss.pgh.pa.us>
To: "David G. Johnston" <david.g.johnston@gmail.com>
cc: alexey.shishkin@enterprisedb.com, pgsql-docs@lists.postgresql.org
Subject: Re: correction suggestion for
 https://www.postgresql.org/docs/17/auth-username-maps.html
In-reply-to: 
 <CAKFQuwZu6kZ8ZPvJ3pWXig+6UX4nTVK-hdL_ZS3fSdps=RJQQQ@mail.gmail.com>
References: 
 <175206279327.3157504.12519088928605422253@wrigleys.postgresql.org>
 <CAKFQuwbhZg8C93_GU0WP=3qGuT0kbPsLL1htP-svrv=Bgjkpeg@mail.gmail.com>
 <1145313.1752078127@sss.pgh.pa.us>
 <CAKFQuwZu6kZ8ZPvJ3pWXig+6UX4nTVK-hdL_ZS3fSdps=RJQQQ@mail.gmail.com>
Comments: In-reply-to "David G. Johnston" <david.g.johnston@gmail.com>
	message dated "Wed, 09 Jul 2025 11:39:24 -0700"
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <1341069.1752089404.1@sss.pgh.pa.us>
Date: Wed, 09 Jul 2025 15:30:04 -0400
Message-ID: <1341070.1752089404@sss.pgh.pa.us>
List-Id: <pgsql-docs.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-docs@lists.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-docs>
Archived-At: 
 <https://www.postgresql.org/message-id/1341070.1752089404%40sss.pgh.pa.us>
Precedence: bulk

"David G. Johnston" <david.g.johnston@gmail.com> writes:
> Its good as far a narrow fix goes.

> But how about the attached?  More invasive but covers the salient points
> better, IMO, and less repetitive than having the two fields have their own
> basically copy-pasted paragraphs.

Meh... I initially thought that merging the two paras sounded like a
good idea, but I'm not finding that this formulation reads any better.
Notably, as things stand we have parallel constructions 
"If the <field> starts with an <x> character" in the preceding para as
well as these two, and I think it's good to keep that parallelism.
I do agree that it's overly repetitive, but we could improve that by
dropping the second instance of the parenthetical link to
posix-syntax-details.

> I didn't add an example but felt the point "be referenced a single time
> within" to be needed since, usefulness not withstanding, writing \1\1 for
> database-username works but only the first instance of \1 is replaced.

Hmm, I wonder if that isn't a bug we should fix.  It's hard to believe
anyone is relying on the second \1 *not* getting replaced, and perhaps
there are use-cases for multiple replacements.

> Also, should we attempt to align this documentation and
> pg_ident.conf.sample as pertains to pg-username vs. database-username?

Agreed that making pg_ident.conf.sample match would be an improvement.

			regards, tom lane