Subject: doc: where best to add ~ 400 words to the manual?
To: Pavel Stehule <pavel.stehule@gmail.com>
References: 
 <CAFj8pRDFQJMoKf-X+3p1ASwU02nnXfAXrg83Z3fHUBd-Gwuuxw@mail.gmail.com>
 <20181025194720.ylmw64xqlnjr5wja@alvherre.pgsql>
 <CAFj8pRB10LxRcYYKWb5omjtAQq_bEVWiQ9B6V=kRZYMvM0B-_w@mail.gmail.com>
 <CAFj8pRBr5tY5b=8gKptwOyuPf8f3fvyHbXNbSCU03guNh-johw@mail.gmail.com>
 <CAFj8pRA6J25CtAZ2TuRvxK3gat7-bBUYh0rfE2yM7Hj9GD14Dg@mail.gmail.com>
 <FB592C2F-E2F3-42FD-A342-EE41BECD3771@winand.at>
 <CAFj8pRC_bi4uzE3Z-XXuGnLFPP-7cZ-zr2JhGauWm3E8K2MqEg@mail.gmail.com>
 <45C74339-3531-46BD-A595-37183C6730A1@winand.at>
 <CAFj8pRB4NHismecE-SnezKz9OektP2H8t_684TbqQ4Ax3swZwQ@mail.gmail.com>
 <5C283168.8060001@anastigmatix.net>
 <CAFj8pRDRrxyr8=2PEFxP_eZCRqJMU4Jpj0whJM9pX0V4Q4EQvw@mail.gmail.com>
 <5C291741.9060506@anastigmatix.net>
Cc: Markus Winand <markus.winand@winand.at>,
 Alvaro Herrera <alvherre@2ndquadrant.com>, Tom Lane <tgl@sss.pgh.pa.us>,
 PostgreSQL Hackers <pgsql-hackers@postgresql.org>
From: Chapman Flack <chap@anastigmatix.net>
Message-ID: <5C298BCB.4060704@anastigmatix.net>
Date: Sun, 30 Dec 2018 22:23:55 -0500
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101
 Thunderbird/38.7.0
MIME-Version: 1.0
In-Reply-To: <5C291741.9060506@anastigmatix.net>
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

I would like to add material to the manual, detailing the differences
between the XPath 1.0 language supported in PG, and the XQuery/XPath 2.0+
expected by the standard.

A good preview of what that would look like is the "related to version
of XPath" wiki section at [1].

That wiki section (minus the two inside-baseball paragraphs about
commit 3963574 and its reversion) comes to a bit under 400 words.

So that's roughly the amount of material I'm thinking to add.
Where should it go?

I have thought of:

1. A new sect2 near the top of the "functions-xml" sect1. This makes sense
because the material applies to all the functions below that involve XPath.
But that seems like the wrong place for 400 words of gory details.

2. A short remark at the top of functions-xml, linked to a footnote with
the gory details. But that would be a long footnote. The longest currently
is a footnote with 101 words in the start tutorial.

3. A sect2 at the very end of functions-xml, linked to from a short remark
at the top.

4. A new appendix, or a new conformance section in the features.sgml
appendix, linked to from a short remark at the top of functions-xml.

Or is there an even better idea I have not thought of?

-Chap


[1]
https://wiki.postgresql.org/wiki/PostgreSQL_vs_SQL/XML_Standards#Related_to_version_of_XPath