Modify pg_standby, pgbench, and pg_upgrade manual pages to be consistent

in their display of command-line options with other client applications.

4 files changed, 396 insertions, 314 deletions

diff --git a/doc/src/sgml/oid2name.sgml b/doc/src/sgml/oid2name.sgml
index 1c127893526..5e793ce1993 100644
--- a/doc/src/sgml/oid2name.sgml
+++ b/doc/src/sgml/oid2name.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/oid2name.sgml,v 1.7 2010/05/20 03:45:38 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/oid2name.sgml,v 1.8 2010/05/25 15:55:28 momjian Exp $ -->
 
 <sect1 id="oid2name">
  <title>oid2name</title>
@@ -36,7 +36,7 @@
  </sect2>
 
  <sect2>
-  <title><application>oid2name</> options</title>
+  <title><application>oid2name</> Options</title>
 
   <para>
    <application>oid2name</application> accepts the following command-line arguments:
diff --git a/doc/src/sgml/pgbench.sgml b/doc/src/sgml/pgbench.sgml
index 98e3b124389..bc0cd9c0c2f 100644
--- a/doc/src/sgml/pgbench.sgml
+++ b/doc/src/sgml/pgbench.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/pgbench.sgml,v 1.15 2010/04/23 23:21:43 rhaas Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/pgbench.sgml,v 1.16 2010/05/25 15:55:28 momjian Exp $ -->
 
 <sect1 id="pgbench">
  <title>pgbench</title>
@@ -116,218 +116,285 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
    in both cases.
   </para>
 
