doc: clarify syntax notation, particularly parentheses

Also move TCL syntax to the PL/tcl section.

Reported-by: davs2rt@gmail.com

Discussion: https://postgr.es/m/164308146320.12460.3590769444508751574@wrigleys.postgresql.org

Backpatch-through: 10

2 files changed, 7 insertions, 5 deletions

diff --git a/doc/src/sgml/notation.sgml b/doc/src/sgml/notation.sgml
index 2f350a329df..245fed04233 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>?</>) 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 23af32583a5..c1c08e5db69 100644
--- 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>