Re: clean up docs for v12

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