Re: minor doc fixes for REL_12_STABLE

On Tue, Aug 20, 2019 at 7:48 AM Michael Paquier <michael@paquier.xyz> wrote:

> On Mon, Aug 19, 2019 at 05:12:12PM +0300, Liudmila Mantrova wrote:
>
> Most of the stuff in v12-doc-fixes.patch looks pretty good.  I don't
> agree with some of the changes in libpq.sgml, as firstterm is used to
> outline the different modes of the error verbosity API.  Using
> firstterm is also more consistent with ErrorContextVisibility.  You
> are right though that a markup for the default mode goes missing.  I
> have tweaked a couple of other things, and committed that part to HEAD
> and REL_12_STABLE.
>

You may be right on this one for consistency reasons, but it still looks
like a mode name to me, not a new term to be explained. BTW, I believe
firstterm is usually used for each term only once, and
<firstterm>TERSE</firstterm> appears twice in a single paragraph now. Also
firstterm is a translatable element, while literal is not (and e.g. TERSE
doesn't look like something to translate in this context).

Looks like you have also changed "an SQL" to "a SQL" in some cases (but not
everywhere), and I wonder what's the official guidance here for PostgreSQL
documentation. I see no consistency, but the first version appears more
often, that's why I decided to use it (although I have to admit that I've
been looking for something to confirm my personal preference).


>
> Now, for the second patch...  First thanks for helping me with my
> laziness and gather all the changes which have been done in the docs
> on HEAD (Alexander has done an awesome lot of work recently and going
> after each doc change was too much for me).
>
All the credit should go to Alexander.
Thank you for a prompt commit!

-- 
Best regards,
Liudmila Mantrova

Technical writer at Postgres Professional: http://www.postgrespro.com