open-dsi
/
postgres
mirror of https://github.com/postgres/postgres
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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.
pull/3/head
Peter Eisentraut 13 years ago
parent ebcaa5fcde
commit 1715ff1128
16 changed files with 101 additions and 101 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 10
      doc/src/sgml/ref/clusterdb.sgml
  2. 4
      doc/src/sgml/ref/createdb.sgml
  3. 6
      doc/src/sgml/ref/createlang.sgml
  4. 2
      doc/src/sgml/ref/createuser.sgml
  5. 6
      doc/src/sgml/ref/droplang.sgml
  6. 2
      doc/src/sgml/ref/dropuser.sgml
  7. 4
      doc/src/sgml/ref/initdb.sgml
  8. 4
      doc/src/sgml/ref/pg_controldata.sgml
  9. 92
      doc/src/sgml/ref/pg_ctl-ref.sgml
  10. 2
      doc/src/sgml/ref/pg_dump.sgml
  11. 16
      doc/src/sgml/ref/pg_resetxlog.sgml
  12. 2
      doc/src/sgml/ref/pg_restore.sgml
  13. 4
      doc/src/sgml/ref/psql-ref.sgml
  14. 20
      doc/src/sgml/ref/reindexdb.sgml
  15. 14
      doc/src/sgml/ref/vacuumdb.sgml
  16. 14
      doc/src/sgml/sql.sgml

10
doc/src/sgml/ref/clusterdb.sgml
Unescape View File

@ -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>

4
doc/src/sgml/ref/createdb.sgml
Unescape View File

@ -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>

6
doc/src/sgml/ref/createlang.sgml
Unescape View File

@ -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>

2
doc/src/sgml/ref/createuser.sgml
Unescape View File

@ -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>

6
doc/src/sgml/ref/droplang.sgml
Unescape View File

@ -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>

2
doc/src/sgml/ref/dropuser.sgml
Unescape View File

@ -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>

4
doc/src/sgml/ref/initdb.sgml
Unescape View File

@ -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>

4
doc/src/sgml/ref/pg_controldata.sgml
Unescape View File

@ -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>

92
doc/src/sgml/ref/pg_ctl-ref.sgml
Unescape View File

@ -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>

2
doc/src/sgml/ref/pg_dump.sgml
Unescape View File

@ -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>

16
doc/src/sgml/ref/pg_resetxlog.sgml
Unescape View File

@ -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>

2
doc/src/sgml/ref/pg_restore.sgml
Unescape View File

@ -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>

4
doc/src/sgml/ref/psql-ref.sgml
Unescape View File

@ -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>

20
doc/src/sgml/ref/reindexdb.sgml
Unescape View File

@ -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>

14
doc/src/sgml/ref/vacuumdb.sgml
Unescape View File

@ -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>

14
doc/src/sgml/sql.sgml
Unescape View File

@ -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>

Write Preview
Loading…
Cancel
Save