Date: Sun, 3 Jan 2021 00:33:54 -0600
From: Justin Pryzby <pryzby@telsasoft.com>
To: Michael Paquier <michael@paquier.xyz>
Cc: pgsql-hackers@postgresql.org, Bruce Momjian <bruce@momjian.us>,
	Thomas Munro <thomas.munro@gmail.com>
Subject: Re: doc review for v14
Message-ID: <20210103063354.GI25152@telsasoft.com>
References: <20201222041153.GK30237@telsasoft.com>
 <X+RNUu+zotOjfL7K@paquier.xyz>
 <20201227202604.GC26311@telsasoft.com>
 <X+r1YyXWE5obOazQ@paquier.xyz>
 <X/Ff7jfnvJUab013@paquier.xyz>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <X/Ff7jfnvJUab013@paquier.xyz>
User-Agent: Mutt/1.9.4 (2018-02-28)
Precedence: bulk

On Sun, Jan 03, 2021 at 03:10:54PM +0900, Michael Paquier wrote:
> On Tue, Dec 29, 2020 at 06:22:43PM +0900, Michael Paquier wrote:
> > Yes, I have done an extra effort on those fixes where needed.  On top
> > of that, I have included catalogs.sgml, pgstatstatements.sgml,
> > explain.sgml, pg_verifybackup.sgml and wal.sgml in 13.
> 
> Justin, I got to look at the libxml2 part, and finished by rewording
> the comment block as follows:
> +    * XmlTable returns a table-set of composite values.  This error context
> +    * is used for providing more details, and needs to be reset between two
> +    * internal calls of libxml2 as different error contexts might have been
> +    * created or used.

I don't like "this error context", since "this" seems to be referring to the
"tableset of composite values" as an err context.

I guess you mean: "needs to be reset between each internal call to libxml2.."

So I'd suggest:

> +    * XmlTable returns a table-set of composite values.  The error context
> +    * is used for providing additional detail. It needs to be reset between each
> +    * call to libxml2, since different error contexts might have been
> +    * created or used since it was last set.


But actually, maybe we should just use the comment that exists everywhere else
for that.

        /* Propagate context related error context to libxml2 */
        xmlSetStructuredErrorFunc((void *) xtCxt->xmlerrcxt, xml_errorHandler);

Maybe should elaborate and say:
	/*
	 * Propagate context related error context to libxml2 (needs to be
	 * reset before each call, in case other error contexts have been assigned since
	 * it was first set) */
	 */
        xmlSetStructuredErrorFunc((void *) xtCxt->xmlerrcxt, xml_errorHandler);

-- 
Justin