public inbox for [email protected]
help / color / mirror / Atom feedFrom: David G. Johnston <[email protected]>
To: Bruce Momjian <[email protected]>
Cc: [email protected]
Cc: Pg Docs <[email protected]>
Subject: Re: Conventions
Date: Tue, 25 Jan 2022 15:20:52 -0700
Message-ID: <CAKFQuwaqq3euLYDdZ+Uy5mdGUX-CjJ_a-8v0_tYwQwTZ60FpXQ@mail.gmail.com> (raw)
In-Reply-To: <YfBcY1QFX038/[email protected]>
References: <[email protected]>
<YfBcY1QFX038/[email protected]>
On Tue, Jan 25, 2022 at 1:24 PM Bruce Momjian <[email protected]> wrote:
> 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?
>
Just like with brackets and braces on that page you should add the
parentheses symbols.....in parentheses....:(...like this: (( and )). But
I'd accept it as-is.
There is an implied "anything else not noted here should be taken as
literal token to type, or a variable, as context dictates" [1] - and since
() isn't mentioned...
I'd probably rather make that implied part explicit and avoid mentioning
parentheses explicitly.
I would suggest moving the Tcl parenthetical to its own sentence. The
percentage of readers who will notice or care about Tcl synopses is
probably close to zero, and they are likely to be familiar enough to not
need our preface to enlighten them.
[1] I'm not really sure how you define the convention that "parent_table"
and "storage_parameter" should not be treated as literal tokens but
basically variables which you replace with values.
David J.
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], [email protected]
Subject: Re: Conventions
In-Reply-To: <CAKFQuwaqq3euLYDdZ+Uy5mdGUX-CjJ_a-8v0_tYwQwTZ60FpXQ@mail.gmail.com>
* 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