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 2f350a329df89f750b47deb8ed70cab1e611a78a..245fed04233ebf4ead924cfd959e8a84b43aac1f 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>?</>) 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>...</>) 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 23af32583a5c8cf849cce70dded3a9dc2d603d11..c1c08e5db69991712af7edf258b1b031c28951fa 100644 (file)
--- a/doc/src/sgml/pltcl.sgml
+++ b/doc/src/sgml/pltcl.sgml
@@ -307,8 +307,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>