Various doc errors and shortcomings - Mailing list pgsql-bugs

Hello PostgreSQL!

  I've found several errors in the documentation.  The first is
a shortcoming rather than an error, but it cost me hours of
needless effort.  You said you welcome bug reports, so here's
what I have:

- - - - -

Programmer's Guide, 8.2.3. Connecting to the Database

According to the documentation, the URL includes what is called
"the database name".  I assumed that the fully qualified path
name was intended here, since that is what normally appears in a
URL.  How else does one unambiguously identify a file?  So that
is what I tried, and it repeatedly resulted in cryptic "no
suitable driver" messages.  I thought the problem was in the
Java configuration.

One or two examples are needed in this section to make it clear
that postgresql has its own directory of "registered" databases,
and the "database name" in question is the name in this
registry, not the database filename.

- - - - -

Tutorial Chapter 2:

In the following "&cup" is erroneously used to represent
intersection:

Relational Algebra

    INTERSECT (∩): builds the set-theoretic intersection of
two tables. Given the tables R and S, R ∪ S is the set of
tuples that are in R and in S. We again require that R and S
have the same arity.


- - - - -

Tutorial Chapter 2:

What does the "\nonumber" signify in the following?

Tuple Relational Calculus

The queries used in TRC are of the following form: x(A) ∣
F(x) where x is a tuple variable A is a set of attributes and F
is a formula. The resulting relation consists of all tuples t(A)
that satisfy F(t).

If we want to answer the question from example A Query Using
Relational Algebra using TRC we formulate the following query:

     {x(SNAME) ∣ x ∈ SUPPLIER ∧ \nonumber
                       ∃ y ∈ SELLS ∃ z ∈
PART (y(SNO)=x(SNO) ∧ \nonumber
                        z(PNO)=y(PNO) ∧ \nonumber
                        z(PNAME)='Screw')} \nonumber


Evaluating the query against the tables from The Suppliers and
Parts Database again leads to the same result as in A Query
Using Relational Algebra.

- - - - -

Tutorial Chapter 2:

In the following, the condition should be "PRICE <= 15"


Example 2-4. Simple Query with Qualification

The qualifications in the WHERE clause can also be logically
connected using the keywords OR, AND, and NOT:

   SELECT PNAME, PRICE
   FROM PART
   WHERE PNAME = 'Bolt' AND
         (PRICE = 0 OR PRICE < 15);


will lead to the result:

                      PNAME  |  PRICE
                     --------+--------
                      Bolt   |   15

- - - - -

Tutorial Chapter 2:

The following example seems incorrect.  In S.SNO is greater than
2, then S.SNO is also greater than 1, so the intersection should
include suppliers 2, 3, 4, etc..

Here an example for INTERSECT:

   SELECT S.SNO, S.SNAME, S.CITY
   FROM SUPPLIER S
   WHERE S.SNO > 1
   INTERSECT
   SELECT S.SNO, S.SNAME, S.CITY
   FROM SUPPLIER S
   WHERE S.SNO > 2;


gives the result:

                     SNO | SNAME |  CITY
                    -----+-------+--------
                      2  | Jones | Paris
The only tuple returned by both parts of the query is the one
having $SNO=2$.

- - - - -