Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1nCUCC-0004rl-Pk for pgsql-docs@arkaria.postgresql.org; Tue, 25 Jan 2022 22:21:48 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1nCUBg-00087m-3M for pgsql-docs@arkaria.postgresql.org; Tue, 25 Jan 2022 22:21:16 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1nCUBf-00087a-Pb for pgsql-docs@lists.postgresql.org; Tue, 25 Jan 2022 22:21:15 +0000 Received: from mail-ua1-x933.google.com ([2607:f8b0:4864:20::933]) by magus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1nCUBb-0000Of-Mc for pgsql-docs@lists.postgresql.org; Tue, 25 Jan 2022 22:21:15 +0000 Received: by mail-ua1-x933.google.com with SMTP id e17so1257007uad.9 for ; Tue, 25 Jan 2022 14:21:11 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=OAifhjfzj6OeudZehgCvIVN4s33oeGfSQDU6mZDyA8Y=; b=lyWa+5YOpxN94bE4qJspladhIOEwMAD1c4SSWbkpef7lfsid9ttJNzfOLgm7wptfo4 rs3qylZFy0FE5W6FCiD065eZFtb7zaiOpZ5odNB7Pbr8OTdaaj1YTsGlfaYu/cwOODiR 8Pv3Gc8Ek/Futy/fyN+WHg2KRnM3F7ZiDCY+Y+A0BBSixcyFyv6iPWZTPoTMEwT77aAF cRPJ3I69xvhpnAw0Y/1brek7449JyJQC3Ezxc+nmE0dJ8ZNClsyNoK9MjYUwk9kpFFbL ve+t7bD9UI9lXaYUKAljjth0JedSEqNEIf+Uj6XtgwXsXUBKlidfrOECsyB23j0XvwQG RpWw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=OAifhjfzj6OeudZehgCvIVN4s33oeGfSQDU6mZDyA8Y=; b=bNtExiwlxlBeuk+OIVtgGI2vvwL4+gZPBzPKnR61irX1D3avz3f6+YNFlVnJZ2b36W TkBg0bexNyjci8k0toJF+5GusGXcC+tdeSrfN6TTGaZXKMII9re+OES4GSCS/Jg04vVK fyvVmOB3L3t3pTovXmhJXJK8AgVARpNZxIaWpY+HmkPkyk21xs9qkKRB3Vxr2cLLPoh1 KfGMmFdTh1TkKsLLp25BB4LRwIhPqum0dhBRLK/82+KHA7ACnsMxNfFfS8T1PlrU7d5d SpGcUQdWabdoDdu4AY3chQ+s0LtYzukPSr+EK/t/j5znVV2BUmdozNM9YVW59KjRsQmu C0vA== X-Gm-Message-State: AOAM531xvg+Q8s3Bqj6fDmPhZprPPHcIMRjwFF74SXwiq/YJ/z63aqhr BHuwZZ9Hi6BJzL8WUZ7Xaxevlsh5HgVR9n/X+zg= X-Google-Smtp-Source: ABdhPJzQmP0ghoEX8VlzrTIoedtDJkMHPkFcLO1wIpL6tZ9smD9yRl4/GxREAElA4rjAfL1ry9jZLn6X3/NnjiUefl8= X-Received: by 2002:a67:b741:: with SMTP id l1mr4385152vsh.40.1643149269699; Tue, 25 Jan 2022 14:21:09 -0800 (PST) MIME-Version: 1.0 References: <164308146320.12460.3590769444508751574@wrigleys.postgresql.org> In-Reply-To: From: "David G. Johnston" Date: Tue, 25 Jan 2022 15:20:52 -0700 Message-ID: Subject: Re: Conventions To: Bruce Momjian Cc: davs2rt@gmail.com, Pg Docs Content-Type: multipart/alternative; boundary="0000000000008891da05d66f8041" List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Archived-At: Precedence: bulk --0000000000008891da05d66f8041 Content-Type: text/plain; charset="UTF-8" On Tue, Jan 25, 2022 at 1:24 PM Bruce Momjian 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. --0000000000008891da05d66f8041 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
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 w= rote:
> The following documentation comment has been logged on the website: >
> Page: https://www.postgresql.org/docs/12/notati= on.html
> Description:
>
> In section 3, Conventions, it would be helpful to point out that
> parentheses, when used in the command descriptions, are to be interpre= ted as
> literal required elements.=C2=A0 As a newbie, the combination of {}, [= ], () was
> already difficult to parse in command descriptions.=C2=A0 =C2=A0Worse = when the
> Conventions element doesn't describe parentheses use in the defini= tions.
> Here's a simple example where the parens are easy to miss, and it&= #39;s not
> otherwise clear what they do:
>
> CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ = IF NOT
> EXISTS ] table_name ( [
>=C2=A0 =C2=A0{ column_name data_type [ COLLATE collation ] [ column_con= straint [ ... ]
> ]
>=C2=A0 =C2=A0 =C2=A0| table_constraint
>=C2=A0 =C2=A0 =C2=A0| LIKE source_table [ like_option ... ] }
>=C2=A0 =C2=A0 =C2=A0[, ... ]
> ] )
> [ INHERITS ( parent_table [, ... ] ) ]
> [ PARTITION BY { RANGE | LIST | HASH } ( { column_name | ( expression = ) } [
> COLLATE collation ] [ opclass ] [, ... ] ) ]
> [ USING method ]
> [ WITH ( storage_parameter [=3D 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.=C2=A0 How is this patch?

Just= like with brackets and braces on that page you should add the parentheses= =C2=A0symbols.....in parentheses....:(...like this:=C2=A0 (( and )).=C2=A0 = 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 mentione= d...

I'd probably rather make that implied part ex= plicit and avoid mentioning parentheses explicitly.

I = would suggest moving the Tcl parenthetical to its own sentence.=C2=A0 The p= ercentage 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 p= reface to enlighten them.

[1] I'm not really sure how you define the convention that "paren= t_table" and "storage_parameter" should not be treated as li= teral tokens but basically variables which you replace with values.

David J.<= /div>

--0000000000008891da05d66f8041--