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-03-01T04:33:55Z
Lists: pgsql-hackers 
On Mon, Mar 01, 2021 at 01:11:10PM +0900, Michael Paquier wrote:
> On Sun, Feb 28, 2021 at 06:46:47PM -0600, Justin Pryzby wrote:
> > It looks like you applied 0010...but I agree that it's not an improvement.  It
> > appears that's something I intended to go back and revisit myself.
> > The rest of the patch looks right, to me.
> 
> Oops.  This was not intended.
> 
> > I'm suggesting to either revert that part, or apply these more polished changes
> > in 0002.
> 
> I would just group both things together.  Monday helping, I can see
> that the new wording is better on a couple of points after doing a
> diff of wal.sgml with c82d59d6:
> - "checksum protected" in the first sentence is weird, so I agree that
> using "By default, data pages are not protected by checksums" is an
> improvement.
> - "assigned" is indeed a bit strange, "includes" is an improvement,
> and I would tend to not use a passive form here.

+1

> - "to recover from corrupt data" is redundant with "to recover data"
> so the second one should be removed.  My take is to use "page
> corruptions" instead of "corrupt data", which should be corrupted data
> to be grammatically correct.

> -   Checksums verification is normally ENABLED when the cluster is initialized using <link
> +   Checksums are normally enabled when the cluster is initialized using <link

I still have an issue with the sentence that begins:
"Checksums are normally enabled..."

It sounds much too close to "Checksums are typically enabled.", which is wrong.
So I proposed something like:

|Enabling checksums is normally done when the cluster is first created by <link
|...

Note, the patch I sent said "create" but should be "created".

> -   When attempting to recover from corrupt data, it may be necessary to bypass
> -   the checksum protection. To do this, temporarily set the configuration
> -   parameter <xref linkend="guc-ignore-checksum-failure" />.
> +   When attempting to recover from page corruptions, it may be necessary to
> +   bypass the checksum protection. To do this, temporarily set the
> +   configuration parameter <xref linkend="guc-ignore-checksum-failure" />.

"page corruptions" is wrong .. you could say "corrupt pages"

-- 
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.