Friendly help for psql

Why not run help when someone enters "help" (or "HELP ME!") on the
command line? \? is hardly an easy thing to remember (and some people
can't be bothered to actually read the screen...)

Greg Sabino Mullane wrote:
> Why not run help when someone enters "help" (or "HELP ME!") on the
> command line? \? is hardly an easy thing to remember (and some people
> can't be bothered to actually read the screen...)

Then surely the help output won't be of use to them either.

--
Peter Eisentraut
http://developer.postgresql.org/~petere/

Peter Eisentraut <peter_e(at)gmx(dot)net> writes:
> Greg Sabino Mullane wrote:
>> Why not run help when someone enters "help" (or "HELP ME!") on the
>> command line? \? is hardly an easy thing to remember (and some people
>> can't be bothered to actually read the screen...)

> Then surely the help output won't be of use to them either.

The actual argument for doing this is nothing more nor less than
"mysql does it like that". 99% of the people who will tell you this
is user-friendly think so because they used mysql before coming to
postgres.

That might be sufficient reason to do it; I'm not sure. Personally
I find it a really bad idea for psql to be usurping syntax that
doesn't start with a backslash, but I don't suppose I'm representative
of people who haven't absorbed the difference between psql and SQL.

Note that the mysql help facility covers both the mysql program and SQL
commands (ie both \? and \h in our terminology) so the proposed patch
is going to be seen as pretty lacking anyway by mysql-trained users.

It's interesting to note that "help", "\h", and "\?" all provoke the
same response(s) in mysql. Perhaps a patch that had had more than two
seconds' design effort in it would do the same in psql; though I'm not
sure what to do to disambiguate the case with no arguments.

regards, tom lane

Tom Lane wrote:

> It's interesting to note that "help", "\h", and "\?" all provoke the
> same response(s) in mysql. Perhaps a patch that had had more than two
> seconds' design effort in it would do the same in psql; though I'm not
> sure what to do to disambiguate the case with no arguments.

I'm not sure that plain \? and \h output is all that useful. If you
can understand what to make from that, you wouldn't be using "help" in
the first place. I think a more extensive text would be more
appropriate, which referenced the \? and \h commands so that the user
could take a peek after reading the blurb.

To avoid the usage of unadorned "help" (which I don't think is going to
ever cause conflicts with a SQL command but perhaps it's better to be
prepared), one idea would be to respond with "please execute \help
instead", and then \help would emit the verbose output. Perhaps
eventually we could adorn it with "\help category", etc.

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

-----BEGIN PGP SIGNED MESSAGE-----
Hash: RIPEMD160

Tom Lane opined:

> The actual argument for doing this is nothing more nor less than
> "mysql does it like that". 99% of the people who will tell you this
> is user-friendly think so because they used mysql before coming to
> postgres.

No. While the original poster may have been making a separate comparison
to MySQL, I can assure you that my impetus for doing this is not being
driven by the behavior of the mysql client. Having "help" do something
other than throw a syntax error is a very common feature in many
interactive programs, for example openssl, gdb, ftp, bash, mail,
telnet, and vim.

> That might be sufficient reason to do it; I'm not sure. Personally
> I find it a really bad idea for psql to be usurping syntax that
> doesn't start with a backslash, but I don't suppose I'm representative
> of people who haven't absorbed the difference between psql and SQL.

Right: this is obviously aimed at people who are new to psql.

> Note that the mysql help facility covers both the mysql program and SQL
> commands (ie both \? and \h in our terminology) so the proposed patch
> is going to be seen as pretty lacking anyway by mysql-trained users.

It gets them pointed in the right direction.

> It's interesting to note that "help", "\h", and "\?" all provoke the
> same response(s) in mysql. Perhaps a patch that had had more than two
> seconds' design effort in it would do the same in psql; though I'm not
> sure what to do to disambiguate the case with no arguments.

I'm not looking to emulate MySQL, I'm looking to do something reasonable
when a user enters "help". Output that is generated in response to a user's
action is more likely to be read than something auto-generated at the
start of the session, and they should be able to take it from there.

Alvaro suggests:

> To avoid the usage of unadorned "help" (which I don't think is going to
> ever cause conflicts with a SQL command but perhaps it's better to be
> prepared), one idea would be to respond with "please execute \help
> instead", and then \help would emit the verbose output.

Ugh. Why make people do two steps?

- --
Greg Sabino Mullane greg(at)turnstep(dot)com
PGP Key: 0x14964AC8 200801201518
http://biglumber.com/x/web?pk=2529DF6AB8F79407E94445B4BC9B906714964AC8
-----BEGIN PGP SIGNATURE-----

iD8DBQFHk683vJuQZxSWSsgRA1F0AJ0RVQqd6LeIGsZDeyP78Y/WngpMdACfdrPZ
LJ5gmCbZ3OuXq6JK5C+BTEQ=
=flsE
-----END PGP SIGNATURE-----

On Sun, 2008-01-20 at 14:08 -0500, Tom Lane wrote:
> Peter Eisentraut <peter_e(at)gmx(dot)net> writes:
> > Greg Sabino Mullane wrote:
> >> Why not run help when someone enters "help" (or "HELP ME!") on the
> >> command line? \? is hardly an easy thing to remember (and some people
> >> can't be bothered to actually read the screen...)
>
> > Then surely the help output won't be of use to them either.
>
> The actual argument for doing this is nothing more nor less than
> "mysql does it like that". 99% of the people who will tell you this
> is user-friendly think so because they used mysql before coming to
> postgres.

The recourse to typing "help" at a command line when an unfamiliar
prompt appears wasn't invented for or by mysql. Most Postgres users I
meet are strung out across many apps and system utilities, so doing
obvious things like this helps them a great deal.

It's more about putting the light switch at hand-height next to the
wall, so that anybody stumbling in the dark can find it. Their next
thought will probably be "Doh! Of course, silly me", but it will still
help them.

I'd be happy with output that explains briefly the difference between
psql and SQL commands and refers people to \? and \h. That way we don't
have to introduce too much change and this can be a forgivable special
case. (Don't like the "Help me" thing though).

--
Simon Riggs
2ndQuadrant http://www.2ndQuadrant.com

Simon Riggs <simon(at)2ndquadrant(dot)com> writes:
> I'd be happy with output that explains briefly the difference between
> psql and SQL commands and refers people to \? and \h. That way we don't
> have to introduce too much change and this can be a forgivable special
> case. (Don't like the "Help me" thing though).

I think you're headed in the same direction as Alvaro. A slight
extension on this would be

help

produces short blurb describing \h and \?

help something

produces same result as \h something

regards, tom lane

Greg Sabino Mullane wrote:

> Alvaro suggests:
>
> > To avoid the usage of unadorned "help" (which I don't think is going to
> > ever cause conflicts with a SQL command but perhaps it's better to be
> > prepared), one idea would be to respond with "please execute \help
> > instead", and then \help would emit the verbose output.
>
> Ugh. Why make people do two steps?

That was a side thought anyway, just to avoid the argument of "what will
we do when SQL decrees that HELP is a keyword to do something else".
Does anyone know if Oracle or DB2's command line tools have "help"
commands?

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

Greg Sabino Mullane wrote:
> No. While the original poster may have been making a separate comparison
> to MySQL, I can assure you that my impetus for doing this is not being
> driven by the behavior of the mysql client.

Then what is the motivation for this? We have many sources of help. I have
never heard of any user not being able to find help.

> Having "help" do something
> other than throw a syntax error is a very common feature in many
> interactive programs, for example openssl, gdb, ftp, bash, mail,
> telnet, and vim.

The difference with these tools is that they don't already tell you how to get
help when you log in.

Now I have actually thought for a while whether we could get rid of the login
text altogether. I would support trading that for extended help options.
But if the login note is there, then we don't need more help options.

--
Peter Eisentraut
http://developer.postgresql.org/~petere/

Peter Eisentraut <peter_e(at)gmx(dot)net> writes:
> Now I have actually thought for a while whether we could get rid of the login
> text altogether. I would support trading that for extended help options.

That makes sense to me. I think people are accustomed to ignoring login
headers because they are usually just copyright boilerplate. I could
see reducing the header to something like

$ psql
Welcome to psql 8.3RC2, the PostgreSQL interactive terminal.
Type \? for help, \q to quit.

dbname=#

in the normal case. (The wrong-backend-version warning and perhaps
the SSL encryption notice would remain as possible additions.)

We really shouldn't be designing this on -patches, though.

regards, tom lane

-----BEGIN PGP SIGNED MESSAGE-----
Hash: RIPEMD160

>> No. While the original poster may have been making a separate comparison
>> to MySQL, I can assure you that my impetus for doing this is not being
>> driven by the behavior of the mysql client.

> Then what is the motivation for this? We have many sources of help. I have
> never heard of any user not being able to find help.

Maybe you need to get out in the trenches more, I've seen users confused
at the psql prompt.

>> Having "help" do something
>> other than throw a syntax error is a very common feature in many
>> interactive programs, for example openssl, gdb, ftp, bash, mail,
>> telnet, and vim.

> The difference with these tools is that they don't already tell you how to get
> help when you log in.
>
> Now I have actually thought for a while whether we could get rid of the login
> text altogether. I would support trading that for extended help options.
> But if the login note is there, then we don't need more help options.

What about when the login note is no longer available? New person logs on,
issues a select * from customer; then tries to remember how to view all the tables.
Or how to quit. Their first instinct is "help" - no reason we cannot support that;
it does no harm at all to people who don't use it. Another use case: someone has a
'screen' session open to a psql prompt, and sends someone else in to it, or comes
back later on. Same thing: the login note is no longer available ('screen' has a
small scrollback), and even if you've used it before, "backslash question mark"
is, let's be honest, very obscure, unintuitive, and hard to remember.

I'd support an alternative text rather than "slashusage" as long as something
is put into place.

- --
Greg Sabino Mullane greg(at)turnstep(dot)com
PGP Key: 0x14964AC8 200801220101
http://biglumber.com/x/web?pk=2529DF6AB8F79407E94445B4BC9B906714964AC8
-----BEGIN PGP SIGNATURE-----

iD8DBQFHlYorvJuQZxSWSsgRA9TNAKDbXm/NLCoM6DFJDsVppjhu0be2VgCeL3Zr
I1lnq4VCw5+5pG20rJgvCvM=
=S9x4
-----END PGP SIGNATURE-----

Alvaro Herrera wrote:
> To avoid the usage of unadorned "help" (which I don't think is going to
> ever cause conflicts with a SQL command but perhaps it's better to be
> prepared), one idea would be to respond with "please execute \help
> instead", and then \help would emit the verbose output. Perhaps
> eventually we could adorn it with "\help category", etc.

Uh, imagine:

test=> SELECT * from pg_class
test-> help

Technically 'help' is now an alias for 'pg_class'. Are you suggesting
supporting 'help' in this usage? People were saying they forget
semicolons, so this 'help' usage is quite possible. We don't want to
hear "Why doesn't 'help' work sometimes?"

I think the fundamental problem is that most programs, like ftp, have a
predefined set of single-line commands, while we have an SQL 'language'
that can be multi-line and has no special markings in psql. In fact the
special marking is for help and psql-commands using backslash.

Supporting 'help' in psql seems like a very slippery slope. We are very
tight in defining when an entry is psql and when it is SQL and this
weakens that.

What would be interesting would be if the _server_ could send back some
message about "Use the help facility of your client application" but it
would have to have a trailing semicolon; unlikely. :-(

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://postgres.enterprisedb.com

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

-----BEGIN PGP SIGNED MESSAGE-----
Hash: RIPEMD160

> Uh, imagine:
>
> test=> SELECT * from pg_class
> test-> help
>
> Technically 'help' is now an alias for 'pg_class'. Are you suggesting
> supporting 'help' in this usage? People were saying they forget
> semicolons, so this 'help' usage is quite possible. We don't want to
> hear "Why doesn't 'help' work sometimes?"

I don't think we have to worry about supporting that case. We only
support it when the command begins with "help". No ambiguity with
SQL to worry about. Don't forget that ctrl-c resets a query as well, so
the above situation is not as dire as it may appear to the uninitiated
user.

> Supporting 'help' in psql seems like a very slippery slope. We are very
> tight in defining when an entry is psql and when it is SQL and this
> weakens that.

Does not seem slippery to me, seems a simple, one-time fix that replaces
a syntax error with a helpful message. As the instigator of this discussion,
I can assure you I have no plans for anything other than "help". It's simple,
standard, and points you to anything else you may need or want to do.

> What would be interesting would be if the _server_ could send back some
> message about "Use the help facility of your client application" but it
> would have to have a trailing semicolon; unlikely. :-(

Now THAT would be a bad mangling of SQL and non-SQL. We'll pretend you
didn't suggest that one. :)

- --
Greg Sabino Mullane greg(at)turnstep(dot)com
PGP Key: 0x14964AC8 200801281451
http://biglumber.com/x/web?pk=2529DF6AB8F79407E94445B4BC9B906714964AC8
-----BEGIN PGP SIGNATURE-----

iD8DBQFHnjJgvJuQZxSWSsgRA8mMAJ4jzlrwYDVguUNt2yAwMTXMvV1S3QCg+SaF
n8ybxb/KbGBxW9aouZGpzaY=
=igJU
-----END PGP SIGNATURE-----

Bruce Momjian <bruce(at)momjian(dot)us> writes:
> Alvaro Herrera wrote:
>> To avoid the usage of unadorned "help" (which I don't think is going to
>> ever cause conflicts with a SQL command but perhaps it's better to be
>> prepared), one idea would be to respond with "please execute \help
>> instead", and then \help would emit the verbose output. Perhaps
>> eventually we could adorn it with "\help category", etc.

> Uh, imagine:

> test=> SELECT * from pg_class
> test-> help

You didn't read the patch: it would recognize "help" only when the input
buffer is empty. The only thing it's assuming is that no SQL command
will ever *begin* with the word "help".

regards, tom lane

This has been saved for the 8.4 release:

http://momjian.postgresql.org/cgi-bin/pgpatches_hold

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

Greg Sabino Mullane wrote:
-- Start of PGP signed section.
> Why not run help when someone enters "help" (or "HELP ME!") on the
> command line? \? is hardly an easy thing to remember (and some people
> can't be bothered to actually read the screen...)
>

[ Attachment, skipping... ]
-- End of PGP section, PGP failed!

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://postgres.enterprisedb.com

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

Greg Sabino Mullane wrote:
> Why not run help when someone enters "help" (or "HELP ME!") on the
> command line? \? is hardly an easy thing to remember (and some people
> can't be bothered to actually read the screen...)

So, have you produced a followup patch?

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

Index: mainloop.c
===================================================================
RCS file: /projects/cvsroot/pgsql/src/bin/psql/mainloop.c,v
retrieving revision 1.87
diff -c -r1.87 mainloop.c
*** mainloop.c 1 Jan 2008 19:45:56 -0000 1.87
--- mainloop.c 2 Apr 2008 12:51:36 -0000
***************
*** 171,176 ****
--- 171,187 ----
continue;
}

+ /* A request for help? Be friendly and give them some guidance */
+ if (pset.cur_cmd_interactive && query_buf->len == 0 &&
+ pg_strncasecmp(line, "help", 4) == 0) {
+ free(line);
+ puts("You are using psql, the command-line interface to PostgreSQL.");
+ puts("Enter SQL commands, or type \\? for a list of backslash options.");
+ puts("Use \\q to quit.");
+ puts("Visit http://postgresql.org for help on PostgreSQL\n");
+ continue;
+ }
+
/* echo back if flag is set */
if (pset.echo == PSQL_ECHO_ALL && !pset.cur_cmd_interactive)
puts(line);

Greg Sabino Mullane wrote:
-- Start of PGP signed section.
> Why not run help when someone enters "help" (or "HELP ME!") on the
> command line? \? is hardly an easy thing to remember (and some people
> can't be bothered to actually read the screen...)
>

I have applied this patch (attached) with a few modifications. First
you were printing \? help for any string beginning with "help" so
"helplkjasdf" also printed help --- I don't think we want that. I
allowed "help", "help "*, and "help;", so "help select" does work
(prints \?).

I also added \? to the list of \? help options because now someone can
get to \? without typing \?.

Shame we can't make \h more prominent in \? output. I am going to try
to trim down that top help section, but that will a separate patch
posting by me.

Any adjustments?

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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