doc: Fix for too many brackets in command synopses on man pages

The default for the choice attribute of the <arg> element is "opt",
which would normally put the argument inside brackets.  But the DSSSL
stylesheets contain a hack that treats <arg> directly inside <group>
specially, so that <group><arg>-x</arg><arg>-y</arg></group> comes out
as [ -x | -y ] rather than [ [-x] | [-y] ], which it would technically
be.  But when building man pages, this doesn't work, and so the
command synopses on the man pages contain lots of extra brackets.

By putting choice="opt" or choice="plain" explicitly on every <arg>
and <group> element, we avoid any toolchain dependencies like that,
and it also makes it clearer in the source code what is meant.

In passing, make some small corrections in the documentation about
which arguments are really optional or not.

16 files changed, 101 insertions, 101 deletions

diff --git a/doc/src/sgml/ref/clusterdb.sgml b/doc/src/sgml/ref/clusterdb.sgml
index e0246b3bca2..097ea912f1c 100644
--- a/doc/src/sgml/ref/clusterdb.sgml
+++ b/doc/src/sgml/ref/clusterdb.sgml
@@ -23,16 +23,16 @@ PostgreSQL documentation
   <cmdsynopsis>
    <command>clusterdb</command>
    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
-   <group><arg><option>--verbose</option></arg><arg><option>-v</option></arg></group>
-   <arg><group choice="plain"><arg><option>--table</option></arg><arg><option>-t</option></arg></group> <replaceable>table</replaceable> </arg>
-   <arg><replaceable>dbname</replaceable></arg>
+   <group choice="opt"><arg choice="plain"><option>--verbose</option></arg><arg choice="plain"><option>-v</option></arg></group>
+   <arg choice="opt"><group choice="plain"><arg choice="plain"><option>--table</option></arg><arg choice="plain"><option>-t</option></arg></group> <replaceable>table</replaceable> </arg>
+   <arg choice="opt"><replaceable>dbname</replaceable></arg>
   </cmdsynopsis>
 
   <cmdsynopsis>
    <command>clusterdb</command>
    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
-   <group><arg><option>--verbose</option></arg><arg><option>-v</option></arg></group>
-   <group><arg><option>--all</option></arg><arg><option>-a</option></arg></group>
+   <group choice="opt"><arg choice="plain"><option>--verbose</option></arg><arg choice="plain"><option>-v</option></arg></group>
+   <group choice="plain"><arg choice="plain"><option>--all</option></arg><arg choice="plain"><option>-a</option></arg></group>
   </cmdsynopsis>
  </refsynopsisdiv>
 
diff --git a/doc/src/sgml/ref/createdb.sgml b/doc/src/sgml/ref/createdb.sgml
index cbbc5c05455..7dbedc2e909 100644
--- a/doc/src/sgml/ref/createdb.sgml
+++ b/doc/src/sgml/ref/createdb.sgml
@@ -24,8 +24,8 @@ PostgreSQL documentation
    <command>createdb</command>
    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
    <arg rep="repeat"><replaceable>option</replaceable></arg>
-   <arg><replaceable>dbname</replaceable></arg>
-   <arg><replaceable>description</replaceable></arg>
+   <arg choice="opt"><replaceable>dbname</replaceable>
+   <arg choice="opt"><replaceable>description</replaceable></arg></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
 
diff --git a/doc/src/sgml/ref/createlang.sgml b/doc/src/sgml/ref/createlang.sgml
index 4ca32fba39a..2bc43627e54 100644
--- a/doc/src/sgml/ref/createlang.sgml
+++ b/doc/src/sgml/ref/createlang.sgml
@@ -24,14 +24,14 @@ PostgreSQL documentation
    <command>createlang</command>
    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
    <arg choice="plain"><replaceable>langname</replaceable></arg>
-   <arg><replaceable>dbname</replaceable></arg>
+   <arg choice="opt"><replaceable>dbname</replaceable></arg>
   </cmdsynopsis>
 
   <cmdsynopsis>
    <command>createlang</command>
    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
