Conventions

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.

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]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. - 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.
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:

"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.

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 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.

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.

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.

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.