Date: Fri, 26 Apr 2019 21:56:47 -0500
From: Justin Pryzby <pryzby@telsasoft.com>
To: Michael Paquier <michael@paquier.xyz>
Cc: Alvaro Herrera <alvherre@2ndquadrant.com>,
	Andres Freund <andres@anarazel.de>, pgsql-hackers@postgresql.org
Subject: Re: clean up docs for v12
Message-ID: <20190427025647.GD3925@telsasoft.com>
References: <20190422160807.xmdhtrtpowkjmyfd@alap3.anarazel.de>
 <20190422161955.GA17411@alvherre.pgsql>
 <20190423025042.GI2712@paquier.xyz>
 <20190426171722.GB3925@telsasoft.com>
 <20190427004420.GD2032@paquier.xyz>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20190427004420.GD2032@paquier.xyz>
User-Agent: Mutt/1.5.24 (2015-08-30)
Precedence: bulk

On Sat, Apr 27, 2019 at 09:44:20AM +0900, Michael Paquier wrote:
> On Fri, Apr 26, 2019 at 12:17:22PM -0500, Justin Pryzby wrote:
> > But I think the biggest part of the patch is still not even reviewed ?
> > I'm referring to ./*review-docs-for-pg12dev.patch
> 
> Nope.  I looked at the patch, and as mentioned upthread the suggested
> changes did not seem like improvements as the existing sentences make
> sense, at least to me.  Do you have any particular part of your patch
> where you think your wording is an improvement?  Why do you think so?

That's mostly new language from v12 commits which I specifically reviewed and
worth cleaning up before release.

If nobody else is interested then I'll forget about it, but they're *all*
(minor) improvements IMO.  

I don't think it's be useful to enumerate justifications for each hunk; if one
of them isn't agreed to be an improvement, I'd just remove it.

But here's some one-liner excerpts.

-      is <literal>2</literal> bits and maximum is <literal>4095</literal>.  Parameters for
+      is <literal>2</literal> bits and the maximum is <literal>4095</literal>.  Parameters for

Adding "the" makes it a complete sentence and not a fragment.

-        all autovacuum actions. Minus-one (the default) disables logging
+        all autovacuum actions. <literal>-1</literal> (the default) disables logging

There's nothing else that says "minus-one" anywhere else on that page.  I just
found one in auto-explain.sgml, which I changed.

-    than 16KB; <function>gss_wrap_size_limit()</function> should be used by the
+    than 16kB; <function>gss_wrap_size_limit()</function> should be used by the

Every other use in documentation has a lowercase "kay", and PG itself doesn't
accept "KB" unit suffix.

-     A few features included in the C99 standard are, at this time, not be
+     A few features included in the C99 standard are, at this time, not
      permitted to be used in core <productname>PostgreSQL</productname>

Indisputably wrong ?

Justin