Doc: specify aclitem syntax more clearly.

The previous wording here relied solely on an example to explain
aclitem output format.  Add an actual syntax synopsis and
explanation of the elements to make it clearer.

David Johnston and Tom Lane, per gripe from Eugen Konkov.

Discussion: https://postgr.es/m/170326116972.1876499.18357820037829248593@wrigleys.postgresql.org

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index e353e425e0083c581ac9cf364eb0500d0a1ccc6c..028bd9f8396d194552f79a5601a086790df7ab96 100644 (file)
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -2280,9 +2280,16 @@ REVOKE ALL ON accounts FROM PUBLIC;
     aclitem
    
    The privileges that have been granted for a particular object are
-   displayed as a list of aclitem entries, where each
-   aclitem describes the permissions of one grantee that
-   have been granted by a particular grantor.  For example,
+   displayed as a list of aclitem entries, each having the
+   format:
+
+grantee=privilege-abbreviation*.../grantor
+
+   Each aclitem lists all the permissions of one grantee that
+   have been granted by a particular grantor.  Specific privileges are
+   represented by one-letter abbreviations from
+   , with *
+   appended if the privilege was granted with grant option.  For example,
    calvin=r*w/hobbes specifies that the role
    calvin has the privilege
    SELECT (r) with grant option