Skip site navigation (1) Skip section navigation (2)

Re: [PATCHES] docs: syntax.sgml patch

From: "Robert B(dot) Easter" <reaster(at)comptechnews(dot)com>
To: Peter Eisentraut <peter_e(at)gmx(dot)net>
Cc: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>, <pgsql-docs(at)postgresql(dot)org>
Subject: Re: [PATCHES] docs: syntax.sgml patch
Date: 2001-01-17 20:02:13
Message-ID: 01011715021307.02219@comptechnews (view raw or flat)
Thread:
Lists: pgsql-docspgsql-patches
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(at)comptechnews(dot)com ---------
-- CompTechNews Message Board http://www.comptechnews.com/ --
-- CompTechServ Tech Services http://www.comptechserv.com/ --
---------- http://www.comptechnews.com/~reaster/ ------------

In response to

Responses

  • SQL Guide at 2001-01-21 01:00:17 from Peter Eisentraut

pgsql-docs by date

Next:From: Oliver ElphickDate: 2001-01-17 20:45:58
Subject: Re: misprints
Previous:From: Bruce MomjianDate: 2001-01-17 16:34:34
Subject: Re: misprints

pgsql-patches by date

Next:From: Bruce MomjianDate: 2001-01-17 22:11:15
Subject: Re: patch for src/backend/port/darwin/sem.c
Previous:From: Richard Bullington-McGuireDate: 2001-01-17 19:32:47
Subject: Fixes and enhancements to JDBC driver (take 2)

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group