Improve wording of initdb and pg_controldata manual pages.

gabrielle <gorthx@gmail.com>

doc/src/sgml/ref/initdb.sgml

@@ -22,9 +22,9 @@ PostgreSQL documentation
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>initdb</command>
-   <arg rep="repeat"><replaceable>option</></arg>
+   <arg rep="repeat"><replaceable>option</replaceable></arg>
    <group choice="plain">
-    <arg>--pgdata </arg>
+    <arg>--pgdata=</arg>
     <arg>-D </arg>
     <replaceable>directory</replaceable>
    </group>
@@ -186,16 +186,14 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>-X <replaceable class="parameter">directory</replaceable></option></term>
-      <term><option>--xlogdir=<replaceable class="parameter">directory</replaceable></option></term>
+      <term><option>--pwfile=<replaceable>filename</></option></term>
       <listitem>
        <para>
-        This option specifies the directory where the transaction log
-        should be stored.
+        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>
@@ -226,14 +224,16 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>--pwfile=<replaceable>filename</></option></term>
+      <term><option>-X <replaceable class="parameter">directory</replaceable></option></term>
+      <term><option>--xlogdir=<replaceable class="parameter">directory</replaceable></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.
+        This option specifies the directory where the transaction log
+        should be stored.
        </para>
       </listitem>
      </varlistentry>
+
     </variablelist>
    </para>
 

doc/src/sgml/ref/pg_controldata.sgml

@@ -22,6 +22,7 @@ PostgreSQL documentation
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>pg_controldata</command>
+   <arg><replaceable class="parameter">option</replaceable></arg>
    <arg><replaceable class="parameter">datadir</replaceable></arg>
   </cmdsynopsis>
  </refsynopsisdiv>

doc/src/sgml/ref/pg_ctl-ref.sgml

@@ -499,22 +499,22 @@ PostgreSQL documentation
    <title>Starting the Server</title>
 
    <para>
-    To start up a server:
+    To start the 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:
+    To start the server, waiting until the server is
+    accepting connections:
 <screen>
 <prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
 </screen>
    </para>
 
    <para>
-    For a server using port 5433, and
+    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>
@@ -530,7 +530,10 @@ PostgreSQL documentation
 <prompt>$</prompt> <userinput>pg_ctl stop</userinput>
 </screen>
     The <option>-m</option> option allows control over
-    <emphasis>how</emphasis> the server shuts down.
+    <emphasis>how</emphasis> the server shuts down:
+<screen>
+<prompt>$</prompt> <userinput>pg_ctl stop -m fast</userinput>
+</screen>
    </para>
   </refsect2>
 
@@ -557,7 +560,7 @@ PostgreSQL documentation
    </para>
 
    <para>
-    To restart using port 5433 and disable <function>fsync</> upon restart:
+    To restart using port 5433, disabling <function>fsync</> upon restart:
 <screen>
 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
 </screen>

doc/src/sgml/ref/postgres-ref.sgml

@@ -66,9 +66,9 @@ PostgreSQL documentation
    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
+   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).
+   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
@@ -413,8 +413,8 @@ PostgreSQL documentation
       <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
+        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>
@@ -763,13 +763,11 @@ PostgreSQL documentation
 
   <para>
    To start <command>postgres</command> with a specific
-   port:
+   port, e.g. 1234:
 <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
+   To connect to this server using <application>psql</>, specify this port with the -p option:
 <screen>
 <prompt>$</prompt> <userinput>psql -p 1234</userinput>
 </screen>