Order some new options on man pages more sensibly, minor improvements

diff --git a/doc/src/sgml/ref/alter_database.sgml b/doc/src/sgml/ref/alter_database.sgml
index 787cfff16736e04cd01d0dd912baf30ae65c5238..cfc28cf9a7708b9a278117b02cd73f223b2ef6f0 100644 (file)
--- a/doc/src/sgml/ref/alter_database.sgml
+++ b/doc/src/sgml/ref/alter_database.sgml
@@ -25,9 +25,9 @@ ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> [ [ WITH ] <rep
 
 <phrase>where <replaceable class="PARAMETER">option</replaceable> can be:</phrase>
 
-    IS_TEMPLATE <replaceable class="PARAMETER">istemplate</replaceable>
     ALLOW_CONNECTIONS <replaceable class="PARAMETER">allowconn</replaceable>
     CONNECTION LIMIT <replaceable class="PARAMETER">connlimit</replaceable>
+    IS_TEMPLATE <replaceable class="PARAMETER">istemplate</replaceable>
 
 ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>new_name</replaceable>
 
@@ -110,17 +110,6 @@ ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> RESET ALL
       </listitem>
      </varlistentry>
 
-     <varlistentry>
-       <term><replaceable class="parameter">istemplate</replaceable></term>
-       <listitem>
-        <para>
-         If true, then this database can be cloned by any user with <literal>CREATEDB</literal>
-         privileges; if false, then only superusers or the owner of the
-         database can clone it.
-        </para>
-       </listitem>
-      </varlistentry>
-
       <varlistentry>
        <term><replaceable class="parameter">allowconn</replaceable></term>
        <listitem>
@@ -140,6 +129,17 @@ ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> RESET ALL
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+       <term><replaceable class="parameter">istemplate</replaceable></term>
+       <listitem>
+        <para>
+         If true, then this database can be cloned by any user with <literal>CREATEDB</literal>
+         privileges; if false, then only superusers or the owner of the
+         database can clone it.
+        </para>
+       </listitem>
+      </varlistentry>
+
    <varlistentry>
     <term><replaceable>new_name</replaceable></term>
     <listitem>

diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml
index 0d187e29f523690ccc6c5a9ce9a48e1153657a65..138996bedc804382177585c12c0eb88b1da1fc03 100644 (file)
--- a/doc/src/sgml/ref/create_database.sgml
+++ b/doc/src/sgml/ref/create_database.sgml
@@ -28,9 +28,9 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
            [ LC_COLLATE [=] <replaceable class="parameter">lc_collate</replaceable> ]
            [ LC_CTYPE [=] <replaceable class="parameter">lc_ctype</replaceable> ]
            [ TABLESPACE [=] <replaceable class="parameter">tablespace_name</replaceable> ]
-           [ IS_TEMPLATE [=] <replaceable class="parameter">istemplate</replaceable> ]
            [ ALLOW_CONNECTIONS [=] <replaceable class="parameter">allowconn</replaceable> ]
            [ CONNECTION LIMIT [=] <replaceable class="parameter">connlimit</replaceable> ] ]
+           [ IS_TEMPLATE [=] <replaceable class="parameter">istemplate</replaceable> ]
 </synopsis>
  </refsynopsisdiv>
 
@@ -149,17 +149,6 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
       </listitem>
      </varlistentry>
 
-     <varlistentry>
-       <term><replaceable class="parameter">istemplate</replaceable></term>
-       <listitem>
-        <para>
-         If true, then this database can be cloned by any user with <literal>CREATEDB</literal>
-         privileges; if false (the default), then only superusers or the owner
-         of the database can clone it.
-        </para>
-       </listitem>
-      </varlistentry>
-
       <varlistentry>
        <term><replaceable class="parameter">allowconn</replaceable></term>
        <listitem>
@@ -180,6 +169,17 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
        </para>
       </listitem>
      </varlistentry>
+
+      <varlistentry>
+       <term><replaceable class="parameter">istemplate</replaceable></term>
+       <listitem>
+        <para>
+         If true, then this database can be cloned by any user with <literal>CREATEDB</literal>
+         privileges; if false (the default), then only superusers or the owner
+         of the database can clone it.
+        </para>
+       </listitem>
+      </varlistentry>
     </variablelist>
 
   <para>

diff --git a/doc/src/sgml/ref/create_policy.sgml b/doc/src/sgml/ref/create_policy.sgml
index 629ed801f24d4043484b8ec2e449f1fb12591441..7b4f9438cd517c70260ba4350431b90607b8fefd 100644 (file)
--- a/doc/src/sgml/ref/create_policy.sgml
+++ b/doc/src/sgml/ref/create_policy.sgml
@@ -34,7 +34,7 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable
 
   <para>
    The <command>CREATE POLICY</command> command defines a new policy for a
-   table.  Note that row level security must also be enabled on the table using
+   table.  Note that row-level security must also be enabled on the table using
    <command>ALTER TABLE</command> in order for created policies to be applied.
   </para>
 

diff --git a/doc/src/sgml/ref/pg_ctl-ref.sgml b/doc/src/sgml/ref/pg_ctl-ref.sgml
index 2df65db0bdde136199122480829d02ff3eb490fe..eaa0cc8b3701e09038a1f69063216026976d7d60 100644 (file)
--- a/doc/src/sgml/ref/pg_ctl-ref.sgml
+++ b/doc/src/sgml/ref/pg_ctl-ref.sgml
@@ -427,10 +427,10 @@ PostgreSQL documentation
        Name of the event source for <application>pg_ctl</application> to use
        for logging to the event log when running as a Windows service.  The
        default is <literal>PostgreSQL</literal>.  Note that this only controls
-       the logging from <application>pg_ctl</application> itself - once
+       the logging from <application>pg_ctl</application> itself; once
        started, the server will use the event source specified
        by <xref linkend="guc-event-source">.  Should the server fail during
-       early startup, it may also log using the default event
+       early startup, it might also log using the default event
        source <literal>PostgreSQL</literal>.
       </para>
      </listitem>

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index cfaec967403c3211df44af51b3aa505cc806156a..9d84f8b4cc3e719c3f4cc0780b9cb7953887510a 100644 (file)
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -707,13 +707,13 @@ PostgreSQL documentation
       <listitem>
        <para>
         This option is relevant only when dumping the contents of a table
-        which has row security.  By default, pg_dump will set
-        <literal>ROW_SECURITY</literal> to <literal>OFF</literal>, to ensure
+        which has row security.  By default, <application>pg_dump</application> will set
+        <xref linkend="guc-row-security"> to off, to ensure
         that all data is dumped from the table.  If the user does not have
         sufficient privileges to bypass row security, then an error is thrown.
         This parameter instructs <application>pg_dump</application> to set
-        row_security to 'ON' instead, allowing the user to dump the contents
-        of the table which they have access to.
+        <xref linkend="guc-row-security"> to on instead, allowing the user
+        to dump the parts of the contents of the table that they have access to.
        </para>
 
       </listitem>
@@ -862,27 +862,6 @@ PostgreSQL documentation
        </listitem>
      </varlistentry>
 
-     <varlistentry>
-       <term><option>--snapshot=<replaceable class="parameter">snapshotname</replaceable></option></term>
-       <listitem>
-         <para>
-          Use the specified synchronized snapshot when making a dump of the
-          database (see
-          <xref linkend="functions-snapshot-synchronization-table"> for more
-          details).
-         </para>
-         <para>
-          This option is useful when needing to synchronize the dump with
-          a logical replication slot (see <xref linkend="logicaldecoding">)
-          or with a concurrent session.
-         </para>
-         <para>
-          In the case of a parallel dump, the snapshot name defined by this
-          option is used rather than taking a new snapshot.
-         </para>
-       </listitem>
-     </varlistentry>
-
      <varlistentry>
       <term><option>--serializable-deferrable</option></term>
       <listitem>
@@ -918,6 +897,27 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+       <term><option>--snapshot=<replaceable class="parameter">snapshotname</replaceable></option></term>
+       <listitem>
+         <para>
+          Use the specified synchronized snapshot when making a dump of the
+          database (see
+          <xref linkend="functions-snapshot-synchronization-table"> for more
+          details).
+         </para>
+         <para>
+          This option is useful when needing to synchronize the dump with
+          a logical replication slot (see <xref linkend="logicaldecoding">)
+          or with a concurrent session.
+         </para>
+         <para>
+          In the case of a parallel dump, the snapshot name defined by this
+          option is used rather than taking a new snapshot.
+         </para>
+       </listitem>
+     </varlistentry>
+
      <varlistentry>
       <term><option>--use-set-session-authorization</></term>
       <listitem>

diff --git a/doc/src/sgml/ref/pg_receivexlog.sgml b/doc/src/sgml/ref/pg_receivexlog.sgml
index 0e6ec1c414467064bc5bf68560a7a882186002ab..0dcba4d54fb7f1ce44609938343af996435a1f13 100644 (file)
--- a/doc/src/sgml/ref/pg_receivexlog.sgml
+++ b/doc/src/sgml/ref/pg_receivexlog.sgml
@@ -50,7 +50,7 @@ PostgreSQL documentation
 
   <para>
    Unlike the standby's WAL receiver, <application>pg_receivexlog</>
-   flushes WAL data only when a WAL file is closed, by default.
+   by default flushes WAL data only when a WAL file is closed.
    <literal>--synchronous</> option must be specified to flush WAL data
    in real time and ensure it's safely flushed to disk.
   </para>

diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index a5a939443d90ce0b7aa51c0b1ea74b4dffe80d39..66d09f4209046537585aac88d13a8d70611a37d7 100644 (file)
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -520,25 +520,25 @@
      </varlistentry>
 
      <varlistentry>
-      <term><option>--enable-row-security</></term>                                                          <listitem>
+      <term><option>--enable-row-security</></term>
+      <listitem>
        <para>
         This option is relevant only when restoring the contents of a table
-        which has row security.  By default, pg_restore will set
-        <literal>ROW_SECURITY</literal> to <literal>OFF</literal>, to ensure
+        which has row security.  By default, <application>pg_restore</application> will set
+        <xref linkend="guc-row-security"> to off, to ensure
         that all data is restored in to the table.  If the user does not have
         sufficient privileges to bypass row security, then an error is thrown.
         This parameter instructs <application>pg_restore</application> to set
-        row_security to 'ON' instead, allowing the user to attempt to restore
-        the contents of the table with row security enabled.  This may still
+        <xref linkend="guc-row-security"> to on instead, allowing the user to attempt to restore
+        the contents of the table with row security enabled.  This might still
         fail if the user does not have the right to insert the rows from the
         dump into the table.
        </para>
 
        <para>
-        Note that this option currently also requires the dump be in INSERT
-        format as COPY TO does not support row security.
+        Note that this option currently also requires the dump be in <command>INSERT</command>
+        format, as <command>COPY TO</command> does not support row security.
        </para>
-
       </listitem>
      </varlistentry>
 

diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml
index 43c05d570cec8802cbac9915bfc1b24c4f3010f0..9cdfa902f5acfcdeb2442a4f21e7acc404974564 100644 (file)
--- a/doc/src/sgml/ref/pg_rewind.sgml
+++ b/doc/src/sgml/ref/pg_rewind.sgml
@@ -81,6 +81,16 @@ PostgreSQL documentation
    <filename>recovery.conf</> file in the target data directory with a
    suitable <varname>restore_command</>.
   </para>
+
+  <para>
+   <application>pg_rewind</> requires that the target server either has
+   the <xref linkend="guc-wal-log-hints"> option is enabled
+   in <filename>postgresql.conf</> or that data checksums were enabled when
+   the cluster was initialized with <application>initdb</>.  Neither of these
+   are currently on by default.
+   <xref linkend="guc-full-page-writes"> must also be enabled.  That is the
+   default.
+  </para>
  </refsect1>
 
  <refsect1>
@@ -159,13 +169,13 @@ PostgreSQL documentation
      <varlistentry>
       <term><option>-V</option></term>
       <term><option>--version</option></term>
-      <listitem><para>Display version information, then exit</para></listitem>
+      <listitem><para>Display version information, then exit.</para></listitem>
      </varlistentry>
 
      <varlistentry>
       <term><option>-?</option></term>
       <term><option>--help</option></term>
-      <listitem><para>Show help, then exit</para></listitem>
+      <listitem><para>Show help, then exit.</para></listitem>
      </varlistentry>
 
     </variablelist>
@@ -185,13 +195,6 @@ PostgreSQL documentation
  <refsect1>
   <title>Notes</title>
 
-  <para>
-   <application>pg_rewind</> requires that the <varname>wal_log_hints</>
-   option is enabled in <filename>postgresql.conf</>, or that data checksums
-   were enabled when the cluster was initialized with <application>initdb</>.
-   <varname>full_page_writes</> must also be enabled.
-  </para>
-
   <refsect2>
    <title>How it works</title>
 

diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index babeb0269bf45df80f4adc629009138896866230..eb113c2629157e73c284a302a3be037d0231505e 100644 (file)
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -414,8 +414,8 @@ pg_upgrade.exe
     servers</title>
 
     <para>
-     If you have Streaming Replication (<xref
-     linkend="streaming-replication">) or Log-Shipping (<xref
+     If you have Streaming Replication (see <xref
+     linkend="streaming-replication">) or Log-Shipping (see <xref
      linkend="warm-standby">) standby servers, follow these steps to
      upgrade them.  You will not be running <application>pg_upgrade</>
      on the standby servers, but rather <application>rsync</>.  Do not

diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml
index e38c34aea37890f57d8a49fd0f87de27715378e2..92b8984b7a6a9db9756ab2176b69841f06485e72 100644 (file)
--- a/doc/src/sgml/ref/vacuumdb.sgml
+++ b/doc/src/sgml/ref/vacuumdb.sgml
@@ -133,6 +133,30 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <term><option>-j <replaceable class="parameter">njobs</replaceable></option></term>
+      <term><option>--jobs=<replaceable class="parameter">njobs</replaceable></option></term>
+      <listitem>
+       <para>
+        Execute the vacuum or analyze commands in parallel by running
+        <replaceable class="parameter">njobs</replaceable>
+        commands simultaneously.  This option reduces the time of the
+        processing but it also increases the load on the database server.
+       </para>
+       <para>
+        <application>vacuumdb</application> will open
+        <replaceable class="parameter">njobs</replaceable> connections to the
+        database, so make sure your <xref linkend="guc-max-connections">
+        setting is high enough to accommodate all connections.
+       </para>
+       <para>
+        Note that using this mode together with the <option>-f</option>
+        (<literal>FULL</literal>) option might cause deadlock failures if
+        certain system catalogs are processed in parallel.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry>
       <term><option>-q</></term>
       <term><option>--quiet</></term>
@@ -203,30 +227,6 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
-     <varlistentry>
-      <term><option>-j <replaceable class="parameter">njobs</replaceable></option></term>
-      <term><option>--jobs=<replaceable class="parameter">njobs</replaceable></option></term>
-      <listitem>
-       <para>
-        Execute the vacuum or analyze commands in parallel by running
-        <replaceable class="parameter">njobs</replaceable>
-        commands simultaneously.  This option reduces the time of the
-        processing but it also increases the load on the database server.
-       </para>
-       <para>
-        <application>vacuumdb</application> will open
-        <replaceable class="parameter">njobs</replaceable> connections to the
-        database, so make sure your <xref linkend="guc-max-connections">
-        setting is high enough to accommodate all connections.
-       </para>
-       <para>
-        Note that using this mode together with the <option>-f</option>
-        (<literal>FULL</literal>) option might cause deadlock failures if
-        certain system catalogs are processed in parallel.
-       </para>
-      </listitem>
-     </varlistentry>
-
      <varlistentry>
       <term><option>--analyze-in-stages</option></term>
       <listitem>