Horton

Thread

Commits

  1. Doc: Fix various typos

  2. Doc: Improve wording of multiple places in documentation

  1. minor doc fixes for REL_12_STABLE

    Liudmila Mantrova <l.mantrova@gmail.com> — 2019-08-19T14:12:12Z

    Hi,
Please consider the attached patches that fix some documentation
inconsistencies in REL_12_STABLE branch. The first one contains fixes of
typos and tagging issues that were discovered during new content
translation.  The other is a back-patch of fixes already accepted in master
after REL_12_STABLE has been created (originally reported by Alexander
Lakhin in "Fix typos and inconsistencies for HEAD" series).

-- 
Best regards,
Liudmila Mantrova

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

  2. Re: minor doc fixes for REL_12_STABLE

    Michael Paquier <michael@paquier.xyz> — 2019-08-20T04:48:09Z

    On Mon, Aug 19, 2019 at 05:12:12PM +0300, Liudmila Mantrova wrote:
> Please consider the attached patches that fix some documentation
> inconsistencies in REL_12_STABLE branch. The first one contains fixes of
> typos and tagging issues that were discovered during new content
> translation.  The other is a back-patch of fixes already accepted in master
> after REL_12_STABLE has been created (originally reported by Alexander
> Lakhin in "Fix typos and inconsistencies for HEAD" series).

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.

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).  Some of the issues are
much older than 12, so I have committed them separately with the
portions that are affected.
--
Michael

  3. Re: minor doc fixes for REL_12_STABLE

    Liudmila Mantrova <l.mantrova@gmail.com> — 2019-08-22T13:13:00Z

    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

  4. Re: minor doc fixes for REL_12_STABLE

    Michael Paquier <michael@paquier.xyz> — 2019-08-23T01:40:17Z

    On Thu, Aug 22, 2019 at 04:13:00PM +0300, Liudmila Mantrova wrote:
> 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).

This was discussed not long ago, and there was no actual consensus
that one was better than the other.  We have that in the code tree:
$ git grep -i "a sql" | wc -l
875
$ git grep -i "an sql" | wc -l
304
--
Michael

  5. Re: minor doc fixes for REL_12_STABLE

    Tom Lane <tgl@sss.pgh.pa.us> — 2019-08-23T04:21:08Z

    Michael Paquier <michael@paquier.xyz> writes:
> On Thu, Aug 22, 2019 at 04:13:00PM +0300, Liudmila Mantrova wrote:
>> 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.

> This was discussed not long ago, and there was no actual consensus
> that one was better than the other.

Yeah.  Some people pronounce SQL as "sequel", while others say
"ess-que-ell", and then whether you say "a" or "an" depends on that.
There's no definitive right answer on the pronunciation.

It might be best to try to cast your sentences so that the issue
doesn't come up ;-)

			regards, tom lane