Thread: 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...)
Attachment
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@gmx.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@turnstep.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@gmx.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@2ndquadrant.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@gmx.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@turnstep.com
PGP Key: 0x14964AC8 200801220101
http://biglumber.com/x/web?pk=2529DF6AB8F79407E94445B4BC9B906714964AC8
-----BEGIN PGP SIGNATURE-----
iD8DBQFHlYorvJuQZxSWSsgRA9TNAKDbXm/NLCoM6DFJDsVppjhu0be2VgCeL3Zr
I1lnq4VCw5+5pG20rJgvCvM=
=S9x4
-----END PGP SIGNATURE-----
-----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@turnstep.com PGP Key: 0x14964AC8 200801281451 http://biglumber.com/x/web?pk=2529DF6AB8F79407E94445B4BC9B906714964AC8 -----BEGIN PGP SIGNATURE----- iD8DBQFHnjJgvJuQZxSWSsgRA8mMAJ4jzlrwYDVguUNt2yAwMTXMvV1S3QCg+SaF n8ybxb/KbGBxW9aouZGpzaY= =igJU -----END PGP SIGNATURE-----
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@momjian.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@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + If your life is a hard drive, Christ can be your backup. + Index: src/bin/psql/help.c =================================================================== RCS file: /cvsroot/pgsql/src/bin/psql/help.c,v retrieving revision 1.124 diff -c -c -r1.124 help.c *** src/bin/psql/help.c 29 Mar 2008 19:40:12 -0000 1.124 --- src/bin/psql/help.c 4 Apr 2008 17:39:05 -0000 *************** *** 188,193 **** --- 188,194 ---- ON(pset.timing)); fprintf(output, _(" \\unset NAME unset (delete) internal variable\n")); fprintf(output, _(" \\! [COMMAND] execute command in shell or start interactive shell\n")); + fprintf(output, _(" \\? display this help output\n")); fprintf(output, "\n"); fprintf(output, _("Query Buffer\n")); Index: src/bin/psql/mainloop.c =================================================================== RCS file: /cvsroot/pgsql/src/bin/psql/mainloop.c,v retrieving revision 1.87 diff -c -c -r1.87 mainloop.c *** src/bin/psql/mainloop.c 1 Jan 2008 19:45:56 -0000 1.87 --- src/bin/psql/mainloop.c 4 Apr 2008 17:39:05 -0000 *************** *** 11,16 **** --- 11,17 ---- #include "command.h" #include "common.h" + #include "help.h" #include "input.h" #include "settings.h" *************** *** 171,176 **** --- 172,187 ---- continue; } + /* A request for help? Be friendly and show them the slash way of doing things */ + if (pset.cur_cmd_interactive && query_buf->len == 0 && + pg_strncasecmp(line, "help", 4) == 0 && + (line[4] == '\0' || line[4] == ';' || isspace(line[4]))) + { + free(line); + slashUsage(pset.popt.topt.pager); + continue; + } + /* echo back if flag is set */ if (pset.echo == PSQL_ECHO_ALL && !pset.cur_cmd_interactive) puts(line);
bruce wrote: > 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. Ah, I see now we later agreed to have 'help' just output a suggestion to use \?. I have expanded on that and removed the mention of the web site, which seemed odd to be just in the 'help' output. (I added a \h mention.) Update patch applied, that also reverses the previous patch. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + If your life is a hard drive, Christ can be your backup. + Index: src/bin/psql/help.c =================================================================== RCS file: /cvsroot/pgsql/src/bin/psql/help.c,v retrieving revision 1.125 diff -c -c -r1.125 help.c *** src/bin/psql/help.c 4 Apr 2008 17:42:43 -0000 1.125 --- src/bin/psql/help.c 4 Apr 2008 17:57:18 -0000 *************** *** 188,194 **** ON(pset.timing)); fprintf(output, _(" \\unset NAME unset (delete) internal variable\n")); fprintf(output, _(" \\! [COMMAND] execute command in shell or start interactive shell\n")); - fprintf(output, _(" \\? display this help output\n")); fprintf(output, "\n"); fprintf(output, _("Query Buffer\n")); --- 188,193 ---- Index: src/bin/psql/mainloop.c =================================================================== RCS file: /cvsroot/pgsql/src/bin/psql/mainloop.c,v retrieving revision 1.88 diff -c -c -r1.88 mainloop.c *** src/bin/psql/mainloop.c 4 Apr 2008 17:42:43 -0000 1.88 --- src/bin/psql/mainloop.c 4 Apr 2008 17:57:18 -0000 *************** *** 11,17 **** #include "command.h" #include "common.h" - #include "help.h" #include "input.h" #include "settings.h" --- 11,16 ---- *************** *** 172,184 **** continue; } ! /* A request for help? Be friendly and show them the slash way of doing things */ if (pset.cur_cmd_interactive && query_buf->len == 0 && pg_strncasecmp(line, "help", 4) == 0 && (line[4] == '\0' || line[4] == ';' || isspace(line[4]))) { free(line); ! slashUsage(pset.popt.topt.pager); continue; } --- 171,186 ---- 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 && (line[4] == '\0' || line[4] == ';' || isspace(line[4]))) { 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 \\h for SQL command help."); ! puts("Use \\q to quit."); continue; }