Re: doc review for v14

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