pg.ddx.io  pgsql-hackers@postgresql.org mailing list archive  

help / color / mirror / Atom feed
From: Chapman Flack <chap@anastigmatix.net>
To: Pavel Stehule <pavel.stehule@gmail.com>
Cc: Markus Winand <markus.winand@winand.at>
Cc: Alvaro Herrera <alvherre@2ndquadrant.com>
Cc: Tom Lane <tgl@sss.pgh.pa.us>
Cc: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
Subject: doc: where best to add ~ 400 words to the manual?
Date: Sun, 30 Dec 2018 22:23:55 -0500
Message-ID: <5C298BCB.4060704@anastigmatix.net> (raw)
In-Reply-To: <5C291741.9060506@anastigmatix.net>
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>

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




view thread (3+ messages)  latest in thread

Message-ID: <5C298BCB.4060704@anastigmatix.net>
Permalink:  ../5C298BCB.4060704@anastigmatix.net/
Also on:    postgresql.org/message-id/5C298BCB.4060704@anastigmatix.net

 · 

reply
Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: pgsql-hackers@postgresql.org
  Cc: chap@anastigmatix.net, pavel.stehule@gmail.com, markus.winand@winand.at, alvherre@2ndquadrant.com, tgl@sss.pgh.pa.us
  Subject: Re: doc: where best to add ~ 400 words to the manual?
  In-Reply-To: <5C298BCB.4060704@anastigmatix.net>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox