Re: [PATCHES] docs: syntax.sgml patch
Re: [PATCHES] docs: syntax.sgml patch
От:
Peter Eisentraut <peter_e@gmx.net>
Дата:
[ 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 Re: [PATCHES] docs: syntax.sgml patch
От:
"Robert B. Easter" <reaster@comptechnews.com>
Дата:
We seem to be in agreement about the SQL documentation. That's cool. :)
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.
The SQL Guide would document all of the SQL language in PostgreSQL based on
the outline of the SQL standards docs and using as many standard terms as
possible without it being too cryptic/formal for normal readers.
The User's guide could focus on non-SQL things that users want to know, like
about psql, pgaccess, and other user apps, explain the basic architecture and
files involved in the system, and commands that are PostgreSQL-specific but
not SQL and not DBA-level commands.
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.
Again, everything is already similar to (or exactly) what I'm saying here! :)
Well, if you think the creation of the SQL Guide is really good, we can work
on the outline of this guide. This would be a toplevel guide like User's,
Admin, Programmer etc. We can look through the outline of the standards docs
more and have a good plan. Once we have a good outline, then its easy for
anyone to write sections and chapters to fill it in with material. I really
think we want to establish the outline before everyone jumps in and it
becomes a disorganized patchwork of documentation.
Let me know what you think. When I have the time, I will look at both the
basic outline in SQL92 Foundation and SQL99 Foundation. PostgreSQL wants
SQL92 compatibility, so we have to see how they differ and what chapters and
sections make sense in a PostgreSQL SQL Guide. At the same time, PostgreSQL
should be looking at SQL99 too for the future, at least for implementing some
intesting new features. I'm thinking to create detailed outlines from both
SQL92 and SQL99, then compare them and compare them both with PostreSQL.
Then, take from both outlines what is right for PostgreSQL and make that the
basic outline of the SQL Guide. Finally, after the outline as been poked
around by enough people on this list, post the skeleton (outline) of the SQL
Guide somewhere (in cvs maybe), and then anyone can write the sections and
chapters. Hopefully the chapters and sections in the outline will be good
enough and people won't try to write different chapter or section names. We
want to keep it so that every chapter and section has a clear mapping to the
offical SQL Foundation docs. The SQL Guide can make footnotes referring the
reader to see the corresponding SQL Foundation section for detailed
information. The SQL Guide would be like a novice to intermediate-level
guide to SQL while the SQL Foundation doc is like the advanced version.
I think it would be a good docs project and a nice opportunity to get into
those specs in detail and learn a lot. By making a new SQL Guide, I won't
have to worry about upsetting the existing docs too. :)
On Monday 15 January 2001 16:03, Peter Eisentraut wrote:
> [ 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 SQL Guide
От:
Peter Eisentraut <peter_e@gmx.net>
Дата:
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 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/