From 2d41d914ab70cfd45f89bc1fdf682144efa001b2 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Thu, 23 Aug 2018 20:32:56 +0200
Subject: [PATCH] Copy-editing of pg_verify_checksums help and ref page

Reformat synopsis, put options into better order, make the desciption
line a bit shorter, and put more details into the description.
---
 doc/src/sgml/ref/pg_verify_checksums.sgml     | 38 +++++++++----------
 .../pg_verify_checksums/pg_verify_checksums.c |  8 ++--
 2 files changed, 22 insertions(+), 24 deletions(-)

diff --git a/doc/src/sgml/ref/pg_verify_checksums.sgml b/doc/src/sgml/ref/pg_verify_checksums.sgml
index c4c15a46ba..ecc5501eae 100644
--- a/doc/src/sgml/ref/pg_verify_checksums.sgml
+++ b/doc/src/sgml/ref/pg_verify_checksums.sgml
@@ -16,14 +16,20 @@ PostgreSQL documentation
 
  <refnamediv>
   <refname>pg_verify_checksums</refname>
-  <refpurpose>verify data checksums in an offline <productname>PostgreSQL</productname> database cluster</refpurpose>
+  <refpurpose>verify data checksums in a <productname>PostgreSQL</productname> database cluster</refpurpose>
  </refnamediv>
 
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>pg_verify_checksums</command>
-   <arg choice="opt"><replaceable class="parameter">option</replaceable></arg>
-   <arg choice="opt"><arg choice="opt"><option>-D</option></arg><arg choice="opt"><option>--pgdata</option></arg> <replaceable class="parameter">datadir</replaceable></arg>
+   <arg rep="repeat" choice="opt"><replaceable class="parameter">option</replaceable></arg>
+   <group choice="opt">
+    <group choice="opt">
+     <arg choice="plain"><option>-D</option></arg>
+     <arg choice="plain"><option>--pgdata</option></arg>
+    </group>
+    <replaceable class="parameter"> datadir</replaceable>
+   </group>
   </cmdsynopsis>
  </refsynopsisdiv>
 
@@ -31,7 +37,9 @@ PostgreSQL documentation
   <title>Description</title>
   <para>
    <command>pg_verify_checksums</command> verifies data checksums in a
-   <productname>PostgreSQL</productname> cluster.
+   <productname>PostgreSQL</productname> cluster.  The server must be shut
+   down cleanly before running <application>pg_verify_checksums</application>.
+   The exit status is zero if there are no checksum errors, otherwise nonzero.
   </para>
  </refsect1>
 
@@ -42,7 +50,6 @@ PostgreSQL documentation
     The following command-line options are available:
 
     <variablelist>
-
      <varlistentry>
       <term><option>-D <replaceable>directory</replaceable></option></term>
       <term><option>--pgdata=<replaceable>directory</replaceable></option></term>
@@ -54,19 +61,19 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>-r <replaceable>relfilenode</replaceable></option></term>
+      <term><option>-d</option></term>
       <listitem>
        <para>
-        Only validate checksums in the relation with specified relfilenode.
+        Enable debug output. Lists all checked blocks and their checksum.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>-d</option></term>
+      <term><option>-r <replaceable>relfilenode</replaceable></option></term>
       <listitem>
        <para>
-        Enable debug output. Lists all checked blocks and their checksum.
+        Only validate checksums in the relation with specified relfilenode.
        </para>
       </listitem>
      </varlistentry>
@@ -76,7 +83,7 @@ PostgreSQL documentation
        <term><option>--version</option></term>
        <listitem>
        <para>
-       Print the <application>pg_verify_checksums</application> version and exit.
+        Print the <application>pg_verify_checksums</application> version and exit.
        </para>
        </listitem>
      </varlistentry>
@@ -104,20 +111,11 @@ PostgreSQL documentation
 
     <listitem>
      <para>
-      Specifies the directory where the database cluster is 
+      Specifies the directory where the database cluster is
       stored; can be overridden using the <option>-D</option> option.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect1>
-
- <refsect1>
-  <title>Notes</title>
-  <para>
-   The cluster must be shut down cleanly before running
-   <application>pg_verify_checksums</application>.
-  </para>
- </refsect1>
-
 </refentry>
diff --git a/src/bin/pg_verify_checksums/pg_verify_checksums.c b/src/bin/pg_verify_checksums/pg_verify_checksums.c
index 28c975446e..7cf3cf35c7 100644
--- a/src/bin/pg_verify_checksums/pg_verify_checksums.c
+++ b/src/bin/pg_verify_checksums/pg_verify_checksums.c
@@ -38,13 +38,13 @@ static const char *progname;
 static void
 usage()
 {
-	printf(_("%s verifies page level checksums in offline PostgreSQL database cluster.\n\n"), progname);
+	printf(_("%s verifies data checksums in a PostgreSQL database cluster.\n\n"), progname);
 	printf(_("Usage:\n"));
-	printf(_("  %s [OPTION] [DATADIR]\n"), progname);
+	printf(_("  %s [OPTION]... [DATADIR]\n"), progname);
 	printf(_("\nOptions:\n"));
 	printf(_(" [-D, --pgdata=]DATADIR  data directory\n"));
-	printf(_("  -r relfilenode         check only relation with specified relfilenode\n"));
-	printf(_("  -d                     debug output, listing all checked blocks\n"));
+	printf(_("  -d                     debug output, list all checked blocks\n"));
+	printf(_("  -r RELFILENODE         check only relation with specified relfilenode\n"));
 	printf(_("  -V, --version          output version information, then exit\n"));
 	printf(_("  -?, --help             show this help, then exit\n"));
 	printf(_("\nIf no data directory (DATADIR) is specified, "
-- 
2.40.0