Horton

doc: where best to add ~ 400 words to the manual?

Chapman Flack <chap@anastigmatix.net>

View thread View on postgr.es
From: Chapman Flack <chap@anastigmatix.net>
To: Pavel Stehule <pavel.stehule@gmail.com>
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>
Date: 2018-12-31T03:23:55Z
Lists: pgsql-hackers 
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

Commits

  1. Improve documentation about our XML functionality

  2. Improve documentation about our XML functionality.

  3. Add volatile qualifier missed in commit 2e616dee9.

  4. Fix crash with old libxml2

  5. Fix minor deficiencies in XMLTABLE, xpath(), xmlexists()

  6. Fix the BY {REF,VALUE} clause of XMLEXISTS/XMLTABLE

  7. doc: Update README.links

  8. XPath fixes: