Re: clean up docs for v12

Hi,

On 2019-05-20 13:20:01 -0500, Justin Pryzby wrote:
> On Sat, Mar 30, 2019 at 05:43:33PM -0500, Justin Pryzby wrote:
> Thanks in advance for any review.

I find these pretty tedious to work with. I'm somewhat dyslexic, not a
native speaker. So it requires a lot of concentration to go through
them...


> @@ -3052,7 +3052,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l
>         simplifies <command>ATTACH/DETACH PARTITION</command> operations:
>         the partition dependencies need only be added or removed.
>         Example: a child partitioned index is made partition-dependent
> -       on both the partition table it is on and the parent partitioned
> +       on both the table partition and the parent partitioned
>         index, so that it goes away if either of those is dropped, but
>         not otherwise.  The dependency on the parent index is primary,
>         so that if the user tries to drop the child partitioned index,

> @@ -3115,7 +3115,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l
>     Note that it's quite possible for two objects to be linked by more than
>     one <structname>pg_depend</structname> entry.  For example, a child
>     partitioned index would have both a partition-type dependency on its
> -   associated partition table, and an auto dependency on each column of
> +   associated table partition, and an auto dependency on each column of
>     that table that it indexes.  This sort of situation expresses the union
>     of multiple dependency semantics.  A dependent object can be dropped
>     without <literal>CASCADE</literal> if any of its dependencies satisfies

Hm, that's not an improvement from my POV? The version before isn't great either,
but it seems to improve this'd require a somewhat bigger hammer.



> @@ -6947,8 +6948,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
>         <para>
>          Causes each action executed by autovacuum to be logged if it ran for at
>          least the specified number of milliseconds.  Setting this to zero logs
> -        all autovacuum actions. <literal>-1</literal> (the default) disables
> -        logging autovacuum actions.  For example, if you set this to
> +        all autovacuum actions. <literal>-1</literal> (the default) disables logging
> +        autovacuum actions.  For example, if you set this to
>          <literal>250ms</literal> then all automatic vacuums and analyzes that run
>          250ms or longer will be logged.  In addition, when this parameter is
>          set to any value other than <literal>-1</literal>, a message will be

Hm?


> diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
> index a0a7435..cfe83a8 100644
> --- a/doc/src/sgml/ddl.sgml
> +++ b/doc/src/sgml/ddl.sgml
> @@ -3867,12 +3867,12 @@ CREATE INDEX ON measurement (logdate);
>  
>      <para>
>        Normally the set of partitions established when initially defining the
> -      table are not intended to remain static.  It is common to want to
> -      remove old partitions of data and periodically add new partitions for
> +      table are not intended to remain static.  It's common to
> +      remove partitions of old data and add partitions for
>        new data. One of the most important advantages of partitioning is
> -      precisely that it allows this otherwise painful task to be executed
> +      allowing this otherwise painful task to be executed
>        nearly instantaneously by manipulating the partition structure, rather
> -      than physically moving large amounts of data around.
> +      than physically moving around large amounts of data.
>      </para>

I don't understand what the point of changing things like "It is" to
"It's". There's more uses of the former in the docs.

I'm also not sure that I like the removal of "to want" etc,
because just because it's a common desire, it's not automatically common
practice. And I think the 'periodically' is actually a reasonable hint
that partition creation doesn't happen automatically or in the
foreground.


>       <row>
>        <entry><structfield>partitions_done</structfield></entry>
>        <entry><type>bigint</type></entry>
>        <entry>
> -       When creating an index on a partitioned table, this column is set to
> -       the number of partitions on which the index has been completed.
> +       When creating an index on a partitioned table, this is
> +       the number of partitions for which the process is complete.
>        </entry>
>       </row>
>      </tbody>

> @@ -3643,9 +3643,9 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
>        <entry>
>         The index is being built by the access method-specific code.  In this phase,
>         access methods that support progress reporting fill in their own progress data,
> -       and the subphase is indicated in this column.  Typically,
> +       and the subphase is indicated in this column.
>         <structname>blocks_total</structname> and <structname>blocks_done</structname>
> -       will contain progress data, as well as potentially
> +       will contain progress data, as may
>         <structname>tuples_total</structname> and <structname>tuples_done</structname>.
>        </entry>

Hm, if you're intent on removing "this column", why not here?

