Patch to change psql default banner

On Wed, 23 Apr 2008 14:41:20 -0700
"Joshua D. Drake" <jd@commandprompt.com> wrote:

Hello,

Per final discussion here:

http://archives.postgresql.org/pgsql-hackers/2008-04/msg01607.php

Joshua D. Drake

--
The PostgreSQL Company since 1997: http://www.commandprompt.com/
PostgreSQL Community Conference: http://www.postgresqlconference.org/
United States PostgreSQL Association: http://www.postgresql.us/
Donate to the PostgreSQL Project: http://www.postgresql.org/about/donate

Joshua D. Drake wrote:

On Wed, 23 Apr 2008 14:41:20 -0700
"Joshua D. Drake" <jd@commandprompt.com> wrote:

Hello,

Per final discussion here:

http://archives.postgresql.org/pgsql-hackers/2008-04/msg01607.php

Isn't this going to mean \g is listed twice?

	+   fprintf(output, _("Execution\n"));
	+   fprintf(output, _("  \\g or ;    execute query\n\n"));

If you want I can look at reorganizing the \? help. I have a larger
reorganization mind.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Joshua D. Drake wrote:

On Wed, 23 Apr 2008 14:41:20 -0700
"Joshua D. Drake" <jd@commandprompt.com> wrote:

Hello,

Per final discussion here:

http://archives.postgresql.org/pgsql-hackers/2008-04/msg01607.php

I have looked over this patch and made a few adjustments.

You used for a help startup banner:

Type: help for help.

I feel this has too much indirection because 'help' then produced:

You are using psql, the command-line interface to PostgreSQL.

\h or \\help for SQL help.
\? for psql help.
\q to quit psql.

\copyright to view the copyright.

Because \? now has \h, \q, and \copyright alone at the top I think we
should just use:

$ psql test
psql (8.4devel) Type \? for help.

test=>

If you type 'help' it just repeats the startup banner suggestion:

test=> help

You are using psql, the command-line interface to PostgreSQL.
Type \? for help.

test=>

I think that consistency will be clearer. In the past we were trying to
avoid \?, but I think now it is clean enough to be used by new people
without confusion.

I also put the version number in parentheses so it wouldn't be as
prominent.

Updated patch attached.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

I think that consistency will be clearer. In the past we were trying to
avoid \?, but I think now it is clean enough to be used by new people
without confusion.

I also put the version number in parentheses so it wouldn't be as
prominent.

Updated patch attached.

FYI, after the patch is applied I will update psql banner examples in
our documentation.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Bruce Momjian wrote:

If you type 'help' it just repeats the startup banner suggestion:

test=> help

You are using psql, the command-line interface to PostgreSQL.
Type \? for help.

I think we wanted to have more information in 'help', not less. Making
it just repeat the startup info is not very helpful.

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

Alvaro Herrera wrote:

Bruce Momjian wrote:

If you type 'help' it just repeats the startup banner suggestion:

test=> help

You are using psql, the command-line interface to PostgreSQL.
Type \? for help.

I think we wanted to have more information in 'help', not less. Making
it just repeat the startup info is not very helpful.

I thought about that, but aren't we just repeating the top of \?. Is
that helpful? Should we just display \?.

I know we decided not to do that, but I am trying to figure out what the
goal if 'help' is? To display the most frequently-used help commands?
Aren't they at the top of \?.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Bruce Momjian wrote:

Alvaro Herrera wrote:

Bruce Momjian wrote:

If you type 'help' it just repeats the startup banner suggestion:

test=> help

You are using psql, the command-line interface to PostgreSQL.
Type \? for help.

I think we wanted to have more information in 'help', not less. Making
it just repeat the startup info is not very helpful.

I thought about that, but aren't we just repeating the top of \?. Is
that helpful? Should we just display \?.

I am a little confused here. The whole point of this patch is to remove
all extraneous information from the startup banner and push it to a
"help" screen. Thus type help for help.

If you type help you get your help options.

