pg.ddx.io pgsql-hackers@postgresql.org mailing list archive
help / color / mirror / Atom feeddoc: where best to add ~ 400 words to the manual?
3+ messages / 1 participants
[nested] [flat]
* doc: where best to add ~ 400 words to the manual?
@ 2018-12-31 03:23 Chapman Flack <chap@anastigmatix.net>
0 siblings, 1 reply; 3+ messages in thread
From: Chapman Flack @ 2018-12-31 03:23 UTC (permalink / raw)
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>; 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
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: doc: where best to add ~ 400 words to the manual?
@ 2019-01-11 04:48 Chapman Flack <chap@anastigmatix.net>
parent: Chapman Flack <chap@anastigmatix.net>
0 siblings, 1 reply; 3+ messages in thread
From: Chapman Flack @ 2019-01-11 04:48 UTC (permalink / raw)
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>; pgsql-hackers
On 12/30/18 22:23, Chapman Flack wrote:
> 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.
> ...
> I have thought of:
> ...
> 3. A sect2 at the very end of functions-xml, linked to from a short remark
> at the top.
(3) seems to be supported by (the only) precedent, the "Limits and
Compatibility" sect3 within functions-posix-regexp.
So, absent objection, I'll work on a Limits and Compatibility sect2
within functions-xml.
-Chap
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: doc: where best to add ~ 400 words to the manual?
@ 2019-01-11 05:19 Chapman Flack <chap@anastigmatix.net>
parent: Chapman Flack <chap@anastigmatix.net>
0 siblings, 0 replies; 3+ messages in thread
From: Chapman Flack @ 2019-01-11 05:19 UTC (permalink / raw)
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>; pgsql-hackers
On 01/10/19 23:48, Chapman Flack wrote:
> On 12/30/18 22:23, Chapman Flack wrote:
> (3) seems to be supported by (the only) precedent, the "Limits and
> Compatibility" sect3 within functions-posix-regexp.
>
> So, absent objection, I'll work on a Limits and Compatibility sect2
> within functions-xml.
One fly in the ointment: tables of contents seem to list sect1 and sect2
elements, but not sect3. So the "Limits and Compatibility" sect3 under
functions-posix-regexp does not clutter the overall "Functions and
Operators" ToC, but a "Limits and Compatibility" sect2 under
functions-xml would be visible there. Tucking it as a sect3 within an
existing sect2 would prevent that, but it is common information that
pertains to more than one of them, so that doesn't seem quite right.
Or is it ok to have a "Limits and Compatibility" visible in the ToC
under XML Functions?
-Chap
^ permalink raw reply [nested|flat] 3+ messages in thread
end of thread, other threads:[~2019-01-11 05:19 UTC | newest]
Thread overview: 3+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2018-12-31 03:23 doc: where best to add ~ 400 words to the manual? Chapman Flack <chap@anastigmatix.net>
2019-01-11 04:48 ` Chapman Flack <chap@anastigmatix.net>
2019-01-11 05:19 ` Chapman Flack <chap@anastigmatix.net>
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