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

The default for the choice attribute of the  element is "opt",
which would normally put the argument inside brackets.  But the DSSSL
stylesheets contain a hack that treats  directly inside 
specially, so that -x-y 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 
and  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.

diff --git a/doc/src/sgml/ref/clusterdb.sgml b/doc/src/sgml/ref/clusterdb.sgml
index e0246b3bca20a4e89fda4a81e038dfcc8689f97d..097ea912f1c7f6a0578fb7bbb3e43a9987d2cfe7 100644 (file)
--- a/doc/src/sgml/ref/clusterdb.sgml
+++ b/doc/src/sgml/ref/clusterdb.sgml
@@ -23,16 +23,16 @@ PostgreSQL documentation
   
    clusterdb
    connection-option
-   >--verbose>-v
-   >--table>-t table 
-   dbname
+    choice="opt">--verbose>-v
+    choice="opt">--table>-t table 
+    choice="opt">dbname
   
 
   
    clusterdb
    connection-option
-   >--verbose>-v
-   >--all>-a
+    choice="opt">--verbose>-v
+    choice="plain">--all>-a
   
  
 

diff --git a/doc/src/sgml/ref/createdb.sgml b/doc/src/sgml/ref/createdb.sgml
index cbbc5c05455371a5e0efeb7bc2ef190b45d4c08f..7dbedc2e90987d6479ed5a50f6a300380803fa9c 100644 (file)
--- a/doc/src/sgml/ref/createdb.sgml
+++ b/doc/src/sgml/ref/createdb.sgml
@@ -24,8 +24,8 @@ PostgreSQL documentation
    createdb
    connection-option
    option
-   >dbname>
-   >description>
+    choice="opt">dbname>
+    choice="opt">description>
   
  
 

diff --git a/doc/src/sgml/ref/createlang.sgml b/doc/src/sgml/ref/createlang.sgml
index 4ca32fba39a70583276075f2f1576e984d9a45e2..2bc43627e5462614dcd7b3361cc9d024b9f8e698 100644 (file)
--- a/doc/src/sgml/ref/createlang.sgml
+++ b/doc/src/sgml/ref/createlang.sgml
@@ -24,14 +24,14 @@ PostgreSQL documentation
    createlang
    connection-option
    langname
-   dbname
+    choice="opt">dbname
   
 
   
    createlang
    connection-option
-   >--list>-l
-   plain">dbname
+    choice="plain">--list>-l
+   opt">dbname
   
  
 

diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml
index 9942cd66f610636b02831fe0e9e5831e19eab4bb..dedc97f2233c7579e35c3c11cada8f22a5f86e93 100644 (file)
--- a/doc/src/sgml/ref/createuser.sgml
+++ b/doc/src/sgml/ref/createuser.sgml
@@ -24,7 +24,7 @@ PostgreSQL documentation
    createuser
    connection-option
    option
-   username
+    choice="opt">username
   
  
 

diff --git a/doc/src/sgml/ref/droplang.sgml b/doc/src/sgml/ref/droplang.sgml
index 2bfdbfe8885bfa47c41df3bb53d265c53d5d4215..81b954a68f0843bac6e1be61cdac104c514c3022 100644 (file)
--- a/doc/src/sgml/ref/droplang.sgml
+++ b/doc/src/sgml/ref/droplang.sgml
@@ -24,14 +24,14 @@ PostgreSQL documentation
    droplang
    connection-option
    langname
-   dbname
+    choice="opt">dbname
   
 
   
    droplang
    connection-option
-   >--list>-l
-   plain">dbname
+    choice="plain">--list>-l
+   opt">dbname
   
  
 

diff --git a/doc/src/sgml/ref/dropuser.sgml b/doc/src/sgml/ref/dropuser.sgml
index bc6feafe9f21016c0a4327135b85fe152ddbbb6b..891bbd60371136bab8eab4327d1c3b412aa5199c 100644 (file)
--- a/doc/src/sgml/ref/dropuser.sgml
+++ b/doc/src/sgml/ref/dropuser.sgml
@@ -24,7 +24,7 @@ PostgreSQL documentation
    dropuser
    connection-option
    option
-   username
+    choice="opt">username
   
  
 

diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml
index 092df33d10074f11b3865e77450dc3566f4dc39b..89f392eaeb04e00c9fc0d85042296ed7fdb4f7a2 100644 (file)
--- a/doc/src/sgml/ref/initdb.sgml
+++ b/doc/src/sgml/ref/initdb.sgml
@@ -25,8 +25,8 @@ PostgreSQL documentation
    option
    
     
-     --pgdata
-     -D
+      choice="plain">--pgdata
+      choice="plain">-D
     
      directory
    

diff --git a/doc/src/sgml/ref/pg_controldata.sgml b/doc/src/sgml/ref/pg_controldata.sgml
index d39b6e18f88e8845558ef58498e83081644e306f..7926acb918083ca61edcad4f56ce2029b7b1e523 100644 (file)
--- a/doc/src/sgml/ref/pg_controldata.sgml
+++ b/doc/src/sgml/ref/pg_controldata.sgml
@@ -22,8 +22,8 @@ PostgreSQL documentation
  
   
    pg_controldata
-   option
-   datadir
+    choice="opt">option
+    choice="opt">datadir
   
  
 

diff --git a/doc/src/sgml/ref/pg_ctl-ref.sgml b/doc/src/sgml/ref/pg_ctl-ref.sgml
index fcc34ecb967dcdeeed0862e59db69b7924d35d68..1409e0c44e4ff7ea49d65e37c895f792e9fab2ef 100644 (file)
--- a/doc/src/sgml/ref/pg_ctl-ref.sgml
+++ b/doc/src/sgml/ref/pg_ctl-ref.sgml
@@ -23,36 +23,36 @@ PostgreSQL documentation
   
    pg_ctl
    init[db]
-   -s
-   -D datadir
-   -o initdb-options
+    choice="opt">-s
+    choice="opt">-D datadir
+    choice="opt">-o initdb-options
   
 
   
    pg_ctl
    start
-   -w
-   -t seconds
-   -s
-   -D datadir
-   -l filename
-   -o options
-   -p path
-   -c
+    choice="opt">-w
+    choice="opt">-t seconds
+    choice="opt">-s
+    choice="opt">-D datadir
+    choice="opt">-l filename
+    choice="opt">-o options
+    choice="opt">-p path
+    choice="opt">-c
   
 
   
    pg_ctl
    stop
-   -W
-   -t seconds
-   -s
-   -D datadir
-   -m
+    choice="opt">-W
+    choice="opt">-t seconds
+    choice="opt">-s
+    choice="opt">-D datadir
+    choice="opt">-m
      
-       s[mart]
-       f[ast]
-       i[mmediate]
+        choice="plain">s[mart]
+        choice="plain">f[ast]
+        choice="plain">i[mmediate]
      
    
   
@@ -60,39 +60,39 @@ PostgreSQL documentation
   
    pg_ctl
    restart
-   -w
-   -t seconds
-   -s
-   -D datadir
-   -c
-   -m
+    choice="opt">-w
+    choice="opt">-t seconds
+    choice="opt">-s
+    choice="opt">-D datadir
+    choice="opt">-c
+    choice="opt">-m
      
-       s[mart]
-       f[ast]
-       i[mmediate]
+        choice="plain">s[mart]
+        choice="plain">f[ast]
+        choice="plain">i[mmediate]
      
    
-   -o options
+    choice="opt">-o options
   
 
   
    pg_ctl
    reload
-   -s
-   -D datadir
+    choice="opt">-s
+    choice="opt">-D datadir
   
 
   
    pg_ctl
    status
-   -D datadir
+    choice="opt">-D datadir
   
 
   
    pg_ctl
    promote
-   -s
-   -D datadir
+    choice="opt">-s
+    choice="opt">-D datadir
   
 
   
@@ -105,26 +105,26 @@ PostgreSQL documentation
   
    pg_ctl
    register
-   -N servicename
-   -U username
-   -P password
-   -D datadir
-   -S
+    choice="opt">-N servicename
+    choice="opt">-U username
+    choice="opt">-P password
+    choice="opt">-D datadir
+    choice="opt">-S
      
-       a[uto]
-       d[emand]
+        choice="plain">a[uto]
+        choice="plain">d[emand]
      
    
-   -w
-   -t seconds
-   -s
-   -o options
+    choice="opt">-w
+    choice="opt">-t seconds
+    choice="opt">-s
+    choice="opt">-o options
   
 
   
    pg_ctl
    unregister
-   -N servicename
+    choice="opt">-N servicename
   
  
 

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 6b315009ff7954062ef53ecfb55d2251aa1d824e..a5e53043267be3b2a72387e9b50020dfb1821edf 100644 (file)
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -27,7 +27,7 @@ PostgreSQL documentation
    pg_dump
    connection-option
    option
-   dbname
+    choice="opt">dbname
   
  
 

diff --git a/doc/src/sgml/ref/pg_resetxlog.sgml b/doc/src/sgml/ref/pg_resetxlog.sgml
index 3a7dfb3c73e7bc593e07c31ffddde1164ba727df..fe67a3d1f20f467c62d779a8b3cf4985fed84eea 100644 (file)
--- a/doc/src/sgml/ref/pg_resetxlog.sgml
+++ b/doc/src/sgml/ref/pg_resetxlog.sgml
@@ -22,14 +22,14 @@ PostgreSQL documentation
  
   
    pg_resetxlog
