Doc: Improve wording of multiple places in documentation

michaelpq · michaelpq · commit 0431a7874692 · 2019-08-20T12:36:31.000+09:00
This has been found during its translation. Author: Liudmila Mantrova Discussion: https://postgr.es/m/CAEkD-mDJHV3bhgezu3MUafJLoAKsOOT86+wHukKU8_NeiJYhLQ@mail.gmail.com Backpatch-through: 12
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
@@ -3017,9 +3017,9 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
        A <command>DROP</command> of the referenced object will result in
        automatically dropping the dependent object
        whether <literal>CASCADE</literal> is specified or not.  If the
-       dependent object is reached due to a dependency on some other object,
-       the drop is converted to a drop of the referenced object, so
-       that <literal>NORMAL</literal> and <literal>AUTO</literal>
+       dependent object has to be dropped due to a dependency on some other
+       object being removed, its drop is converted to a drop of the referenced
+       object, so that <literal>NORMAL</literal> and <literal>AUTO</literal>
        dependencies of the dependent object behave much like they were
        dependencies of the referenced object.
        Example: a view's <literal>ON SELECT</literal> rule is made
@@ -10967,7 +10967,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
 
   <para>
    <structname>pg_stats_ext</structname> is also designed to present the
-   information in a more readable format than the underlying catalog
+   information in a more readable format than the underlying catalogs
    &mdash; at the cost that its schema must be extended whenever new types
    of extended statistics are added to <structname>pg_statistic_ext</structname>.
   </para>
@@ -11024,7 +11024,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
       <entry><structfield>attnames</structfield></entry>
       <entry><type>name[]</type></entry>
       <entry><literal><link linkend="catalog-pg-attribute"><structname>pg_attribute</structname></link>.attname</literal></entry>
-      <entry>Names of the column the extended statistics is defined on</entry>
+      <entry>Names of the columns the extended statistics is defined on</entry>
      </row>
 
      <row>
@@ -11038,9 +11038,9 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
       <entry><structfield>n_distinct</structfield></entry>
       <entry><type>pg_ndistinct</type></entry>
       <entry></entry>