I know we decided not to do that, but I am trying to figure out what the
goal if 'help' is? To display the most frequently-used help commands?
Aren't they at the top of \?.

The purpose of help is to provide what help options there are available
to those who need them.

Joshua D. Drake

Bruce Momjian wrote:

I know we decided not to do that, but I am trying to figure out what the
goal if 'help' is? To display the most frequently-used help commands?
Aren't they at the top of \?.

The purpose of 'help' is to provide useful help. If it only says "see \?"
then it's just redirecting you somewhere else, which isn't useful.

I don't think the various help commands need to be completely
orthogonal. If you agree with that, then making 'help' repeat part of
what \? says is acceptable. (Of course, the idea is not just to repeat,
but also to provide useful advice to the unwary.)

Remember, the people who is going to type 'help' is not the 10-year-Pg-
experience types. It's the newbies.

--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Alvaro Herrera wrote:

Bruce Momjian wrote:

I know we decided not to do that, but I am trying to figure out what the
goal if 'help' is? To display the most frequently-used help commands?
Aren't they at the top of \?.

The purpose of 'help' is to provide useful help. If it only says "see \?"
then it's just redirecting you somewhere else, which isn't useful.

I don't think the various help commands need to be completely
orthogonal. If you agree with that, then making 'help' repeat part of
what \? says is acceptable. (Of course, the idea is not just to repeat,
but also to provide useful advice to the unwary.)

OK.

Remember, the people who is going to type 'help' is not the 10-year-Pg-
experience types. It's the newbies.

The larger issue is whether we want to advertise only "help" in the
startup banner. The patch has just:

Type: help for help.

Now, aside from being confusing (we need quotes around "help"), I
thought we should only mention \?.

My question is whether we agreed that suggesting "help" as the best way
to get help was what we agreed upon? If we did, I forgot. I thought
the 'help' ideas was just for people who forgot the help commands.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Bruce Momjian wrote:

My question is whether we agreed that suggesting "help" as the best way
to get help was what we agreed upon? If we did, I forgot. I thought
the 'help' ideas was just for people who forgot the help commands.

Please review the previous discussion:

http://archives.postgresql.org/message-id/1200851790.19135.68.camel%40greg-laptop

--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Alvaro Herrera wrote:

Bruce Momjian wrote:

My question is whether we agreed that suggesting "help" as the best way
to get help was what we agreed upon? If we did, I forgot. I thought
the 'help' ideas was just for people who forgot the help commands.

Please review the previous discussion:

http://archives.postgresql.org/message-id/1200851790.19135.68.camel%40greg-laptop

OK, I just read the thread and saw no one say we should be promoting
_only_ 'help' in the startup banner. Where is that email discussion?

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Bruce Momjian wrote:

Alvaro Herrera wrote:

Bruce Momjian wrote:

My question is whether we agreed that suggesting "help" as the best way
to get help was what we agreed upon? If we did, I forgot. I thought
the 'help' ideas was just for people who forgot the help commands.

Please review the previous discussion:

http://archives.postgresql.org/message-id/1200851790.19135.68.camel%40greg-laptop

OK, I just read the thread and saw no one say we should be promoting
_only_ 'help' in the startup banner. Where is that email discussion?

http://archives.postgresql.org/pgsql-hackers/2008-04/msg01476.php

And most specifically:

http://archives.postgresql.org/pgsql-hackers/2008-04/msg01376.php

Joshua D. Drake

Joshua D. Drake wrote:

Bruce Momjian wrote:

Alvaro Herrera wrote:

Bruce Momjian wrote:

My question is whether we agreed that suggesting "help" as the best way
to get help was what we agreed upon? If we did, I forgot. I thought
the 'help' ideas was just for people who forgot the help commands.

Please review the previous discussion:

http://archives.postgresql.org/message-id/1200851790.19135.68.camel%40greg-laptop

OK, I just read the thread and saw no one say we should be promoting
_only_ 'help' in the startup banner. Where is that email discussion?

http://archives.postgresql.org/pgsql-hackers/2008-04/msg01476.php

