Re: Conventions

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