doc: Generate keywords table automatically

The SQL keywords table in the documentation had until now been
generated by some ad hoc scripting outside the source tree once for
each major release.  This 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.

Discussion: https://www.postgresql.org/message-id/flat/07daeadd-8c82-0d95-5e19-e350502cb749%402ndquadrant.com

Author: petere

doc/src/sgml/.gitignore

@@ -15,6 +15,7 @@
 /features-supported.sgml
 /features-unsupported.sgml
 /errcodes-table.sgml
+/keywords-table.sgml
 /version.sgml
 # Assorted byproducts from building the above
 /postgres.xml

doc/src/sgml/Makefile

@@ -53,7 +53,8 @@ override XSLTPROCFLAGS += --stringparam pg.version '$(VERSION)'
 
 
 GENERATED_SGML = version.sgml \
-	features-supported.sgml features-unsupported.sgml errcodes-table.sgml
+	features-supported.sgml features-unsupported.sgml errcodes-table.sgml \
+	keywords-table.sgml
 
 ALLSGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML)
 
@@ -96,6 +97,9 @@ features-unsupported.sgml: $(top_srcdir)/src/backend/catalog/sql_feature_package
 errcodes-table.sgml: $(top_srcdir)/src/backend/utils/errcodes.txt generate-errcodes-table.pl
 	$(PERL) $(srcdir)/generate-errcodes-table.pl $< > $@
 
+keywords-table.sgml: $(top_srcdir)/src/include/parser/kwlist.h $(wildcard $(srcdir)/keywords/sql*.txt) generate-keywords-table.pl
+	$(PERL) $(srcdir)/generate-keywords-table.pl $(srcdir) > $@
+
 
 ##
 ## Generation of some text files.

doc/src/sgml/filelist.sgml

@@ -175,6 +175,7 @@
 <!ENTITY features-unsupported SYSTEM "features-unsupported.sgml">
 
 <!ENTITY errcodes-table SYSTEM "errcodes-table.sgml">
+<!ENTITY keywords-table SYSTEM "keywords-table.sgml">
 
 <!-- back matter -->
 <!ENTITY biblio     SYSTEM "biblio.sgml">

doc/src/sgml/generate-keywords-table.pl

@@ -0,0 +1,122 @@
+#!/usr/bin/perl
+#
+# Generate the keywords table file
+# Copyright (c) 2019, PostgreSQL Global Development Group
+
+use strict;
+use warnings;
+
+my @sql_versions = reverse sort ('1992', '2008', '2011');
+
+my $srcdir = $ARGV[0];
+
+my %keywords;
+
+# read SQL keywords
+
+foreach my $ver (@sql_versions)
+{
+	foreach my $res ('reserved', 'nonreserved')
+	{
+		foreach my $file (glob "$srcdir/keywords/sql${ver}*-${res}.txt")
+		{
+			open my $fh, '<', $file or die;
+
+			while (<$fh>)
+			{
+				chomp;
+				$keywords{$_}{$ver}{$res} = 1;
+			}
+
+			close $fh;
+		}
+	}
+}
+
+# read PostgreSQL keywords
+
+open my $fh, '<', "$srcdir/../../../src/include/parser/kwlist.h" or die;
+
+while (<$fh>)
+{
+	if (/^PG_KEYWORD\("(\w+)", \w+, (\w+)_KEYWORD\)/)
+	{
+		$keywords{ uc $1 }{'pg'}{ lc $2 } = 1;
+	}
+}
+
+close $fh;
+
+# print output
+
+print "<!-- autogenerated, do not edit -->\n";
+
+print <<END;
+<table id="keywords-table">
+ <title><acronym>SQL</acronym> Key Words</title>
+
+ <tgroup cols="5">
+  <thead>
+   <row>
+    <entry>Key Word</entry>
+    <entry><productname>PostgreSQL</productname></entry>
+END
+
+foreach my $ver (@sql_versions)
+{
+	my $s = ($ver eq '1992' ? 'SQL-92' : "SQL:$ver");
+	print "    <entry>$s</entry>\n";
+}
+
+print <<END;
+   </row>
+  </thead>
+
+  <tbody>
+END
+
+foreach my $word (sort keys %keywords)
+{
+	print "   <row>\n";
+	print "    <entry><token>$word</token></entry>\n";
+
+	print "    <entry>";
+	if ($keywords{$word}{pg}{'unreserved'})
+	{
+		print "non-reserved";
+	}
+	elsif ($keywords{$word}{pg}{'col_name'})
+	{
+		print "non-reserved (cannot be function or type)";
+	}
+	elsif ($keywords{$word}{pg}{'type_func_name'})
+	{
+		print "reserved (can be function or type)";
+	}
+	elsif ($keywords{$word}{pg}{'reserved'})
+	{
+		print "reserved";
+	}
+	print "</entry>\n";
+
+	foreach my $ver (@sql_versions)
+	{
+		print "    <entry>";
+		if ($keywords{$word}{$ver}{'reserved'})
+		{
+			print "reserved";
+		}
+		elsif ($keywords{$word}{$ver}{'nonreserved'})
+		{
+			print "non-reserved";
+		}
+		print "</entry>\n";
+	}
+	print "   </row>\n";
+}
+
+print <<END;
+  </tbody>
+ </tgroup>
+</table>
+END