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.