New man pages

I've posted a tarball of new man pages at

ftp://postgresql.org/pub/doc/man.tar.gz

I *think* these are ready for prime time, or close to it. They are
generated completely automatically from the sgml sources, using some
patched perl utilities. I'll try to post the complete set of docs
tools on the ftp site sometime soon.

Note that there are a few more man pages than were available in the
original versions, and that *all* information in the original man
pages appears in the new ones (or somewhere in the other docs).

I haven't yet updated the cvs tree to contain these new man pages.
Please look through the tarball and report any problems you see, if
you have any interest in the man page issue. Also, please report if
they look OK, so I know *someone* looked at them ;)

I looked at the new pages, and they looked very good, much better than I
thought they would. The only problem was the display of the command
syntax was wrapped rather than being one operator per line:

select [distinct [on attr_name]]
expression1 [as attr_name-1]
{, expression-1 [as attr_name-i]}
[into [temp] [table] classname]
[from from-list]
[where where-clause]
[group by attr_name1 {, attr_name-i....}]
[having having-clause]

became:

select [distinct [on attr_name]] expression1 [as attr_name-1]
{, expression-1 [as attr_name-i]} [into [temp] [table] classname]
[from from-list] [where where-clause] [group by attr_name1
{, attr_name-i....}] [having having-clause]

Which is almost unreadable.

-- 
  Bruce Momjian                        |  http://www.op.net/~candle
  maillist@candle.pha.pa.us            |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

I looked at the new pages, and they looked very good, much better than I
thought they would.

:)

The only problem was the display of the command
syntax was wrapped rather than being one operator per line:
Which is almost unreadable.

Fixed it.

- Thomas

--
Thomas Lockhart lockhart@alumni.caltech.edu
South Pasadena, California

I looked at the new pages, and they looked very good, much better than I
thought they would.

:)

Yes, I was prepared to really lose some of the nice formatting we had,
but we really didn't lose anything.

The only problem was the display of the command
syntax was wrapped rather than being one operator per line:
Which is almost unreadable.

Fixed it.

Thanks.

-- 
  Bruce Momjian                        |  http://www.op.net/~candle
  maillist@candle.pha.pa.us            |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

I mentioned this earlier in the context of pg_dump, which fails
trying to create the table "pgdump_oid".

After a bit, a memory jog reminded me that I've seen this
before, with the table "foo", which I once used for testing.

After a fair number of "create/drop" cycles, making then
dropping tables for testing, pgsql now refuses to let me
"create table foo...", giving the same simple error message
"can't create foo" as pg_dump's getting on pgdump_oid.

I can't "drop table foo", getting an error message telling
me the class doesn't exist, so that's not the problem.

I CAN create/drop other tables, i.e. "create table bar..."
followed by "drop table bar" works fine.

So it doesn't appear to be a general permissions problem,
i.e. it's not as though the system thinks I don't have
create table rights.

It would seem as some system table is being corrupted???

Does this sound at all familiar?

Unfortunately, I don't know how to reproduce this other
than create/drop tables until eventually it fails. As
I mentioned in my first note, pg_dump has been running
nightly on this database for weeks, at least, with no
errors reported. Suddenly - poof! can't create pgdump_oid.

- Don Baccus, Portland OR <dhogaza@pacifier.com>
Nature photos, on-line guides, Pacific Northwest
Rare Bird Alert Service and other goodies at
http://donb.photo.net.

Don Baccus wrote:

I can't "drop table foo", getting an error message telling
me the class doesn't exist, so that's not the problem.

It would seem as some system table is being corrupted???

Check pg_tables and pg_class -- select * from pg_tables; will give you a
list of tables from the system catalog, and select * from ps_class; will
do the same for classes -- if the psuedo-dropped table shows in either
of these tables, delete it, and see if that helps. If this indeed is a
system table corruption..... eeewwww....

Lamar Owen
WGCR Internet Radio

At 02:14 PM 8/6/99 -0400, Lamar Owen wrote:

Don Baccus wrote:

I can't "drop table foo", getting an error message telling
me the class doesn't exist, so that's not the problem.

