Обсуждение: documenting divergence from the SQL spec
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.
Thoughts ?
Dave Cramer
www.postgres.rocks
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