-      <entry>N-distinct counts for combinations of columns. If greater than
-       zero, the estimated number of distinct values in the combination.  If
-       less than zero, the negative of the number of distinct values divided
+      <entry>N-distinct counts for combinations of column values. If greater
+       than zero, the estimated number of distinct values in the combination.
+       If less than zero, the negative of the number of distinct values divided
        by the number of rows.
        (The negated form is used when <command>ANALYZE</command> believes that
        the number of distinct values is likely to increase as the table grows;
@@ -11063,8 +11063,8 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
       <entry><type>anyarray</type></entry>
       <entry></entry>
       <entry>
-       A list of the most common combinations in the columns. (Null if
-       no values seem to be more common than any others.)
+       A list of the most common combinations of values in the columns.
+       (Null if no combinations seem to be more common than any others.)
       </entry>
      </row>
 
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
@@ -196,7 +196,8 @@ hostnogssenc <replaceable>database</replaceable>  <replaceable>user</replaceable
       </para>
 
       <para>
-        Note that the only supported <xref linkend="auth-methods"/> for use
+        Note that the only supported
+        <link linkend="auth-methods">authentication methods</link> for use
         with <acronym>GSSAPI</acronym> encryption
         are <literal>gss</literal>, <literal>reject</literal>,
         and <literal>trust</literal>.
@@ -489,7 +490,7 @@ hostnogssenc <replaceable>database</replaceable>  <replaceable>user</replaceable
         <listitem>
          <para>
           Use GSSAPI to authenticate the user. This is only
-          available for TCP/IP connections . See <xref
+          available for TCP/IP connections. See <xref
           linkend="gssapi-auth"/> for details.  It can be used in conjunction
           with GSSAPI encryption.
          </para>
@@ -610,8 +611,8 @@ hostnogssenc <replaceable>database</replaceable>  <replaceable>user</replaceable
        <literal>verify-full</literal> additionally enforces that the
        <literal>cn</literal> (Common Name) in the certificate matches
        the username or an applicable mapping.
-       This behavior is similar to the cert authentication method
-       (see <xref linkend="auth-cert"/> ) but enables pairing
+       This behavior is similar to the <literal>cert</literal> authentication
+       method (see <xref linkend="auth-cert"/>) but enables pairing
        the verification of client certificates with any authentication
        method that supports <literal>hostssl</literal> entries.
       </para>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
@@ -3146,29 +3146,29 @@ include_dir 'conf.d'
     </para>
 
     <para>
-     To start the server in standby mode create file called
+     To start the server in standby mode, create a file called
      <filename>standby.signal</filename><indexterm><primary>standby.signal</primary></indexterm>
      in the data directory.  The server will enter recovery and will not stop
      recovery when the end of archived WAL is reached, but will keep trying to
      continue recovery by connecting to the sending server as specified by the
      <varname>primary_conninfo</varname> setting and/or by fetching new WAL
-     segments using <varname>restore_command</varname>.  In this mode, you may
+     segments using <varname>restore_command</varname>.  In this mode, you can
      use parameters in both <xref
      linkend="runtime-config-wal-archive-recovery"/> and <xref
-     linkend="runtime-config-replication-standby"/> sections.  Parameters from
+     linkend="runtime-config-replication-standby"/>.  Parameters from
      <xref linkend="runtime-config-wal-recovery-target"/> will not be used.
     </para>
 
     <para>
-     To start the server in targeted recovery create a file called
+     To start the server in targeted recovery mode, create a file called
      <filename>recovery.signal</filename><indexterm><primary>recovery.signal</primary></indexterm>
      in the data directory.  If both <filename>standby.signal</filename> and
      <filename>recovery.signal</filename> files are created, standby mode
-     takes precedence.  Targeted recovery mode will end when end of archived
-     WAL is reached, or when <varname>recovery_target</varname> is reached.
-     In this mode you may use parameters from both <xref
+     takes precedence.  Targeted recovery mode ends when the archived WAL is
+     fully replayed, or when <varname>recovery_target</varname> is reached.
+     In this mode, you can use parameters from both <xref
      linkend="runtime-config-wal-archive-recovery"/> and <xref
-     linkend="runtime-config-wal-recovery-target"/> sections.  Parameters from <xref
+     linkend="runtime-config-wal-recovery-target"/>.  Parameters from <xref
      linkend="runtime-config-replication-standby"/> will not be used.
     </para>
 
@@ -8032,8 +8032,9 @@ SET XML OPTION { DOCUMENT | CONTENT };
         given decimal precision. The precision used is the standard number of
         digits for the type (<literal>FLT_DIG</literal>
         or <literal>DBL_DIG</literal> as appropriate) reduced according to the
-        value of this parameter. (For example, specifying -1 will cause float4
-        values to be output rounded to 5 significant digits, and float8 values
+        value of this parameter. (For example, specifying -1 will cause
+        <type>float4</type> values to be output rounded to 5 significant
+        digits, and <type>float8</type> values
         rounded to 14 digits.) This format is slower and does not preserve all
         the bits of the binary float value, but may be more human-readable.
        </para>
@@ -9201,10 +9202,10 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
       </term>
       <listitem>
        <para>
-        Reports the name of the SSL library that this PostgreSQL server was
-        built with (even if SSL is not currently configured or in use on this
-        instance), for example <literal>OpenSSL</literal>, or an empty string
-        if none.
+        Reports the name of the SSL library that this
+        <productname>PostgreSQL</productname> server was built with (even if
+        SSL is not currently configured or in use on this instance), for
+        example <literal>OpenSSL</literal>, or an empty string if none.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml
@@ -312,14 +312,14 @@ current=testdb1 (should be testdb1)
   </para>
 
   <para>
-   The third option is to declare a sql identifier linked to
+   The third option is to declare a SQL identifier linked to
    the connection, for example:
 <programlisting>
 EXEC SQL AT <replaceable>connection-name</replaceable> DECLARE <replaceable>statement-name</replaceable> STATEMENT;
 EXEC SQL PREPARE <replaceable>statement-name</replaceable> FROM :<replaceable>dyn-string</replaceable>;
 </programlisting>
-   Once you link a sql identifier to a connection, you execute a dynamic SQL
-   without AT clause.
+   Once you link a SQL identifier to a connection, execute dynamic SQL
+   statements using this identifier without the <literal>AT</literal> clause.
   </para>
   </sect2>
 
@@ -1209,8 +1209,8 @@ EXEC SQL END DECLARE SECTION;
      <title id="ecpg-type-bytea">bytea</title>
 
      <para>
-      The handling of the <type>bytea</type> type is also similar to
-      the <type>VARCHAR</type>. The definition on an array of type
+      The handling of the <type>bytea</type> type is similar to
+      that of <type>VARCHAR</type>. The definition on an array of type
       <type>bytea</type> is converted into a named struct for every
       variable. A declaration like:
 <programlisting>
@@ -1221,8 +1221,8 @@ bytea var[180];
 struct bytea_var { int len; char arr[180]; } var;
 </programlisting>
       The member <structfield>arr</structfield> hosts binary format
-      data. It also can handle even <literal>'\0'</literal> as part of
-      data unlike <type>VARCHAR</type>.
+      data. It can also handle <literal>'\0'</literal> as part of
+      data, unlike <type>VARCHAR</type>.
       The data is converted from/to hex format and sent/received by
       ecpglib.
      </para>
@@ -6810,7 +6810,7 @@ EXEC SQL DECLARE cur1 CURSOR FOR stmt1;
   <refentry id="ecpg-sql-declare-statement">
    <refnamediv>
     <refname>DECLARE STATEMENT</refname>
-    <refpurpose>declares SQL statement identifier associated with connection</refpurpose>
+    <refpurpose>declares a SQL statement identifier associated with connection</refpurpose>
    </refnamediv>
 
    <refsynopsisdiv>
@@ -6823,12 +6823,13 @@ EXEC SQL [ AT <replaceable class="parameter">connection_name</replaceable> ] DEC
     <title>Description</title>
 
     <para>
-     <command>DECLARE STATEMENT</command> declares SQL statement identifier.
-     SQL statement identifier is associated with connection.
+     <command>DECLARE STATEMENT</command> declares a SQL statement identifier
+     to be associated with connection.
     </para>
 
     <para>
-     <command>DECLARE CURSOR</command> with a SQL statement identifier can be written before PREPARE.
+     <command>DECLARE CURSOR</command> with an SQL statement identifier
+     can be written before <command>PREPARE</command>.
     </para>
    </refsect1>
 
@@ -6843,7 +6844,8 @@ EXEC SQL [ AT <replaceable class="parameter">connection_name</replaceable> ] DEC
         A database connection name established by the <command>CONNECT</command> command.
        </para>
        <para>
-        If AT clause is omitted, an SQL statement identifier is associated with the DEFAULT connection.
+        If the <literal>AT</literal> clause is omitted, the SQL statement
+        identifier is associated with the <literal>DEFAULT</literal> connection.
        </para>
       </listitem>
      </varlistentry>
@@ -6854,7 +6856,8 @@ EXEC SQL [ AT <replaceable class="parameter">connection_name</replaceable> ] DEC
       <term><replaceable class="parameter">statement_name</replaceable></term>
       <listitem>
        <para>
-        The name of a SQL statement identifier, either as an SQL identifier or a host variable.
+        The name of the SQL statement identifier, either as an SQL identifier
+        or a host variable.
        </para>
       </listitem>
      </varlistentry>
@@ -6864,26 +6867,27 @@ EXEC SQL [ AT <replaceable class="parameter">connection_name</replaceable> ] DEC
    <refsect1>
     <title>Notes</title>
     <para>
-     AT clause can be used at other dynamic SQL statements. The following table
-     gives the connected database when AT clause is used at DECLARE STATEMENT
-     and other dynamic statements.
+     The <literal>AT</literal> clause can be used with both
+     <command>DECLARE STATEMENT</command> and other dynamic SQL statements.
+     The following table illustrates how it affects the selected database
+     connection.
     </para>
     <table tocentry="1" id="ecpg-declare-statement-table">
      <title>Scenario</title>
      <tgroup cols="4">
       <thead>
        <row>
         <entry>
-         Using Scenario
+         Usage Scenario
         </entry>
         <entry>
-         Declare Statement
+         DECLARE STATEMENT
         </entry>
         <entry>
          Other Dynamic Statements
         </entry>
         <entry>
-         Executed Database
+         Target Database
         </entry>
        </row>
       </thead>
@@ -6893,10 +6897,10 @@ EXEC SQL [ AT <replaceable class="parameter">connection_name</replaceable> ] DEC
          1
         </entry>
         <entry>
-         Without AT clause
+         Without <literal>AT</literal>
         </entry>
         <entry>
-         Without AT clause
+         Without <literal>AT</literal>
         </entry>
         <entry>
          Default connection
@@ -6907,10 +6911,10 @@ EXEC SQL [ AT <replaceable class="parameter">connection_name</replaceable> ] DEC
          2
         </entry>
         <entry>
-         Using AT clause connecting at con1
+         With <literal>AT</literal> that connects to <literal>con1</literal>
         </entry>
         <entry>
-         Without AT clause
+         Without <literal>AT</literal>
         </entry>
         <entry>
          con1
@@ -6921,10 +6925,10 @@ EXEC SQL [ AT <replaceable class="parameter">connection_name</replaceable> ] DEC
          3
         </entry>
         <entry>
-         Using AT clause connecting at con1
+         With <literal>AT</literal> that connects to <literal>con1</literal>
         </entry>
         <entry>
-         Using AT clause connecting at con2
+         With <literal>AT</literal> that connects to <literal>con2</literal>
         </entry>
         <entry>
          con1
@@ -6935,10 +6939,10 @@ EXEC SQL [ AT <replaceable class="parameter">connection_name</replaceable> ] DEC
          4
         </entry>
         <entry>
-         Without AT clause
+         Without <literal>AT</literal>
         </entry>
         <entry>
-         Using AT clause connecting at con2
+         With <literal>AT</literal> that connects to <literal>con2</literal>
         </entry>
         <entry>
          con2
@@ -6948,7 +6952,7 @@ EXEC SQL [ AT <replaceable class="parameter">connection_name</replaceable> ] DEC
      </tgroup>
     </table>
     <para>
-     In scenario 4, DECLARE STATEMENT will be ignored.
+     In scenario 4, <command>DECLARE STATEMENT</command> will be ignored.
     </para>
    </refsect1>
 
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
@@ -5620,13 +5620,13 @@ PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);
       returning the connection's previous setting.
       In <firstterm>TERSE</firstterm> mode, returned messages include
       severity, primary text, and position only; this will normally fit on a
-      single line.  The default mode produces messages that include the above
-      plus any detail, hint, or context fields (these might span multiple
-      lines).  The <firstterm>VERBOSE</firstterm> mode includes all available
-      fields.  The <firstterm>SQLSTATE</firstterm> mode includes only the
-      error severity and the <symbol>SQLSTATE</symbol> error code, if one is
-      available (if not, the output is like <firstterm>TERSE</firstterm>
-      mode).
+      single line.  The <firstterm>DEFAULT</firstterm> mode produces messages
+      that include the above plus any detail, hint, or context fields (these
+      might span multiple lines).  The <firstterm>VERBOSE</firstterm> mode
+      includes all available fields.  The <firstterm>SQLSTATE</firstterm>
+      mode includes only the error severity and the <symbol>SQLSTATE</symbol>
+      error code, if one is available (if not, the output is like
+      <firstterm>TERSE</firstterm> mode).
      </para>
 
      <para>
diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
@@ -871,7 +871,7 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
    <xref linkend="sql-reindex"/> can be used safely and easily in all cases.
    This command requires an <literal>ACCESS EXCLUSIVE</literal> lock by
    default, hence it is often preferable to execute it with its
-   <literal>CONCURRENTLY</literal> option which requires only a
+   <literal>CONCURRENTLY</literal> option, which requires only a
    <literal>SHARE UPDATE EXCLUSIVE</literal> lock.
   </para>
  </sect1>
diff --git a/doc/src/sgml/planstats.sgml b/doc/src/sgml/planstats.sgml
@@ -681,8 +681,8 @@ EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a = 1 AND b = 10;
 </programlisting>
 
     Secondly, <acronym>MCV</acronym> lists handle a wider range of clause types,
-    not just equality clauses like functional dependencies. See for example the
-    example range query, presented earlier:
+    not just equality clauses like functional dependencies. For example,
+    consider the following range query for the same table:
 
 <programlisting>
 EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a &lt;= 49 AND b &gt; 49;
diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
@@ -2239,9 +2239,9 @@ CREATE TABLE cities_partdef
     Typed tables implement a subset of the SQL standard.  According to
     the standard, a typed table has columns corresponding to the
     underlying composite type as well as one other column that is
-    the <quote>self-referencing column</quote>.  PostgreSQL does not
-    support these self-referencing columns explicitly, but the same
-    effect can be had using the OID feature.
+    the <quote>self-referencing column</quote>.
+    <productname>PostgreSQL</productname> does not support self-referencing
+    columns explicitly.
    </para>
   </refsect2>
 
diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
@@ -957,7 +957,8 @@ data. Empty in ordinary tables.</entry>
   only present if the <firstterm>HEAP_HASNULL</firstterm> bit is set in
   <structfield>t_infomask</structfield>. If it is present it begins just after
   the fixed header and occupies enough bytes to have one bit per data column
-  (that is, <structfield>t_natts</structfield> bits altogether). In this list of bits, a
+  (that is, the number of bits that equals the attribute count in
+  <structfield>t_infomask2</structfield>). In this list of bits, a
   1 bit indicates not-null, a 0 bit is a null.  When the bitmap is not
   present, all columns are assumed not-null.
   The object ID is only present if the <firstterm>HEAP_HASOID_OLD</firstterm> bit