And most specifically:

http://archives.postgresql.org/pgsql-hackers/2008-04/msg01376.php

Ah, OK. I had forgotten. Here is the new output:

$ sql test
psql (8.4devel) Type "help" for help.

test=> help

You are using psql, the command-line interface to PostgreSQL.
\h or \help for SQL help
\? for psql help
\q to quit psql

\copyright to view the copyright

test=> \?
General
\copyright show PostgreSQL usage and distribution terms
\g [FILE] or ; send query buffer to server (and results to file or |pipe)
\h [NAME] help on syntax of SQL commands, * for all commands
\q quit psql

Query Buffer
\e [FILE] edit the query buffer (or file) with external editor
...

I moved '\g' up into the "General" section rather than make it a
single-entry section.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Bruce Momjian wrote:

test=> \?
General
\copyright show PostgreSQL usage and distribution terms
\g [FILE] or ; send query buffer to server (and results to file or |pipe)
\h [NAME] help on syntax of SQL commands, * for all commands
\q quit psql

Query Buffer
\e [FILE] edit the query buffer (or file) with external editor
...

I moved '\g' up into the "General" section rather than make it a
single-entry section.

"send query buffer to server means nothing to a newbie". You execute
queries, you don't send buffers (from a user perspective).

Sincerely,

Joshua D. Drake

Joshua D. Drake wrote:

Bruce Momjian wrote:

test=> \?
General
\copyright show PostgreSQL usage and distribution terms
\g [FILE] or ; send query buffer to server (and results to file or |pipe)
\h [NAME] help on syntax of SQL commands, * for all commands
\q quit psql

Query Buffer
\e [FILE] edit the query buffer (or file) with external editor
...

I moved '\g' up into the "General" section rather than make it a
single-entry section.

"send query buffer to server means nothing to a newbie". You execute
queries, you don't send buffers (from a user perspective).

Yep, good, updated:

General
\copyright show PostgreSQL usage and distribution terms
\g [FILE] or ; execute query (and send results to file or |pipe)
\h [NAME] help on syntax of SQL commands, * for all commands
\q quit psql

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Bruce Momjian wrote:

Joshua D. Drake wrote:

Bruce Momjian wrote:

I moved '\g' up into the "General" section rather than make it a
single-entry section.

"send query buffer to server means nothing to a newbie". You execute
queries, you don't send buffers (from a user perspective).

Yep, good, updated:

General
\copyright show PostgreSQL usage and distribution terms
\g [FILE] or ; execute query (and send results to file or |pipe)
\h [NAME] help on syntax of SQL commands, * for all commands
\q quit psql

Cool.

Joshua D. Drake

Bruce Momjian <bruce@momjian.us> writes:

Ah, OK. I had forgotten. Here is the new output:

$ sql test
psql (8.4devel) Type "help" for help.

test=> help

You are being unreasonably cryptic here. What happens when there
is optional output --- ie, version mismatch warning and/or SSL info?

regards, tom lane

Tom Lane wrote:

Bruce Momjian <bruce@momjian.us> writes:

Ah, OK. I had forgotten. Here is the new output:

$ sql test
psql (8.4devel) Type "help" for help.

test=> help

You are being unreasonably cryptic here. What happens when there
is optional output --- ie, version mismatch warning and/or SSL info?

Oh, good point. Let me look at that. Thanks. You prefer:

$ sql test
psql (8.4devel)
Type "help" for help.

test=> help

That looked so sparse to me.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Bruce Momjian <bruce@momjian.us> writes:

Oh, good point. Let me look at that. Thanks. You prefer:

$ sql test
psql (8.4devel)
Type "help" for help.

test=> help

Well, the question is still "where is the optional info going to go?"

I think what I'd find nice looking is

$ psql test
psql 8.4devel [ server version warning here, if needed ]
[ line with SSL info here, if needed ]
Type "help" for help.

test=>

I do feel that the help statement ought to be on its own line;
the other way is going to look cluttered, particularly as soon
as there's a version warning in there.

regards, tom lane