BUG #13609: Documentation Section 9.14.3 nsarray usage problem

The following bug has been logged on the website:

Bug reference:      13609
Logged by:          Donald R Laster Jr
Email address:      dlaster@innovative-as.com
PostgreSQL version: 9.4.4
Operating system:   RHEL 5.6 and other Linux based systems
Description:

This description of how to use the nsarray argument to xpath() and
xpath_exists() is inaccurate based upon some work I am involved in.  We are
using both 9.2.4 and 9.4.4.

The 9.4.4 documentation states:

"The optional third argument of the function is an array of namespace
mappings. This array should be a two-dimensional text  array with the length
of the second axis being equal to 2 (i.e., it should be an array of arrays,
each of which consists of exactly 2 elements). The first element of each
array entry is the namespace name (alias), the second the namespace URI. It
is not required that aliases provided in this array be the same as those
being used in the XML document itself (in other words, both in the XML
document and in the xpath  function context, aliases are local )."

I believe it would be better written something like:

“The optional third argument of the function is an array of namespace
mappings.  The array should be a two-dimensional text array with the length
of each of the second axises being equal to 2 (i.e. it should be an array of
arrays).  Each inner array is 2 elements long, with the first element being
the namespace name (alias), the second the namespace URI.  Each namespace
that is present in the XML must be specified to be detected.

Thus if two namespaces exist in the XML, as 'my' and 'theirs', the nsarray
array would be defined as:

ARRAY[ARRAY[’my’, ’http://example.com’], ARRAY['theirs',
'http://theirs.com']]

Each namespace used in the xpath()/xpath_exists() must be present in the
array.”

My co-worker and I have been working with the some database records that
contain multiple namespaces and each namespace that is being searched in the
XML data with xpath_exists() must be specified in the nsarray or the
specific XML data fields do not get found.

We started with the basic description and found we had to specify each
namespace that was to be searched for in the nsarray.