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.g.johns...@gmail.com> wrote: > On Tue, Jan 25, 2022 at 1:24 PM Bruce Momjian <br...@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. > >
