Date: Wed, 24 Feb 2021 01:39:55 -0600
From: Justin Pryzby <pryzby@telsasoft.com>
To: Michael Paquier <michael@paquier.xyz>
Cc: pgsql-hackers@postgresql.org, Bruce Momjian <bruce@momjian.us>,
	Thomas Munro <thomas.munro@gmail.com>
Subject: Re: doc review for v14
Message-ID: <20210224073955.GH14772@telsasoft.com>
References: <20201222041153.GK30237@telsasoft.com>
 <X+RNUu+zotOjfL7K@paquier.xyz>
 <20201227202604.GC26311@telsasoft.com>
 <YAv3TG9fOrNXxJoK@paquier.xyz>
 <YBD/jjCqGoSFeUWW@paquier.xyz>
 <YBO6ZGbYRoc5Rkra@paquier.xyz>
 <20210210235557.GQ20012@telsasoft.com>
 <20210222080345.GA23313@telsasoft.com>
 <YDX924cg0EKAgW8v@paquier.xyz>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <YDX924cg0EKAgW8v@paquier.xyz>
User-Agent: Mutt/1.9.4 (2018-02-28)
Precedence: bulk

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