Message-ID: <519B8281.10105@2ndQuadrant.com>
Date: Tue, 21 May 2013 10:19:45 -0400
From: Greg Smith <greg@2ndQuadrant.com>
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7;
	rv:14.0) Gecko/20120713 Thunderbird/14.0
MIME-Version: 1.0
To: pgsql-docs <pgsql-docs@postgresql.org>
Subject: Reserved word "date" in tutorial example
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Precedence: bulk
Sender: pgsql-docs-owner@postgresql.org

doc/src/sgml/query.sgml includes a tutorial example with this definition:

CREATE TABLE weather (
...
     date            date
);

The fact that "date" is used for both the column name and the type is 
highlighted by two later comments:

   (Yes, the column of type date is also named date.  This might be 
convenient or confusing--you choose.)

   type names are not key words in the syntax, except where required to 
support special cases in the SQL standard.

But as a documentation comment submitted recently points out, "date" 
*is* a reserved word in the SQL spec: 
http://www.postgresql.org/docs/current/interactive/sql-keywords-appendix.html 
, just not in PostgreSQL.  That makes using it as a column name in an 
example an odd choice for a tutorial.  The example is using the 
ambiguity to point out where the line between what is and isn't legal is 
at, and maybe that's a feature instead of a bug.

There are a few approaches that could improve on this:

-Keep all of that, but expand the description to link to "SQL Key 
Words"--right now "SQL standard" doesn't go to that section--and say 
this might be a reserved word in other SQL implementations.  This is the 
smallest useful improvement.

-Change the name of the column and remove the two related descriptions.  
This will lose the lesson about where the parser's line is at.

-Do both:  move this example of parser trivia somewhere else, but remove 
it from the tutorial material by using a non-reserved column name there.

-- 
Greg Smith   2ndQuadrant US    greg@2ndQuadrant.com   Baltimore, MD
PostgreSQL Training, Services, and 24x7 Support www.2ndQuadrant.com


-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs