public inbox for [email protected]
help / color / mirror / Atom feedFrom: Dave Stewart <[email protected]>
To: David G. Johnston <[email protected]>
Cc: Bruce Momjian <[email protected]>
Cc: Pg Docs <[email protected]>
Subject: Re: Conventions
Date: Tue, 25 Jan 2022 14:35:50 -0800
Message-ID: <CADQBm3QcndPBjeNVswur=KupHzHeVYWU5wHNSSJL-0qnTTNgqQ@mail.gmail.com> (raw)
In-Reply-To: <CAKFQuwaqq3euLYDdZ+Uy5mdGUX-CjJ_a-8v0_tYwQwTZ60FpXQ@mail.gmail.com>
References: <[email protected]>
<YfBcY1QFX038/[email protected]>
<CAKFQuwaqq3euLYDdZ+Uy5mdGUX-CjJ_a-8v0_tYwQwTZ60FpXQ@mail.gmail.com>
Thanks, all, for considering this update.
I like the "anything not noted here..." phrase better than "parentheses
should be interpreted literally." That's a little vague to me.
And *bold_italic* for variables was somehow obvious to me, but I agree with
[1] that it could also be made explicit, too.
On Tue, Jan 25, 2022 at 2:21 PM David G. Johnston <
[email protected]> wrote:
> 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: <CADQBm3QcndPBjeNVswur=KupHzHeVYWU5wHNSSJL-0qnTTNgqQ@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