Fix and improve several places in the docs

michaelpq · michaelpq · commit de14e54d7bd7 · 2019-07-13T14:43:48.000+09:00
This adds some missing markups, fixes a couple of incorrect ones and clarifies some documentation in various places. Author: Liudmila Mantrova Discussion: https://postgr.es/m/a068f947-7a51-5df1-b3fd-1a131ae5c044@postgrespro.ru Backpatch-through: 12
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
@@ -962,10 +962,10 @@ SELECT * FROM pg_stop_backup(false, true);
      The process for an exclusive backup is mostly the same as for a
      non-exclusive one, but it differs in a few key steps. This type of
      backup can only be taken on a primary and does not allow concurrent
-     backups.  Moreover, because it writes a backup_label file on the
-     master, it can cause the master to fail to restart automatically after
-     a crash.  On the other hand, the erroneous removal of a backup_label
-     file from a backup or standby is a common mistake which can result
+     backups.  Moreover, because it creates a backup label file, as
+     described below, it can block automatic restart of the master server
+     after a crash.  On the other hand, the erroneous removal of this
+     file from a backup or standby is a common mistake, which can result
      in serious data corruption.  If it is necessary to use this method,
      the following steps may be used.
     </para>
@@ -1025,10 +1025,10 @@ SELECT pg_start_backup('label', true);
     </para>
     <para>
      As noted above, if the server crashes during the backup it may not be
-     possible to restart until the <literal>backup_label</literal> file has
+     possible to restart until the <filename>backup_label</filename> file has
      been manually deleted from the <envar>PGDATA</envar> directory.  Note
      that it is very important to never remove the
-     <literal>backup_label</literal> file when restoring a backup, because
+     <filename>backup_label</filename> file when restoring a backup, because
      this will result in corruption.  Confusion about when it is appropriate
      to remove this file is a common cause of data corruption when using this
      method; be very certain that you remove the file only on an existing
@@ -1075,7 +1075,7 @@ SELECT pg_stop_backup();
      lack of disk space, failure to call <function>pg_stop_backup</function>
      will leave the server in backup mode indefinitely, causing future backups
      to fail and increasing the risk of a restart failure during the time that
-     <literal>backup_label</literal> exists.
+     <filename>backup_label</filename> exists.
     </para>
    </listitem>
   </orderedlist>
diff --git a/doc/src/sgml/biblio.sgml b/doc/src/sgml/biblio.sgml
@@ -137,14 +137,11 @@
    </biblioentry>
 
    <biblioentry id="sqltr-19075-6">
-    <title>SQL Technical Report</title>
+    <title><ulink url="http://standards.iso.org/ittf/PubliclyAvailableStandards/c067367_ISO_IEC_TR_19075-6_2017.zip">SQL Technical Report</ulink></title>
     <subtitle>Part 6: SQL support for JavaScript Object
       Notation (JSON)</subtitle>
-    <edition>First Edition.</edition>
-    <biblioid>
-    <ulink url="http://standards.iso.org/ittf/PubliclyAvailableStandards/c067367_ISO_IEC_TR_19075-6_2017.zip"></ulink>.
-    </biblioid>
-    <pubdate>2017.</pubdate>
+    <edition>First Edition</edition>
+    <pubdate>2017</pubdate>
    </biblioentry>
 
   </bibliodiv>
diff --git a/doc/src/sgml/ref/alter_foreign_table.sgml b/doc/src/sgml/ref/alter_foreign_table.sgml
@@ -227,8 +227,8 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab
     <listitem>
      <para>
       Backward compatibility syntax for removing the <literal>oid</literal>
-      system column. As oid system columns cannot be added anymore, this never
-      has an effect.
+      system column. As <literal>oid</literal> system columns cannot be added
+      anymore, this never has an effect.
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/ref/pg_checksums.sgml b/doc/src/sgml/ref/pg_checksums.sgml
@@ -120,7 +120,7 @@ PostgreSQL documentation
         to be written safely to disk.  This option causes
         <command>pg_checksums</command> to return without waiting, which is
         faster, but means that a subsequent operating system crash can leave
-        the updated data folder corrupt.  Generally, this option is useful
+        the updated data directory corrupt.  Generally, this option is useful
         for testing but should not be used on a production installation.
         This option has no effect when using <literal>--check</literal>.
        </para>
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
@@ -749,7 +749,7 @@ PostgreSQL documentation
       <term><option>--extra-float-digits=<replaceable class="parameter">ndigits</replaceable></option></term>
       <listitem>
        <para>
-        Use the specified value of extra_float_digits when dumping
+        Use the specified value of <option>extra_float_digits</option> when dumping
         floating-point data, instead of the maximum available precision.
         Routine dumps made for backup purposes should not use this option.
        </para>
diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml
@@ -184,7 +184,7 @@ PostgreSQL documentation
         to be written safely to disk.  This option causes
         <command>pg_rewind</command> to return without waiting, which is
         faster, but means that a subsequent operating system crash can leave
-        the synchronized data folder corrupt.  Generally, this option is
+        the synchronized data directory corrupt.  Generally, this option is
         useful for testing but should not be used when creating a production
         installation.
        </para>
diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml
@@ -474,10 +474,10 @@ pgbench <optional> <replaceable>options</replaceable> </optional> <replaceable>d
            </listitem>
           </itemizedlist>
 
-        Because in "prepared" mode <application>pgbench</application> reuses
-        the parse analysis result for the second and subsequent query
-        iteration, <application>pgbench</application> runs faster in the
-        prepared mode than in other modes.
+        In the <literal>prepared</literal> mode, <application>pgbench</application>
+        reuses the parse analysis result starting from the second query
+        iteration, so <application>pgbench</application> runs faster
+        than in other modes.
        </para>
        <para>
         The default is simple query protocol.  (See <xref linkend="protocol"/>
diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml
@@ -156,7 +156,7 @@ REINDEX [ ( VERBOSE ) ] { INDEX | TABLE | SCHEMA | DATABASE | SYSTEM } [ CONCURR
      <para>
       When this option is used, <productname>PostgreSQL</productname> will rebuild the
       index without taking any locks that prevent concurrent inserts,
-      updates, or deletes on the table; whereas a standard reindex build
+      updates, or deletes on the table; whereas a standard index rebuild
       locks out writes (but not reads) on the table until it's done.
       There are several caveats to be aware of when using this option
       &mdash; see <xref linkend="sql-reindex-concurrently"
@@ -280,12 +280,12 @@ REINDEX [ ( VERBOSE ) ] { INDEX | TABLE | SCHEMA | DATABASE | SYSTEM } [ CONCURR
     of writes.  This method is invoked by specifying the
     <literal>CONCURRENTLY</literal> option of <command>REINDEX</command>. When this option
     is used, <productname>PostgreSQL</productname> must perform two scans of the table
-    for each index that needs to be rebuild and in addition it must wait for
-    all existing transactions that could potentially use the index to
-    terminate. This method requires more total work than a standard index
+    for each index that needs to be rebuilt and wait for termination of
+    all existing transactions that could potentially use the index.
+    This method requires more total work than a standard index
     rebuild and takes significantly longer to complete as it needs to wait
     for unfinished transactions that might modify the index. However, since
-    it allows normal operations to continue while the index is rebuilt, this
+    it allows normal operations to continue while the index is being rebuilt, this
     method is useful for rebuilding indexes in a production environment. Of
     course, the extra CPU, memory and I/O load imposed by the index rebuild
     may slow down other operations.
@@ -442,8 +442,8 @@ broken_db=&gt; \q
 </programlisting></para>
 
   <para>
-   Rebuild a table while authorizing read and write operations on involved
-   relations when performed:
+   Rebuild indexes for a table, without blocking read and write operations
+   on involved relations while reindexing is in progress:
 
 <programlisting>
 REINDEX TABLE CONCURRENTLY my_broken_table;
