Date: Sun, 28 Feb 2021 18:46:47 -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: <20210301004647.GF20769@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: multipart/mixed; boundary="enGqbSaueFq5omEL"
Content-Disposition: inline
In-Reply-To: <YDX924cg0EKAgW8v@paquier.xyz>
User-Agent: Mutt/1.9.4 (2018-02-28)
Precedence: bulk


--enGqbSaueFq5omEL
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

On Wed, Feb 24, 2021 at 04:18:51PM +0900, Michael Paquier wrote:
> This leaves 0003, 0004, 0005, 0010, 0012, 0018, 0020 and 0021 as these
> did not look like improvements after review.

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.

Subject: [PATCH 10/21] doc review for checksum docs
 doc/src/sgml/wal.sgml | 18 +++++++++---------                                                                                                                                                                                     

I'm suggesting to either revert that part, or apply these more polished changes
in 0002.

-- 
Justin

--enGqbSaueFq5omEL
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
 filename="0001-Partially-revert-bcf2667bf62d72faced64cb60ffbd2e599a.patch"

From 03d014809720d90ba43c780cb34fc82dd7173c8d Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Fri, 26 Feb 2021 19:42:54 -0600
Subject: [PATCH 1/2] Partially revert bcf2667bf62d72faced64cb60ffbd2e599a0ebe8

---
 doc/src/sgml/wal.sgml | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
index 02f576a1a9..66de1ee2f8 100644
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -237,19 +237,19 @@
   </indexterm>
 
   <para>
-   By default, data pages are not protected by checksums, but this can optionally be
-   enabled for a cluster.  When enabled, each data page will be ASSIGNED a
-   checksum that is updated when the page is written and verified each time
-   the page is read. Only data pages are protected by checksums; internal data
+   Data pages are not checksum protected by default, but this can optionally be
+   enabled for a cluster.  When enabled, each data page will be assigned a
+   checksum that is updated when the page is written and verified every time
+   the page is read. Only data pages are protected by checksums, internal data
    structures and temporary files are not.
   </para>
 
   <para>
-   Checksums verification is normally ENABLED when the cluster is initialized using <link
+   Checksums are normally enabled when the cluster is initialized using <link
    linkend="app-initdb-data-checksums"><application>initdb</application></link>.
    They can also be enabled or disabled at a later time as an offline
    operation. Data checksums are enabled or disabled at the full cluster
-   level, and cannot be specified for individual databases or tables.
+   level, and cannot be specified individually for databases or tables.
   </para>
 
   <para>
@@ -260,9 +260,9 @@
   </para>
 
   <para>
-   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 corrupt data it may be necessary to bypass
+   the checksum protection in order to recover data. To do this, temporarily
+   set the configuration parameter <xref linkend="guc-ignore-checksum-failure" />.
   </para>
 
   <sect2 id="checksums-offline-enable-disable">
-- 
2.17.0


--enGqbSaueFq5omEL
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
 filename="0002-Second-attempt-to-improve-checksum-docs.patch"

From bed0d532bc2415cea1e2da54b6842053ecc27e04 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Fri, 26 Feb 2021 19:56:25 -0600
Subject: [PATCH 2/2] Second attempt to improve checksum docs

'assigned' is odd

Each not every

Colon not comma

Rephase 'Checksums are normally enabled...', since this is easy to mis-interpret and sounds like they're enabled by default

Do not repeat: 'to recover...data'
---
 doc/src/sgml/wal.sgml | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
index 66de1ee2f8..347be030b2 100644
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -238,18 +238,18 @@
 
   <para>
    Data pages are not checksum protected by default, but this can optionally be
-   enabled for a cluster.  When enabled, each data page will be assigned a
-   checksum that is updated when the page is written and verified every time
-   the page is read. Only data pages are protected by checksums, internal data
+   enabled for a cluster.  When enabled, a checksum is included in each data page
+   when the page is written and verified each time
+   the page is read. Only data pages are protected by checksums; internal data
    structures and temporary files are not.
   </para>
 
   <para>
-   Checksums are normally enabled when the cluster is initialized using <link
+   Enabling checksums is normally done when the cluster is first create by <link
    linkend="app-initdb-data-checksums"><application>initdb</application></link>.
    They can also be enabled or disabled at a later time as an offline
    operation. Data checksums are enabled or disabled at the full cluster
-   level, and cannot be specified individually for databases or tables.
+   level, and cannot be specified for individual databases or tables.
   </para>
 
   <para>
@@ -260,8 +260,8 @@
   </para>
 
   <para>
-   When attempting to recover from corrupt data it may be necessary to bypass
-   the checksum protection in order to recover data. To do this, temporarily
+   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" />.
   </para>
 
-- 
2.17.0


--enGqbSaueFq5omEL--