documenting divergence from the SQL spec

Dave Cramer <davecramer@postgres.rocks> writes:

We have a section in the main docs for conformance
https://www.postgresql.org/docs/12/features.html
And then this https://wiki.postgresql.org/wiki/PostgreSQL_vs_SQL_Standard for
divergence.
I'd like to see the divergence section put into the main docs so that it is
easier to find.

The individual statement reference pages already have sections for
standards divergences. Admittedly, that framework doesn't help for
discrepancies that can't be tied to a statement type ... but I don't
think we should throw in duplicative material of this sort. It's
tough enough to keep one instance of the info up-to-date. So I'd
want to see some structure for this that respects that existing
set of information.

regards, tom lane

On Fri, 14 Feb 2020 at 11:26, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Dave Cramer <davecramer@postgres.rocks> writes:

We have a section in the main docs for conformance
https://www.postgresql.org/docs/12/features.html
And then this

https://wiki.postgresql.org/wiki/PostgreSQL_vs_SQL_Standard for

divergence.
I'd like to see the divergence section put into the main docs so that it

is

easier to find.

The individual statement reference pages already have sections for
standards divergences. Admittedly, that framework doesn't help for
discrepancies that can't be tied to a statement type ... but I don't
think we should throw in duplicative material of this sort. It's
tough enough to keep one instance of the info up-to-date. So I'd
want to see some structure for this that respects that existing
set of information.

I get that we don't want duplicative material.
Would it be possible to tag the current documentation in such a way to
extract the
divergences where they were already documented at the statement level ?
Then everything that isn't tied to a statement could be documented manually
in the divergence
section ?

The problem I am trying to address is that it is very difficult to know all
the places I should look for documentation.

The wiki seems to be the dumping ground for everything that doesn't fit
into the documentation.
The problem with this is that if you don't know it is documented there it
is very difficult to find.

Dave Cramer
www.postgres.rocks

On 2020-Feb-14, Dave Cramer wrote:

The wiki seems to be the dumping ground for everything that doesn't fit
into the documentation.
The problem with this is that if you don't know it is documented there it
is very difficult to find.

Would it help to have some sort of index? The simplest I can think of
is to add <indexterm> for each Nonstandard Clauses section, with
something like

<primary>Nonstandard Clauses</primary>
<secondary>in SELECT</secondary>

so that in the index you'd get a list of all commands that have
Nonstandard Clauses subsections.

Perhaps something more sophisticated can be built by using dedicated XML
tags in an ad-hoc namespace.

--
�lvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services