-   -f
-   -n
-   -o oid
-   -x xid
-   -e xid_epoch
-   -m mxid
-   -O mxoff
-   -l timelineid,fileid,seg
+    choice="opt">-f
+    choice="opt">-n
+    choice="opt">-o oid
+    choice="opt">-x xid
+    choice="opt">-e xid_epoch
+    choice="opt">-m mxid
+    choice="opt">-O mxoff
+    choice="opt">-l timelineid,fileid,seg
    datadir
   
  

diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 6c3326668ff8bb9b895797e8750403ed637f495e..47e972223e69db06af079fdf8639018a47fc9492 100644 (file)
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -25,7 +25,7 @@
    pg_restore
    connection-option
    option
-   filename
+    choice="opt">filename
   
  
 

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index bdcadf3692864dd665bec195067f2c5d55c8c695..487df7461769873b40bc69466b2c0af786b22dd8 100644 (file)
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -25,8 +25,8 @@ PostgreSQL documentation
   
    psql
    option
-   dbname
-   username
+    choice="opt">dbname
+    choice="opt">username
   
  
 

diff --git a/doc/src/sgml/ref/reindexdb.sgml b/doc/src/sgml/ref/reindexdb.sgml
index 526fd7681789a30cecdb5c91548796598472e9be..7b2f72d04f8fa652bf1d2df0ec01fc9c9a7f2a42 100644 (file)
--- a/doc/src/sgml/ref/reindexdb.sgml
+++ b/doc/src/sgml/ref/reindexdb.sgml
@@ -25,27 +25,27 @@ PostgreSQL documentation
    connection-option
    
     
-     --table
-     -t
+      choice="plain">--table
+      choice="plain">-t
     
     table
    
    
     
-     --index
-     -i
+      choice="plain">--index
+      choice="plain">-i
     
     index
    
-   dbname
+    choice="opt">dbname
   
 
   
    reindexdb
    connection-option
    
-    --all
-    -a
+     choice="plain">--all
+     choice="plain">-a
    
   
 
@@ -53,10 +53,10 @@ PostgreSQL documentation
    reindexdb
    connection-option
    
-    --system
-    -s
+     choice="plain">--system
+     choice="plain">-s
    
-   dbname
+    choice="opt">dbname
   
  
 

diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml
index c008611a5af3866eedfaa37a71c023bb3ead2e65..c60ba4424fe75b3f79042aa762cc996ee65ebf01 100644 (file)
--- a/doc/src/sgml/ref/vacuumdb.sgml
+++ b/doc/src/sgml/ref/vacuumdb.sgml
@@ -24,15 +24,15 @@ PostgreSQL documentation
    vacuumdb
    connection-option
    option
-   
+    choice="opt">
     
-     --table
-     -t
+      choice="plain">--table
+      choice="plain">-t
     
     table
-    ( column [,...] )
+     choice="opt">( column [,...] )
    
-   dbname
+    choice="opt">dbname
   
 
   
@@ -40,8 +40,8 @@ PostgreSQL documentation
    connection-option
    option
    
-    --all
-    -a
+     choice="plain">--all
+     choice="plain">-a
    
   
  

diff --git a/doc/src/sgml/sql.sgml b/doc/src/sgml/sql.sgml
index c19e8232baa89997da96f8610a5232d463f9ff3b..ba92607966c33700d84b82ce94dcb80dcec19aa9 100644 (file)
--- a/doc/src/sgml/sql.sgml
+++ b/doc/src/sgml/sql.sgml
@@ -1103,7 +1103,7 @@ SELECT sname, pname from supplier
              NATURAL 
             
                  INNER 
-                
+                 choice="plain">
                 
                      LEFT 
                      RIGHT 
@@ -1115,8 +1115,8 @@ SELECT sname, pname from supplier
              JOIN 
              T2 
             
-                 ON search condition
-                 USING ( join column list ) 
+                 choice="plain"> ON search condition
+                 choice="plain"> USING ( join column list ) 
             
             
 
@@ -1141,7 +1141,7 @@ SELECT sname, pname from supplier
             
                 
                     
-                         INNER 
+                         choice="opt"> INNER 
                          JOIN 
                     
                 
@@ -1163,7 +1163,7 @@ SELECT sname, pname from supplier
                 
                     
                          LEFT 
-                         OUTER 
+                         choice="opt"> OUTER 
                          JOIN 
                     
                 
@@ -1185,7 +1185,7 @@ SELECT sname, pname from supplier
                 
                     
                          RIGHT 
-                         OUTER 
+                         choice="opt"> OUTER 
                          JOIN 
                     
                 
@@ -1207,7 +1207,7 @@ SELECT sname, pname from supplier
                 
                     
                          FULL 
-                         OUTER 
+                         choice="opt"> OUTER 
                          JOIN