Is the removal of "typically" and "potentially" actually correct here?
Somebody clearly wanted to indicate it's not guaranteed?


> @@ -3922,9 +3922,9 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
>    <title>CLUSTER Progress Reporting</title>
>  
>    <para>
> -   Whenever <command>CLUSTER</command> or <command>VACUUM FULL</command> is
> -   running, the <structname>pg_stat_progress_cluster</structname> view will
> -   contain a row for each backend that is currently running either command.
> +   The <structname>pg_stat_progress_cluster</structname> view will contain a
> +   row for each backend that is running either
> +   <command>CLUSTER</command> or <command>VACUUM FULL</command>.
>     The tables below describe the information that will be reported and
>     provide information about how to interpret it.
>    </para>

Unrelated to your change, but I noticed it in this hunk. Isn't it weird
to say "will contain" rather than just "contains" for this type of
reference documentation?


> diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml
> index a84be85..65c161b 100644
> --- a/doc/src/sgml/perform.sgml
> +++ b/doc/src/sgml/perform.sgml
> @@ -899,10 +899,10 @@ EXPLAIN ANALYZE SELECT * FROM tenk1 WHERE unique1 < 100 AND unique2 > 9000
>      Generally, the <command>EXPLAIN</command> output will display details for
>      every plan node which was generated by the query planner.  However, there
>      are cases where the executor is able to determine that certain nodes are
> -    not required; currently, the only node types to support this are the
> -    <literal>Append</literal> and <literal>MergeAppend</literal> nodes.  These
> -    node types have the ability to discard subnodes which they are able to
> -    determine won't contain any records required by the query.  It is possible
> +    not required; currently, the only node types to support this are
> +    <literal>Append</literal> and <literal>MergeAppend</literal>, which
> +    are able to discard subnodes when it's deduced that
> +    they will not contain any records required by the query.  It is possible
>      to determine that nodes have been removed in this way by the presence of a
>      "Subplans Removed" property in the <command>EXPLAIN</command> output.
>     </para>

Shrug.


> diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
> index 49b081a..dd80bd0 100644
> --- a/doc/src/sgml/ref/alter_table.sgml
> +++ b/doc/src/sgml/ref/alter_table.sgml
> @@ -219,7 +219,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
>  
>       <para>
>        <literal>SET NOT NULL</literal> may only be applied to a column
> -      providing none of the records in the table contain a
> +      provided none of the records in the table contain a
>        <literal>NULL</literal> value for the column.  Ordinarily this is
>        checked during the <literal>ALTER TABLE</literal> by scanning the
>        entire table; however, if a valid <literal>CHECK</literal> constraint is

It'd be easier to review / apply this kind of thing if stylistic
choices, especially borderline ones, were separated from clear typos
(like this one).


> diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml
> index 30bb38b..bf4f550 100644
> --- a/doc/src/sgml/ref/create_index.sgml
> +++ b/doc/src/sgml/ref/create_index.sgml
> @@ -181,8 +181,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
>         </para>
>  
>         <para>
> -        Currently, the B-tree and the GiST index access methods support this
> -        feature.  In B-tree and the GiST indexes, the values of columns listed
> +        Currently, only the B-tree and GiST index access methods support this
> +        feature.  In B-tree and GiST indexes, the values of columns listed
>          in the <literal>INCLUDE</literal> clause are included in leaf tuples
>          which correspond to heap tuples, but are not included in upper-level
>          index entries used for tree navigation.

Hm. External index AMs also can also support uniqueness. So perhaps not
adding only is actually better? I realize that other places in the same
file already say "only".


> diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml
> index 4d91eeb..6f6d220 100644
> --- a/doc/src/sgml/ref/pg_rewind.sgml
> +++ b/doc/src/sgml/ref/pg_rewind.sgml
> @@ -106,15 +106,14 @@ PostgreSQL documentation
>     </para>
>  
>     <para>
> -    <application>pg_rewind</application> will fail immediately if it finds
> -    files it cannot write directly to.  This can happen for example when
> -    the source and the target server use the same file mapping for read-only
> -    SSL keys and certificates.  If such files are present on the target server
> +    <application>pg_rewind</application> will fail immediately if it experiences
> +    a write error.  This can happen for example when
> +    the source and target server use the same file mapping for read-only
> +    SSL keys and certificates.  If such files are present on the target server,
>      it is recommended to remove them before running

