Re: documenting divergence from the SQL spec

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

> Dave Cramer <davecramer(at)postgres(dot)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