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