Thread: Conventions
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.
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? -- Bruce Momjian <bruce@momjian.us> https://momjian.us EDB https://enterprisedb.com If only the physical world exists, free will is an illusion.
Attachment
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.
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 <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.
"David G. Johnston" <david.g.johnston@gmail.com> writes:
> 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.
+1. I mean, if we have to say this for parentheses, what about
commas, dashes, etc?
> 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.
Maybe time to drop the Tcl reference altogether? I like that language,
but I fear it's next door to dead, so it certainly doesn't need to be
mentioned outside the pltcl docs.
regards, tom lane
On Tue, Jan 25, 2022 at 07:15:45PM -0500, Tom Lane wrote: > "David G. Johnston" <david.g.johnston@gmail.com> writes: > > 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. > > +1. I mean, if we have to say this for parentheses, what about > commas, dashes, etc? > > > 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. > > Maybe time to drop the Tcl reference altogether? I like that language, > but I fear it's next door to dead, so it certainly doesn't need to be > mentioned outside the pltcl docs. How is this patch? -- Bruce Momjian <bruce@momjian.us> https://momjian.us EDB https://enterprisedb.com If only the physical world exists, free will is an illusion.
Attachment
Bruce Momjian <bruce@momjian.us> writes:
> How is this patch?
I'd still drop the Tcl bit, or if you must have it, move it to
pltcl.sgml. Otherwise OK by me.
regards, tom lane
On Tuesday, January 25, 2022, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Bruce Momjian <bruce@momjian.us> writes:
> How is this patch?
I'd still drop the Tcl bit, or if you must have it, move it to
pltcl.sgml. Otherwise OK by me.
Agreed.
David J.
I'm good with it. Thank you!
On Tue, Jan 25, 2022 at 6:15 PM David G. Johnston <david.g.johnston@gmail.com> wrote:
On Tuesday, January 25, 2022, Tom Lane <tgl@sss.pgh.pa.us> wrote:Bruce Momjian <bruce@momjian.us> writes:
> How is this patch?
I'd still drop the Tcl bit, or if you must have it, move it to
pltcl.sgml. Otherwise OK by me.
Agreed.David J.
On Tue, Jan 25, 2022 at 06:45:47PM -0800, Dave Stewart wrote: > I'm good with it. Thank you! OK, updated patch attached. I don't think we even show TCL syntax anywhere anymore, so I removed that text, rather than moving it. -- Bruce Momjian <bruce@momjian.us> https://momjian.us EDB https://enterprisedb.com If only the physical world exists, free will is an illusion.
Attachment
Bruce Momjian <bruce@momjian.us> writes:
> OK, updated patch attached. I don't think we even show TCL syntax
> anywhere anymore, so I removed that text, rather than moving it.
WFM.
regards, tom lane
On 2022-Jan-26, Bruce Momjian wrote: > On Tue, Jan 25, 2022 at 06:45:47PM -0800, Dave Stewart wrote: > > I'm good with it. Thank you! > > OK, updated patch attached. I don't think we even show TCL syntax > anywhere anymore, so I removed that text, rather than moving it. We do here: https://www.postgresql.org/docs/14/pltcl-dbaccess.html Maybe not worth bothering, though. I think it should be obvious to someone already familiar with the language; and for those who aren't, they probably won't be reading this page. -- Álvaro Herrera 39°49'30"S 73°17'W — https://www.EnterpriseDB.com/ "Every machine is a smoke machine if you operate it wrong enough." https://twitter.com/libseybieda/status/1541673325781196801
On Wed, Jan 26, 2022 at 02:01:40PM -0300, Álvaro Herrera wrote: > On 2022-Jan-26, Bruce Momjian wrote: > > > On Tue, Jan 25, 2022 at 06:45:47PM -0800, Dave Stewart wrote: > > > I'm good with it. Thank you! > > > > OK, updated patch attached. I don't think we even show TCL syntax > > anywhere anymore, so I removed that text, rather than moving it. > > We do here: > https://www.postgresql.org/docs/14/pltcl-dbaccess.html > Maybe not worth bothering, though. I think it should be obvious to > someone already familiar with the language; and for those who aren't, > they probably won't be reading this page. Oh, that helps. I looked for '?' in pltcl.sgml and when I couldn't find any, I think the use of the question-mark syntax was gone, but I do see it in the output: https://www.postgresql.org/docs/14/pltcl-dbaccess.html and then I found this in stylesheet-common.xsl: <!-- Special support for Tcl synopses --> <xsl:template match="optional[@role='tcl']"> --> <xsl:text>?</xsl:text> <xsl:call-template name="inline.charseq"/> <xsl:text>?</xsl:text> </xsl:template> The attached patch moves the TCL syntax mention to a more appropriate place. -- Bruce Momjian <bruce@momjian.us> https://momjian.us EDB https://enterprisedb.com If only the physical world exists, free will is an illusion.
Attachment
Bruce Momjian <bruce@momjian.us> writes:
> OK, updated patch attached. I don't think we even show TCL syntax
> anywhere anymore, so I removed that text, rather than moving it.
I really don't care for this phrasing at all:
- the body of a PL/Tcl function:
+ the body of a PL/Tcl function (brackets (<literal>[</literal> and
+ <literal>]</literal>) are represented here as question marks):
It's unclear whether you mean actual brackets or metasyntactic brackets;
somebody who hasn't completely internalized the notion of brackets as
indicating optional elements would be particularly likely to
misunderstand.
I'd also suggest that wedging this into a parenthetic remark between a
sentence and the example the sentence is talking about is awkward.
I'd suggest a separate para at some point before the first usage,
along the lines of
In this section, we follow the usual Tcl convention of using question
marks, rather than brackets, to indicate an optional element in a
syntax synopsis.
regards, tom lane
On Wed, Jan 26, 2022 at 09:33:58PM -0500, Tom Lane wrote: > Bruce Momjian <bruce@momjian.us> writes: > > OK, updated patch attached. I don't think we even show TCL syntax > > anywhere anymore, so I removed that text, rather than moving it. > > I really don't care for this phrasing at all: > > - the body of a PL/Tcl function: > + the body of a PL/Tcl function (brackets (<literal>[</literal> and > + <literal>]</literal>) are represented here as question marks): > > It's unclear whether you mean actual brackets or metasyntactic brackets; > somebody who hasn't completely internalized the notion of brackets as > indicating optional elements would be particularly likely to > misunderstand. > > I'd also suggest that wedging this into a parenthetic remark between a > sentence and the example the sentence is talking about is awkward. > > I'd suggest a separate para at some point before the first usage, > along the lines of > > In this section, we follow the usual Tcl convention of using question > marks, rather than brackets, to indicate an optional element in a > syntax synopsis. Oh, then I didn't understand it either. I know Tcl uses brackets for stuff so I thought there was some weird syntax that represented brackets as something else. Anyway, updated patch attached. -- Bruce Momjian <bruce@momjian.us> https://momjian.us EDB https://enterprisedb.com If only the physical world exists, free will is an illusion.
Attachment
On Wed, Jan 26, 2022 at 09:51:53PM -0500, Bruce Momjian wrote: > > I'd suggest a separate para at some point before the first usage, > > along the lines of > > > > In this section, we follow the usual Tcl convention of using question > > marks, rather than brackets, to indicate an optional element in a > > syntax synopsis. > > Oh, then I didn't understand it either. I know Tcl uses brackets for > stuff so I thought there was some weird syntax that represented brackets > as something else. Anyway, updated patch attached. Patch applied to all supported versions. Dave, thanks for pointing out this problem. -- Bruce Momjian <bruce@momjian.us> https://momjian.us EDB https://enterprisedb.com If only the physical world exists, free will is an illusion.