Re: [PATCHES] docs: syntax.sgml patch

[ 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(at)gmx(dot)net http://yi.org/peter-e/