-  <table id="pgbench-init-options">
-   <title><application>pgbench</application> initialization options</title>
-   <tgroup cols="2">
-    <thead>
-     <row>
-      <entry>Option</entry>
-      <entry>Description</entry>
-     </row>
-    </thead>
-
-    <tbody>
-     <row>
-      <entry><literal>-i</literal></entry>
-      <entry>
-       Required to invoke initialization mode.
-      </entry>
-     </row>
-     <row>
-      <entry><literal>-s</literal> <replaceable>scale_factor</></entry>
-      <entry>
-       Multiply the number of rows generated by the scale factor.
-       For example, <literal>-s 100</> will create 10,000,000 rows
-       in the <structname>pgbench_accounts</> table. Default is 1.
-      </entry>
-     </row>
-     <row>
-      <entry><literal>-F</literal> <replaceable>fillfactor</></entry>
-      <entry>
-       Create the <structname>pgbench_accounts</>,
-       <structname>pgbench_tellers</> and
-       <structname>pgbench_branches</> tables with the given fillfactor.
-       Default is 100.
-      </entry>
-     </row>
-    </tbody>
-   </tgroup>
-  </table>
-
-  <table id="pgbench-run-options">
-   <title><application>pgbench</application> benchmarking options</title>
-   <tgroup cols="2">
-    <thead>
-     <row>
-      <entry>Option</entry>
-      <entry>Description</entry>
-     </row>
-    </thead>
-
-    <tbody>
-     <row>
-      <entry><literal>-c</literal> <replaceable>clients</></entry>
-      <entry>
-       Number of clients simulated, that is, number of concurrent database
-       sessions.  Default is 1.
-      </entry>
-     </row>
-     <row>
-      <entry><literal>-j</literal> <replaceable>threads</></entry>
-      <entry>
-       Number of worker threads within <application>pgbench</application>.
-       Using more than one thread can be helpful on multi-CPU machines.
-       The number of clients must be a multiple of the number of threads,
-       since each thread is given the same number of client sessions to manage.
-       Default is 1.
-      </entry>
-     </row>
-     <row>
-      <entry><literal>-t</literal> <replaceable>transactions</></entry>
-      <entry>
-       Number of transactions each client runs.  Default is 10.
-      </entry>
-     </row>
-     <row>
-      <entry><literal>-T</literal> <replaceable>seconds</></entry>
-      <entry>
-       Run the test for this many seconds, rather than a fixed number of
-       transactions per client. <literal>-t</literal> and
-       <literal>-T</literal> are mutually exclusive.
-      </entry>
-     </row>
-     <row>
-      <entry><literal>-M</literal> <replaceable>querymode</></entry>
-      <entry>
-       Protocol to use for submitting queries to the server:
-         <itemizedlist>
-          <listitem>
-           <para><literal>simple</>: use simple query protocol.</para>
-          </listitem>
-          <listitem>
-           <para><literal>extended</>: use extended query protocol.</para>
-          </listitem>
-          <listitem>
-           <para><literal>prepared</>: use extended query protocol with prepared statements.</para>
-          </listitem>
-         </itemizedlist>
-       The default is simple query protocol.  (See <xref linkend="protocol">
-       for more information.)
-      </entry>
-     </row>
-     <row>
-      <entry><literal>-N</literal></entry>
-      <entry>
-       Do not update <structname>pgbench_tellers</> and
-       <structname>pgbench_branches</>.
-       This will avoid update contention on these tables, but
-       it makes the test case even less like TPC-B.
-      </entry>
-     </row>
-     <row>
-      <entry><literal>-S</literal></entry>
-      <entry>
-       Perform select-only transactions instead of TPC-B-like test.
-      </entry>
-     </row>
-     <row>
-      <entry><literal>-f</literal> <replaceable>filename</></entry>
-      <entry>
-       Read transaction script from <replaceable>filename</>.
-       See below for details.
-       <literal>-N</literal>, <literal>-S</literal>, and <literal>-f</literal>
-       are mutually exclusive.
-      </entry>
-     </row>
-     <row>
-      <entry><literal>-n</literal></entry>
-      <entry>
-       Perform no vacuuming before running the test.
-       This option is <emphasis>necessary</>
-       if you are running a custom test scenario that does not include
-       the standard tables <structname>pgbench_accounts</>,
-       <structname>pgbench_branches</>, <structname>pgbench_history</>, and
-       <structname>pgbench_tellers</>.
-      </entry>
-     </row>
-     <row>
-      <entry><literal>-v</literal></entry>
-      <entry>
-       Vacuum all four standard tables before running the test.
-       With neither <literal>-n</> nor <literal>-v</>, pgbench will vacuum the
-       <structname>pgbench_tellers</> and <structname>pgbench_branches</>
-       tables, and will truncate <structname>pgbench_history</>.
-      </entry>
-     </row>
-     <row>
-      <entry><literal>-D</literal> <replaceable>varname</><literal>=</><replaceable>value</></entry>
-      <entry>
-       Define a variable for use by a custom script (see below).
-       Multiple <literal>-D</> options are allowed.
-      </entry>
-     </row>
-     <row>
-      <entry><literal>-C</literal></entry>
-      <entry>
-       Establish a new connection for each transaction, rather than
-       doing it just once per client session.
-       This is useful to measure the connection overhead.
-      </entry>
-     </row>
-     <row>
-      <entry><literal>-l</literal></entry>
-      <entry>
-       Write the time taken by each transaction to a logfile.
-       See below for details.
-      </entry>
-     </row>
-     <row>
-      <entry><literal>-s</literal> <replaceable>scale_factor</></entry>
-      <entry>
-       Report the specified scale factor in <application>pgbench</>'s
-       output.  With the built-in tests, this is not necessary; the
-       correct scale factor will be detected by counting the number of
-       rows in the <structname>pgbench_branches</> table.  However, when testing
-       custom benchmarks (<literal>-f</> option), the scale factor
-       will be reported as 1 unless this option is used.
-      </entry>
-     </row>
-     <row>
-      <entry><literal>-d</literal></entry>
-      <entry>
-       Print debugging output.
-      </entry>
-     </row>
-    </tbody>
-   </tgroup>
-  </table>
-
-  <table id="pgbench-common-options">
-   <title><application>pgbench</application> common options</title>
-   <tgroup cols="2">
-    <thead>
-     <row>
-      <entry>Option</entry>
-      <entry>Description</entry>
-     </row>
-    </thead>
-
-    <tbody>
-     <row>
-      <entry><literal>-h</literal> <replaceable>hostname</></entry>
-      <entry>database server's host</entry>
-     </row>
-     <row>
-      <entry><literal>-p</literal> <replaceable>port</></entry>
-      <entry>database server's port</entry>
-     </row>
-     <row>
-      <entry><literal>-U</literal> <replaceable>login</></entry>
-      <entry>username to connect as</entry>
-     </row>
-    </tbody>
-   </tgroup>
-  </table>
+ </sect2>
+
+ <sect2 id="pgbench-init-options">
+  <title><application>pgbench</> Initialization Options</title>
+
+   <para>
+    <application>pgbench</application> accepts the following command-line
+    initialization arguments:
+
+    <variablelist>
+
+     <varlistentry>
+      <term><option>-F</option> <replaceable>fillfactor</></term>
+      <listitem>
+       <para>
+        Create the <structname>pgbench_accounts</>,
+        <structname>pgbench_tellers</> and
+        <structname>pgbench_branches</> tables with the given fillfactor.
+        Default is 100.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-i</option></term>
+      <listitem>
+       <para>
+        Required to invoke initialization mode.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-s</option> <replaceable>scale_factor</></term>
+      <listitem>
+       <para>
+        Multiply the number of rows generated by the scale factor.
+        For example, <literal>-s 100</> will create 10,000,000 rows
+        in the <structname>pgbench_accounts</> table. Default is 1.
+       </para>
+      </listitem>
+     </varlistentry>
+
+    </variablelist>
+   </para>
+
+ </sect2>
+
+ <sect2 id="pgbench-run-options">
+  <title><application>pgbench</> Benchmarking Options</title>
+
+   <para>
+    <application>pgbench</application> accepts the following command-line
+    benchmarking arguments:
+
+    <variablelist>
+
+     <varlistentry>
+      <term><option>-c</option> <replaceable>clients</></term>
+      <listitem>
+       <para>
+        Number of clients simulated, that is, number of concurrent database
+        sessions.  Default is 1.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-C</option></term>
+      <listitem>
+       <para>
+        Establish a new connection for each transaction, rather than
+        doing it just once per client session.
+        This is useful to measure the connection overhead.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-d</option></term>
+      <listitem>
+       <para>
+        Print debugging output.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-D</option> <replaceable>varname</><literal>=</><replaceable>value</></term>
+      <listitem>
+       <para>
+        Define a variable for use by a custom script (see below).
+        Multiple <literal>-D</> options are allowed.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-f</option> <replaceable>filename</></term>
+      <listitem>
+       <para>
+        Read transaction script from <replaceable>filename</>.
+        See below for details.
+        <literal>-N</literal>, <literal>-S</literal>, and <literal>-f</literal>
+        are mutually exclusive.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-j</option> <replaceable>threads</></term>
+      <listitem>
+       <para>
+        Number of worker threads within <application>pgbench</application>.
+        Using more than one thread can be helpful on multi-CPU machines.
+        The number of clients must be a multiple of the number of threads,
+        since each thread is given the same number of client sessions to manage.
+        Default is 1.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-l</option></term>
+      <listitem>
+       <para>
+        Write the time taken by each transaction to a logfile.
+        See below for details.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-M</option> <replaceable>querymode</></term>
+      <listitem>
+       <para>
+        Protocol to use for submitting queries to the server:
+          <itemizedlist>
+           <listitem>
+            <para><literal>simple</>: use simple query protocol.</para>
+           </listitem>
+           <listitem>
+            <para><literal>extended</>: use extended query protocol.</para>
+           </listitem>
+           <listitem>
+            <para><literal>prepared</>: use extended query protocol with prepared statements.</para>
+           </listitem>
+          </itemizedlist>
+        The default is simple query protocol.  (See <xref linkend="protocol">
+        for more information.)
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-n</option></term>
+      <listitem>
+       <para>
+        Perform no vacuuming before running the test.
+        This option is <emphasis>necessary</>
+        if you are running a custom test scenario that does not include
+        the standard tables <structname>pgbench_accounts</>,
+        <structname>pgbench_branches</>, <structname>pgbench_history</>, and
+        <structname>pgbench_tellers</>.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-N</option></term>
+      <listitem>
+       <para>
+        Do not update <structname>pgbench_tellers</> and
+        <structname>pgbench_branches</>.
+        This will avoid update contention on these tables, but
+        it makes the test case even less like TPC-B.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-s</option> <replaceable>scale_factor</></term>
+      <listitem>
+       <para>
+        Report the specified scale factor in <application>pgbench</>'s
+        output.  With the built-in tests, this is not necessary; the
+        correct scale factor will be detected by counting the number of
+        rows in the <structname>pgbench_branches</> table.  However, when testing
+        custom benchmarks (<literal>-f</> option), the scale factor
+        will be reported as 1 unless this option is used.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-S</option></term>
+      <listitem>
+       <para>
+        Perform select-only transactions instead of TPC-B-like test.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-t</option> <replaceable>transactions</></term>
+      <listitem>
+       <para>
+        Number of transactions each client runs.  Default is 10.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-T</option> <replaceable>seconds</></term>
+      <listitem>
+       <para>
+        Run the test for this many seconds, rather than a fixed number of
+        transactions per client. <literal>-t</literal> and
+        <literal>-T</literal> are mutually exclusive.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-v</option></term>
+      <listitem>
+       <para>
+        Vacuum all four standard tables before running the test.
+        With neither <literal>-n</> nor <literal>-v</>, pgbench will vacuum the
+        <structname>pgbench_tellers</> and <structname>pgbench_branches</>
+        tables, and will truncate <structname>pgbench_history</>.
+       </para>
+      </listitem>
+     </varlistentry>
+
+    </variablelist>
+   </para>
+
+ </sect2>
+
+ <sect2 id="pgbench-common-options">
+  <title><application>pgbench</> Common Options</title>
+
+   <para>
+    <application>pgbench</application> accepts the following command-line
+    common arguments:
+
+    <variablelist>
+
+     <varlistentry>
+      <term><option>-h</option> <replaceable>hostname</></term>
+      <listitem>
+       <para>
+        The database server's hostname
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-p</option> <replaceable>port</></term>
+      <listitem>
+       <para>
+        The database server's port number
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-U</option> <replaceable>login</></term>
+      <listitem>
+       <para>
+        The username to connect as
+       </para>
+      </listitem>
+     </varlistentry>
+
+    </variablelist>
+   </para>
+
  </sect2>
 
  <sect2>
