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