Re: blatantly a bug in the documentation

I hope this is the right place to report a bug/issue in the official
documentation...

In
http://www.postgresql.org/docs/current/interactive/plpgsql-control-structures.html
there is an example for a function, cs_refresh_mviews(), chapter 38.6.4.
Within this function there are a "PERFORM cs_log('Refreshing
materialized views...');", but such a function cs_log() are not in the
core distibution.

I think, this is a problem for users which read the doc and try to
reproduce the example or write own code based on the example.

Regards, and many thanks for PostgreSQL to the developer, Andreas
--
Andreas Kretschmer
Kontakt: Heynitz: 035242/47150, D1: 0160/7141639 (mehr: -> Header)
GnuPG-ID: 0x3FFF606C, privat 0x7F4584DA http://wwwkeys.de.pgp.net

On Mon, Nov 24, 2008 at 6:02 AM, A. Kretschmer
<andreas(dot)kretschmer(at)schollglas(dot)com> wrote:
> I hope this is the right place to report a bug/issue in the official
> documentation...
>
> In
> http://www.postgresql.org/docs/current/interactive/plpgsql-control-structures.html
> there is an example for a function, cs_refresh_mviews(), chapter 38.6.4.
> Within this function there are a "PERFORM cs_log('Refreshing
> materialized views...');", but such a function cs_log() are not in the
> core distibution.

The example in the docs is pseudo-code. None of the tables referenced
exist either...the purpose of the example was to demonstrate the
syntax of for loops.

merlin

am Mon, dem 24.11.2008, um 7:24:47 -0500 mailte Merlin Moncure folgendes:
> On Mon, Nov 24, 2008 at 6:02 AM, A. Kretschmer
> <andreas(dot)kretschmer(at)schollglas(dot)com> wrote:
> > I hope this is the right place to report a bug/issue in the official
> > documentation...
> >
> > In
> > http://www.postgresql.org/docs/current/interactive/plpgsql-control-structures.html
> > there is an example for a function, cs_refresh_mviews(), chapter 38.6.4.
> > Within this function there are a "PERFORM cs_log('Refreshing
> > materialized views...');", but such a function cs_log() are not in the
> > core distibution.
>
> The example in the docs is pseudo-code. None of the tables referenced
> exist either...the purpose of the example was to demonstrate the
> syntax of for loops.