-   <group choice="plain"><arg><option>--list</option></arg><arg><option>-l</option></arg></group>
-   <arg choice="plain"><replaceable>dbname</replaceable></arg>
+   <group choice="plain"><arg choice="plain"><option>--list</option></arg><arg choice="plain"><option>-l</option></arg></group>
+   <arg choice="opt"><replaceable>dbname</replaceable></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
 
diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml
index 9942cd66f61..dedc97f2233 100644
--- a/doc/src/sgml/ref/createuser.sgml
+++ b/doc/src/sgml/ref/createuser.sgml
@@ -24,7 +24,7 @@ PostgreSQL documentation
    <command>createuser</command>
    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
    <arg rep="repeat"><replaceable>option</replaceable></arg>
-   <arg><replaceable>username</replaceable></arg>
+   <arg choice="opt"><replaceable>username</replaceable></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
 
diff --git a/doc/src/sgml/ref/droplang.sgml b/doc/src/sgml/ref/droplang.sgml
index 2bfdbfe8885..81b954a68f0 100644
--- a/doc/src/sgml/ref/droplang.sgml
+++ b/doc/src/sgml/ref/droplang.sgml
@@ -24,14 +24,14 @@ PostgreSQL documentation
    <command>droplang</command>
    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
    <arg choice="plain"><replaceable>langname</replaceable></arg>
-   <arg><replaceable>dbname</replaceable></arg>
+   <arg choice="opt"><replaceable>dbname</replaceable></arg>
   </cmdsynopsis>
 
   <cmdsynopsis>
    <command>droplang</command>
    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
-   <group choice="plain"><arg><option>--list</option></arg><arg><option>-l</option></arg></group>
-   <arg choice="plain"><replaceable>dbname</replaceable></arg>
+   <group choice="plain"><arg choice="plain"><option>--list</option></arg><arg choice="plain"><option>-l</option></arg></group>
+   <arg choice="opt"><replaceable>dbname</replaceable></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
 
diff --git a/doc/src/sgml/ref/dropuser.sgml b/doc/src/sgml/ref/dropuser.sgml
index bc6feafe9f2..891bbd60371 100644
--- a/doc/src/sgml/ref/dropuser.sgml
+++ b/doc/src/sgml/ref/dropuser.sgml
@@ -24,7 +24,7 @@ PostgreSQL documentation
    <command>dropuser</command>
    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
    <arg rep="repeat"><replaceable>option</replaceable></arg>
-   <arg><replaceable>username</replaceable></arg>
+   <arg choice="opt"><replaceable>username</replaceable></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
 
diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml
index 092df33d100..89f392eaeb0 100644
--- a/doc/src/sgml/ref/initdb.sgml
+++ b/doc/src/sgml/ref/initdb.sgml
@@ -25,8 +25,8 @@ PostgreSQL documentation
    <arg rep="repeat"><replaceable>option</replaceable></arg>
    <group choice="plain">
     <group choice="opt">
-     <arg><option>--pgdata</option></arg>
-     <arg><option>-D</option></arg>
+     <arg choice="plain"><option>--pgdata</option></arg>
+     <arg choice="plain"><option>-D</option></arg>
     </group>
     <replaceable> directory</replaceable>
    </group>
diff --git a/doc/src/sgml/ref/pg_controldata.sgml b/doc/src/sgml/ref/pg_controldata.sgml
index d39b6e18f88..7926acb9180 100644
--- a/doc/src/sgml/ref/pg_controldata.sgml
+++ b/doc/src/sgml/ref/pg_controldata.sgml
@@ -22,8 +22,8 @@ PostgreSQL documentation
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>pg_controldata</command>
-   <arg><replaceable class="parameter">option</replaceable></arg>
-   <arg><replaceable class="parameter">datadir</replaceable></arg>
+   <arg choice="opt"><replaceable class="parameter">option</replaceable></arg>
+   <arg choice="opt"><replaceable class="parameter">datadir</replaceable></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
 
diff --git a/doc/src/sgml/ref/pg_ctl-ref.sgml b/doc/src/sgml/ref/pg_ctl-ref.sgml
index fcc34ecb967..1409e0c44e4 100644
--- a/doc/src/sgml/ref/pg_ctl-ref.sgml
+++ b/doc/src/sgml/ref/pg_ctl-ref.sgml
@@ -23,36 +23,36 @@ PostgreSQL documentation
   <cmdsynopsis>
    <command>pg_ctl</command>
    <arg choice="plain"><option>init[db]</option></arg>
-   <arg><option>-s</option></arg>
-   <arg><option>-D</option> <replaceable>datadir</replaceable></arg>
-   <arg><option>-o</option> <replaceable>initdb-options</replaceable></arg>
+   <arg choice="opt"><option>-s</option></arg>
+   <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
+   <arg choice="opt"><option>-o</option> <replaceable>initdb-options</replaceable></arg>
   </cmdsynopsis>
 
   <cmdsynopsis>
    <command>pg_ctl</command>
    <arg choice="plain"><option>start</option></arg>
-   <arg><option>-w</option></arg>
-   <arg><option>-t</option> <replaceable>seconds</replaceable></arg>
-   <arg><option>-s</option></arg>
-   <arg><option>-D</option> <replaceable>datadir</replaceable></arg>
-   <arg><option>-l</option> <replaceable>filename</replaceable></arg>
-   <arg><option>-o</option> <replaceable>options</replaceable></arg>
-   <arg><option>-p</option> <replaceable>path</replaceable></arg>
-   <arg><option>-c</option></arg>
+   <arg choice="opt"><option>-w</option></arg>
+   <arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg>
+   <arg choice="opt"><option>-s</option></arg>
+   <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
+   <arg choice="opt"><option>-l</option> <replaceable>filename</replaceable></arg>
+   <arg choice="opt"><option>-o</option> <replaceable>options</replaceable></arg>
+   <arg choice="opt"><option>-p</option> <replaceable>path</replaceable></arg>
+   <arg choice="opt"><option>-c</option></arg>
   </cmdsynopsis>
 
   <cmdsynopsis>
    <command>pg_ctl</command>
    <arg choice="plain"><option>stop</option></arg>
-   <arg><option>-W</option></arg>
-   <arg><option>-t</option> <replaceable>seconds</replaceable></arg>
-   <arg><option>-s</option></arg>
-   <arg><option>-D</option> <replaceable>datadir</replaceable></arg>
-   <arg><option>-m</option>
+   <arg choice="opt"><option>-W</option></arg>
+   <arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg>
+   <arg choice="opt"><option>-s</option></arg>
+   <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
+   <arg choice="opt"><option>-m</option>
      <group choice="plain">
-       <arg><option>s[mart]</option></arg>
-       <arg><option>f[ast]</option></arg>
-       <arg><option>i[mmediate]</option></arg>
+       <arg choice="plain"><option>s[mart]</option></arg>
+       <arg choice="plain"><option>f[ast]</option></arg>
+       <arg choice="plain"><option>i[mmediate]</option></arg>
      </group>
    </arg>
   </cmdsynopsis>
@@ -60,39 +60,39 @@ PostgreSQL documentation
   <cmdsynopsis>
    <command>pg_ctl</command>
    <arg choice="plain"><option>restart</option></arg>
-   <arg><option>-w</option></arg>
-   <arg><option>-t</option> <replaceable>seconds</replaceable></arg>
-   <arg><option>-s</option></arg>
-   <arg><option>-D</option> <replaceable>datadir</replaceable></arg>
-   <arg><option>-c</option></arg>
-   <arg><option>-m</option>
+   <arg choice="opt"><option>-w</option></arg>
+   <arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg>
+   <arg choice="opt"><option>-s</option></arg>
+   <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
+   <arg choice="opt"><option>-c</option></arg>
+   <arg choice="opt"><option>-m</option>
      <group choice="plain">
-       <arg><option>s[mart]</option></arg>
-       <arg><option>f[ast]</option></arg>
-       <arg><option>i[mmediate]</option></arg>
+       <arg choice="plain"><option>s[mart]</option></arg>
+       <arg choice="plain"><option>f[ast]</option></arg>
+       <arg choice="plain"><option>i[mmediate]</option></arg>
      </group>
    </arg>
-   <arg><option>-o</option> <replaceable>options</replaceable></arg>
+   <arg choice="opt"><option>-o</option> <replaceable>options</replaceable></arg>
   </cmdsynopsis>
 
   <cmdsynopsis>
    <command>pg_ctl</command>
    <arg choice="plain"><option>reload</option></arg>
