From 03739f23ff9911aea7d58c9cc0b58109c8ea95a6 Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Wed, 2 Feb 2022 21:53:51 -0500
Subject: [PATCH] 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
---
doc/src/sgml/notation.sgml | 6 +++---
doc/src/sgml/pltcl.sgml | 6 ++++--
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>
--
2.39.5