From: | PG Doc comments form <noreply(at)postgresql(dot)org> |
---|---|
To: | pgsql-docs(at)lists(dot)postgresql(dot)org |
Cc: | davs2rt(at)gmail(dot)com |
Subject: | Conventions |
Date: | 2022-01-25 03:31:03 |
Message-ID: | 164308146320.12460.3590769444508751574@wrigleys.postgresql.org |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Thread: | |
Lists: | pgsql-docs |
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.
From | Date | Subject | |
---|---|---|---|
Next Message | Bruce Momjian | 2022-01-25 20:24:03 | Re: Conventions |
Previous Message | Eric Mutta | 2022-01-24 20:48:05 | Re: Typo in "27.2.8. Synchronous Replication" |