Re: Conventions

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 <
david(dot)g(dot)johnston(at)gmail(dot)com> wrote:

> On Tue, Jan 25, 2022 at 1:24 PM Bruce Momjian <bruce(at)momjian(dot)us> 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.
>
>