Re: Conventions

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(at)momjian(dot)us> https://momjian.us
EDB https://enterprisedb.com

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