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 1nCUQW-0005fV-PI for pgsql-docs@arkaria.postgresql.org; Tue, 25 Jan 2022 22:36:36 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1nCUQU-000440-KB for pgsql-docs@arkaria.postgresql.org; Tue, 25 Jan 2022 22:36:34 +0000 Received: from makus.postgresql.org ([2001:4800:3e1:1::229]) by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1nCUQU-00043r-6A for pgsql-docs@lists.postgresql.org; Tue, 25 Jan 2022 22:36:34 +0000 Received: from mail-ot1-x330.google.com ([2607:f8b0:4864:20::330]) by makus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1nCUQN-0005o5-EZ for pgsql-docs@lists.postgresql.org; Tue, 25 Jan 2022 22:36:33 +0000 Received: by mail-ot1-x330.google.com with SMTP id b17-20020a9d4791000000b005a17fc2dfc1so227878otf.1 for ; Tue, 25 Jan 2022 14:36:27 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:references:in-reply-to:reply-to:from:date:message-id :subject:to:cc; bh=jItyLWxAT345Vsh5BkE+TK/AUSSLl0Xv+wWFCaoWoWI=; b=FCElzJ6Xcx39FTm3JZ16MjotLZZqT9zy7/IeUUJAl1e10uoBRZ57evaPNsDFYpHlpc J+3iQut33wCvyDrJ/P+qOBIwxtMNX989UlwlM3ltgYZfwZxJQyHQc75A3q2CaxUpR/xO QhbKrEFPTRB1WmGcia/RbDUVJLzU48efUY95nYg/WqbR2CeM1amtlpd6Kv6l4wgmAMjF k2l/VRzvUyoHskU/sdjXA+toxO65HWiOG4ZyOWcwiZVJ0FKfCIlPFY162OlZ7zomPstF x21KT934ao4KnohZBEPzfjsv2HL12KaeVJ/36UKokspKNqWg1EpeAxCid170Or/9X/ZX ILRQ== 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:reply-to :from:date:message-id:subject:to:cc; bh=jItyLWxAT345Vsh5BkE+TK/AUSSLl0Xv+wWFCaoWoWI=; b=PSmrG17Lwesz8uNSaRnLlbfZCNWvvCJ3j5bHrQOZcuauiBUn69zRh/aFVe+3wtNnCy +hnFSdmzWs1ih2/EUaF6eU7jwJPqwLO+JGHAy6FXanRwpdBZQxCADhBY62TRCnDrZxwI b+ET/ZT69WkTifJL2qnwwBodO3DfAjgDVp+FPsdp9/UUzu45yFV77NASjRKd4uZXySAd lFYtOO1rCQkIEY4S/MHLiD5SWGEvB8lQcymIDemgh+F0ZZweb6Lt9moZDwAjkiYJ7lhy e9+jHs0BNy6FINGQYkg1xO1Sb+e7vlKt/+yes43YNm21cXToiQWpdl+NADylFVe9QUQM S8sg== X-Gm-Message-State: AOAM531gRtb14wnvGVpnDDtZ8nJuo2GQDn3ciatN2/rnTHQKXKYcDiEx pXm2hiVlJ5UeF71e2FyCQtoV0hB9NdaFKER02HY= X-Google-Smtp-Source: ABdhPJwD8Cxc+DPjDv0DQZQ5WgAoOGmUioTKwE9OdGkfM7vcfuv6j7iaHTrJzXIBXZmZFaVRKH/Au/iQ8/W1CkWQi7g= X-Received: by 2002:a05:6830:12c1:: with SMTP id a1mr16028782otq.286.1643150186403; Tue, 25 Jan 2022 14:36:26 -0800 (PST) MIME-Version: 1.0 References: <164308146320.12460.3590769444508751574@wrigleys.postgresql.org> In-Reply-To: Reply-To: davs2rt@gmail.com From: Dave Stewart Date: Tue, 25 Jan 2022 14:35:50 -0800 Message-ID: Subject: Re: Conventions To: "David G. Johnston" Cc: Bruce Momjian , Pg Docs Content-Type: multipart/alternative; boundary="0000000000002c5c7005d66fb778" List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Archived-At: Precedence: bulk --0000000000002c5c7005d66fb778 Content-Type: text/plain; charset="UTF-8" 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.johnston@gmail.com> wrote: > 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. > > --0000000000002c5c7005d66fb778 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Tha= nks, all, for considering this update.

I like the "anything not noted here..." phrase bett= er than "parentheses should be interpreted literally."=C2=A0 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.johnston@gmail.com> wrote:
On Tue, = Jan 25, 2022 at 1:24 PM Bruce Momjian <bruce@momjian.us> wrote:
=
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>

--0000000000002c5c7005d66fb778--