diff --git a/doc/src/sgml/pgstandby.sgml b/doc/src/sgml/pgstandby.sgml
index ce81de3a189..2a4e03185f9 100644
--- a/doc/src/sgml/pgstandby.sgml
+++ b/doc/src/sgml/pgstandby.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/pgstandby.sgml,v 2.10 2009/06/25 12:03:11 heikki Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/pgstandby.sgml,v 2.11 2010/05/25 15:55:28 momjian Exp $ -->
 
 <sect1 id="pgstandby">
  <title>pg_standby</title>
@@ -122,99 +122,114 @@ pg_standby <optional> <replaceable>option</> ... </optional> <replaceable>archiv
    </variablelist>
   </para>
 
-  <table>
-   <title><application>pg_standby</> options</title>
-   <tgroup cols="3">
-     <thead>
-     <row>
-      <entry>Option</entry>
-      <entry>Default</entry>
-      <entry>Description</entry>
-     </row>
-    </thead>
-    <tbody>
-     <row>
-      <entry><literal>-c</></entry>
-      <entry>yes</entry>
-      <entry>
-       Use <literal>cp</> or <literal>copy</> command to restore WAL files
-       from archive.
-      </entry>
-     </row>
-     <row>
-      <entry><literal>-d</></entry>
-      <entry>no</entry>
-      <entry>Print lots of debug logging output on <filename>stderr</>.</entry>
-     </row>
-     <row>
-      <entry><literal>-k</> <replaceable>numfiles</></entry>
-      <entry>0</entry>
-      <entry>
-       Remove files from <replaceable>archivelocation</replaceable> so that
-       no more than this many WAL files before the current one are kept in the
-       archive.  Zero (the default) means not to remove any files from
-       <replaceable>archivelocation</replaceable>.
-       This parameter will be silently ignored if
-       <replaceable>restartwalfile</replaceable> is specified, since that
-       specification method is more accurate in determining the correct
-       archive cut-off point.
-       Use of this parameter is <emphasis>deprecated</> as of
-       <productname>PostgreSQL</> 8.3; it is safer and more efficient to
-       specify a <replaceable>restartwalfile</replaceable> parameter.  A too
-       small setting could result in removal of files that are still needed
-       for a restart of the standby server, while a too large setting wastes
-       archive space.
-      </entry>
-     </row>
-     <row>
-      <entry><literal>-r</> <replaceable>maxretries</></entry>
-      <entry>3</entry>
-      <entry>
-        Set the maximum number of times to retry the copy command if it
-        fails. After each failure, we wait for <replaceable>sleeptime</> *
-        <replaceable>num_retries</>
+ </sect2>
+
+ <sect2>
+  <title><application>pg_standby</> Options</title>
+
+   <para>
+    <application>pg_standby</application> accepts the following command-line arguments:
+
+    <variablelist>
+
+     <varlistentry>
+      <term><option>-c</option></term>
+      <listitem>
+       <para>
+        Use <literal>cp</> or <literal>copy</> command to restore WAL files
+        from archive.  This is the only supported behavior so this option is useless.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-d</option></term>
+      <listitem>
+       <para>
+        Print lots of debug logging output on <filename>stderr</>.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-k</option></term>
+      <listitem>
+       <para>
+        Remove files from <replaceable>archivelocation</replaceable> so that
+        no more than this many WAL files before the current one are kept in the
+        archive.  Zero (the default) means not to remove any files from
+        <replaceable>archivelocation</replaceable>.
+        This parameter will be silently ignored if
+        <replaceable>restartwalfile</replaceable> is specified, since that
+        specification method is more accurate in determining the correct
+        archive cut-off point.
+        Use of this parameter is <emphasis>deprecated</> as of
+        <productname>PostgreSQL</> 8.3; it is safer and more efficient to
+        specify a <replaceable>restartwalfile</replaceable> parameter.  A too
+        small setting could result in removal of files that are still needed
+        for a restart of the standby server, while a too large setting wastes
+        archive space.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-r</option> <replaceable>maxretries</></term>
+      <listitem>
+       <para>
+        Set the maximum number of times to retry the copy command if
+        it fails (default 3). After each failure, we wait for
+        <replaceable>sleeptime</> * <replaceable>num_retries</>
         so that the wait time increases progressively.  So by default,
         we will wait 5 secs, 10 secs, then 15 secs before reporting
         the failure back to the standby server. This will be
         interpreted as end of recovery and the standby will come
         up fully as a result.
