Horton

Re: doc review for v14

Justin Pryzby <pryzby@telsasoft.com>

View thread View on postgr.es
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>
Date: 2021-02-24T07:39:55Z
Lists: pgsql-hackers 
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

Commits

  1. Fix typos and grammar in comments and docs

  2. Fix typos and grammar in documentation and code comments

  3. Move pg_stat_statements query jumbling to core.

  4. doc: Improve description of data checksums

  5. Fix some typos, grammar and style in docs and comments

  6. doc: Improve wording of section for repslot statistics

  7. Implement support for bulk inserts in postgres_fdw

  8. psql \dX: list extended statistics objects

  9. Add documentation chapter about checksums

  10. Simplify some comments in xml.c

  11. Allow decoding at prepare time in ReorderBuffer.

  12. Extend the output plugin API to allow decoding of prepared xacts.

  13. doc: Improve some grammar and sentences

  14. doc: Improve description of min_dynamic_shared_memory

  15. Fix typos and grammar in docs and comments

  16. Multirange datatypes

  17. Move per-agg and per-trans duplicate finding to the planner.

  18. Allow pg_rewind to use a standby server as the source system.

  19. snapshot scalability: cache snapshots using a xact completion counter.

  20. Add tests for tuplesort.c.

  21. Document piecemeal construction of partitioned indexes

  22. Report progress of CREATE INDEX operations

  23. Fix misc typos, mostly in comments.

  24. Improve pageinspect module

  25. Revamp the WAL record format.

  26. Fix assorted bugs in CREATE/DROP INDEX CONCURRENTLY.