pg.ddx.io  pgsql-docs@postgresql.org mailing list archive  
help / color / mirror / Atom feed
From: PG Doc comments form <noreply@postgresql.org>
To: pgsql-docs@lists.postgresql.org
Cc: davs2rt@gmail.com
Subject: Conventions
Date: Tue, 25 Jan 2022 03:31:03 +0000
Message-ID: <164308146320.12460.3590769444508751574@wrigleys.postgresql.org> (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.


view thread (18+ messages)  latest in thread

Message-ID: <164308146320.12460.3590769444508751574@wrigleys.postgresql.org>
Permalink:  ../164308146320.12460.3590769444508751574@wrigleys.postgresql.org/
Also on:    postgresql.org/message-id/164308146320.12460.3590769444508751574@wrigleys.postgresql.org

 · 

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 from your mail client; the link fills in
  the headers below: reply via email
  Some clients, webmail especially, drop In-Reply-To and References from
  a link, and the reply then starts a new thread: use the mbox below.

  To: pgsql-docs@postgresql.org
  Cc: noreply@postgresql.org, davs2rt@gmail.com
  Subject: Re: Conventions
  In-Reply-To: <164308146320.12460.3590769444508751574@wrigleys.postgresql.org>
  References: <164308146320.12460.3590769444508751574@wrigleys.postgresql.org>

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

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