Horton

Thread

Commits

  1. doc: Generate keywords table automatically

  1. generate documentation keywords table automatically

    Peter Eisentraut <peter.eisentraut@2ndquadrant.com> — 2019-04-27T07:33:47Z

    The SQL keywords table in the documentation had until now been generated
by me every year by some ad hoc scripting outside the source tree once
for each major release.  This patch changes it to an automated process.

We have the PostgreSQL keywords available in a parseable format in
parser/kwlist.h[*].  For the relevant SQL standard versions, keep the
keyword lists in new text files.  A new script
generate-keywords-table.pl pulls it all together and produces a DocBook
table.

The final output in the documentation should be identical after this
change.

(Updates for SQL:2016 to come.)

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

  2. Re: generate documentation keywords table automatically

    Tom Lane <tgl@sss.pgh.pa.us> — 2019-04-27T15:25:22Z

    Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
> The SQL keywords table in the documentation had until now been generated
> by me every year by some ad hoc scripting outside the source tree once
> for each major release.  This patch changes it to an automated process.

Didn't test this, but +1 for the concept.

Would it make more sense to have just one source file per SQL standard
version, and distinguish the keyword types by labels within the file?
The extreme version of that would be to format the standards-info files
just like parser/kwlist.h, which perhaps would even save a bit of
parsing code in the Perl script.  I don't insist you have to go that
far, but lists of keywords-and-categories seem to make sense.

The thing in the back of my mind here is that at some point the SQL
standard might have more than two keyword categories.  What you've got
here would take some effort to handle that, whereas it'd be an entirely
trivial data change in the scheme I'm thinking of.

A policy issue, independent of this mechanism, is how many different
SQL spec versions we want to show in the table.  HEAD currently shows just
three (2011, 2008, SQL92), and it doesn't look to me like the table can
accommodate more than one or at most two more columns without getting
too wide for most output formats.  We could buy back some space by making
the "cannot be X" annotations for PG keywords more compact, but I fear
that'd still not be enough for the seven spec versions you propose to
show in this patch.  (And, presumably, the committee's not done.)
Can we pick a different table layout?

			regards, tom lane

  3. Re: generate documentation keywords table automatically

    Peter Eisentraut <peter.eisentraut@2ndquadrant.com> — 2019-04-29T18:45:05Z

    On 2019-04-27 17:25, Tom Lane wrote:
> Would it make more sense to have just one source file per SQL standard
> version, and distinguish the keyword types by labels within the file?

The way I have written it, the lists can be compared directly with the
relevant standards by a human.  Otherwise we'd need another level of
tooling to compose and verify those lists.

> A policy issue, independent of this mechanism, is how many different
> SQL spec versions we want to show in the table.

We had previously established that we want to show 92 and the latest
two.  I don't propose to change that.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

  4. Re: generate documentation keywords table automatically

    Chapman Flack <chap@anastigmatix.net> — 2019-04-29T19:19:02Z

    On 4/29/19 2:45 PM, Peter Eisentraut wrote:
>> A policy issue, independent of this mechanism, is how many different
>> SQL spec versions we want to show in the table.
> 
> We had previously established that we want to show 92 and the latest
> two.  I don't propose to change that.

An annoying API requirement imposed by the JDBC spec applies to its
method DatabaseMetaData.getSQLKeywords():

It is required to return a list of the keywords supported by the DBMS
that are NOT also SQL:2003 keywords. [1]

Why? I have no idea. Were the JDBC spec authors afraid of infringing
ISO copyright if they specified a method that just returns all the
keywords?

So instead they implicitly require every JDBC developer to know just
what all the SQL:2003 keywords are, to make any practical use of the
JDBC method that returns only the keywords that aren't those.

To make it even goofier, the requirement in the JDBC spec has changed
(once, that I know of). It has been /all the keywords not in SQL:2003/
since JDBC 4 / Java SE 6 [2], but before that, it (the same method!)
was spec'd to return /all the keywords not in SQL92/. [3]

So the ideal JDBC developer will know (a) exactly what keywords are
SQL92, (b) exactly what keywords are SQL:2003, and (c) which JDBC
version the driver in use is implementing (though, mercifully, drivers
from pre-4.0 should be rare by now).

If the reorganization happening in this thread were to make possible
run-time-enumerable keyword lists that could be filtered for SQL92ness
or SQL:2003ness, that might relieve an implementation headache that,
at present, both PgJDBC and PL/Java have to deal with.

Regards,
-Chap


[1]
https://docs.oracle.com/en/java/javase/12/docs/api/java.sql/java/sql/DatabaseMetaData.html#getSQLKeywords()

[2]
https://docs.oracle.com/javase/6/docs/api/index.html?overview-summary.html

[3]
https://docs.oracle.com/javase/1.5.0/docs/api/index.html?overview-summary.html

  5. Re: generate documentation keywords table automatically

    Peter Eisentraut <peter.eisentraut@2ndquadrant.com> — 2019-04-30T06:02:35Z

    On 2019-04-29 21:19, Chapman Flack wrote:
> If the reorganization happening in this thread were to make possible
> run-time-enumerable keyword lists that could be filtered for SQL92ness
> or SQL:2003ness, that might relieve an implementation headache that,
> at present, both PgJDBC and PL/Java have to deal with.

Good information, but probably too big of a change at this point.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services