doc: clarify syntax notation, particularly parentheses

Also move TCL syntax to the PL/tcl section.

Reported-by: [email protected]
Discussion: https://postgr.es/m/164308146320.12460.3590769444508751574@wrigleys.postgresql.org

Backpatch-through: 10

diff --git a/doc/src/sgml/notation.sgml b/doc/src/sgml/notation.sgml
index bd1e8f629a6cc1b97959b0737a3b248802e096f0..c3798d5f1bed9f59806a24c45e9a522a7f9d46d8 100644 (file)
--- 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 1759fc44985d6dde76126b810340d4ff452ba1a7..9839e375ad3b636a6fd8a970b071e697da043bf7 100644 (file)
--- 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>