SQL Guide - Mailing list pgsql-docs

Robert B. Easter writes:

> We seem to be in agreement about the SQL documentation.  That's cool. :)

I thought about this some more and came to the conclusion that the outline
used in the SQL standard is not appropriate to use for such an SQL guide.
The SQL standard is organized "bottom-up", it explains the meaning of each
syntactic clause and then assembles more complex clauses as it goes along.
The result is that the plain-old SELECT statement is not discussed until
chapter 17 of part 5, which is in essence just about the last thing
overall.  This is okay for what that document is:  it's a plain language
version of a grammar specification.

For our purposes we need to organize the thing top-down.  We start with
the big four commands SELECT, INSERT, UPDATE, DELETE with simple cases,
then move on to more complicated things such as joins and subqueries.  Of
course the lexical rules still go first, and the basics of the scalar
expression syntax as well, but we don't want to define ordering or joining
rules before introducing the SELECT command.  I came up with an outline
like this:

1. Lexical structure [done]
2. Simple selects and Inserts
3. Expression syntax, complicated selects
4. Delete and Update
5. Joins, Subqueries, Naming scope, Unions
6. Aggregates
7. Ordering
8. Creating tables in all its glory, maybe more than one chapter

This would be the generic part (applicable to any SQL RDBMS).  Following
this would be the existing chapters about data types, functions, type
conversion, concurrency control.

> I'd really like to see the "SQL Guide" when we can do it.  As for the User's
> Guide, you say it might be nice to rename it SQL Guide.  That could be done
> or have both.  Maybe having both an SQL guide and a User's guide is best.

We don't have a lot of material to have both, but we can divide them into
<part>s.  Really, the current split between books is primarily so you can
print them individually without having to buy a ton of paper.  It is not
necessarily a mandate to make a library out of it. ;-)

> The Admin guide covers those commands and programs (initdb/postmaster) that
> affect the whole database management system, its tuning, backup and other
> things. All the other guides could reference the SQL Guide when needing to
> explain the full details of an sql command.

Correct.  The Admin Guide is basically defined as comprising all activity
that needs to be done on the server system.

--
Peter Eisentraut      peter_e@gmx.net       http://yi.org/peter-e/