Thread: minor doc fixes for REL_12_STABLE
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
Attachment
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
Attachment
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.
--
Best regards,
Liudmila Mantrova
Technical writer at Postgres Professional: http://www.postgrespro.com
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
Attachment
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