blatantly a bug in the documentation

On Mon, Nov 24, 2008 at 6:02 AM, A. Kretschmer
<andreas.kretschmer@schollglas.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.kretschmer@schollglas.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@commandprompt.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@commandprompt.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@commandprompt.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@dunslane.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@dunslane.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@dunslane.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@sss.pgh.pa.us> wrote:

Andrew Dunstan <andrew@dunslane.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@hagander.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@pgadmin.org> writes:

On Mon, Nov 24, 2008 at 1:53 PM, Andrew Dunstan <andrew@dunslane.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@sss.pgh.pa.us> wrote:

"Dave Page" <dpage@pgadmin.org> writes:

On Mon, Nov 24, 2008 at 1:53 PM, Andrew Dunstan <andrew@dunslane.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@dunslane.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@sss.pgh.pa.us> wrote:

Andrew Dunstan <andrew@dunslane.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@hagander.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@users.sourceforge.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