Improve initdb and pg_controldata manual pages - Mailing list pgsql-docs

I have applied the attached patch to improve the initdb and
pg_controldata manual pages.  Patch from gabrielle <gorthx@gmail.com>.

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +
diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml
index 04f047b..e3fdebd 100644
*** a/doc/src/sgml/ref/initdb.sgml
--- b/doc/src/sgml/ref/initdb.sgml
*************** PostgreSQL documentation
*** 22,30 ****
   <refsynopsisdiv>
    <cmdsynopsis>
     <command>initdb</command>
!    <arg rep="repeat"><replaceable>option</></arg>
     <group choice="plain">
!     <arg>--pgdata </arg>
      <arg>-D </arg>
      <replaceable>directory</replaceable>
     </group>
--- 22,30 ----
   <refsynopsisdiv>
    <cmdsynopsis>
     <command>initdb</command>
!    <arg rep="repeat"><replaceable>option</replaceable></arg>
     <group choice="plain">
!     <arg>--pgdata=</arg>
      <arg>-D </arg>
      <replaceable>directory</replaceable>
     </group>
*************** PostgreSQL documentation
*** 186,201 ****
       </varlistentry>

       <varlistentry>
!       <term><option>-X <replaceable class="parameter">directory</replaceable></option></term>
!       <term><option>--xlogdir=<replaceable class="parameter">directory</replaceable></option></term>
        <listitem>
         <para>
!         This option specifies the directory where the transaction log
!         should be stored.
         </para>
        </listitem>
       </varlistentry>
-
       <varlistentry>
        <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
        <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
--- 186,199 ----
       </varlistentry>

       <varlistentry>
!       <term><option>--pwfile=<replaceable>filename</></option></term>
        <listitem>
         <para>
!         Makes <command>initdb</command> read the database superuser's password
!         from a file.  The first line of the file is taken as the password.
         </para>
        </listitem>
       </varlistentry>
       <varlistentry>
        <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
        <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
*************** PostgreSQL documentation
*** 226,239 ****
       </varlistentry>

       <varlistentry>
!       <term><option>--pwfile=<replaceable>filename</></option></term>
        <listitem>
         <para>
!         Makes <command>initdb</command> read the database superuser's password
!         from a file.  The first line of the file is taken as the password.
         </para>
        </listitem>
       </varlistentry>
      </variablelist>
     </para>

--- 224,239 ----
       </varlistentry>

       <varlistentry>
!       <term><option>-X <replaceable class="parameter">directory</replaceable></option></term>
!       <term><option>--xlogdir=<replaceable class="parameter">directory</replaceable></option></term>
        <listitem>
         <para>
!         This option specifies the directory where the transaction log
!         should be stored.
         </para>
        </listitem>
       </varlistentry>
+
      </variablelist>
     </para>

diff --git a/doc/src/sgml/ref/pg_controldata.sgml b/doc/src/sgml/ref/pg_controldata.sgml
index 50b1909..d39b6e1 100644
*** a/doc/src/sgml/ref/pg_controldata.sgml
--- b/doc/src/sgml/ref/pg_controldata.sgml
*************** PostgreSQL documentation
*** 22,27 ****
--- 22,28 ----
   <refsynopsisdiv>
    <cmdsynopsis>
     <command>pg_controldata</command>
+    <arg><replaceable class="parameter">option</replaceable></arg>
     <arg><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 307f66b..608749f 100644
*** a/doc/src/sgml/ref/pg_ctl-ref.sgml
--- b/doc/src/sgml/ref/pg_ctl-ref.sgml
*************** PostgreSQL documentation
*** 499,520 ****
     <title>Starting the Server</title>

     <para>
!     To start up a server:
  <screen>
  <prompt>$</prompt> <userinput>pg_ctl start</userinput>
  </screen>
     </para>

     <para>
!     An example of starting the server, and waiting until the server is
!     accepting connection:
  <screen>
  <prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
  </screen>
     </para>

     <para>
!     For a server using port 5433, and
      running without <function>fsync</function>, use:
  <screen>
  <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
--- 499,520 ----
     <title>Starting the Server</title>

     <para>
!     To start the server:
  <screen>
  <prompt>$</prompt> <userinput>pg_ctl start</userinput>
  </screen>
     </para>

     <para>
!     To start the server, waiting until the server is
!     accepting connections:
  <screen>
  <prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
  </screen>
     </para>

     <para>
!     To start the server using port 5433, and
      running without <function>fsync</function>, use:
  <screen>
  <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
*************** PostgreSQL documentation
*** 530,536 ****
  <prompt>$</prompt> <userinput>pg_ctl stop</userinput>
  </screen>
      The <option>-m</option> option allows control over
!     <emphasis>how</emphasis> the server shuts down.
     </para>
    </refsect2>

--- 530,539 ----
  <prompt>$</prompt> <userinput>pg_ctl stop</userinput>
  </screen>
      The <option>-m</option> option allows control over
!     <emphasis>how</emphasis> the server shuts down:
! <screen>
! <prompt>$</prompt> <userinput>pg_ctl stop -m fast</userinput>
! </screen>
     </para>
    </refsect2>

*************** PostgreSQL documentation
*** 557,563 ****
     </para>

     <para>
!     To restart using port 5433 and disable <function>fsync</> upon restart:
  <screen>
  <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
  </screen>
--- 560,566 ----
     </para>

     <para>
!     To restart using port 5433, disabling <function>fsync</> upon restart:
  <screen>
  <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
  </screen>
diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml
index 4437bf8..d332cba 100644
*** a/doc/src/sgml/ref/postgres-ref.sgml
--- b/doc/src/sgml/ref/postgres-ref.sgml
*************** PostgreSQL documentation
*** 66,74 ****
     The <command>postgres</command> command can also be called in
     single-user mode.  The primary use for this mode is during
     bootstrapping by <xref linkend="app-initdb">.  Sometimes it is used
!    for debugging or disaster recovery (but note that running a single-user
     server is not truly suitable for debugging the server, since no
!    realistic interprocess communication and locking will happen).
     When invoked in single-user
     mode from the shell, the user can enter queries and the results
     will be printed to the screen, but in a form that is more useful
--- 66,74 ----
     The <command>postgres</command> command can also be called in
     single-user mode.  The primary use for this mode is during
     bootstrapping by <xref linkend="app-initdb">.  Sometimes it is used
!    for debugging or disaster recovery;  note that running a single-user
     server is not truly suitable for debugging the server, since no
!    realistic interprocess communication and locking will happen.
     When invoked in single-user
     mode from the shell, the user can enter queries and the results
     will be printed to the screen, but in a form that is more useful
*************** PostgreSQL documentation
*** 413,420 ****
        <term><option>-P</option></term>
        <listitem>
         <para>
!         Ignore system indexes when reading system tables (but still update
!         the indexes when modifying the tables).  This is useful when
          recovering from damaged system indexes.
         </para>
        </listitem>
--- 413,420 ----
        <term><option>-P</option></term>
        <listitem>
         <para>
!         Ignore system indexes when reading system tables, but still update
!         the indexes when modifying the tables.  This is useful when
          recovering from damaged system indexes.
         </para>
        </listitem>
*************** PostgreSQL documentation
*** 763,775 ****

    <para>
     To start <command>postgres</command> with a specific
!    port:
  <screen>
  <prompt>$</prompt> <userinput>postgres -p 1234</userinput>
  </screen>
!    This command will start up <command>postgres</command>
!    communicating through the port 1234. In order to connect to this
!    server using <application>psql</>, you would need to run it as
  <screen>
  <prompt>$</prompt> <userinput>psql -p 1234</userinput>
  </screen>
--- 763,773 ----

    <para>
     To start <command>postgres</command> with a specific
!    port, e.g. 1234:
  <screen>
  <prompt>$</prompt> <userinput>postgres -p 1234</userinput>
  </screen>
!    To connect to this server using <application>psql</>, specify this port with the -p option:
  <screen>
  <prompt>$</prompt> <userinput>psql -p 1234</userinput>
  </screen>