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 1rHpjU-004UHp-Lr
	for pgsql-docs@arkaria.postgresql.org; Mon, 25 Dec 2023 18:31:20 +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 1rHpjQ-004SCN-J5
	for pgsql-docs@arkaria.postgresql.org; Mon, 25 Dec 2023 18:31:16 +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 1rHpjQ-004SCF-42
	for pgsql-docs@lists.postgresql.org; Mon, 25 Dec 2023 18:31:16 +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.94.2)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1rHpjM-00CA0i-L9
	for pgsql-docs@lists.postgresql.org; Mon, 25 Dec 2023 18:31:14 +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 3BPIVBTt1887862;
	Mon, 25 Dec 2023 13:31:11 -0500
From: Tom Lane <tgl@sss.pgh.pa.us>
To: "David G. Johnston" <david.g.johnston@gmail.com>
cc: Eugen Konkov <konkove@gmail.com>,
        "pgsql-docs@lists.postgresql.org" <pgsql-docs@lists.postgresql.org>
Subject: Re: Documentation does not describes format for access privileges:
 =Tc/user
In-reply-to: 
 <CAKFQuwbRk15AthfdkzZ9xDS0E+QvXG07Btcvv8V6DUg9jJdz2g@mail.gmail.com>
References: 
 <170326116972.1876499.18357820037829248593@wrigleys.postgresql.org>
 <CAKFQuwYrHMBJCDTUGHRBhhZtvpgvDyR_G8yRtWqLuFA31QYYig@mail.gmail.com>
 <CAAwmOLxHUERXUyOpgbb1-7x0Yo_+r8fVQpVeQ84pG9wGEKtUwQ@mail.gmail.com>
 <CAKFQuwYtgkkGr0nx_vn255hXxdBnoV=_9expMk+KHxooP=9oZA@mail.gmail.com>
 <CAKFQuwbRk15AthfdkzZ9xDS0E+QvXG07Btcvv8V6DUg9jJdz2g@mail.gmail.com>
Comments: In-reply-to "David G. Johnston" <david.g.johnston@gmail.com>
	message dated "Mon, 25 Dec 2023 11:16:33 -0700"
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="----- =_aaaaaaaaaa0"
Content-ID: <1887782.1703529057.0@sss.pgh.pa.us>
Content-Transfer-Encoding: 8bit
Date: Mon, 25 Dec 2023 13:31:11 -0500
Message-ID: <1887860.1703529071@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/1887860.1703529071%40sss.pgh.pa.us>
Precedence: bulk

------- =_aaaaaaaaaa0
Content-Type: text/plain; charset="UTF-8"
Content-ID: <1887782.1703529057.1@sss.pgh.pa.us>
Content-Transfer-Encoding: 8bit

"David G. Johnston" <david.g.johnston@gmail.com> writes:
> We probably should write the syntax like we do everywhere else:
> [grantee]={privilege[*]}[…]/grantor
> Then define the placeholders in the subsequent paragraph.

Seems reasonable.  About like this?

			regards, tom lane


------- =_aaaaaaaaaa0
Content-Type: text/x-diff; name="doc-aclitem-format-explicitly.patch";
	charset="us-ascii"
Content-ID: <1887782.1703529057.2@sss.pgh.pa.us>
Content-Description: doc-aclitem-format-explicitly.patch
Content-Transfer-Encoding: quoted-printable

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index d2951cd754..664361a724 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -2318,8 +2318,12 @@ REVOKE ALL ON accounts FROM PUBLIC;
     <primary><type>aclitem</type></primary>
    </indexterm>
    The privileges that have been granted for a particular object are
-   displayed as a list of <type>aclitem</type> entries, where each
-   <type>aclitem</type> describes the permissions of one grantee that
+   displayed as a list of <type>aclitem</type> entries, each having the
+   format:
+<synopsis>
+<replaceable>grantee</replaceable><literal>=3D</literal><replaceable>priv=
ilege-abbreviations</replaceable><literal>/</literal><replaceable>grantor<=
/replaceable>
+</synopsis>
+   Each <type>aclitem</type> describes the permissions of one grantee tha=
t
    have been granted by a particular grantor.  For example,
    <literal>calvin=3Dr*w/hobbes</literal> specifies that the role
    <literal>calvin</literal> has the privilege

------- =_aaaaaaaaaa0--