Documentation/help for materialized and recursive views

2013/6/27 Magnus Hagander <magnus@hagander.net>:

Is there a particular reason why CREATE RECURSIVE VIEW is part of the
help for CREATE VIEW, but CREATE MATERIALIZED VIEW doesn't show up
there?

I realize the technical reason (they're different man pages, and that
also controls what's in \h in psql which is where I ran into it), but
was there any particular reason to split those up in the first place?

Normal views are an abstraction layer, while materialized views
(despite containing the word “view”) are mainly a performance tool (in
a way similar to indexes).

The functionality of materialized views will (over time) totally swamp
that of normal views, so mixing all the corresponding documentation
with the documentation for normal views probably doesn’t make things
easier for people that are only interested in normal views.

Nicolas

--
A. Because it breaks the logical sequence of discussion.
Q. Why is top posting bad?

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Thu, Jun 27, 2013 at 10:56 AM, Nicolas Barbier
<nicolas.barbier@gmail.com> wrote:

2013/6/27 Magnus Hagander <magnus@hagander.net>:

Is there a particular reason why CREATE RECURSIVE VIEW is part of the
help for CREATE VIEW, but CREATE MATERIALIZED VIEW doesn't show up
there?

I realize the technical reason (they're different man pages, and that
also controls what's in \h in psql which is where I ran into it), but
was there any particular reason to split those up in the first place?

Normal views are an abstraction layer, while materialized views
(despite containing the word “view”) are mainly a performance tool (in
a way similar to indexes).

Oh yes, I'm well aware of this of course.

The functionality of materialized views will (over time) totally swamp
that of normal views, so mixing all the corresponding documentation
with the documentation for normal views probably doesn’t make things
easier for people that are only interested in normal views.

That's a better point I think. That said, it would be very useful if
it actually showed up in "\h CREATE VIEW" in psql - I wonder if we
should just add the syntax to that page, and then link said future
information on a separate page somehow?

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Thu, Jun 27, 2013 at 5:29 AM, Magnus Hagander <magnus@hagander.net> wrote:

The functionality of materialized views will (over time) totally swamp
that of normal views, so mixing all the corresponding documentation
with the documentation for normal views probably doesn’t make things
easier for people that are only interested in normal views.

That's a better point I think. That said, it would be very useful if
it actually showed up in "\h CREATE VIEW" in psql - I wonder if we
should just add the syntax to that page, and then link said future
information on a separate page somehow?

IMHO, it's better to keep them separate; they are very different beasts.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Robert Haas <robertmhaas@gmail.com> wrote:

Magnus Hagander <magnus@hagander.net> wrote:

The functionality of materialized views will (over time) totally swamp
that of normal views, so mixing all the corresponding documentation
with the documentation for normal views probably doesn’t make things
easier for people that are only interested in normal views.

That's a better point I think. That said, it would be very useful if
it actually showed up in "\h CREATE VIEW" in psql - I wonder if we
should just add the syntax to that page, and then link said future
information on a separate page somehow?

IMHO, it's better to keep them separate; they are very different beasts.

+1

Although I wonder whether we shouldn't cross-link those pages....

 
--
Kevin Grittner
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Fri, Jun 28, 2013 at 5:54 AM, Kevin Grittner <kgrittn@ymail.com> wrote:

Robert Haas <robertmhaas@gmail.com> wrote:

Magnus Hagander <magnus@hagander.net> wrote:

The functionality of materialized views will (over time) totally swamp
that of normal views, so mixing all the corresponding documentation
with the documentation for normal views probably doesn’t make things
easier for people that are only interested in normal views.

That's a better point I think. That said, it would be very useful if
it actually showed up in "\h CREATE VIEW" in psql - I wonder if we
should just add the syntax to that page, and then link said future
information on a separate page somehow?

IMHO, it's better to keep them separate; they are very different beasts.

+1

Although I wonder whether we shouldn't cross-link those pages....

They are already crosslinked under "see also". But that doesn't really
help the guy doing "\h CREATE VIEW" in psql, which was the case where
it was brought to my attention.

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Magnus Hagander escribi�:

They are already crosslinked under "see also". But that doesn't really
help the guy doing "\h CREATE VIEW" in psql, which was the case where
it was brought to my attention.

Maybe \h should somehow display the "see also" section?

--
�lvaro Herrera http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Training & Services

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Fri, Jun 28, 2013 at 4:49 PM, Alvaro Herrera
<alvherre@2ndquadrant.com> wrote:

Magnus Hagander escribió:

They are already crosslinked under "see also". But that doesn't really
help the guy doing "\h CREATE VIEW" in psql, which was the case where
it was brought to my attention.

Maybe \h should somehow display the "see also" section?

I've been toying with the idea getting \h to show an actual http://
link to the reference page on the website, since most terminals lets
you deal with URLs easily lately. I haven't actually looked into how
feasible that would be though, but it would be interesting to check
out. (With a toggle to turn it on/off of course)

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On 6/28/13 10:49 AM, Alvaro Herrera wrote:

Magnus Hagander escribi�:

They are already crosslinked under "see also". But that doesn't really
help the guy doing "\h CREATE VIEW" in psql, which was the case where
it was brought to my attention.

Maybe \h should somehow display the "see also" section?

You can run \! man from within psql, which should give you everything
you need. It's admittedly a bit obscure, but it's there. Maybe it
ought to be added to the initial help output.

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Peter Eisentraut escribi�:

On 6/28/13 10:49 AM, Alvaro Herrera wrote:

Magnus Hagander escribi�:

They are already crosslinked under "see also". But that doesn't really
help the guy doing "\h CREATE VIEW" in psql, which was the case where
it was brought to my attention.

Maybe \h should somehow display the "see also" section?

You can run \! man from within psql, which should give you everything
you need. It's admittedly a bit obscure, but it's there. Maybe it
ought to be added to the initial help output.

That's a neat trick, but obviously it won't work in Windows. Maybe we
ought to have \man ..

--
�lvaro Herrera http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Training & Services

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Fri, Jun 28, 2013 at 01:34:17PM -0400, Peter Eisentraut wrote:

On 6/28/13 10:49 AM, Alvaro Herrera wrote:

Magnus Hagander escribi�:

They are already crosslinked under "see also". But that doesn't
really help the guy doing "\h CREATE VIEW" in psql, which was the
case where it was brought to my attention.

Maybe \h should somehow display the "see also" section?

You can run \! man from within psql,

And if you're on Windows, you're Sadly Out of Luck with that. Is
there an equivalent we could #ifdef in for that platform?

Cheers,
David.
--
David Fetter <david@fetter.org> http://fetter.org/
Phone: +1 415 235 3778 AIM: dfetter666 Yahoo!: dfetter
Skype: davidfetter XMPP: david.fetter@gmail.com
iCal: webcal://www.tripit.com/feed/ical/people/david74/tripit.ics

Remember to vote!
Consider donating to Postgres: http://www.postgresql.org/about/donate

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On 6/28/13 2:27 PM, David Fetter wrote:

You can run \! man from within psql,

And if you're on Windows, you're Sadly Out of Luck with that. Is
there an equivalent we could #ifdef in for that platform?

If you are using psql on Windows extensively, you probably have one of
mingw, cygwin, or pgadmin handy, all of which can get you to the
documentation. I don't think it's worth devising a mechanism for those
not covered by this.

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Mon, Jul 01, 2013 at 10:05:24AM -0400, Peter Eisentraut wrote:

On 6/28/13 2:27 PM, David Fetter wrote:

You can run \! man from within psql,

And if you're on Windows, you're Sadly Out of Luck with that. Is
there an equivalent we could #ifdef in for that platform?

If you are using psql on Windows extensively, you probably have one of
mingw, cygwin, or pgadmin handy, all of which can get you to the
documentation. I don't think it's worth devising a mechanism for those
not covered by this.

With deepest respect, failing to provide documentation to users on our
widest-deployed platform seems pretty hostile to me. There was an
earlier suggestion that we provide URLs, which seems like a decent way
forward as those environments so locked down as to disallow outbound
HTTP are pretty rare, and non-networked computers are even more rare.

Cheers,
David.
--
David Fetter <david@fetter.org> http://fetter.org/
Phone: +1 415 235 3778 AIM: dfetter666 Yahoo!: dfetter
Skype: davidfetter XMPP: david.fetter@gmail.com
iCal: webcal://www.tripit.com/feed/ical/people/david74/tripit.ics

Remember to vote!
Consider donating to Postgres: http://www.postgresql.org/about/donate

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On 7/1/13 10:20 AM, David Fetter wrote:

On Mon, Jul 01, 2013 at 10:05:24AM -0400, Peter Eisentraut wrote:

On 6/28/13 2:27 PM, David Fetter wrote:

You can run \! man from within psql,

And if you're on Windows, you're Sadly Out of Luck with that. Is
there an equivalent we could #ifdef in for that platform?

If you are using psql on Windows extensively, you probably have one of
mingw, cygwin, or pgadmin handy, all of which can get you to the
documentation. I don't think it's worth devising a mechanism for those
not covered by this.

With deepest respect, failing to provide documentation to users on our
widest-deployed platform seems pretty hostile to me.

As I argue above, I don't think this is the widest-deployed platform.
The actual platform in use is either mingw, which has man, or
click-and-drool, which has pgadmin, both of which provide the documentation.

There was an
earlier suggestion that we provide URLs, which seems like a decent way
forward as those environments so locked down as to disallow outbound
HTTP are pretty rare, and non-networked computers are even more rare.

Does clicking on links in cmd.exe do anything useful?

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Mon, Jul 01, 2013 at 10:52:55AM -0400, Peter Eisentraut wrote:

On 7/1/13 10:20 AM, David Fetter wrote:

On Mon, Jul 01, 2013 at 10:05:24AM -0400, Peter Eisentraut wrote:

On 6/28/13 2:27 PM, David Fetter wrote:

You can run \! man from within psql,

And if you're on Windows, you're Sadly Out of Luck with that.
Is there an equivalent we could #ifdef in for that platform?

If you are using psql on Windows extensively, you probably have
one of mingw, cygwin, or pgadmin handy, all of which can get you
to the documentation. I don't think it's worth devising a
mechanism for those not covered by this.

With deepest respect, failing to provide documentation to users on
our widest-deployed platform seems pretty hostile to me.

As I argue above, I don't think this is the widest-deployed
platform. The actual platform in use is either mingw, which has
man, or click-and-drool, which has pgadmin, both of which provide
the documentation.

I'm not going to get into a big definitional wrangle here. "Has
available" (as in you could install software if you wanted to) is a
pretty long distance from "actually handy," which URLs are a bit
closer to.

There was an earlier suggestion that we provide URLs, which seems
like a decent way forward as those environments so locked down as
to disallow outbound HTTP are pretty rare, and non-networked
computers are even more rare.

Does clicking on links in cmd.exe do anything useful?

Apparently

start URL

works for some large class of URLs. More details here:
http://www.dwheeler.com/essays/open-files-urls.html

Cheers,
David.
--
David Fetter <david@fetter.org> http://fetter.org/
Phone: +1 415 235 3778 AIM: dfetter666 Yahoo!: dfetter
Skype: davidfetter XMPP: david.fetter@gmail.com
iCal: webcal://www.tripit.com/feed/ical/people/david74/tripit.ics

Remember to vote!
Consider donating to Postgres: http://www.postgresql.org/about/donate

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Mon, Jul 1, 2013 at 10:20 AM, David Fetter <david@fetter.org> wrote:

With deepest respect, failing to provide documentation to users on our
widest-deployed platform seems pretty hostile to me.

Yes, that would be pretty hostile. However, we don't do anything that
remotely resembles that statement, nor has anyone proposed any such
thing.

Personally, I think this whole thread is much ado about nothing.
Magnus is basically arguing that people might expect that CREATE VIEW
ought to tell you about CREATE MATERIALIZED VIEW also, but I don't
find that argument to have a whole lot of merit. Views and
materialized views are pretty different things; it is a bit like
asking why Googling for "dog" does not give you information on hot
dogs. The output of psql's \h command is intended to be a succinct
synopsis summarizing the salient syntax (try saying that five times
fast), not a comprehensive reference. If you want the latter, read
the fine manual. I admit that this particular case is slightly more
prone to confusion than some, but I'm just not that exercised about
it. Every bit of detail we add to the \h output is better for the
people who otherwise would have been unhappy, but it's worse for all
the people who did need it because it's more to read through.

Regardless of whether you agree with or disagree with the above
statement, building a high-quality documentation reader into psql so
that users who are running Windows but not mingw, cygwin, or pgAdmin
can access the documentation more easily doesn't seem like the correct
solution to this problem. I don't really object if somebody wants to
do it (although someone else may object) but it's certainly taking the
long way around as far as this particular confusion is concerned.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On 07/01/2013 03:26 PM, Robert Haas wrote:

Regardless of whether you agree with or disagree with the above
statement, building a high-quality documentation reader into psql so
that users who are running Windows but not mingw, cygwin, or pgAdmin
can access the documentation more easily doesn't seem like the correct
solution to this problem. I don't really object if somebody wants to
do it (although someone else may object) but it's certainly taking the
long way around as far as this particular confusion is concerned.

FWIW, in my reasonably substantial experience, virtually every user on
Windows uses pgadmin3. Use of psql is fairly rare.

cheers

andrew

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Mon, Jul 1, 2013 at 9:26 PM, Robert Haas <robertmhaas@gmail.com> wrote:

On Mon, Jul 1, 2013 at 10:20 AM, David Fetter <david@fetter.org> wrote:

With deepest respect, failing to provide documentation to users on our
widest-deployed platform seems pretty hostile to me.

Yes, that would be pretty hostile. However, we don't do anything that
remotely resembles that statement, nor has anyone proposed any such
thing.

Personally, I think this whole thread is much ado about nothing.
Magnus is basically arguing that people might expect that CREATE VIEW
ought to tell you about CREATE MATERIALIZED VIEW also, but I don't
find that argument to have a whole lot of merit. Views and
materialized views are pretty different things; it is a bit like

How different are they really? Yes, they are very different from an
implementation standpoint, from an enduser perspective they really are
not. If they were, they'd probably be called something else..

asking why Googling for "dog" does not give you information on hot
dogs. The output of psql's \h command is intended to be a succinct

I'd personally say it's more like googling for dog gives me hits
specifically around "dog breeding" and not just dogs themselves.

synopsis summarizing the salient syntax (try saying that five times
fast), not a comprehensive reference. If you want the latter, read
the fine manual. I admit that this particular case is slightly more
prone to confusion than some, but I'm just not that exercised about
it. Every bit of detail we add to the \h output is better for the
people who otherwise would have been unhappy, but it's worse for all
the people who did need it because it's more to read through.

True.

Regardless of whether you agree with or disagree with the above
statement, building a high-quality documentation reader into psql so
that users who are running Windows but not mingw, cygwin, or pgAdmin
can access the documentation more easily doesn't seem like the correct
solution to this problem. I don't really object if somebody wants to
do it (although someone else may object) but it's certainly taking the
long way around as far as this particular confusion is concerned.

I still think a better option to that would be to get psql to provide
a link to the full documentation there.

pgAdmin could also do that, but doesn't - it gets you a link to the
main documentation, but not a context sensitive one IIRC.

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Mon, Jul 1, 2013 at 3:57 PM, Magnus Hagander <magnus@hagander.net> wrote:

How different are they really? Yes, they are very different from an
implementation standpoint, from an enduser perspective they really are
not. If they were, they'd probably be called something else.

They're different because they consume storage, require effort to
update, and aren't always up-to-date. Those things are all quite
user-visible.

I still think a better option to that would be to get psql to provide
a link to the full documentation there.

It seems like clutter to me, but I'll defer to whatever the consensus is.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On 07/01/2013 07:20 AM, David Fetter wrote:

On Mon, Jul 01, 2013 at 10:05:24AM -0400, Peter Eisentraut wrote:

On 6/28/13 2:27 PM, David Fetter wrote:

You can run \! man from within psql,

And if you're on Windows, you're Sadly Out of Luck with that. Is
there an equivalent we could #ifdef in for that platform?

If you are using psql on Windows extensively, you probably have one of
mingw, cygwin, or pgadmin handy, all of which can get you to the
documentation. I don't think it's worth devising a mechanism for those
not covered by this.

With deepest respect, failing to provide documentation to users on our
widest-deployed platform seems pretty hostile to me. There was an
earlier suggestion that we provide URLs, which seems like a decent way
forward as those environments so locked down as to disallow outbound
HTTP are pretty rare, and non-networked computers are even more rare.

Although I agree with the sentiment the idea that postgres more widely
deployed on windows than other platforms is rather laughable. The only
metrics we have are "downloads" which doesn't count cause linux ships
with postgres with a simple yum or apt-get.

Whatever solution we decide, we should not push this responsibility off
on pgadmin as pgadmin is not part of PostgreSQL but a third party tool.
The "standard" postgresql client is psql (for good or bad) and we should
support psql fully on all platforms.

Sincerely,

Joshua D. Drake

--
Command Prompt, Inc. - http://www.commandprompt.com/ 509-416-6579
PostgreSQL Support, Training, Professional Services and Development
High Availability, Oracle Conversion, Postgres-XC, @cmdpromptinc
For my dreams of your image that blossoms
a rose in the deeps of my heart. - W.B. Yeats

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Robert Haas escribi�:

On Mon, Jul 1, 2013 at 3:57 PM, Magnus Hagander <magnus@hagander.net> wrote:

I still think a better option to that would be to get psql to provide
a link to the full documentation there.

It seems like clutter to me, but I'll defer to whatever the consensus is.

I second the idea of having psql's \h provide a link to the command's
specific reference page.

--
�lvaro Herrera http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Training & Services

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers