Re: [PATCHES] docs: syntax.sgml patch - Mailing list pgsql-docs

[ redirected to -docs ]

Robert B. Easter writes:

> I see what you are saying and I expected my stuff to not fit so well.  The
> >FROM list section, which I replaced, doesn't really belong there either.  The
> whole outline of the SQL Syntax chapter could maybe use a redesign with a
> structure that follows the breakdown of SQL as expressed in the SQL standards
> documents and then Postgres extensions/compatibility chapters or material
> mixed in.

Not a bad idea.  I think we already have it similar to that.

> The basic outline of the standard I read (SQL1999) is like:
>
> 1. Scope
> 2. Normative References
> 3. Definitions, notations, conventions.

Skip that.

> 4. Concepts

Maybe tutorial?

> 5. Lexical Elements

We have that.

> 6. Scalar Expressions
>     Value Expression
>         Scalar Subquery
>         Case Expression
>         Element Reference

We have some of that.  You're writing the rest. (?)

> 7. Query Expressions
>     Table Expression
>     FROM clause
>     WHERE clause
>     etc ...

You're writing that.

> 8. Predicates
>     LIKE
>     BETWEEN
>     EXISTS

This should be in the functions/operators chapter.

> 9. Data Assignment Rules and Routine Determination

This is sort of the function/operator resolution and type casting rules.
These are documented somewhere.

> 10. Additional Common Elements
> 11. Schema Definition and Manipulation
> 12. Access Control
> 13. SQL-client modules
> 14. Data Manipulation
> 15. Control Statements

These all have varyingly little documentation between the tutorial,
reference manual, smoke and mirrors.

> 16. Transaction Management

Documented

> 17. Connection Management
> 18. Session Management
> 19. Diagnostics Management
> 20. Information Schema
> 21. Definition Schema
> 22. Status Codes

We don't have these implemented.

> Anyhow, this outline could be a basis from which to build an "SQL Guide" or
> something.

The User's Guide is effectively the SQL Guide, it just isn't called that.
In the future we might want to ponder renaming it.

> Maybe calling it SQL Syntax is not the best.  More than just pure
> syntax is laid out.  The semantics is explained too.  The standard document
> has a good structure but is very formal.  Taking this structure and writing
> something that is normal, readable english with real examples from PostgreSQL
> would be something good but is a large task - basically, derive a document
> based on the standard doc (no verbatim plagiarism though).

I think you have the right idea.  The schedule is probably too short to
accomplish all of this for 7.1, though.

> > 5. In some places you have {curly braces} around syntactic variables.
> > Don't do that, use the appropriate markup.
>
> It would be more like:
>
> SELECT <select list> <table expression>
>
> ??  DocBook puts those curly braces on automatically when I use choice="req"
> in a <arg> tag.  Guess I can't use those DocBook tags all the time unless it
> can do < and > with some other tag or option.

You can use choice="plain".  I don't feel partial either way but I wonder
how it looks in print.

> The documentation seems to need a lot of work.  I'm not sure how radically it
> can be changed since I don't want to disturb others work any. I've just been
> trying to squeeze in my stuff where I can fit it! :)

I don't think you will disturb too many people...

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