Date: Tue, 25 Jan 2022 15:24:03 -0500
From: Bruce Momjian <bruce@momjian.us>
To: davs2rt@gmail.com, pgsql-docs@lists.postgresql.org
Subject: Re: Conventions
Message-ID: <YfBcY1QFX038/aZ8@momjian.us>
References: <164308146320.12460.3590769444508751574@wrigleys.postgresql.org>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="N4dMflSYIyDniJaK"
Content-Disposition: inline
In-Reply-To: <164308146320.12460.3590769444508751574@wrigleys.postgresql.org>
Archived-At: 
 <https://www.postgresql.org/message-id/YfBcY1QFX038/aZ8%40momjian.us>
Precedence: bulk


--N4dMflSYIyDniJaK
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

On Tue, Jan 25, 2022 at 03:31:03AM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/12/notation.html
> Description:
> 
> In section 3, Conventions, it would be helpful to point out that
> parentheses, when used in the command descriptions, are to be interpreted as
> literal required elements.  As a newbie, the combination of {}, [], () was
> already difficult to parse in command descriptions.   Worse when the
> Conventions element doesn't describe parentheses use in the definitions. 
> Here's a simple example where the parens are easy to miss, and it's not
> otherwise clear what they do:
> 
> CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT
> EXISTS ] table_name ( [
>   { column_name data_type [ COLLATE collation ] [ column_constraint [ ... ]
> ]
>     | table_constraint
>     | LIKE source_table [ like_option ... ] }
>     [, ... ]
> ] )
> [ INHERITS ( parent_table [, ... ] ) ]
> [ PARTITION BY { RANGE | LIST | HASH } ( { column_name | ( expression ) } [
> COLLATE collation ] [ opclass ] [, ... ] ) ]
> [ USING method ]
> [ WITH ( storage_parameter [= value] [, ... ] ) | WITHOUT OIDS ]
> [ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
> [ TABLESPACE tablespace_name ]
> 
> I think a single sentence, like "parens () are required elements in the
> syntax" would suffice.

Good point.  How is this patch?

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  If only the physical world exists, free will is an illusion.


--N4dMflSYIyDniJaK
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="paren.diff"

diff --git a/doc/src/sgml/notation.sgml b/doc/src/sgml/notation.sgml
index bd1e8f629a..77499e8507 100644
--- a/doc/src/sgml/notation.sgml
+++ b/doc/src/sgml/notation.sgml
@@ -11,7 +11,7 @@
   (<literal>{</literal> and <literal>}</literal>) and vertical lines
   (<literal>|</literal>) indicate that you must choose one
   alternative.  Dots (<literal>...</literal>) mean that the preceding element
-  can be repeated.
+  can be repeated.  Parentheses should be interpreted literally.
  </para>
 
  <para>

--N4dMflSYIyDniJaK--