It would seem as some system table is being corrupted???

Check pg_tables and pg_class -- select * from pg_tables; will give you a
list of tables from the system catalog, and select * from ps_class; will
do the same for classes -- if the psuedo-dropped table shows in either
of these tables, delete it, and see if that helps. If this indeed is a
system table corruption..... eeewwww....

Neither "pgdump_oid" or "foo" (my other example from my
follow-up message) appear to exist in pg_class or pg_tables.

Thanks for the suggestion, though :(

- Don Baccus, Portland OR <dhogaza@pacifier.com>
Nature photos, on-line guides, Pacific Northwest
Rare Bird Alert Service and other goodies at
http://donb.photo.net.

At 11:23 AM 8/6/99 -0700, Don Baccus wrote:

Neither "pgdump_oid" or "foo" (my other example from my
follow-up message) appear to exist in pg_class or pg_tables.

Thanks for the suggestion, though :(

Things are getting more and more odd...

I've done some more testing and things are now in a state
where I can create a table, drop the table (and get the
message "DROP" back), yet the relation still exists.

In fact, I can do a "select count(*) from ..." on it and
get zero rows back.

Argh!

Of course, now if I try to create a table with that name,
I'm told the relation already exists.

Different than the situation with pgdump_oid and foo,
where I'm just told that the create failed.

Obviously, some table contents somewhere must be messed
up. Any ideas?

- Don Baccus, Portland OR <dhogaza@pacifier.com>
Nature photos, on-line guides, Pacific Northwest
Rare Bird Alert Service and other goodies at
http://donb.photo.net.

On Fri, Aug 06, 1999 at 11:54:31AM -0700, Don Baccus wrote:

At 11:23 AM 8/6/99 -0700, Don Baccus wrote:

Neither "pgdump_oid" or "foo" (my other example from my
follow-up message) appear to exist in pg_class or pg_tables.

Thanks for the suggestion, though :(

Things are getting more and more odd...

I've done some more testing and things are now in a state
where I can create a table, drop the table (and get the
message "DROP" back), yet the relation still exists.

In fact, I can do a "select count(*) from ..." on it and
get zero rows back.

Argh!

Of course, now if I try to create a table with that name,
I'm told the relation already exists.

Different than the situation with pgdump_oid and foo,
where I'm just told that the create failed.

Obviously, some table contents somewhere must be messed
up. Any ideas?

Check to see if there are files in the pgsql/data/base/'yourdbname'
directory called 'pgdump_oid' and 'foo'. Some situations lead to a table
being almost completely deleted, but leaving the file behind. Doesn't
explain the 'table still there' phenomena, but might let you recreate a
'dropped' table.

Ross
P.S. once common problem is dropping a table doesn't always get all the
objects created by 'convenience' types. For example, not not sure the
sequence created for a serial type gets dropped with its table. In fact,
I'm pretty sure it doesn't (and, for now, shouldn't)

--
Ross J. Reedstrom, Ph.D., <reedstrm@rice.edu>
NSBRI Research Scientist/Programmer
Computer and Information Technology Institute
Rice University, 6100 S. Main St., Houston, TX 77005

Don Baccus wrote:

Obviously, some table contents somewhere must be messed
up. Any ideas?

Ooooo....

If this were happening to me, I'd probably stop postmaster, rename the
PGDATA tree to something else, initdb, start postmaster, restore from
the last good dump, stop postmaster, copy back the user database dirs
under PGDATA, restart postmaster, VACUUM all tables -- on the production
machine, if that is where the problems are. Then, I'd pull that PGDATA
binary backup over to a development workstation, start up a postmaster
pointing to it, and do a post-mortem, checking all system tables for
their contents, running vacuum, et al (all the while keeping a good copy
of the old PGDATA tree -- just in case something blows up).

Obviously, some system catalog somewhere is getting farkled -- Don, I'm
assuming that you are vacuuming often.

HTHaL

Lamar

At 02:46 PM 8/6/99 -0500, Ross J. Reedstrom wrote:

Check to see if there are files in the pgsql/data/base/'yourdbname'
directory called 'pgdump_oid' and 'foo'. Some situations lead to a table
being almost completely deleted, but leaving the file behind. Doesn't
explain the 'table still there' phenomena, but might let you recreate a
'dropped' table.

Thanks, I thought of this one myself, and deleted "foo". This is
when it got into the mode of allowing "create table foo..." and
an apparently successful "drop table foo", but with "foo" left
behind in pg_class (I think that's right) and "select count(*)
from foo" returning 0 rows (i.e. the relation really seems to
exist!)

Ross
P.S. once common problem is dropping a table doesn't always get all the
objects created by 'convenience' types. For example, not not sure the
sequence created for a serial type gets dropped with its table. In fact,
I'm pretty sure it doesn't (and, for now, shouldn't)

Yes, this isn't my problem, though.

- Don Baccus, Portland OR <dhogaza@pacifier.com>
Nature photos, on-line guides, Pacific Northwest
Rare Bird Alert Service and other goodies at
http://donb.photo.net.

At 03:53 PM 8/6/99 -0400, Lamar Owen wrote:

Don Baccus wrote:

Obviously, some table contents somewhere must be messed
up. Any ideas?

Ooooo....

If this were happening to me, I'd probably stop postmaster, rename the
PGDATA tree to something else, initdb, start postmaster, restore from
the last good dump, stop postmaster, copy back the user database dirs
under PGDATA, restart postmaster, VACUUM all tables -- on the production
machine, if that is where the problems are. Then, I'd pull that PGDATA
binary backup over to a development workstation, start up a postmaster
pointing to it, and do a post-mortem, checking all system tables for
their contents, running vacuum, et al (all the while keeping a good copy
of the old PGDATA tree -- just in case something blows up).

I decided awhile back to punt and rebuild.

Obviously, some system catalog somewhere is getting farkled -- Don, I'm
assuming that you are vacuuming often.

Nightly, after dumping.

- Don Baccus, Portland OR <dhogaza@pacifier.com>
Nature photos, on-line guides, Pacific Northwest
Rare Bird Alert Service and other goodies at
http://donb.photo.net.

Hi Thomas,

I'm looking at man pages, and I find it very good. Now we have only one
documentation's version. Nice job.
There's only a little thing that I would like to recall your attention;
I see whenever the name Postgres instead of
PostgreSQL. Is there a reason to continue to call it Postgres in the
docs ?

-------------------------------------------------------------------------

UPDATE(l) UPDATE(l)

NAME
UPDATE - Replaces values of columns in a table

SYNOPSIS
UPDATE table SET R">colle> = expression [, ...] [ FROM
^^^^^^^
fromlist ] [ WHERE condition ]

INPUTS
table The name of an existing table.

column The name of a column in table.

expression
A valid expression or value to assign to column.

fromlist
A Postgres non-standard extension to allow columns
^^^^^^^
from other tables to appear in the WHERE condition.

Jos�

Thomas Lockhart ha scritto:

There's only a little thing that I would like to recall your attention;
I see whenever the name Postgres instead of
PostgreSQL. Is there a reason to continue to call it Postgres in the
docs ?

I have chosen to use "Postgres" within the docs, as a shorter (and
pronouncable ;) form of our product. "PostgreSQL" appears in all
titles and introductory material. I have considered the "SQL" part of
the "PostgreSQL" as sort of a version or branch, like "OpenIngres" or
"Windows 2000", and a bit cumbersome in the body of the docs.

But that was a choice which can always be reconsidered, we're just a
"sed" away from a different name...

- Thomas

--
Thomas Lockhart lockhart@alumni.caltech.edu
South Pasadena, California

There's only a little thing that I would like to recall your attention;
I see whenever the name Postgres instead of
PostgreSQL. Is there a reason to continue to call it Postgres in the
docs ?

I have chosen to use "Postgres" within the docs, as a shorter (and
pronouncable ;) form of our product. "PostgreSQL" appears in all
titles and introductory material. I have considered the "SQL" part of
the "PostgreSQL" as sort of a version or branch, like "OpenIngres" or
"Windows 2000", and a bit cumbersome in the body of the docs.

But that was a choice which can always be reconsidered, we're just a
"sed" away from a different name...

I vote for PostgreSQL.

-- 
  Bruce Momjian                        |  http://www.op.net/~candle
  maillist@candle.pha.pa.us            |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

On Mon, 9 Aug 1999, Bruce Momjian wrote:

There's only a little thing that I would like to recall your attention;
I see whenever the name Postgres instead of
PostgreSQL. Is there a reason to continue to call it Postgres in the
docs ?

I have chosen to use "Postgres" within the docs, as a shorter (and
pronouncable ;) form of our product. "PostgreSQL" appears in all
titles and introductory material. I have considered the "SQL" part of
the "PostgreSQL" as sort of a version or branch, like "OpenIngres" or
"Windows 2000", and a bit cumbersome in the body of the docs.

But that was a choice which can always be reconsidered, we're just a
"sed" away from a different name...

I vote for PostgreSQL.

I'm just an end user who loves the product...with an opinion. ;-)

Although I never used postgres (i.e., prior to the suffix being appended)
I always use `postgres' in conversation both as it is easily pronounced
and as there is a rather noteable history/lineage. When communicating
with other postgres fans I say pee-gee...

When I refer specfically to the newer incarnation I say Postgres SQL
(post-gress see-qwell) rather than postgreS-Q-L...

I don't really mind if the man pages get edited as if I ever choose to
read them to my 4 year old son I will swap in the generic name, on the
fly. But we are not up to that point yet - my son is still learning
about grep. ;-)

I fully appreciate what the name is designed to convey but it does not
roll off the tongue...so I kinda like Thomas' decision to stick with
the more generic term - and the more poetic.

Cheers,
Tom

------- North Richmond Community Mental Health Center -------

Thomas Good MIS Coordinator
Vital Signs: tomg@ { admin | q8 } .nrnet.org
Phone: 718-354-5528
Fax: 718-354-5056

/* Member: Computer Professionals For Social Responsibility */

Thomas Lockhart wrote:

I have chosen to use "Postgres" within the docs, as a shorter (and
pronouncable ;) form of our product. "PostgreSQL" appears in all

How hard is it to say "Postgresquel", really? Don't tell me you've been
saying "Postgres cue ell".....;-)

Lamar Owen
WGCR Internet Radio

On Mon, 9 Aug 1999, Lamar Owen wrote:

Thomas Lockhart wrote:

I have chosen to use "Postgres" within the docs, as a shorter (and
pronouncable ;) form of our product. "PostgreSQL" appears in all

How hard is it to say "Postgresquel", really? Don't tell me you've been
saying "Postgres cue ell".....;-)

I have! I don't see that there is really any difference between saying
"postgresequel" and "postgres-cue-ell". The syllables are just switched.
(kind of) However, perhaps the inventors of this term could offer their
insight into their intended pronounciation.

--
Peter Eisentraut
PathWay Computing, Inc.

Peter Eisentraut wrote:

On Mon, 9 Aug 1999, Lamar Owen wrote:

How hard is it to say "Postgresquel", really? Don't tell me you've been
saying "Postgres cue ell".....;-)

I have! I don't see that there is really any difference between saying
"postgresequel" and "postgres-cue-ell". The syllables are just switched.
(kind of) However, perhaps the inventors of this term could offer their
insight into their intended pronounciation.

Not post-gre'-se-quel -- post-gres'-quel. One less syllable. At least,
that's how I've been saying it. But, then again, when referring to
MySQL I don't say my-s-q-l; I say my'-squel.

Oh well...

Lamar

The only thing I hate about PostgreSQL is that it's hard to type with all
that mixed case. I confess that I've always pronounced it "postgres"
anyway, so there!

The point of a name is to be distinctive and somewhat descriptive.
Postgres suffices to set the product off from other database systems.
There's no real need for the SQL to be in the name. Even Microsoft, in
their eternal marketing battle, doesn't make a point of writing AccesSQL.

My two bits, and your mileage may vary.

On Mon, 9 Aug 1999, Peter Eisentraut wrote: