Re: Documentation Style Issue - semi-colon at the end of SQL statement examples

Laura Stewart wrote:
> Hi -
> Should there be a semi-colon at the end of the SQL statement examples
> in the Derby documentation.  In other documentation work that I have
> done, this was the standard. I just wanted to check with the Derby
> community to see what is appropriate for the Derby docs.

I don't know if there's a "rule" for this in Derby docs, but it seems to me that
at some point someone somewhere pointed out that, technically, the semi-colon is
NOT part of the SQL statement.  For example, I think if you include the
semi-colon at the end of a SQL statement in a JDBC call like:

   ResultSet rs = st.executeQuery("SELECT * FROM T1;");

the result will be a syntax error caused by the presence of the semi-colon:

ERROR 42X01: Syntax error: Encountered ";" at line 1 ...

I think the semi-colon is a popular statement terminator for a lot of
command-line interfaces to databases, including Derby's own ij.  But in the case
of ij the semi-colon is stripped off before the statement is actually passed to
the Derby engine, so it (the semi-colon) is really an ij requirement, not a SQL
statement requirement.

My personal answer to your question, then, would be that the semi-colon should
only be included if the doc is showing the example statement as it would be
executed in ij.  So if the doc looked like:

ij> connect 'mydb';
ij> select * from t1;

I'd say include the semi-colon.  But if the example is just an example of how to
select all the rows from t1 or an example of how to use the syntax for a Derby
SQL statement, I'd say leave the semicolon off:

   select * from t1

FWIW,
Army