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 @@
  
   The following conventions are used in the synopsis of a command:
   brackets ([ and ]) indicate
-  optional parts.  (In the synopsis of a Tcl command, question marks
-  (?) are used instead, as is usual in Tcl.)  Braces
+  optional parts.  Braces
   ({ and }) and vertical lines
   (|) indicate that you must choose one
   alternative.  Dots (...) mean that the preceding element
-  can be repeated.
+  can be repeated.  All other symbols, including parentheses, should be
+  taken literally.
  
 
  

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;
     Database Access from PL/Tcl
 
     
-     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: