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 <br...@momjian.us> https://momjian.us EDB https://enterprisedb.com If only the physical world exists, free will is an illusion.
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>