Re: doc review for v14

On Wed, Feb 24, 2021 at 04:18:51PM +0900, Michael Paquier wrote:
> On Mon, Feb 22, 2021 at 02:03:45AM -0600, Justin Pryzby wrote:
> > Rebased, with a few additions.
>
> Thanks. I have done a pass through this series, and applied most of
> this stuff with a backpatch for the doc portions.
>
> + The status of each kind of extended statistics is shown in a column
> + named after the "kind" (e.g. Ndistinct).
> + NULL means that it doesn't exist. "defined" means that it was requested
> From 0009, there is a grammar mistake on HEAD here, but I don't
> understand what you mean by "kind" here. Wouldn't it be better to not
> use quotes and just refer to "its type of statistics"?

I mean stxkind. "type" doesn't mean anything.

> 0016 was missing some <command> markups.
>
> This leaves 0003, 0004, 0005, 0010, 0012, 0018, 0020 and 0021 as these
> did not look like improvements after review.

Thanks.

- vacuum the main relation. This option is required when the
+ vacuum the main relation. This option may not be disabled when the
<literal>FULL</literal> option is used.

"This option is required.." sounds like "this option must be specified", which
is wrong.

- publisher. Once the synchronization is done, the control of the
+ publisher. Once synchronization is done, control of the
replication of the table is given back to the main apply process where
- the replication continues as normal.
+ replication continues as normal.

I think "the synchronization" is ok, but "the control" is poor, and "the
replication" is unneeded.

When creating an index on a partitioned table, this column is set to
- the number of partitions on which the index has been completed.
+ the number of partitions on which the index has been created.

What is index "completion" ?

This is very
- convenient, as not only will the existing partitions become indexed, but
- also any partitions that are created in the future will. One limitation is
+ convenient, as not only the existing partitions will be indexed, but
+ so will any partitions that are created in the future. One limitation is

"become indexed" sounds strange (and vague), and "will." is additionally awkward.

--
Justin