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

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 <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...

--
-------- Robert B. Easter  reaster@comptechnews.com ---------
-- CompTechNews Message Board http://www.comptechnews.com/ --
-- CompTechServ Tech Services http://www.comptechserv.com/ --
---------- http://www.comptechnews.com/~reaster/ ------------