-   <arg><option>-s</option></arg>
-   <arg><option>-D</option> <replaceable>datadir</replaceable></arg>
+   <arg choice="opt"><option>-s</option></arg>
+   <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
   </cmdsynopsis>
 
   <cmdsynopsis>
    <command>pg_ctl</command>
    <arg choice="plain"><option>status</option></arg>
-   <arg><option>-D</option> <replaceable>datadir</replaceable></arg>
+   <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
   </cmdsynopsis>
 
   <cmdsynopsis>
    <command>pg_ctl</command>
    <arg choice="plain"><option>promote</option></arg>
-   <arg><option>-s</option></arg>
-   <arg><option>-D</option> <replaceable>datadir</replaceable></arg>
+   <arg choice="opt"><option>-s</option></arg>
+   <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
   </cmdsynopsis>
 
   <cmdsynopsis>
@@ -105,26 +105,26 @@ PostgreSQL documentation
   <cmdsynopsis>
    <command>pg_ctl</command>
    <arg choice="plain"><option>register</option></arg>
-   <arg><option>-N</option> <replaceable>servicename</replaceable></arg>
-   <arg><option>-U</option> <replaceable>username</replaceable></arg>
-   <arg><option>-P</option> <replaceable>password</replaceable></arg>
-   <arg><option>-D</option> <replaceable>datadir</replaceable></arg>
-   <arg><option>-S</option>
+   <arg choice="opt"><option>-N</option> <replaceable>servicename</replaceable></arg>
+   <arg choice="opt"><option>-U</option> <replaceable>username</replaceable></arg>
+   <arg choice="opt"><option>-P</option> <replaceable>password</replaceable></arg>
+   <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
+   <arg choice="opt"><option>-S</option>
      <group choice="plain">
-       <arg><option>a[uto]</option></arg>
-       <arg><option>d[emand]</option></arg>
+       <arg choice="plain"><option>a[uto]</option></arg>
+       <arg choice="plain"><option>d[emand]</option></arg>
      </group>
    </arg>
-   <arg><option>-w</option></arg>
-   <arg><option>-t</option> <replaceable>seconds</replaceable></arg>
-   <arg><option>-s</option></arg>
-   <arg><option>-o</option> <replaceable>options</replaceable></arg>
+   <arg choice="opt"><option>-w</option></arg>
+   <arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg>
+   <arg choice="opt"><option>-s</option></arg>
+   <arg choice="opt"><option>-o</option> <replaceable>options</replaceable></arg>
   </cmdsynopsis>
 
   <cmdsynopsis>
    <command>pg_ctl</command>
    <arg choice="plain"><option>unregister</option></arg>
-   <arg><option>-N</option> <replaceable>servicename</replaceable></arg>
+   <arg choice="opt"><option>-N</option> <replaceable>servicename</replaceable></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
 
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 6b315009ff7..a5e53043267 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -27,7 +27,7 @@ PostgreSQL documentation
    <command>pg_dump</command>
    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
    <arg rep="repeat"><replaceable>option</replaceable></arg>
-   <arg><replaceable>dbname</replaceable></arg>
+   <arg choice="opt"><replaceable>dbname</replaceable></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
 
diff --git a/doc/src/sgml/ref/pg_resetxlog.sgml b/doc/src/sgml/ref/pg_resetxlog.sgml
index 3a7dfb3c73e..fe67a3d1f20 100644
--- a/doc/src/sgml/ref/pg_resetxlog.sgml
+++ b/doc/src/sgml/ref/pg_resetxlog.sgml
@@ -22,14 +22,14 @@ PostgreSQL documentation
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>pg_resetxlog</command>
-   <arg><option>-f</option></arg>
-   <arg><option>-n</option></arg>
-   <arg><option>-o</option> <replaceable class="parameter">oid</replaceable></arg>
-   <arg><option>-x</option> <replaceable class="parameter">xid</replaceable></arg>
-   <arg><option>-e</option> <replaceable class="parameter">xid_epoch</replaceable></arg>
-   <arg><option>-m</option> <replaceable class="parameter">mxid</replaceable></arg>
-   <arg><option>-O</option> <replaceable class="parameter">mxoff</replaceable></arg>
-   <arg><option>-l</option> <replaceable class="parameter">timelineid</replaceable>,<replaceable class="parameter">fileid</replaceable>,<replaceable class="parameter">seg</replaceable></arg>
+   <arg choice="opt"><option>-f</option></arg>
+   <arg choice="opt"><option>-n</option></arg>
+   <arg choice="opt"><option>-o</option> <replaceable class="parameter">oid</replaceable></arg>
+   <arg choice="opt"><option>-x</option> <replaceable class="parameter">xid</replaceable></arg>
+   <arg choice="opt"><option>-e</option> <replaceable class="parameter">xid_epoch</replaceable></arg>
+   <arg choice="opt"><option>-m</option> <replaceable class="parameter">mxid</replaceable></arg>
+   <arg choice="opt"><option>-O</option> <replaceable class="parameter">mxoff</replaceable></arg>
+   <arg choice="opt"><option>-l</option> <replaceable class="parameter">timelineid</replaceable>,<replaceable class="parameter">fileid</replaceable>,<replaceable class="parameter">seg</replaceable></arg>
    <arg choice="plain"><replaceable>datadir</replaceable></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 6c3326668ff..47e972223e6 100644
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -25,7 +25,7 @@
    <command>pg_restore</command>
    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
    <arg rep="repeat"><replaceable>option</replaceable></arg>
-   <arg><replaceable>filename</replaceable></arg>
+   <arg choice="opt"><replaceable>filename</replaceable></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
 
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index bdcadf36928..487df746176 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -25,8 +25,8 @@ PostgreSQL documentation
   <cmdsynopsis>
    <command>psql</command>
    <arg rep="repeat"><replaceable class="parameter">option</replaceable></arg>
-   <arg><replaceable class="parameter">dbname</replaceable>
-   <arg><replaceable class="parameter">username</replaceable></arg></arg>
+   <arg choice="opt"><replaceable class="parameter">dbname</replaceable>
+   <arg choice="opt"><replaceable class="parameter">username</replaceable></arg></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
 
diff --git a/doc/src/sgml/ref/reindexdb.sgml b/doc/src/sgml/ref/reindexdb.sgml
index 526fd768178..7b2f72d04f8 100644
--- a/doc/src/sgml/ref/reindexdb.sgml
+++ b/doc/src/sgml/ref/reindexdb.sgml
@@ -25,27 +25,27 @@ PostgreSQL documentation
    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
    <group choice="opt">
     <group choice="plain">
-     <arg><option>--table</option></arg>
-     <arg><option>-t</option></arg>
+     <arg choice="plain"><option>--table</option></arg>
+     <arg choice="plain"><option>-t</option></arg>
     </group>
     <replaceable>table</replaceable>
    </group>
    <group choice="opt">
     <group choice="plain">
-     <arg><option>--index</option></arg>
-     <arg><option>-i</option></arg>
+     <arg choice="plain"><option>--index</option></arg>
+     <arg choice="plain"><option>-i</option></arg>
     </group>
     <replaceable>index</replaceable>
    </group>
-   <arg><replaceable>dbname</replaceable></arg>
+   <arg choice="opt"><replaceable>dbname</replaceable></arg>
   </cmdsynopsis>
 
   <cmdsynopsis>
    <command>reindexdb</command>
    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
    <group choice="plain">
-    <arg><option>--all</option></arg>
-    <arg><option>-a</option></arg>
+    <arg choice="plain"><option>--all</option></arg>
+    <arg choice="plain"><option>-a</option></arg>
    </group>
   </cmdsynopsis>
 
@@ -53,10 +53,10 @@ PostgreSQL documentation
    <command>reindexdb</command>
    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
    <group choice="plain">
-    <arg><option>--system</option></arg>
-    <arg><option>-s</option></arg>
+    <arg choice="plain"><option>--system</option></arg>
+    <arg choice="plain"><option>-s</option></arg>
    </group>
-   <arg><replaceable>dbname</replaceable></arg>
+   <arg choice="opt"><replaceable>dbname</replaceable></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
 
diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml
index c008611a5af..c60ba4424fe 100644
--- a/doc/src/sgml/ref/vacuumdb.sgml
+++ b/doc/src/sgml/ref/vacuumdb.sgml
@@ -24,15 +24,15 @@ PostgreSQL documentation
    <command>vacuumdb</command>
    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
    <arg rep="repeat"><replaceable>option</replaceable></arg>
-   <arg>
+   <arg choice="opt">
     <group choice="plain">
-     <arg><option>--table</option></arg>
-     <arg><option>-t</option></arg>
+     <arg choice="plain"><option>--table</option></arg>
+     <arg choice="plain"><option>-t</option></arg>
     </group>
     <replaceable>table</replaceable>
-    <arg>( <replaceable class="parameter">column</replaceable> [,...] )</arg>
+    <arg choice="opt">( <replaceable class="parameter">column</replaceable> [,...] )</arg>
    </arg>
-   <arg><replaceable>dbname</replaceable></arg>
+   <arg choice="opt"><replaceable>dbname</replaceable></arg>
   </cmdsynopsis>
 
   <cmdsynopsis>
@@ -40,8 +40,8 @@ PostgreSQL documentation
    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
    <arg rep="repeat"><replaceable>option</replaceable></arg>
    <group choice="plain">
-    <arg><option>--all</option></arg>
-    <arg><option>-a</option></arg>
+    <arg choice="plain"><option>--all</option></arg>
+    <arg choice="plain"><option>-a</option></arg>
    </group>
   </cmdsynopsis>
  </refsynopsisdiv>
diff --git a/doc/src/sgml/sql.sgml b/doc/src/sgml/sql.sgml
index c19e8232baa..ba92607966c 100644
--- a/doc/src/sgml/sql.sgml
+++ b/doc/src/sgml/sql.sgml
@@ -1103,7 +1103,7 @@ SELECT sname, pname from supplier
             <arg choice="opt"> NATURAL </arg>
             <group choice="opt">
                 <arg choice="opt"> INNER </arg>
-                <arg>
+                <arg choice="plain">
                 <group choice="req">
                     <arg choice="plain"> LEFT </arg>
                     <arg choice="plain"> RIGHT </arg>
@@ -1115,8 +1115,8 @@ SELECT sname, pname from supplier
             <command> JOIN </command>
             <arg choice="req"> <replaceable class="parameter">T2</replaceable> </arg>
             <group choice="req">
-                <arg> ON <replaceable>search condition</replaceable></arg>
-                <arg> USING ( <replaceable>join column list</replaceable> ) </arg>
+                <arg choice="plain"> ON <replaceable>search condition</replaceable></arg>
+                <arg choice="plain"> USING ( <replaceable>join column list</replaceable> ) </arg>
             </group>
             </cmdsynopsis>
 
@@ -1141,7 +1141,7 @@ SELECT sname, pname from supplier
             <varlistentry>
                 <term>
                     <cmdsynopsis>
-                        <arg> INNER </arg>
+                        <arg choice="opt"> INNER </arg>
                         <command> JOIN </command>
                     </cmdsynopsis>
                 </term>
@@ -1163,7 +1163,7 @@ SELECT sname, pname from supplier
                 <term>
                     <cmdsynopsis>
                         <arg choice="plain"> LEFT </arg>
-                        <arg> OUTER </arg>
+                        <arg choice="opt"> OUTER </arg>
                         <command> JOIN </command>
                     </cmdsynopsis>
                 </term>
@@ -1185,7 +1185,7 @@ SELECT sname, pname from supplier
                 <term>
                     <cmdsynopsis>
                         <arg choice="plain"> RIGHT </arg>
-                        <arg> OUTER </arg>
+                        <arg choice="opt"> OUTER </arg>
                         <command> JOIN </command>
                     </cmdsynopsis>
                 </term>
@@ -1207,7 +1207,7 @@ SELECT sname, pname from supplier
                 <term>
                     <cmdsynopsis>
                         <arg choice="plain"> FULL </arg>
-                        <arg> OUTER </arg>
+                        <arg choice="opt"> OUTER </arg>
                         <command> JOIN </command>
                     </cmdsynopsis>
                 </term>