public inbox for [email protected]  

help / color / mirror / Atom feed

From: PG Doc comments form <[email protected]>
To: [email protected]
Cc: [email protected]
Subject: Conventions
Date: Tue, 25 Jan 2022 03:31:03 +0000
Message-ID: <[email protected]> (raw)

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.

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected], [email protected]
  Subject: Re: Conventions
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox