public inbox for [email protected]
help / color / mirror / Atom feedConventions
16+ messages / 6 participants
[nested] [flat]
* Conventions
@ 2022-01-25 03:31 PG Doc comments form <[email protected]>
2022-01-25 20:24 ` Re: Conventions Bruce Momjian <[email protected]>
0 siblings, 1 reply; 16+ messages in thread
From: PG Doc comments form @ 2022-01-25 03:31 UTC (permalink / raw)
To: [email protected]; +Cc: [email protected]
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.
^ permalink raw reply [nested|flat] 16+ messages in thread
* Re: Conventions
2022-01-25 03:31 Conventions PG Doc comments form <[email protected]>
@ 2022-01-25 20:24 ` Bruce Momjian <[email protected]>
2022-01-25 22:20 ` Re: Conventions David G. Johnston <[email protected]>
0 siblings, 1 reply; 16+ messages in thread
From: Bruce Momjian @ 2022-01-25 20:24 UTC (permalink / raw)
To: [email protected]; [email protected]
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 <[email protected]> https://momjian.us
EDB https://enterprisedb.com
If only the physical world exists, free will is an illusion.
Attachments:
[text/x-diff] paren.diff (505B, 2-paren.diff)
download | inline diff:
diff --git a/doc/src/sgml/notation.sgml b/doc/src/sgml/notation.sgml
index bd1e8f629a..77499e8507 100644
--- a/doc/src/sgml/notation.sgml
+++ b/doc/src/sgml/notation.sgml
@@ -11,7 +11,7 @@
(<literal>{</literal> and <literal>}</literal>) and vertical lines
(<literal>|</literal>) indicate that you must choose one
alternative. Dots (<literal>...</literal>) mean that the preceding element
- can be repeated.
+ can be repeated. Parentheses should be interpreted literally.
</para>
<para>
^ permalink raw reply [nested|flat] 16+ messages in thread
* Re: Conventions
2022-01-25 03:31 Conventions PG Doc comments form <[email protected]>
2022-01-25 20:24 ` Re: Conventions Bruce Momjian <[email protected]>
@ 2022-01-25 22:20 ` David G. Johnston <[email protected]>
2022-01-25 22:35 ` Re: Conventions Dave Stewart <[email protected]>
2022-01-26 00:15 ` Re: Conventions Tom Lane <[email protected]>
0 siblings, 2 replies; 16+ messages in thread
From: David G. Johnston @ 2022-01-25 22:20 UTC (permalink / raw)
To: Bruce Momjian <[email protected]>; +Cc: [email protected]; Pg Docs <[email protected]>
On Tue, Jan 25, 2022 at 1:24 PM Bruce Momjian <[email protected]> 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.
^ permalink raw reply [nested|flat] 16+ messages in thread
* Re: Conventions
2022-01-25 03:31 Conventions PG Doc comments form <[email protected]>
2022-01-25 20:24 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-25 22:20 ` Re: Conventions David G. Johnston <[email protected]>
@ 2022-01-25 22:35 ` Dave Stewart <[email protected]>
1 sibling, 0 replies; 16+ messages in thread
From: Dave Stewart @ 2022-01-25 22:35 UTC (permalink / raw)
To: David G. Johnston <[email protected]>; +Cc: Bruce Momjian <[email protected]>; Pg Docs <[email protected]>
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 <
[email protected]> wrote:
> On Tue, Jan 25, 2022 at 1:24 PM Bruce Momjian <[email protected]> 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.
>
>
^ permalink raw reply [nested|flat] 16+ messages in thread
* Re: Conventions
2022-01-25 03:31 Conventions PG Doc comments form <[email protected]>
2022-01-25 20:24 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-25 22:20 ` Re: Conventions David G. Johnston <[email protected]>
@ 2022-01-26 00:15 ` Tom Lane <[email protected]>
2022-01-26 01:35 ` Re: Conventions Bruce Momjian <[email protected]>
1 sibling, 1 reply; 16+ messages in thread
From: Tom Lane @ 2022-01-26 00:15 UTC (permalink / raw)
To: David G. Johnston <[email protected]>; +Cc: Bruce Momjian <[email protected]>; [email protected]; Pg Docs <[email protected]>
"David G. Johnston" <[email protected]> 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
^ permalink raw reply [nested|flat] 16+ messages in thread
* Re: Conventions
2022-01-25 03:31 Conventions PG Doc comments form <[email protected]>
2022-01-25 20:24 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-25 22:20 ` Re: Conventions David G. Johnston <[email protected]>
2022-01-26 00:15 ` Re: Conventions Tom Lane <[email protected]>
@ 2022-01-26 01:35 ` Bruce Momjian <[email protected]>
2022-01-26 02:14 ` Re: Conventions Tom Lane <[email protected]>
0 siblings, 1 reply; 16+ messages in thread
From: Bruce Momjian @ 2022-01-26 01:35 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: David G. Johnston <[email protected]>; [email protected]; Pg Docs <[email protected]>
On Tue, Jan 25, 2022 at 07:15:45PM -0500, Tom Lane wrote:
> "David G. Johnston" <[email protected]> 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 <[email protected]> https://momjian.us
EDB https://enterprisedb.com
If only the physical world exists, free will is an illusion.
Attachments:
[text/x-diff] paren.diff (956B, 2-paren.diff)
download | inline diff:
diff --git a/doc/src/sgml/notation.sgml b/doc/src/sgml/notation.sgml
index bd1e8f629a..c0f41569cb 100644
--- a/doc/src/sgml/notation.sgml
+++ b/doc/src/sgml/notation.sgml
@@ -6,12 +6,13 @@
<para>
The following conventions are used in the synopsis of a command:
brackets (<literal>[</literal> and <literal>]</literal>) indicate
- optional parts. (In the synopsis of a Tcl command, question marks
- (<literal>?</literal>) are used instead, as is usual in Tcl.) Braces
+ optional parts. Braces
(<literal>{</literal> and <literal>}</literal>) and vertical lines
(<literal>|</literal>) indicate that you must choose one
alternative. Dots (<literal>...</literal>) mean that the preceding element
- can be repeated.
+ can be repeated. All other symbols, including parentheses, should be
+ taken literally. (In the synopsis of a Tcl command, question marks
+ (<literal>?</literal>) are used instead of brackets.)
</para>
<para>
^ permalink raw reply [nested|flat] 16+ messages in thread
* Re: Conventions
2022-01-25 03:31 Conventions PG Doc comments form <[email protected]>
2022-01-25 20:24 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-25 22:20 ` Re: Conventions David G. Johnston <[email protected]>
2022-01-26 00:15 ` Re: Conventions Tom Lane <[email protected]>
2022-01-26 01:35 ` Re: Conventions Bruce Momjian <[email protected]>
@ 2022-01-26 02:14 ` Tom Lane <[email protected]>
2022-01-26 02:15 ` Re: Conventions David G. Johnston <[email protected]>
0 siblings, 1 reply; 16+ messages in thread
From: Tom Lane @ 2022-01-26 02:14 UTC (permalink / raw)
To: Bruce Momjian <[email protected]>; +Cc: David G. Johnston <[email protected]>; [email protected]; Pg Docs <[email protected]>
Bruce Momjian <[email protected]> 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
^ permalink raw reply [nested|flat] 16+ messages in thread
* Re: Conventions
2022-01-25 03:31 Conventions PG Doc comments form <[email protected]>
2022-01-25 20:24 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-25 22:20 ` Re: Conventions David G. Johnston <[email protected]>
2022-01-26 00:15 ` Re: Conventions Tom Lane <[email protected]>
2022-01-26 01:35 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-26 02:14 ` Re: Conventions Tom Lane <[email protected]>
@ 2022-01-26 02:15 ` David G. Johnston <[email protected]>
2022-01-26 02:45 ` Re: Conventions Dave Stewart <[email protected]>
0 siblings, 1 reply; 16+ messages in thread
From: David G. Johnston @ 2022-01-26 02:15 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: Bruce Momjian <[email protected]>; [email protected] <[email protected]>; Pg Docs <[email protected]>
On Tuesday, January 25, 2022, Tom Lane <[email protected]> wrote:
> Bruce Momjian <[email protected]> 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.
^ permalink raw reply [nested|flat] 16+ messages in thread
* Re: Conventions
2022-01-25 03:31 Conventions PG Doc comments form <[email protected]>
2022-01-25 20:24 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-25 22:20 ` Re: Conventions David G. Johnston <[email protected]>
2022-01-26 00:15 ` Re: Conventions Tom Lane <[email protected]>
2022-01-26 01:35 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-26 02:14 ` Re: Conventions Tom Lane <[email protected]>
2022-01-26 02:15 ` Re: Conventions David G. Johnston <[email protected]>
@ 2022-01-26 02:45 ` Dave Stewart <[email protected]>
2022-01-26 15:52 ` Re: Conventions Bruce Momjian <[email protected]>
0 siblings, 1 reply; 16+ messages in thread
From: Dave Stewart @ 2022-01-26 02:45 UTC (permalink / raw)
To: David G. Johnston <[email protected]>; +Cc: Tom Lane <[email protected]>; Bruce Momjian <[email protected]>; Pg Docs <[email protected]>
I'm good with it. Thank you!
On Tue, Jan 25, 2022 at 6:15 PM David G. Johnston <
[email protected]> wrote:
> On Tuesday, January 25, 2022, Tom Lane <[email protected]> wrote:
>
>> Bruce Momjian <[email protected]> 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.
>
^ permalink raw reply [nested|flat] 16+ messages in thread
* Re: Conventions
2022-01-25 03:31 Conventions PG Doc comments form <[email protected]>
2022-01-25 20:24 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-25 22:20 ` Re: Conventions David G. Johnston <[email protected]>
2022-01-26 00:15 ` Re: Conventions Tom Lane <[email protected]>
2022-01-26 01:35 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-26 02:14 ` Re: Conventions Tom Lane <[email protected]>
2022-01-26 02:15 ` Re: Conventions David G. Johnston <[email protected]>
2022-01-26 02:45 ` Re: Conventions Dave Stewart <[email protected]>
@ 2022-01-26 15:52 ` Bruce Momjian <[email protected]>
2022-01-26 15:56 ` Re: Conventions Tom Lane <[email protected]>
2022-01-26 17:01 ` Re: Conventions Alvaro Herrera <[email protected]>
0 siblings, 2 replies; 16+ messages in thread
From: Bruce Momjian @ 2022-01-26 15:52 UTC (permalink / raw)
To: Dave Stewart <[email protected]>; +Cc: David G. Johnston <[email protected]>; Tom Lane <[email protected]>; Pg Docs <[email protected]>
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 <[email protected]> https://momjian.us
EDB https://enterprisedb.com
If only the physical world exists, free will is an illusion.
Attachments:
[text/x-diff] paren.diff (848B, 2-paren.diff)
download | inline diff:
diff --git a/doc/src/sgml/notation.sgml b/doc/src/sgml/notation.sgml
index bd1e8f629a..c3798d5f1b 100644
--- a/doc/src/sgml/notation.sgml
+++ b/doc/src/sgml/notation.sgml
@@ -6,12 +6,12 @@
<para>
The following conventions are used in the synopsis of a command:
brackets (<literal>[</literal> and <literal>]</literal>) indicate
- optional parts. (In the synopsis of a Tcl command, question marks
- (<literal>?</literal>) are used instead, as is usual in Tcl.) Braces
+ optional parts. Braces
(<literal>{</literal> and <literal>}</literal>) and vertical lines
(<literal>|</literal>) indicate that you must choose one
alternative. Dots (<literal>...</literal>) mean that the preceding element
- can be repeated.
+ can be repeated. All other symbols, including parentheses, should be
+ taken literally.
</para>
<para>
^ permalink raw reply [nested|flat] 16+ messages in thread
* Re: Conventions
2022-01-25 03:31 Conventions PG Doc comments form <[email protected]>
2022-01-25 20:24 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-25 22:20 ` Re: Conventions David G. Johnston <[email protected]>
2022-01-26 00:15 ` Re: Conventions Tom Lane <[email protected]>
2022-01-26 01:35 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-26 02:14 ` Re: Conventions Tom Lane <[email protected]>
2022-01-26 02:15 ` Re: Conventions David G. Johnston <[email protected]>
2022-01-26 02:45 ` Re: Conventions Dave Stewart <[email protected]>
2022-01-26 15:52 ` Re: Conventions Bruce Momjian <[email protected]>
@ 2022-01-26 15:56 ` Tom Lane <[email protected]>
1 sibling, 0 replies; 16+ messages in thread
From: Tom Lane @ 2022-01-26 15:56 UTC (permalink / raw)
To: Bruce Momjian <[email protected]>; +Cc: Dave Stewart <[email protected]>; David G. Johnston <[email protected]>; Pg Docs <[email protected]>
Bruce Momjian <[email protected]> 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
^ permalink raw reply [nested|flat] 16+ messages in thread
* Re: Conventions
2022-01-25 03:31 Conventions PG Doc comments form <[email protected]>
2022-01-25 20:24 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-25 22:20 ` Re: Conventions David G. Johnston <[email protected]>
2022-01-26 00:15 ` Re: Conventions Tom Lane <[email protected]>
2022-01-26 01:35 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-26 02:14 ` Re: Conventions Tom Lane <[email protected]>
2022-01-26 02:15 ` Re: Conventions David G. Johnston <[email protected]>
2022-01-26 02:45 ` Re: Conventions Dave Stewart <[email protected]>
2022-01-26 15:52 ` Re: Conventions Bruce Momjian <[email protected]>
@ 2022-01-26 17:01 ` Alvaro Herrera <[email protected]>
2022-01-26 23:32 ` Re: Conventions Bruce Momjian <[email protected]>
1 sibling, 1 reply; 16+ messages in thread
From: Alvaro Herrera @ 2022-01-26 17:01 UTC (permalink / raw)
To: Bruce Momjian <[email protected]>; +Cc: Dave Stewart <[email protected]>; David G. Johnston <[email protected]>; Tom Lane <[email protected]>; Pg Docs <[email protected]>
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
^ permalink raw reply [nested|flat] 16+ messages in thread
* Re: Conventions
2022-01-25 03:31 Conventions PG Doc comments form <[email protected]>
2022-01-25 20:24 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-25 22:20 ` Re: Conventions David G. Johnston <[email protected]>
2022-01-26 00:15 ` Re: Conventions Tom Lane <[email protected]>
2022-01-26 01:35 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-26 02:14 ` Re: Conventions Tom Lane <[email protected]>
2022-01-26 02:15 ` Re: Conventions David G. Johnston <[email protected]>
2022-01-26 02:45 ` Re: Conventions Dave Stewart <[email protected]>
2022-01-26 15:52 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-26 17:01 ` Re: Conventions Alvaro Herrera <[email protected]>
@ 2022-01-26 23:32 ` Bruce Momjian <[email protected]>
2022-01-27 02:33 ` Re: Conventions Tom Lane <[email protected]>
0 siblings, 1 reply; 16+ messages in thread
From: Bruce Momjian @ 2022-01-26 23:32 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Dave Stewart <[email protected]>; David G. Johnston <[email protected]>; Tom Lane <[email protected]>; Pg Docs <[email protected]>
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 <[email protected]> https://momjian.us
EDB https://enterprisedb.com
If only the physical world exists, free will is an illusion.
Attachments:
[text/x-diff] paren.diff (1.3K, 2-paren.diff)
download | inline diff:
diff --git a/doc/src/sgml/notation.sgml b/doc/src/sgml/notation.sgml
index bd1e8f629a..c3798d5f1b 100644
--- a/doc/src/sgml/notation.sgml
+++ b/doc/src/sgml/notation.sgml
@@ -6,12 +6,12 @@
<para>
The following conventions are used in the synopsis of a command:
brackets (<literal>[</literal> and <literal>]</literal>) indicate
- optional parts. (In the synopsis of a Tcl command, question marks
- (<literal>?</literal>) are used instead, as is usual in Tcl.) Braces
+ optional parts. Braces
(<literal>{</literal> and <literal>}</literal>) and vertical lines
(<literal>|</literal>) indicate that you must choose one
alternative. Dots (<literal>...</literal>) mean that the preceding element
- can be repeated.
+ can be repeated. All other symbols, including parentheses, should be
+ taken literally.
</para>
<para>
diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml
index 1759fc4498..6ef968e078 100644
--- a/doc/src/sgml/pltcl.sgml
+++ b/doc/src/sgml/pltcl.sgml
@@ -321,7 +321,8 @@ $$ LANGUAGE pltcl;
<para>
The following commands are available to access the database from
- 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):
<variablelist>
^ permalink raw reply [nested|flat] 16+ messages in thread
* Re: Conventions
2022-01-25 03:31 Conventions PG Doc comments form <[email protected]>
2022-01-25 20:24 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-25 22:20 ` Re: Conventions David G. Johnston <[email protected]>
2022-01-26 00:15 ` Re: Conventions Tom Lane <[email protected]>
2022-01-26 01:35 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-26 02:14 ` Re: Conventions Tom Lane <[email protected]>
2022-01-26 02:15 ` Re: Conventions David G. Johnston <[email protected]>
2022-01-26 02:45 ` Re: Conventions Dave Stewart <[email protected]>
2022-01-26 15:52 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-26 17:01 ` Re: Conventions Alvaro Herrera <[email protected]>
2022-01-26 23:32 ` Re: Conventions Bruce Momjian <[email protected]>
@ 2022-01-27 02:33 ` Tom Lane <[email protected]>
2022-01-27 02:51 ` Re: Conventions Bruce Momjian <[email protected]>
0 siblings, 1 reply; 16+ messages in thread
From: Tom Lane @ 2022-01-27 02:33 UTC (permalink / raw)
To: Bruce Momjian <[email protected]>; +Cc: Alvaro Herrera <[email protected]>; Dave Stewart <[email protected]>; David G. Johnston <[email protected]>; Pg Docs <[email protected]>
Bruce Momjian <[email protected]> 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
^ permalink raw reply [nested|flat] 16+ messages in thread
* Re: Conventions
2022-01-25 03:31 Conventions PG Doc comments form <[email protected]>
2022-01-25 20:24 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-25 22:20 ` Re: Conventions David G. Johnston <[email protected]>
2022-01-26 00:15 ` Re: Conventions Tom Lane <[email protected]>
2022-01-26 01:35 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-26 02:14 ` Re: Conventions Tom Lane <[email protected]>
2022-01-26 02:15 ` Re: Conventions David G. Johnston <[email protected]>
2022-01-26 02:45 ` Re: Conventions Dave Stewart <[email protected]>
2022-01-26 15:52 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-26 17:01 ` Re: Conventions Alvaro Herrera <[email protected]>
2022-01-26 23:32 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-27 02:33 ` Re: Conventions Tom Lane <[email protected]>
@ 2022-01-27 02:51 ` Bruce Momjian <[email protected]>
2022-02-03 02:54 ` Re: Conventions Bruce Momjian <[email protected]>
0 siblings, 1 reply; 16+ messages in thread
From: Bruce Momjian @ 2022-01-27 02:51 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: Alvaro Herrera <[email protected]>; Dave Stewart <[email protected]>; David G. Johnston <[email protected]>; Pg Docs <[email protected]>
On Wed, Jan 26, 2022 at 09:33:58PM -0500, Tom Lane wrote:
> Bruce Momjian <[email protected]> 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 <[email protected]> https://momjian.us
EDB https://enterprisedb.com
If only the physical world exists, free will is an illusion.
Attachments:
[text/x-diff] paren.diff (1.5K, 2-paren.diff)
download | inline diff:
diff --git a/doc/src/sgml/notation.sgml b/doc/src/sgml/notation.sgml
index bd1e8f629a..c3798d5f1b 100644
--- a/doc/src/sgml/notation.sgml
+++ b/doc/src/sgml/notation.sgml
@@ -6,12 +6,12 @@
<para>
The following conventions are used in the synopsis of a command:
brackets (<literal>[</literal> and <literal>]</literal>) indicate
- optional parts. (In the synopsis of a Tcl command, question marks
- (<literal>?</literal>) are used instead, as is usual in Tcl.) Braces
+ optional parts. Braces
(<literal>{</literal> and <literal>}</literal>) and vertical lines
(<literal>|</literal>) indicate that you must choose one
alternative. Dots (<literal>...</literal>) mean that the preceding element
- can be repeated.
+ can be repeated. All other symbols, including parentheses, should be
+ taken literally.
</para>
<para>
diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml
index 1759fc4498..9839e375ad 100644
--- a/doc/src/sgml/pltcl.sgml
+++ b/doc/src/sgml/pltcl.sgml
@@ -320,8 +320,10 @@ $$ LANGUAGE pltcl;
<title>Database Access from PL/Tcl</title>
<para>
- The following commands are available to access the database from
- the body of a PL/Tcl function:
+ 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. The following commands are available to access
+ the database from the body of a PL/Tcl function:
<variablelist>
^ permalink raw reply [nested|flat] 16+ messages in thread
* Re: Conventions
2022-01-25 03:31 Conventions PG Doc comments form <[email protected]>
2022-01-25 20:24 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-25 22:20 ` Re: Conventions David G. Johnston <[email protected]>
2022-01-26 00:15 ` Re: Conventions Tom Lane <[email protected]>
2022-01-26 01:35 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-26 02:14 ` Re: Conventions Tom Lane <[email protected]>
2022-01-26 02:15 ` Re: Conventions David G. Johnston <[email protected]>
2022-01-26 02:45 ` Re: Conventions Dave Stewart <[email protected]>
2022-01-26 15:52 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-26 17:01 ` Re: Conventions Alvaro Herrera <[email protected]>
2022-01-26 23:32 ` Re: Conventions Bruce Momjian <[email protected]>
2022-01-27 02:33 ` Re: Conventions Tom Lane <[email protected]>
2022-01-27 02:51 ` Re: Conventions Bruce Momjian <[email protected]>
@ 2022-02-03 02:54 ` Bruce Momjian <[email protected]>
0 siblings, 0 replies; 16+ messages in thread
From: Bruce Momjian @ 2022-02-03 02:54 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: Alvaro Herrera <[email protected]>; Dave Stewart <[email protected]>; David G. Johnston <[email protected]>; Pg Docs <[email protected]>
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 <[email protected]> https://momjian.us
EDB https://enterprisedb.com
If only the physical world exists, free will is an illusion.
^ permalink raw reply [nested|flat] 16+ messages in thread
end of thread, other threads:[~2022-02-03 02:54 UTC | newest]
Thread overview: 16+ messages (download: mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2022-01-25 03:31 Conventions PG Doc comments form <[email protected]>
2022-01-25 20:24 ` Bruce Momjian <[email protected]>
2022-01-25 22:20 ` David G. Johnston <[email protected]>
2022-01-25 22:35 ` Dave Stewart <[email protected]>
2022-01-26 00:15 ` Tom Lane <[email protected]>
2022-01-26 01:35 ` Bruce Momjian <[email protected]>
2022-01-26 02:14 ` Tom Lane <[email protected]>
2022-01-26 02:15 ` David G. Johnston <[email protected]>
2022-01-26 02:45 ` Dave Stewart <[email protected]>
2022-01-26 15:52 ` Bruce Momjian <[email protected]>
2022-01-26 15:56 ` Tom Lane <[email protected]>
2022-01-26 17:01 ` Alvaro Herrera <[email protected]>
2022-01-26 23:32 ` Bruce Momjian <[email protected]>
2022-01-27 02:33 ` Tom Lane <[email protected]>
2022-01-27 02:51 ` Bruce Momjian <[email protected]>
2022-02-03 02:54 ` Bruce Momjian <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox