doc: wording improvements

Discussion: https://postgr.es/m/a5180360-ec04-ac58-25ce-3d795d3d1f6c@postgrespro.ru

Author: Ekaterina Kiryanova

Backpatch-through: master

doc/src/sgml/charset.sgml

@@ -293,10 +293,10 @@ initdb --locale=sv_SE
      <para>
       As explained above, the environment of the operating system provides the
       defaults for the locales of a newly initialized database cluster.  In
-      many cases, this is enough: If the operating system is configured for
+      many cases, this is enough: if the operating system is configured for
-      the desired language/territory, then
+      the desired language/territory, by default
-      <productname>PostgreSQL</productname> will by default also behave
+      <productname>PostgreSQL</productname> will also behave according
-      according to that locale.
+      to that locale.
      </para>
     </listitem>
 

doc/src/sgml/config.sgml

@@ -9041,7 +9041,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
        <para>
         The timeout is measured from the time a command arrives at the
         server until it is completed by the server.  If multiple SQL
-        statements appear in a single simple-Query message, the timeout
+        statements appear in a single simple-query message, the timeout
         is applied to each statement separately.
         (<productname>PostgreSQL</productname> versions before 13 usually
         treated the timeout as applying to the whole query string.)

doc/src/sgml/high-availability.sgml

@@ -1359,8 +1359,8 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)'
 
    <para>
     If you need to re-create a standby server while transactions are
-    waiting, make sure that the commands pg_backup_start() and
+    waiting, make sure that the functions <function>pg_backup_start()</function>
-    pg_backup_stop() are run in a session with
+    and <function>pg_backup_stop()</function> are run in a session with
     <varname>synchronous_commit</varname> = <literal>off</literal>, otherwise those
     requests will wait forever for the standby to appear.
    </para>
@@ -2219,10 +2219,11 @@ HINT:  You can then restart the server after making the necessary configuration
     The cumulative statistics system is active during recovery. All scans,
     reads, blocks, index usage, etc., will be recorded normally on the
     standby. However, WAL replay will not increment relation and database
-    specific counters. I.e. replay will not increment pg_stat_all_tables
+    specific counters. I.e. replay will not increment
-    columns (like n_tup_ins), nor will reads or writes performed by the
+    <structname>pg_stat_all_tables</structname> columns (like <structfield>n_tup_ins</structfield>),
-    startup process be tracked in the pg_statio views, nor will associated
+    nor will reads or writes performed by the startup process be tracked in the
-    pg_stat_database columns be incremented.
+    <structname>pg_statio_</structname> views, nor will associated
+    <structname>pg_stat_database</structname> columns be incremented.
    </para>
 
    <para>

doc/src/sgml/indices.sgml

@@ -754,7 +754,7 @@ CREATE INDEX people_names ON people ((first_name || ' ' || last_name));
   <para>
    Index expressions are relatively expensive to maintain, because the
    derived expression(s) must be computed for each row insertion
-   and <link linkend="storage-hot">non-HOT update.</link>  However, the index expressions are
+   and <link linkend="storage-hot">non-HOT update</link>. However, the index expressions are
    <emphasis>not</emphasis> recomputed during an indexed search, since they are
    already stored in the index.  In both examples above, the system
    sees the query as just <literal>WHERE indexedcolumn = 'constant'</literal>

doc/src/sgml/logicaldecoding.sgml

@@ -144,7 +144,7 @@ postgres=# SELECT pg_drop_replication_slot('regression_slot');
 </programlisting>
 
    <para>
-    The following examples shows how logical decoding is controlled over the
+    The following examples show how logical decoding is controlled over the
     streaming replication protocol, using the
     program <xref linkend="app-pgrecvlogical"/> included in the PostgreSQL
     distribution.  This requires that client authentication is set up to allow

doc/src/sgml/monitoring.sgml

@@ -261,7 +261,7 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
    unnecessary and can be avoided by setting
    <varname>stats_fetch_consistency</varname> to <literal>none</literal>.
 
-   You can invoke <function>pg_stat_clear_snapshot</function>() to discard the
+   You can invoke <function>pg_stat_clear_snapshot()</function> to discard the
    current transaction's statistics snapshot or cached values (if any).  The
    next use of statistical information will (when in snapshot mode) cause a
    new snapshot to be built or (when in cache mode) accessed statistics to be

doc/src/sgml/ref/merge.sgml

@@ -381,9 +381,9 @@ DELETE
       An expression to assign to the column.  If used in a
       <literal>WHEN MATCHED</literal> clause, the expression can use values
       from the original row in the target table, and values from the
-      <literal>data_source</literal> row.
+      <replaceable>data_source</replaceable> row.
       If used in a <literal>WHEN NOT MATCHED</literal> clause, the
-      expression can use values from the <literal>data_source</literal>.
+      expression can use values from the <replaceable>data_source</replaceable>.
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/pg_basebackup.sgml

@@ -422,8 +422,9 @@ PostgreSQL documentation
         A compression detail string can optionally be specified.
         If the detail string is an integer, it specifies the compression
         level.  Otherwise, it should be a comma-separated list of items,
-        each of the form <literal>keyword</literal> or
+        each of the form
-        <literal>keyword=value</literal>.
+        <replaceable>keyword</replaceable> or
+        <replaceable>keyword=value</replaceable>.
         Currently, the supported keywords are <literal>level</literal>,
         <literal>long</literal>, and <literal>workers</literal>.
         The detail string cannot be used when the compression method
@@ -1019,7 +1020,7 @@ PostgreSQL documentation
 </screen></para>
 
   <para>
-   To create a backup of a local server with one tar file for each tablespace
+   To create a backup of the local server with one tar file for each tablespace
    compressed with <application>gzip</application> at level 9, stored in the
    directory <filename>backup</filename>:
 <screen>

doc/src/sgml/ref/pg_receivewal.sgml

@@ -281,7 +281,8 @@ PostgreSQL documentation
         A compression detail string can optionally be specified.  If the
         detail string is an integer, it specifies the compression level.
         Otherwise, it should be a comma-separated list of items, each of the
-        form <literal>keyword</literal> or <literal>keyword=value</literal>.
+        form <replaceable>keyword</replaceable> or
+        <replaceable>keyword=value</replaceable>.
         Currently, the only supported keyword is <literal>level</literal>.
        </para>
        <para>

doc/src/sgml/ref/pg_recvlogical.sgml

@@ -274,7 +274,7 @@ PostgreSQL documentation
        <listitem>
        <para>
         Enables decoding of prepared transactions. This option may only be specified with
-        <option>--create-slot</option>
+        <option>--create-slot</option>.
        </para>
        </listitem>
      </varlistentry>

doc/src/sgml/ref/pg_restore.sgml

@@ -659,7 +659,7 @@ PostgreSQL documentation
        <para>
         Do not output commands to select table access methods.
         With this option, all objects will be created with whichever
-        access method is the default during restore.
+        table access method is the default during restore.
        </para>
       </listitem>
      </varlistentry>

doc/src/sgml/ref/pg_waldump.sgml

@@ -117,7 +117,7 @@ PostgreSQL documentation
       <term><option>--fork=<replaceable>fork</replaceable></option></term>
       <listitem>
        <para>
-        If provided, only display records that modify blocks in the given fork.
+        Only display records that modify blocks in the given fork.
         The valid values are <literal>main</literal> for the main fork,
         <literal>fsm</literal> for the free space map,
         <literal>vm</literal> for the visibility map,
@@ -174,12 +174,13 @@ PostgreSQL documentation
         names, and exit.
        </para>
        <para>
-        Extensions may define custom resource managers, but pg_waldump does
+        Extensions may define custom resource managers, but
+        <application>pg_waldump</application> does
         not load the extension module and therefore does not recognize custom
         resource managers by name. Instead, you can specify the custom
         resource managers as <literal>custom###</literal> where
-        "<literal>###</literal>" is the three-digit resource manager ID. Names
+        <replaceable>###</replaceable> is the three-digit resource manager ID.
-        of this form will always be considered valid.
+        Names of this form will always be considered valid.
        </para>
       </listitem>
      </varlistentry>

doc/src/sgml/ref/pgbench.sgml

@@ -229,7 +229,8 @@ pgbench <optional> <replaceable>options</replaceable> </optional> <replaceable>d
             data is generated in <command>pgbench</command> client and then
             sent to the server. This uses the client/server bandwidth
             extensively through a <command>COPY</command>.
-            <command>pgbench</command> uses the FREEZE option with version 14 or later
+            <command>pgbench</command> uses the <option>FREEZE</option> option
+            with version 14 or later
             of <productname>PostgreSQL</productname> to speed up
             subsequent <command>VACUUM</command>, except on the
             <literal>pgbench_accounts</literal> table if partitions are
@@ -1118,7 +1119,8 @@ pgbench <optional> <replaceable>options</replaceable> </optional> <replaceable>d
     each SQL command on a single line ending with a semicolon.
    </para>
    <para>
-    It is assumed that pgbench scripts do not contain incomplete blocks of SQL
+    It is assumed that <application>pgbench</application> scripts do not contain
+    incomplete blocks of SQL
     transactions. If at runtime the client reaches the end of the script without
     completing the last transaction block, it will be aborted.
    </para>
@@ -2636,7 +2638,7 @@ END;
   </para>
 
   <para>
-   Here is some example output generated with these options:
+   Here is some example output generated with this option:
 <screen>
 <userinput>pgbench --aggregate-interval=10 --time=20 --client=10 --log --rate=1000 --latency-limit=10 --failures-detailed --max-tries=10 test</userinput>