Re: doc review for v13

On Mon, Aug 31, 2020 at 04:28:20PM +0900, Michael Paquier wrote:
> On Tue, Aug 18, 2020 at 12:17:03PM -0500, Justin Pryzby wrote:
> > The WAL sender process is currently performing
> > - <function>pg_start_backup</function> to set up for
> > - taking a base backup, and waiting for backup start
> > + <function>pg_start_backup</function> to prepare to
> > + take a base backup, and waiting for the start-of-backup
> > checkpoint to finish.
>
> Wouldn't it be more simple to use "to prepare for a base backup" here?

I think it's useful to say "prepare to take" since it's more specific.. It's
not "preparing to receive" or "preparing to scan" or "preparing to parse".

> > Replication is only supported by tables, including partitioned tables.
> > Attempts to replicate other types of relations such as views, materialized
> > - views, or foreign tables, will result in an error.
> > + views, or foreign tables will result in an error.
> > </para>
>
> I think that the original is fine.

I think this is indisputably wrong, but I realized that it's actually better
with an *additional* comma:

| Attempts to replicate other types of relations COMMA such as views, materialized
| views, or foreign tables, will result in an error.

> > </para>
> >
> > @@ -121,7 +121,7 @@ PostgreSQL documentation
> > <title>Options</title>
> >
> > <para>
> > - The following command-line options control the behavior.
> > + The following command-line options control the behavior of this program.
>
> "pg_verifybackup accepts the following command-line arguments:" is
> more consistent with the style of all the other tools. This needs to
> be fixed.

> > - to have problems. Also, files which were ignored in the previous step are
> > + to have problems. Files which were ignored in the previous step are
> > also ignored in this step.
>
> No sure this needs to change

Two "also"s seems poor, and the first one detracts from the 2nd.

> > the case of a crash the slot may return to an earlier LSN, which will
> > - then cause recent changes to be resent when the server restarts.
> > + then cause recent changes to be re-sent when the server restarts.
> > Logical decoding clients are responsible for avoiding ill effects from
> > handling the same message more than once. Clients may wish to record
> > the last LSN they saw when decoding and skip over any repeated data or
> > [...]
> > It is safe to use <literal>off</literal> for logical replication:
> > If the subscriber loses transactions because of missing
> > - synchronization, the data will be resent from the publisher.
> > + synchronization, the data will be re-sent from the publisher.
> > </para>
> > [...]
> > - /* prevent signal from being resent more than once */
> > + /* prevent signal from being re-sent more than once */
> > allow_autovacuum_cancel = false;
>
> "resent" is wrong, but "re-sent" does not sound like the best choice
> to me. Shouldn't we just say "sent again" for all three places?

I don't think so.

--
Justin