Okay, it is an argument. On the other side, it was a question today in
the irc-channel (#postgresql) today, someone asked, why his funktion
don't work. I think, such examples should not contain such code. It is
not apparent that this function are not available.

Again, thx to all people behind PostgreSQL, it is a great thing and it
has a really informatively documentation. My post was only a hint to
make it better.

Andreas
--
Andreas Kretschmer
Kontakt: Heynitz: 035242/47150, D1: 0160/7141639 (mehr: -> Header)
GnuPG-ID: 0x3FFF606C, privat 0x7F4584DA http://wwwkeys.de.pgp.net

A. Kretschmer wrote:

> Okay, it is an argument. On the other side, it was a question today in
> the irc-channel (#postgresql) today, someone asked, why his funktion
> don't work. I think, such examples should not contain such code. It is
> not apparent that this function are not available.

Perhaps the whole chapter could be improved if all the examples referred
to a set of tables and functions previously defined in the introduction
of the chapter. It would be good if the user could cut'n paste the code
and try it out directly, instead of having to reverse engineer the
tables/columns used for each example (and they're quite inconsistent).
Also, some examples give the complete code including CREATE FUNCTION and
others don't.

Feel like submitting a patch?

--
Alvaro Herrera http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc.

On Mon, Nov 24, 2008 at 1:38 PM, Alvaro Herrera
<alvherre(at)commandprompt(dot)com> wrote:
> A. Kretschmer wrote:
>
>> Okay, it is an argument. On the other side, it was a question today in
>> the irc-channel (#postgresql) today, someone asked, why his funktion
>> don't work. I think, such examples should not contain such code. It is
>> not apparent that this function are not available.
>
> Perhaps the whole chapter could be improved if all the examples referred
> to a set of tables and functions previously defined in the introduction
> of the chapter. It would be good if the user could cut'n paste the code
> and try it out directly, instead of having to reverse engineer the
> tables/columns used for each example (and they're quite inconsistent).
> Also, some examples give the complete code including CREATE FUNCTION and
> others don't.

It might also be useful to create such a database at initdb time so
newbies have something interesting to look at right away.

--
Dave Page
EnterpriseDB UK: http://www.enterprisedb.com

Dave Page wrote:
> On Mon, Nov 24, 2008 at 1:38 PM, Alvaro Herrera
> <alvherre(at)commandprompt(dot)com> wrote:
>
>> A. Kretschmer wrote:
>>
>>
>>> Okay, it is an argument. On the other side, it was a question today in
>>> the irc-channel (#postgresql) today, someone asked, why his funktion
>>> don't work. I think, such examples should not contain such code. It is
>>> not apparent that this function are not available.
>>>
>> Perhaps the whole chapter could be improved if all the examples referred
>> to a set of tables and functions previously defined in the introduction
>> of the chapter. It would be good if the user could cut'n paste the code
>> and try it out directly, instead of having to reverse engineer the
>> tables/columns used for each example (and they're quite inconsistent).
>> Also, some examples give the complete code including CREATE FUNCTION and
>> others don't.
>>
>
> It might also be useful to create such a database at initdb time so
> newbies have something interesting to look at right away.
>

No, there is no need to clutter every installation in the world with
such a database. You could make it an addon module, or a pgfoundry project.

cheers

andrew

am Mon, dem 24.11.2008, um 13:47:54 +0000 mailte Dave Page folgendes:
> On Mon, Nov 24, 2008 at 1:38 PM, Alvaro Herrera
> <alvherre(at)commandprompt(dot)com> wrote:
> > A. Kretschmer wrote:
> >
> >> Okay, it is an argument. On the other side, it was a question today in
> >> the irc-channel (#postgresql) today, someone asked, why his funktion
> >> don't work. I think, such examples should not contain such code. It is
> >> not apparent that this function are not available.
> >
> > Perhaps the whole chapter could be improved if all the examples referred
> > to a set of tables and functions previously defined in the introduction
> > of the chapter. It would be good if the user could cut'n paste the code
> > and try it out directly, instead of having to reverse engineer the
> > tables/columns used for each example (and they're quite inconsistent).
> > Also, some examples give the complete code including CREATE FUNCTION and
> > others don't.
>
> It might also be useful to create such a database at initdb time so
> newbies have something interesting to look at right away.

Nice idea.

Andreas
--
Andreas Kretschmer
Kontakt: Heynitz: 035242/47150, D1: 0160/7141639 (mehr: -> Header)
GnuPG-ID: 0x3FFF606C, privat 0x7F4584DA http://wwwkeys.de.pgp.net

On Mon, Nov 24, 2008 at 1:53 PM, Andrew Dunstan <andrew(at)dunslane(dot)net> wrote:
>
>> It might also be useful to create such a database at initdb time so
>> newbies have something interesting to look at right away.
>>
>
> No, there is no need to clutter every installation in the world with such a
> database. You could make it an addon module, or a pgfoundry project.
>

That would defeat the point. Not that I have any great feelings either
way, but fwiw, Microsoft and Oracle both create a sample database
iirc.

--
Dave Page
EnterpriseDB UK: http://www.enterprisedb.com

Dave Page wrote:
> On Mon, Nov 24, 2008 at 1:53 PM, Andrew Dunstan <andrew(at)dunslane(dot)net> wrote:
>>> It might also be useful to create such a database at initdb time so
>>> newbies have something interesting to look at right away.
>>>
>> No, there is no need to clutter every installation in the world with such a
>> database. You could make it an addon module, or a pgfoundry project.
>>
>
> That would defeat the point. Not that I have any great feelings either
> way, but fwiw, Microsoft and Oracle both create a sample database
> iirc.

Last I checked, MS did it optionally only, no?

//Magnus

Andrew Dunstan <andrew(at)dunslane(dot)net> writes:
> Dave Page wrote:
>> It might also be useful to create such a database at initdb time so
>> newbies have something interesting to look at right away.

> No, there is no need to clutter every installation in the world with
> such a database. You could make it an addon module, or a pgfoundry project.

The whole thing strikes me as extreme overkill, not to mention a
misunderstanding of what an example is supposed to be for. If we're
going to insist that every example in the docs work when
copied-and-pasted into an empty database, then simple and to-the-point
examples will be history. Instead of one-liners we'll have clutter.

regards, tom lane

On Mon, Nov 24, 2008 at 2:02 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> Andrew Dunstan <andrew(at)dunslane(dot)net> writes:
>> Dave Page wrote:
>>> It might also be useful to create such a database at initdb time so
>>> newbies have something interesting to look at right away.
>
>> No, there is no need to clutter every installation in the world with
>> such a database. You could make it an addon module, or a pgfoundry project.
>
> The whole thing strikes me as extreme overkill, not to mention a
> misunderstanding of what an example is supposed to be for. If we're
> going to insist that every example in the docs work when
> copied-and-pasted into an empty database, then simple and to-the-point
> examples will be history. Instead of one-liners we'll have clutter.

That's the point of having a sample database ready to play with. The
docs needn't have clutter, but the user can try out any of the
examples without needing to setup anything first. It's a simple
usability tweak that can help ease the learning curve for new users.

--
Dave Page
EnterpriseDB UK: http://www.enterprisedb.com

On Mon, Nov 24, 2008 at 2:01 PM, Magnus Hagander <magnus(at)hagander(dot)net> wrote:
> Dave Page wrote:
>> That would defeat the point. Not that I have any great feelings either
>> way, but fwiw, Microsoft and Oracle both create a sample database
>> iirc.
>
> Last I checked, MS did it optionally only, no?

Yes, but it defaults on iirc. We can emulate that behaviour in an
installer (and do in Postgres Plus for example), but that doesn't help
users of other distributions.

--
Dave Page
EnterpriseDB UK: http://www.enterprisedb.com

"Dave Page" <dpage(at)pgadmin(dot)org> writes:
> On Mon, Nov 24, 2008 at 1:53 PM, Andrew Dunstan <andrew(at)dunslane(dot)net> wrote:
>> No, there is no need to clutter every installation in the world with such a
>> database. You could make it an addon module, or a pgfoundry project.

> That would defeat the point.

By that logic, we should install the sample stuff in template1, to
ensure that the examples would "just work" wherever $newbie tries
to execute them :-(

regards, tom lane

On Mon, Nov 24, 2008 at 2:14 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> "Dave Page" <dpage(at)pgadmin(dot)org> writes:
>> On Mon, Nov 24, 2008 at 1:53 PM, Andrew Dunstan <andrew(at)dunslane(dot)net> wrote:
>>> No, there is no need to clutter every installation in the world with such a
>>> database. You could make it an addon module, or a pgfoundry project.
>
>> That would defeat the point.
>
> By that logic, we should install the sample stuff in template1, to
> ensure that the examples would "just work" wherever $newbie tries
> to execute them :-(

*sigh*. Or one of us could visit their office and show them what to
do, but I think we know the difference between making something usable
out of the box and going overboard.

--
Dave Page
EnterpriseDB UK: http://www.enterprisedb.com

am Mon, dem 24.11.2008, um 9:02:37 -0500 mailte Tom Lane folgendes:
> Andrew Dunstan <andrew(at)dunslane(dot)net> writes:
> > Dave Page wrote:
> >> It might also be useful to create such a database at initdb time so
> >> newbies have something interesting to look at right away.
>
> > No, there is no need to clutter every installation in the world with
> > such a database. You could make it an addon module, or a pgfoundry project.
>
> The whole thing strikes me as extreme overkill, not to mention a
> misunderstanding of what an example is supposed to be for. If we're
> going to insist that every example in the docs work when
> copied-and-pasted into an empty database, then simple and to-the-point
> examples will be history. Instead of one-liners we'll have clutter.

For a beginner, a "relation 'foo' does not exist" is a clean message,
but a "function foo() does not exist" from an example in the doc are a real
problem. And, in this example in my first post, the call to the
nonexistent function are neither necessary nor 'to-the-point' to explain a
for-loop.

The starting point for my post was a real question on IRC today.
Someone was really confused because he tried to use this nonexistent
funktion to log something into a log-file. I think, this example can
rewritten, either without this funktion-call or with raise notice ...

Regards, Andreas
--
Andreas Kretschmer
Kontakt: Heynitz: 035242/47150, D1: 0160/7141639 (mehr: -> Header)
GnuPG-ID: 0x3FFF606C, privat 0x7F4584DA http://wwwkeys.de.pgp.net

On Mon, Nov 24, 2008 at 9:02 AM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> Andrew Dunstan <andrew(at)dunslane(dot)net> writes:
>> Dave Page wrote:
>>> It might also be useful to create such a database at initdb time so
>>> newbies have something interesting to look at right away.
>
>> No, there is no need to clutter every installation in the world with
>> such a database. You could make it an addon module, or a pgfoundry project.
>
> The whole thing strikes me as extreme overkill, not to mention a
> misunderstanding of what an example is supposed to be for. If we're
> going to insist that every example in the docs work when
> copied-and-pasted into an empty database, then simple and to-the-point
> examples will be history. Instead of one-liners we'll have clutter.

Clutter is the problem. The cs_log functions in the example do not
serve any purpose that is helpful to describe a for loop. They serve
no real purpose...why not 'raise notice' or just remove them? It
should be clear to distinguish from real and non-real elements.

merlin

> Clutter is the problem. The cs_log functions in the example do not
> serve any purpose that is helpful to describe a for loop. They serve
> no real purpose...why not 'raise notice' or just remove them? It
> should be clear to distinguish from real and non-real elements.

+1 for RAISE NOTICE.

...Robert

On Monday 24 November 2008 16:07:49 Dave Page wrote:
> That's the point of having a sample database ready to play with. The
> docs needn't have clutter, but the user can try out any of the
> examples without needing to setup anything first. It's a simple
> usability tweak that can help ease the learning curve for new users.

I find that the regression test database usually works for that.

On Monday 24 November 2008 09:10:29 Dave Page wrote:
> On Mon, Nov 24, 2008 at 2:01 PM, Magnus Hagander <magnus(at)hagander(dot)net>
wrote:
> > Dave Page wrote:
> >> That would defeat the point. Not that I have any great feelings either
> >> way, but fwiw, Microsoft and Oracle both create a sample database
> >> iirc.
> >
> > Last I checked, MS did it optionally only, no?
>
> Yes, but it defaults on iirc. We can emulate that behaviour in an
> installer (and do in Postgres Plus for example), but that doesn't help
> users of other distributions.
>

We actually have such a database on pgfoundry already
(http://pgfoundry.org/frs/download.php/1719/pagila-0.10.1.zip), which i think
devrim may have packaged into an rpm; it wouldn't hurt to add it to the win32
installer, but would you feel better if it were a contrib module or
something?

--
Robert Treat
Conjecture: http://www.xzilla.net
Consulting: http://www.omniti.com

On Tue, Nov 25, 2008 at 1:42 AM, Robert Treat
<xzilla(at)users(dot)sourceforge(dot)net> wrote:
>
> We actually have such a database on pgfoundry already
> (http://pgfoundry.org/frs/download.php/1719/pagila-0.10.1.zip), which i think
> devrim may have packaged into an rpm; it wouldn't hurt to add it to the win32
> installer, but would you feel better if it were a contrib module or
> something?

I'm in favour of including it by default (at initdb), so it's there
for new users to play with on any fresh install - however, there is
only a point to that if all the documentation examples are based on
that database to allow copy-paste-play.

--
Dave Page
EnterpriseDB UK: http://www.enterprisedb.com

Dave Page wrote:
>On Tue, Nov 25, 2008 at 1:42 AM, Robert Treat
><xzilla(at)users(dot)sourceforge(dot)net> wrote:

>> We actually have such a database on pgfoundry already
>> (http://pgfoundry.org/frs/download.php/1719/pagila-0.10.1.zip), which i think
>> devrim may have packaged into an rpm; it wouldn't hurt to add it to the win32
>> installer, but would you feel better if it were a contrib module or
>> something?

>I'm in favour of including it by default (at initdb), so it's there
>for new users to play with on any fresh install - however, there is

+1

It's reasonably easy to create a sample database during the initdb phase
automatically. It's rather easy for an experienced DBA to "dropdb sampledb"
to get rid of it, and it would be orders of magnitude more difficult for
a novice to create the sample database from contrib or anywhere else.
Besides the "waste" of space for the sample database should be negligible for
almost any real production environment.

>only a point to that if all the documentation examples are based on
>that database to allow copy-paste-play.

True. Though this is a chicken and egg problem, by simply creating the
sample DB first, it creates the opportunity to gradually convert all examples
in the manual to use the sample DB (and patch the sample DB in the process to
be populated with the proper tables/functions to actually be useful in
the required examples).
--
Sincerely,
Stephen R. van den Berg.
"Give a man a fire and he's warm for a day,
but set fire to him and he's warm for the rest of his life."

On Tue, Nov 25, 2008 at 7:31 PM, Dave Page <dpage(at)pgadmin(dot)org> wrote:
> I'm in favour of including it by default (at initdb), so it's there
> for new users to play with on any fresh install ...

Could we perhaps punt on the issue of whether to install the
"sampledb" by default. It could be controlled by a flag to initdb,
say

$ initdb --sample data

Whereas if you omit the flag, then initdb just does a vanilla install.
Then we can leave it up to the distributions whether they want to
install it by default, or give the user options in their package
management systems to control this. In Apt it could be a debconf
question, in Portage it could be a USE flag, etc.

I think it's a pretty safe bet that the "newbies" we're talking about
in this thread are going to be installing postgres via a package
management system. If they are installing from source, they are
already reading the documentation and will have to learn about running
initdb on the command line anyway.

Cheers,
BJ

"Dave Page" <dpage(at)pgadmin(dot)org> writes:
> I'm in favour of including it by default (at initdb), so it's there
> for new users to play with on any fresh install - however, there is
> only a point to that if all the documentation examples are based on
> that database to allow copy-paste-play.

You would also have to assume that all the examples are non-destructive,
and that no one ever extends an example in a destructive way. This
seems like a non-starter. Better to provide the sample database in a
form in which it can be easily dropped/reloaded. I'm envisioning that
there's a source file in $sharedir and we tell people

createdb example
psql -f $sharedir/example.sql example

regards, tom lane

On Tue, Nov 25, 2008 at 1:23 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> "Dave Page" <dpage(at)pgadmin(dot)org> writes:
>> I'm in favour of including it by default (at initdb), so it's there
>> for new users to play with on any fresh install - however, there is
>> only a point to that if all the documentation examples are based on
>> that database to allow copy-paste-play.
>
> You would also have to assume that all the examples are non-destructive,
> and that no one ever extends an example in a destructive way.

That's a good point.

> This
> seems like a non-starter. Better to provide the sample database in a
> form in which it can be easily dropped/reloaded. I'm envisioning that
> there's a source file in $sharedir and we tell people
>
> createdb example
> psql -f $sharedir/example.sql example

I was assuming that it would be in such a form anyway - similar to
system_views.sql for example. I'd be happy with that setup - it's far
better than referring people to pgFoundry, and should be simple for
anyone to use.

--
Dave Page
EnterpriseDB UK: http://www.enterprisedb.com

On Tue, Nov 25, 2008 at 8:23 AM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> "Dave Page" <dpage(at)pgadmin(dot)org> writes:
>> I'm in favour of including it by default (at initdb), so it's there
>> for new users to play with on any fresh install - however, there is
>> only a point to that if all the documentation examples are based on
>> that database to allow copy-paste-play.
>
> You would also have to assume that all the examples are non-destructive,
> and that no one ever extends an example in a destructive way. This
> seems like a non-starter. Better to provide the sample database in a
> form in which it can be easily dropped/reloaded. I'm envisioning that
> there's a source file in $sharedir and we tell people
>
> createdb example
> psql -f $sharedir/example.sql example

There's good precedent for that...SQL Server for example does something similar:
http://msdn.microsoft.com/en-us/library/aa276825(SQL.80).aspx

It's a good learning tool and would really raise the value of the documentation.

merlin

Tom Lane wrote:
> Better to provide the sample database in a
> form in which it can be easily dropped/reloaded. I'm envisioning that
> there's a source file in $sharedir and we tell people
>
> createdb example
> psql -f $sharedir/example.sql example
>
>
>

This is a much better idea than doing it at initdb time, IMNSHO.

cheers

andrew

Stephen R. van den Berg wrote:
> ... it would be orders of magnitude more difficult for
> a novice to create the sample database from contrib or anywhere else.

It seems to me that *this* is the more serious problem that
we should fix instead.

If, from the psql command prompt I could type:

psql=# install module sampledb;
Downloading sampledb from pgfoundry...
Installing sampledb....
Connecting to sampledb....
sampledb=#

it'd remove the need for pre-installing a rarely-needed ad-on,
as well as being useful for other projects. For exmaple:
psql=# install module US_Census_Tiger_Maps;
Installing dependency Postgis...
Installing module US_Census_Tiger_Maps....
to install a GIS system with all the road networks.

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi,

Le 25 nov. 08 à 20:29, Ron Mayer a écrit :
> psql=# install module sampledb;
> Downloading sampledb from pgfoundry...
> Installing sampledb....
> Connecting to sampledb....
> sampledb=#

This could be part of an installer for PostgreSQL extensions. See
following email for a proposal on how to deal with extension packaging:
http://archives.postgresql.org/pgsql-hackers/2008-07/msg01098.php

The proposal purposefully let fetching and building steps out of the
database manager itself, and makes it so that building is to be cared
about by distributors. So it would be something like:
create sampledb
pg_pkg fetch pgsampledb

and either
pg_pkg install pgsampledb sampledb
psql sampledb
or
psql sampledb
sampledb=# install package pgsampledb;

> it'd remove the need for pre-installing a rarely-needed ad-on,
> as well as being useful for other projects. For exmaple:
> psql=# install module US_Census_Tiger_Maps;
> Installing dependency Postgis...
> Installing module US_Census_Tiger_Maps....
> to install a GIS system with all the road networks.

The dependancy system is yet to be though about, but definitely in the
scope of the extension manager.

While at it, calling all those things extensions rather than package
would probably help not confusing people with Oracle compatibility
etc. Last time I checked I didn't find mention of "package" into the
standard, but still.

So PosgtreSQL could have an extension manager at SQL level (create or
replace extension, install extension, or maybe load extension (which
would LOAD the modules associated), etc) with a system command line
tool to fetch & build, etc (pg_ext ?) that source level users and
packagers (distributors) would use?

What do you dear readers think about the "extension" vocabulary?

Regards,
- --
dim

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Darwin)

iEYEARECAAYFAkksZooACgkQlBXRlnbh1bmyvgCaAobd8kWhtkO+DxmDjbnqAWCz
5pQAoMauBWbyuvYxg6bDndYpb9CYiYZc
=Reeq
-----END PGP SIGNATURE-----

Dimitri Fontaine <dfontaine(at)hi-media(dot)com> writes:
> What do you dear readers think about the "extension" vocabulary?

+1 ... we should stay away from "package" unless we are going to
implement an Oracle-compatible facility. Which I don't particularly
wish to do, but we should leave it open for the future.

regards, tom lane

On Tue, 2008-11-25 at 08:23 -0500, Tom Lane wrote:
> "Dave Page" <dpage(at)pgadmin(dot)org> writes:
> > I'm in favour of including it by default (at initdb), so it's there
> > for new users to play with on any fresh install - however, there is
> > only a point to that if all the documentation examples are based on
> > that database to allow copy-paste-play.
>
> You would also have to assume that all the examples are non-destructive,
> and that no one ever extends an example in a destructive way. This
> seems like a non-starter. Better to provide the sample database in a
> form in which it can be easily dropped/reloaded. I'm envisioning that
> there's a source file in $sharedir and we tell people
>
> createdb example
> psql -f $sharedir/example.sql example

Sounds good.

Please could we do this in a way that allows the example database to be
localised. It will help beginners understand things better if we have
table and column names in the local language. One more thing to
translate maybe, but lets leave the door open for localisation.

--
Simon Riggs www.2ndQuadrant.com
PostgreSQL Training, Services and Support