That's not really the same. The failure will often be *before* a write
error. E.g.
    mode = O_WRONLY | O_CREAT | PG_BINARY;
    if (trunc)
        mode |= O_TRUNC;
    dstfd = open(dstpath, mode, pg_file_create_mode);
    if (dstfd < 0)
        pg_fatal("could not open target file \"%s\": %m",
                 dstpath);
will fail, rather than a write().




> @@ -474,10 +474,8 @@ 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.
> +        <application>pgbench</application> runs faster in prepared mode because the
> +        parse analysis happens only during the first query.
>         </para>

That text seems wrong before and after. It's not just parse analysis,
but also planning?


> --- a/doc/src/sgml/runtime.sgml
> +++ b/doc/src/sgml/runtime.sgml
> @@ -2634,8 +2634,9 @@ openssl x509 -req -in server.csr -text -days 365 \
>     using <acronym>GSSAPI</acronym> to encrypt client/server communications for
>     increased security.  Support requires that a <acronym>GSSAPI</acronym>
>     implementation (such as MIT krb5) is installed on both client and server
> -   systems, and that support in <productname>PostgreSQL</productname> is
> -   enabled at build time (see <xref linkend="installation"/>).
> +   systems, and must be enabled at the time
> +   <productname>PostgreSQL</productname> is built (see <xref
> +   linkend="installation"/>).
>    </para>

This is weird before and after. I'd just say "that PostgreSQL has been
built with GSSAPI support".


>      <para>
> -     For example <literal>_StaticAssert()</literal> and
> +     For example, <literal>_StaticAssert()</literal> and
>       <literal>__builtin_constant_p</literal> are currently used, even though
> -     they are from newer revisions of the C standard and a
> -     <productname>GCC</productname> extension respectively. If not available
> -     we respectively fall back to using a C99 compatible replacement that
> -     performs the same checks, but emits rather cryptic messages and do not
> +     they are from a newer revision of the C standard and a
> +     <productname>GCC</productname> extension, respectively. If not available, in the first case, 
> +     we fall back to using a C99 compatible replacement that
> +     performs the same checks, but emits rather cryptic messages; in the second case, we do not
>       use <literal>__builtin_constant_p</literal>.
>      </para>

To me the point of changing just about equivalent formulations into
another isn't clear.


> @@ -3381,7 +3381,7 @@ if (!ptr)
>      The parallel safety property (<literal>PARALLEL
>      UNSAFE</literal>, <literal>PARALLEL RESTRICTED</literal>, or
>      <literal>PARALLEL SAFE</literal>) must also be specified if you hope
> -    to use the function in parallelized queries.
> +    queries calling the function to use parallel query.
>      It can also be useful to specify the function's estimated execution
>      cost, and/or the number of rows a set-returning function is estimated
>      to return.  However, the declarative way of specifying those two

Seems like a larger rewrite is needed


> @@ -3393,7 +3393,7 @@ if (!ptr)
>      It is also possible to attach a <firstterm>planner support
>      function</firstterm> to a SQL-callable function (called
>      its <firstterm>target function</firstterm>), and thereby provide
> -    knowledge about the target function that is too complex to be
> +    information about the target function that is too complex to be
>      represented declaratively.  Planner support functions have to be
>      written in C (although their target functions might not be), so this is
>      an advanced feature that relatively few people will use.

Why s/knowledge/information/?


> From d8c8b5416726909203db53cfa73ea2c7cc0fe9a0 Mon Sep 17 00:00:00 2001
> From: Justin Pryzby <pryzbyj@telsasoft.com>
> Date: Fri, 29 Mar 2019 19:37:35 -0500
> Subject: [PATCH v3 02/12] Add comma for readability

You did plenty of that in the previous set of changes...

> ---
>  doc/src/sgml/backup.sgml              |  2 +-
>  doc/src/sgml/bki.sgml                 |  2 +-
>  doc/src/sgml/client-auth.sgml         |  4 ++--
>  doc/src/sgml/config.sgml              |  4 ++--
>  doc/src/sgml/ddl.sgml                 |  2 +-
>  doc/src/sgml/indices.sgml             |  2 +-
>  doc/src/sgml/installation.sgml        |  2 +-
>  doc/src/sgml/logical-replication.sgml |  2 +-
>  doc/src/sgml/protocol.sgml            |  6 +++---
>  doc/src/sgml/ref/create_table.sgml    |  2 +-
>  doc/src/sgml/ref/create_table_as.sgml |  2 +-
>  doc/src/sgml/ref/pgupgrade.sgml       |  2 +-
>  doc/src/sgml/ref/psql-ref.sgml        |  2 +-
>  doc/src/sgml/sources.sgml             | 14 +++++++-------
>  doc/src/sgml/wal.sgml                 |  2 +-
>  doc/src/sgml/xoper.sgml               |  2 +-
>  16 files changed, 26 insertions(+), 26 deletions(-)
> 
> diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
> index b67da89..ae41bc7 100644
> --- a/doc/src/sgml/backup.sgml
> +++ b/doc/src/sgml/backup.sgml
> @@ -1024,7 +1024,7 @@ SELECT pg_start_backup('label', true);
>       consider during this backup.
>      </para>
>      <para>
> -     As noted above, if the server crashes during the backup it may not be
> +     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
>       been manually deleted from the <envar>PGDATA</envar> directory.  Note
>       that it is very important to never remove the
> diff --git a/doc/src/sgml/bki.sgml b/doc/src/sgml/bki.sgml
> index aa3d6f8..e27fa76 100644
> --- a/doc/src/sgml/bki.sgml
> +++ b/doc/src/sgml/bki.sgml
> @@ -403,7 +403,7 @@
>      8000—9999.  This minimizes the risk of OID collisions with other
>      patches being developed concurrently.  To keep the 8000—9999
>      range free for development purposes, after a patch has been committed
> -    to the master git repository its OIDs should be renumbered into
> +    to the master git repository, its OIDs should be renumbered into
>      available space below that range.  Typically, this will be done
>      near the end of each development cycle, moving all OIDs consumed by
>      patches committed in that cycle at the same time.  The script
> diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
> index ffed887..098900e 100644
> --- a/doc/src/sgml/client-auth.sgml
> +++ b/doc/src/sgml/client-auth.sgml
> @@ -157,7 +157,7 @@ hostnogssenc <replaceable>database</replaceable>  <replaceable>user</replaceable
>        </para>
>  
>        <para>
> -       To make use of this option the server must be built with
> +       To make use of this option, the server must be built with
>         <acronym>SSL</acronym> support. Furthermore,
>         <acronym>SSL</acronym> must be enabled
>         by setting the <xref linkend="guc-ssl"/> configuration parameter (see
> @@ -189,7 +189,7 @@ hostnogssenc <replaceable>database</replaceable>  <replaceable>user</replaceable
>        </para>
>  
>        <para>
> -       To make use of this option the server must be built with
> +       To make use of this option, the server must be built with
>         <acronym>GSSAPI</acronym> support.  Otherwise,
>         the <literal>hostgssenc</literal> record is ignored except for logging
>         a warning that it cannot match any connections.
> diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
> index 73eb768..54b91d3 100644
> --- a/doc/src/sgml/config.sgml
> +++ b/doc/src/sgml/config.sgml
> @@ -3458,7 +3458,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
>          reached. The default is <literal>pause</literal>, which means recovery will
>          be paused. <literal>promote</literal> means the recovery process will finish
>          and the server will start to accept connections.
> -        Finally <literal>shutdown</literal> will stop the server after reaching the
> +        Finally, <literal>shutdown</literal> will stop the server after reaching the
>          recovery target.
>         </para>
>         <para>
> @@ -4188,7 +4188,7 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="
>         </para>
>         <para>
>          The delay occurs once the database in recovery has reached a consistent
> -        state, until the standby is promoted or triggered. After that the standby
> +        state, until the standby is promoted or triggered. After that, the standby
>          will end recovery without further waiting.
>         </para>
>         <para>
> diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
> index cfe83a8..8135507 100644
> --- a/doc/src/sgml/ddl.sgml
> +++ b/doc/src/sgml/ddl.sgml
> @@ -3866,7 +3866,7 @@ CREATE INDEX ON measurement (logdate);
>      <title>Partition Maintenance</title>
>  
>      <para>
> -      Normally the set of partitions established when initially defining the
> +      Normally, the set of partitions established when initially defining the
>        table are not intended to remain static.  It's common to
>        remove partitions of old data and add partitions for
>        new data. One of the most important advantages of partitioning is
> diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml
> index 95c0a19..e940ddb 100644
> --- a/doc/src/sgml/indices.sgml
> +++ b/doc/src/sgml/indices.sgml
> @@ -1081,7 +1081,7 @@ SELECT x FROM tab WHERE x = 'key' AND z < 42;
>     scan.  Even in the successful case, this approach trades visibility map
>     accesses for heap accesses; but since the visibility map is four orders
>     of magnitude smaller than the heap it describes, far less physical I/O is
> -   needed to access it.  In most situations the visibility map remains
> +   needed to access it.  In most situations, the visibility map remains
>     cached in memory all the time.
>    </para>
>  
> diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
> index 4493862..847e028 100644
> --- a/doc/src/sgml/installation.sgml
> +++ b/doc/src/sgml/installation.sgml
> @@ -2527,7 +2527,7 @@ xcodebuild -version -sdk macosx Path
>  </programlisting>
>      Note that building an extension using a different sysroot version than
>      was used to build the core server is not really recommended; in the
> -    worst case it could result in hard-to-debug ABI inconsistencies.
> +    worst case, it could result in hard-to-debug ABI inconsistencies.
>     </para>
>  
>     <para>
> diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
> index 3f2f674..31c814c 100644
> --- a/doc/src/sgml/logical-replication.sgml
> +++ b/doc/src/sgml/logical-replication.sgml
> @@ -201,7 +201,7 @@
>  
>    <para>
>     Subscriptions are dumped by <command>pg_dump</command> if the current user
> -   is a superuser.  Otherwise a warning is written and subscriptions are
> +   is a superuser.  Otherwise, a warning is written and subscriptions are
>     skipped, because non-superusers cannot read all subscription information
>     from the <structname>pg_subscription</structname> catalog.
>    </para>
> diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
> index 70f7286..3f907f6 100644
> --- a/doc/src/sgml/protocol.sgml
> +++ b/doc/src/sgml/protocol.sgml
> @@ -1449,7 +1449,7 @@ SELECT 1/0;
>      <literal>S</literal>, perform an <acronym>SSL</acronym> startup handshake
>      (not described here, part of the <acronym>SSL</acronym>
>      specification) with the server.  If this is successful, continue
> -    with sending the usual StartupMessage.  In this case the
> +    with sending the usual StartupMessage.  In this case, the
>      StartupMessage and all subsequent data will be
>      <acronym>SSL</acronym>-encrypted.  To continue after
>      <literal>N</literal>, send the usual StartupMessage and proceed without
> @@ -1462,7 +1462,7 @@ SELECT 1/0;
>      the server predates the addition of <acronym>SSL</acronym> support
>      to <productname>PostgreSQL</productname>.  (Such servers are now very ancient,
>      and likely do not exist in the wild anymore.)
> -    In this case the connection must
> +    In this case, the connection must
>      be closed, but the frontend might choose to open a fresh connection
>      and proceed without requesting <acronym>SSL</acronym>.
>     </para>
> @@ -1528,7 +1528,7 @@ SELECT 1/0;
>      The frontend should also be prepared to handle an ErrorMessage
>      response to GSSENCRequest from the server.  This would only occur if
>      the server predates the addition of <acronym>GSSAPI</acronym> encryption
> -    support to <productname>PostgreSQL</productname>.  In this case the
> +    support to <productname>PostgreSQL</productname>.  In this case, the
>      connection must be closed, but the frontend might choose to open a fresh
>      connection and proceed without requesting <acronym>GSSAPI</acronym>
>      encryption.  Given the length limits specified above, the ErrorMessage
> diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
> index 44a61ef..dbb1468 100644
> --- a/doc/src/sgml/ref/create_table.sgml
> +++ b/doc/src/sgml/ref/create_table.sgml
> @@ -1189,7 +1189,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
>        This clause specifies optional storage parameters for a table or index;
>        see <xref linkend="sql-createtable-storage-parameters"
>        endterm="sql-createtable-storage-parameters-title"/> for more
> -      information.  For backward-compatibility the <literal>WITH</literal>
> +      information.  For backward-compatibility, the <literal>WITH</literal>
>        clause for a table can also include <literal>OIDS=FALSE</literal> to
>        specify that rows of the new table should not contain OIDs (object
>        identifiers), <literal>OIDS=TRUE</literal> is not supported anymore.
> diff --git a/doc/src/sgml/ref/create_table_as.sgml b/doc/src/sgml/ref/create_table_as.sgml
> index b5c4ce6..0880459 100644
> --- a/doc/src/sgml/ref/create_table_as.sgml
> +++ b/doc/src/sgml/ref/create_table_as.sgml
> @@ -142,7 +142,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
>        This clause specifies optional storage parameters for the new table;
>        see <xref linkend="sql-createtable-storage-parameters"
>        endterm="sql-createtable-storage-parameters-title"/> for more
> -      information.   For backward-compatibility the <literal>WITH</literal>
> +      information.   For backward-compatibility, the <literal>WITH</literal>
>        clause for a table can also include <literal>OIDS=FALSE</literal> to
>        specify that rows of the new table should contain no OIDs (object
>        identifiers), <literal>OIDS=TRUE</literal> is not supported anymore.
> diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
> index 8288676..6a898d9 100644
> --- a/doc/src/sgml/ref/pgupgrade.sgml
> +++ b/doc/src/sgml/ref/pgupgrade.sgml
> @@ -746,7 +746,7 @@ psql --username=postgres --file=script.sql postgres
>     <application>pg_upgrade</application> launches short-lived postmasters in
>     the old and new data directories.  Temporary Unix socket files for
>     communication with these postmasters are, by default, made in the current
> -   working directory.  In some situations the path name for the current
> +   working directory.  In some situations, the path name for the current
>     directory might be too long to be a valid socket name.  In that case you
>     can use the <option>-s</option> option to put the socket files in some
>     directory with a shorter path name.  For security, be sure that that
> diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
> index b867640..55cc78c 100644
> --- a/doc/src/sgml/ref/psql-ref.sgml
> +++ b/doc/src/sgml/ref/psql-ref.sgml
> @@ -1053,7 +1053,7 @@ testdb=>
>          These operations are not as efficient as the <acronym>SQL</acronym>
>          <command>COPY</command> command with a file or program data source or
>          destination, because all data must pass through the client/server
> -        connection.  For large amounts of data the <acronym>SQL</acronym>
> +        connection.  For large amounts of data, the <acronym>SQL</acronym>
>          command might be preferable.
>          </para>
>          </tip>
> diff --git a/doc/src/sgml/sources.sgml b/doc/src/sgml/sources.sgml
> index 2b9f59d..520bbae 100644
> --- a/doc/src/sgml/sources.sgml
> +++ b/doc/src/sgml/sources.sgml
> @@ -100,7 +100,7 @@ less -x4
>     <para>
>      There are two required elements for every message: a severity level
>      (ranging from <literal>DEBUG</literal> to <literal>PANIC</literal>) and a primary
> -    message text.  In addition there are optional elements, the most
> +    message text.  In addition, there are optional elements, the most
>      common of which is an error identifier code that follows the SQL spec's
>      SQLSTATE conventions.
>      <function>ereport</function> itself is just a shell function that exists
> @@ -473,7 +473,7 @@ Hint:       the addendum
>  
>     <para>
>      Rationale: Messages are not necessarily displayed on terminal-type
> -    displays.  In GUI displays or browsers these formatting instructions are
> +    displays.  In GUI displays or browsers, these formatting instructions are
>      at best ignored.
>     </para>
>  
> @@ -897,14 +897,14 @@ BETTER: unrecognized node type: 42
>     <simplesect>
>      <title>Function-Like Macros and Inline Functions</title>
>      <para>
> -     Both, macros with arguments and <literal>static inline</literal>
> -     functions, may be used. The latter are preferable if there are
> +     Both macros with arguments and <literal>static inline</literal>
> +     functions may be used. The latter are preferable if there are
>       multiple-evaluation hazards when written as a macro, as e.g. the
>       case with
>  <programlisting>
>  #define Max(x, y)       ((x) > (y) ? (x) : (y))
>  </programlisting>
> -     or when the macro would be very long. In other cases it's only
> +     or when the macro would be very long. In other cases, it's only
>       possible to use macros, or at least easier.  For example because
>       expressions of various types need to be passed to the macro.
>      </para>
> @@ -936,7 +936,7 @@ MemoryContextSwitchTo(MemoryContext context)
>     <simplesect>
>      <title>Writing Signal Handlers</title>
>      <para>
> -     To be suitable to run inside a signal handler code has to be
> +     To be suitable to run inside a signal handler, code has to be
>       written very carefully. The fundamental problem is that, unless
>       blocked, a signal handler can interrupt code at any time. If code
>       inside the signal handler uses the same state as code outside,
> @@ -945,7 +945,7 @@ MemoryContextSwitchTo(MemoryContext context)
>       interrupted code.
>      </para>
>      <para>
> -     Barring special arrangements code in signal handlers may only
> +     Barring special arrangements, code in signal handlers may only
>       call async-signal safe functions (as defined in POSIX) and access
>       variables of type <literal>volatile sig_atomic_t</literal>. A few
>       functions in <command>postgres</command> are also deemed signal safe; specifically,
> diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
> index 4eb8feb..30bde24 100644
> --- a/doc/src/sgml/wal.sgml
> +++ b/doc/src/sgml/wal.sgml
> @@ -326,7 +326,7 @@
>     before returning a success indication to the client.  The client is
>     therefore guaranteed that a transaction reported to be committed will
>     be preserved, even in the event of a server crash immediately after.
> -   However, for short transactions this delay is a major component of the
> +   However, for short transactions, this delay is a major component of the
>     total transaction time.  Selecting asynchronous commit mode means that
>     the server returns success as soon as the transaction is logically
>     completed, before the <acronym>WAL</acronym> records it generated have
> diff --git a/doc/src/sgml/xoper.sgml b/doc/src/sgml/xoper.sgml
> index 260e43c..55cd3b1 100644
> --- a/doc/src/sgml/xoper.sgml
> +++ b/doc/src/sgml/xoper.sgml
> @@ -375,7 +375,7 @@ table1.column1 OP table2.column2
>       Another example is that on machines that meet the <acronym>IEEE</acronym>
>       floating-point standard, negative zero and positive zero are different
>       values (different bit patterns) but they are defined to compare equal.
> -     If a float value might contain negative zero then extra steps are needed
> +     If a float value might contain negative zero, then extra steps are needed
>       to ensure it generates the same hash value as positive zero.
>      </para>
>  
> -- 
> 2.7.4
> 

> From 4d7e3b99d6e9e203e539cc8658554294121732b1 Mon Sep 17 00:00:00 2001
> From: Justin Pryzby <pryzbyj@telsasoft.com>
> Date: Fri, 29 Mar 2019 19:40:49 -0500
> Subject: [PATCH v3 03/12] Consistent language: "must be superuser"
> 
> ---
>  src/backend/storage/ipc/signalfuncs.c | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/src/backend/storage/ipc/signalfuncs.c b/src/backend/storage/ipc/signalfuncs.c
> index 4bfbd57..1df5861 100644
> --- a/src/backend/storage/ipc/signalfuncs.c
> +++ b/src/backend/storage/ipc/signalfuncs.c
> @@ -115,7 +115,7 @@ pg_cancel_backend(PG_FUNCTION_ARGS)
>      if (r == SIGNAL_BACKEND_NOSUPERUSER)
>          ereport(ERROR,
>                  (errcode(ERRCODE_INSUFFICIENT_PRIVILEGE),
> -                 (errmsg("must be a superuser to cancel superuser query"))));
> +                 (errmsg("must be superuser to cancel superuser query"))));
>  
>      if (r == SIGNAL_BACKEND_NOPERMISSION)
>          ereport(ERROR,
> @@ -139,12 +139,12 @@ pg_terminate_backend(PG_FUNCTION_ARGS)
>      if (r == SIGNAL_BACKEND_NOSUPERUSER)
>          ereport(ERROR,
>                  (errcode(ERRCODE_INSUFFICIENT_PRIVILEGE),
> -                 (errmsg("must be a superuser to terminate superuser process"))));
> +                 (errmsg("must be superuser to terminate superuser process"))));
>
There's a number of
errhint("The owner of a subscription must be a superuser.")));
style messages, if you're trying for further consistency here...


... Out of steam. And, as it turns out, battery power.

Greetings,

Andres Freund