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

Re: [PATCHES] docs: syntax.sgml patch

From: Peter Eisentraut <peter_e(at)gmx(dot)net>
To: "Robert B(dot) Easter" <reaster(at)comptechnews(dot)com>
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-15 21:03:38
Message-ID: Pine.LNX.4.30.0101152142500.755-100000@peter.localdomain (view raw or flat)
Thread:
Lists: pgsql-docspgsql-patches
[ 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/


In response to

Responses

pgsql-docs by date

Next:From: Vince VielhaberDate: 2001-01-15 21:36:28
Subject: Re: broken link to Bruce Momjian's book
Previous:From: Igor VlasenkoDate: 2001-01-15 14:53:05
Subject: misprints

pgsql-patches by date

Next:From: Michael StephensonDate: 2001-01-16 09:43:02
Subject: Re: Patch for JDBC timestamp problems
Previous:From: Joseph ShraibmanDate: 2001-01-15 20:14:26
Subject: Re: Patch for JDBC timestamp problems

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