-      </entry>
-     </row>
-     <row>
-      <entry><literal>-s</> <replaceable>sleeptime</></entry>
-      <entry>5</entry>
-      <entry>
-       Set the number of seconds (up to 60) to sleep between tests to see
-       if the WAL file to be restored is available in the archive yet.
-       The default setting is not necessarily recommended;
-       consult <xref linkend="warm-standby"> for discussion.
-      </entry>
-     </row>
-     <row>
-      <entry><literal>-t</> <replaceable>triggerfile</></entry>
-      <entry>none</entry>
-      <entry>
-       Specify a trigger file whose presence should cause failover.
-       It is recommended that you use a structured filename to
-       avoid confusion as to which server is being triggered
-       when multiple servers exist on the same system; for example
-       <filename>/tmp/pgsql.trigger.5432</>.
-      </entry>
-     </row>
-     <row>
-      <entry><literal>-w</> <replaceable>maxwaittime</></entry>
-      <entry>0</entry>
-      <entry>
-       Set the maximum number of seconds to wait for the next WAL file,
-       after which a fast failover will be performed.
-       A setting of zero (the default) means wait forever.
-       The default setting is not necessarily recommended;
-       consult <xref linkend="warm-standby"> for discussion.
-      </entry>
-     </row>
-    </tbody>
-   </tgroup>
-  </table>
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-s</option> <replaceable>sleeptime</></term>
+      <listitem>
+       <para>
+        Set the number of seconds (up to 60, default 5) to sleep between
+        tests to see if the WAL file to be restored is available in
+        the archive yet.  The default setting is not necessarily
+        recommended; consult <xref linkend="warm-standby"> for discussion.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-t</option> <replaceable>triggerfile</></term>
+      <listitem>
+       <para>
+        Specify a trigger file whose presence should cause failover.
+        It is recommended that you use a structured filename to
+        avoid confusion as to which server is being triggered
+        when multiple servers exist on the same system; for example
+        <filename>/tmp/pgsql.trigger.5432</>.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-w</option> <replaceable>maxwaittime</></term>
+      <listitem>
+       <para>
+        Set the maximum number of seconds to wait for the next WAL file,
+        after which a fast failover will be performed.
+        A setting of zero (the default) means wait forever.
+        The default setting is not necessarily recommended;
+        consult <xref linkend="warm-standby"> for discussion.
+       </para>
+      </listitem>
+     </varlistentry>
+
+    </variablelist>
+   </para>
+
  </sect2>
 
  <sect2>
diff --git a/doc/src/sgml/pgupgrade.sgml b/doc/src/sgml/pgupgrade.sgml
index e5c054c1375..69ff9dba1b2 100644
--- a/doc/src/sgml/pgupgrade.sgml
+++ b/doc/src/sgml/pgupgrade.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/pgupgrade.sgml,v 1.11 2010/05/25 14:50:56 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/pgupgrade.sgml,v 1.12 2010/05/25 15:55:28 momjian Exp $ -->
 
 <sect1 id="pgupgrade">
  <title>pg_upgrade</title>
@@ -38,7 +38,7 @@
  </sect2>
 
  <sect2>
-  <title><application>pg_upgrade</> options</title>
+  <title><application>pg_upgrade</> Options</title>
 
    <para>
     <application>pg_upgrade</application> accepts the following command-line arguments:
@@ -46,13 +46,13 @@
     <variablelist>
 
      <varlistentry>
-      <term><option>-b</option> <replaceable>OLDBINDIR</></term>
+      <term><option>-b</option> <replaceable>old_bindir</></term>
       <term><option>--old-bindir</option> <replaceable>OLDBINDIR</></term>
       <listitem><para>specify the old cluster executable directory</para></listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>-B</option> <replaceable>NEWBINDIR</></term>
+      <term><option>-B</option> <replaceable>new_bindir</></term>
       <term><option>--new-bindir</option> <replaceable>NEWBINDIR</></term>
       <listitem><para>specify the new cluster executable directory</para></listitem>
      </varlistentry>
@@ -64,13 +64,13 @@
      </varlistentry>
 
      <varlistentry>
-      <term><option>-d</option> <replaceable>OLDDATADIR</></term>
+      <term><option>-d</option> <replaceable>old_datadir</></term>
       <term><option>--old-datadir</option> <replaceable>OLDDATADIR</></term>
       <listitem><para>specify the old cluster data directory</para></listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>-D</option> <replaceable>NEWDATADIR</></term>
+      <term><option>-D</option> <replaceable>new_datadir</></term>
       <term><option>--new-datadir</option> <replaceable>NEWDATADIR</></term>
       <listitem><para>specify the new cluster data directory</para></listitem>
      </varlistentry>
@@ -82,7 +82,7 @@
      </varlistentry>
 
      <varlistentry>
-      <term><option>-G</option> <replaceable>DEBUGFILENAME</></term>
+      <term><option>-G</option> <replaceable>debug_filename</></term>
       <term><option>--debugfile</option> <replaceable>DEBUGFILENAME</></term>
       <listitem><para>output debugging activity to file</para></listitem>
      </varlistentry>
@@ -94,19 +94,19 @@
      </varlistentry>
 
      <varlistentry>
-      <term><option>-l</option> <replaceable>LOGFILENAME</></term>
+      <term><option>-l</option> <replaceable>log_filename</></term>
       <term><option>--logfile</option> <replaceable>LOGFILENAME</></term>
       <listitem><para>log session activity to file</para></listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>-p</option> <replaceable>portnum</></term>
+      <term><option>-p</option> <replaceable>old_portnum</></term>
       <term><option>--old-port</option> <replaceable>portnum</></term>
       <listitem><para>specify the old cluster port number</para></listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>-P</option> <replaceable>portnum</></term>
+      <term><option>-P</option> <replaceable>new_portnum</></term>
       <term><option>--new-port</option> <replaceable>portnum</></term>
       <listitem><para>specify the new cluster port number</para></listitem>
      </varlistentry>