Thread: psql \? help display
I promised to review our psql \? output to see if I could improve it,
particularly the "General" section at the top. Below are the results.
Are the new sections ideal, and in the best ordering? Should \copyright
be kept in "General" at the top? Should \? be listed?
I also pulled up some descriptive text that caused the options to have
blank lines between them.
---------------------------------------------------------------------------
General \copyright show PostgreSQL usage and distribution terms \h [NAME] help on syntax of SQL commands, *
forall commands \q quit psql
Query Buffer \e [FILE] edit the query buffer (or file) with external editor \g [FILE] send query buffer to
server(and results to file or |pipe) \p show the contents of the query buffer \r reset (clear)
thequery buffer \s [FILE] display history or save it to file \w FILE write query buffer to file
Input/Output \echo [STRING] write string to standard output \i FILE execute commands from file \o [FILE]
sendall query results to file or |pipe \qecho [STRING] write string to query output stream (see \o)
Informational \d [NAME] describe table, index, sequence, or view \d{t|i|s|v|S} [PATTERN] (add "+" for more detail)
list tables/indexes/sequences/views/system tables \da [PATTERN] list aggregate functions \db [PATTERN]
listtablespaces (add "+" for more detail) \dc [PATTERN] list conversions \dC list casts \dd [PATTERN] show
commentfor object \dD [PATTERN] list domains \df [PATTERN] list functions (add "+" for more detail) \dF [PATTERN]
listtext search configurations (add "+" for more detail) \dFd [PATTERN] list text search dictionaries (add "+" for more
detail)\dFt [PATTERN] list text search templates \dFp [PATTERN] list text search parsers (add "+" for more detail) \dg
[PATTERN] list roles (groups) \dn [PATTERN] list schemas (add "+" for more detail) \do [NAME] list operators \dl
list large objects, same as \lo_list \dp [PATTERN] list table, view, and sequence access privileges \dT
[PATTERN] list data types (add "+" for more detail) \du [PATTERN] list roles (users) \l list all databases
(add"+" for more detail) \z [PATTERN] list table, view, and sequence access privileges (same as \dp)
Formatting \a toggle between unaligned and aligned output mode \C [STRING] set table title, or unset if
none\f [STRING] show or set field separator for unaligned query output \H toggle HTML output mode
(currentlyoff) \pset NAME [VALUE] set table output option (NAME :=
{format|border|expanded|fieldsep|footer|null| numericlocale|recordsep|tuples_only|title|tableattr|pager})
\t show only rows (currently off) \T [STRING] set HTML <table> tag attributes, or unset if none \x
toggle expanded output (currently off)
Connection \c[onnect] [DBNAME|- USER|- HOST|- PORT|-] connect to new database (currently "test")
\encoding[ENCODING] show or set client encoding \password [USERNAME] securely change the password for a user
External \cd [DIR] change the current working directory \timing toggle timing of commands (currently off)
\![COMMAND] execute command in shell or start interactive shell
Variable \prompt [TEXT] NAME prompt user to set internal variable \set [NAME [VALUE]] set internal variable, or list
allif no parameters \unset NAME unset (delete) internal variable
Copy, Large Object \copy ... perform SQL COPY with data stream to the client host \lo_export LOBOID FILE
\lo_importFILE [COMMENT] \lo_list \lo_unlink LOBOID large object operations
-- 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: > I promised to review our psql \? output to see if I could improve it, > particularly the "General" section at the top. Below are the results. > > Are the new sections ideal, and in the best ordering? Should \copyright > be kept in "General" at the top? Should \? be listed? Why do we have a section named "Copy, Large Objects"? It would seem to make sense to put the LO stuff on its own section. > I also pulled up some descriptive text that caused the options to have > blank lines between them. It was like that to keep the alignment of descriptions. It's a judgement call of course, but personally I think the other way was better. -- Alvaro Herrera http://www.CommandPrompt.com/ PostgreSQL Replication, Consulting, Custom Development, 24x7 support
Alvaro Herrera wrote: > Bruce Momjian wrote: > > I promised to review our psql \? output to see if I could improve it, > > particularly the "General" section at the top. Below are the results. > > > > Are the new sections ideal, and in the best ordering? Should \copyright > > be kept in "General" at the top? Should \? be listed? > > Why do we have a section named "Copy, Large Objects"? It would seem to > make sense to put the LO stuff on its own section. OK, new version attached. I moved \copy into "External" and relabled the section as just "Large Object" (singular?). > > I also pulled up some descriptive text that caused the options to have > > blank lines between them. > > It was like that to keep the alignment of descriptions. It's a > judgement call of course, but personally I think the other way was > better. Yea, I looked at that and though the description on a new line was clearer it was harder to see the options in one glance. Lack of line breaks now makes the sections easier to identify. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + If your life is a hard drive, Christ can be your backup. + General \copyright show PostgreSQL usage and distribution terms \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 \g [FILE] send query buffer to server (and results to file or |pipe) \p show the contents of the query buffer \r reset (clear) the query buffer \s [FILE] display history or save it to file \w FILE write query buffer to file Input/Output \echo [STRING] write string to standard output \i FILE execute commands from file \o [FILE] send all query results to file or |pipe \qecho [STRING] write string to query output stream (see \o) Informational \d [NAME] describe table, index, sequence, or view \d{t|i|s|v|S} [PATTERN] (add "+" for more detail) list tables/indexes/sequences/views/system tables \da [PATTERN] list aggregate functions \db [PATTERN] list tablespaces (add "+" for more detail) \dc [PATTERN] list conversions \dC list casts \dd [PATTERN] show comment for object \dD [PATTERN] list domains \df [PATTERN] list functions (add "+" for more detail) \dF [PATTERN] list text search configurations (add "+" for more detail) \dFd [PATTERN] list text search dictionaries (add "+" for more detail) \dFt [PATTERN] list text search templates \dFp [PATTERN] list text search parsers (add "+" for more detail) \dg [PATTERN] list roles (groups) \dn [PATTERN] list schemas (add "+" for more detail) \do [NAME] list operators \dl list large objects, same as \lo_list \dp [PATTERN] list table, view, and sequence access privileges \dT [PATTERN] list data types (add "+" for more detail) \du [PATTERN] list roles (users) \l list all databases (add "+" for more detail) \z [PATTERN] list table, view, and sequence access privileges (same as \dp) Formatting \a toggle between unaligned and aligned output mode \C [STRING] set table title, or unset if none \f [STRING] show or set field separator for unaligned query output \H toggle HTML output mode (currently off) \pset NAME [VALUE] set table output option (NAME := {format|border|expanded|fieldsep|footer|null| numericlocale|recordsep|tuples_only|title|tableattr|pager}) \t show only rows (currently off) \T [STRING] set HTML <table> tag attributes, or unset if none \x toggle expanded output (currently off) Connection \c[onnect] [DBNAME|- USER|- HOST|- PORT|-] connect to new database (currently "test") \encoding [ENCODING] show or set client encoding \password [USERNAME] securely change the password for a user External \cd [DIR] change the current working directory \copy ... perform SQL COPY with data stream to the client host \timing toggle timing of commands (currently off) \! [COMMAND] execute command in shell or start interactive shell Variable \prompt [TEXT] NAME prompt user to set internal variable \set [NAME [VALUE]] set internal variable, or list all if no parameters \unset NAME unset (delete) internal variable Large Object \lo_export LOBOID FILE \lo_import FILE [COMMENT] \lo_list \lo_unlink LOBOID large object operations
Bruce Momjian wrote: > Alvaro Herrera wrote: >> Bruce Momjian wrote: >>> I promised to review our psql \? output to see if I could improve it, >>> particularly the "General" section at the top. Below are the results. >>> >>> Are the new sections ideal, and in the best ordering? Should \copyright >>> be kept in "General" at the top? Should \? be listed? >> Why do we have a section named "Copy, Large Objects"? It would seem to >> make sense to put the LO stuff on its own section. > > OK, new version attached. I moved \copy into "External" and relabled > the section as just "Large Object" (singular?). > I would think copy would fit better with i/o - basically a subset/variation of \i external is more for executing external code than importing data. Yes singular - all the others are singular. If we go plural variable and maybe connection would fit plural as well (or maybe after the multi connection patch)? -- Shane Ambler pgSQL (at) Sheeky (dot) Biz Get Sheeky @ http://Sheeky.Biz
Shane Ambler wrote: > Bruce Momjian wrote: > > Alvaro Herrera wrote: > >> Bruce Momjian wrote: > >>> I promised to review our psql \? output to see if I could improve it, > >>> particularly the "General" section at the top. Below are the results. > >>> > >>> Are the new sections ideal, and in the best ordering? Should \copyright > >>> be kept in "General" at the top? Should \? be listed? > >> Why do we have a section named "Copy, Large Objects"? It would seem to > >> make sense to put the LO stuff on its own section. > > > > OK, new version attached. I moved \copy into "External" and relabled > > the section as just "Large Object" (singular?). > > > > I would think copy would fit better with i/o - basically a > subset/variation of \i > external is more for executing external code than importing data. OK, new version attached. > Yes singular - all the others are singular. If we go plural variable and > maybe connection would fit plural as well (or maybe after the multi > connection patch)? OK, singular. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + If your life is a hard drive, Christ can be your backup. + General \copyright show PostgreSQL usage and distribution terms \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 \g [FILE] send query buffer to server (and results to file or |pipe) \p show the contents of the query buffer \r reset (clear) the query buffer \s [FILE] display history or save it to file \w FILE write query buffer to file Input/Output \copy ... perform SQL COPY with data stream to the client host \echo [STRING] write string to standard output \i FILE execute commands from file \o [FILE] send all query results to file or |pipe \qecho [STRING] write string to query output stream (see \o) Informational \d [NAME] describe table, index, sequence, or view \d{t|i|s|v|S} [PATTERN] (add "+" for more detail) list tables/indexes/sequences/views/system tables \da [PATTERN] list aggregate functions \db [PATTERN] list tablespaces (add "+" for more detail) \dc [PATTERN] list conversions \dC list casts \dd [PATTERN] show comment for object \dD [PATTERN] list domains \df [PATTERN] list functions (add "+" for more detail) \dF [PATTERN] list text search configurations (add "+" for more detail) \dFd [PATTERN] list text search dictionaries (add "+" for more detail) \dFt [PATTERN] list text search templates \dFp [PATTERN] list text search parsers (add "+" for more detail) \dg [PATTERN] list roles (groups) \dn [PATTERN] list schemas (add "+" for more detail) \do [NAME] list operators \dl list large objects, same as \lo_list \dp [PATTERN] list table, view, and sequence access privileges \dT [PATTERN] list data types (add "+" for more detail) \du [PATTERN] list roles (users) \l list all databases (add "+" for more detail) \z [PATTERN] list table, view, and sequence access privileges (same as \dp) Formatting \a toggle between unaligned and aligned output mode \C [STRING] set table title, or unset if none \f [STRING] show or set field separator for unaligned query output \H toggle HTML output mode (currently off) \pset NAME [VALUE] set table output option (NAME := {format|border|expanded|fieldsep|footer|null| numericlocale|recordsep|tuples_only|title|tableattr|pager}) \t show only rows (currently off) \T [STRING] set HTML <table> tag attributes, or unset if none \x toggle expanded output (currently off) Connection \c[onnect] [DBNAME|- USER|- HOST|- PORT|-] connect to new database (currently "test") \encoding [ENCODING] show or set client encoding \password [USERNAME] securely change the password for a user External \cd [DIR] change the current working directory \timing toggle timing of commands (currently off) \! [COMMAND] execute command in shell or start interactive shell Variable \prompt [TEXT] NAME prompt user to set internal variable \set [NAME [VALUE]] set internal variable, or list all if no parameters \unset NAME unset (delete) internal variable Large Object \lo_export LOBOID FILE \lo_import FILE [COMMENT] \lo_list \lo_unlink LOBOID large object operations
Patch applied, matching attached output. More suggestions welcomed. --------------------------------------------------------------------------- Bruce Momjian wrote: > Shane Ambler wrote: > > Bruce Momjian wrote: > > > Alvaro Herrera wrote: > > >> Bruce Momjian wrote: > > >>> I promised to review our psql \? output to see if I could improve it, > > >>> particularly the "General" section at the top. Below are the results. > > >>> > > >>> Are the new sections ideal, and in the best ordering? Should \copyright > > >>> be kept in "General" at the top? Should \? be listed? > > >> Why do we have a section named "Copy, Large Objects"? It would seem to > > >> make sense to put the LO stuff on its own section. > > > > > > OK, new version attached. I moved \copy into "External" and relabled > > > the section as just "Large Object" (singular?). > > > > > > > I would think copy would fit better with i/o - basically a > > subset/variation of \i > > external is more for executing external code than importing data. > > OK, new version attached. > > > Yes singular - all the others are singular. If we go plural variable and > > maybe connection would fit plural as well (or maybe after the multi > > connection patch)? > > OK, singular. > > -- > Bruce Momjian <bruce@momjian.us> http://momjian.us > EnterpriseDB http://enterprisedb.com > > + If your life is a hard drive, Christ can be your backup. + > General > \copyright show PostgreSQL usage and distribution terms > \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 > \g [FILE] send query buffer to server (and results to file or |pipe) > \p show the contents of the query buffer > \r reset (clear) the query buffer > \s [FILE] display history or save it to file > \w FILE write query buffer to file > > Input/Output > \copy ... perform SQL COPY with data stream to the client host > \echo [STRING] write string to standard output > \i FILE execute commands from file > \o [FILE] send all query results to file or |pipe > \qecho [STRING] write string to query output stream (see \o) > > Informational > \d [NAME] describe table, index, sequence, or view > \d{t|i|s|v|S} [PATTERN] (add "+" for more detail) > list tables/indexes/sequences/views/system tables > \da [PATTERN] list aggregate functions > \db [PATTERN] list tablespaces (add "+" for more detail) > \dc [PATTERN] list conversions > \dC list casts > \dd [PATTERN] show comment for object > \dD [PATTERN] list domains > \df [PATTERN] list functions (add "+" for more detail) > \dF [PATTERN] list text search configurations (add "+" for more detail) > \dFd [PATTERN] list text search dictionaries (add "+" for more detail) > \dFt [PATTERN] list text search templates > \dFp [PATTERN] list text search parsers (add "+" for more detail) > \dg [PATTERN] list roles (groups) > \dn [PATTERN] list schemas (add "+" for more detail) > \do [NAME] list operators > \dl list large objects, same as \lo_list > \dp [PATTERN] list table, view, and sequence access privileges > \dT [PATTERN] list data types (add "+" for more detail) > \du [PATTERN] list roles (users) > \l list all databases (add "+" for more detail) > \z [PATTERN] list table, view, and sequence access privileges (same as \dp) > > Formatting > \a toggle between unaligned and aligned output mode > \C [STRING] set table title, or unset if none > \f [STRING] show or set field separator for unaligned query output > \H toggle HTML output mode (currently off) > \pset NAME [VALUE] set table output option > (NAME := {format|border|expanded|fieldsep|footer|null| > numericlocale|recordsep|tuples_only|title|tableattr|pager}) > \t show only rows (currently off) > \T [STRING] set HTML <table> tag attributes, or unset if none > \x toggle expanded output (currently off) > > Connection > \c[onnect] [DBNAME|- USER|- HOST|- PORT|-] > connect to new database (currently "test") > \encoding [ENCODING] show or set client encoding > \password [USERNAME] securely change the password for a user > > External > \cd [DIR] change the current working directory > \timing toggle timing of commands (currently off) > \! [COMMAND] execute command in shell or start interactive shell > > Variable > \prompt [TEXT] NAME prompt user to set internal variable > \set [NAME [VALUE]] set internal variable, or list all if no parameters > \unset NAME unset (delete) internal variable > > Large Object > \lo_export LOBOID FILE > \lo_import FILE [COMMENT] > \lo_list > \lo_unlink LOBOID large object operations > > -- > Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) > To make changes to your subscription: > http://www.postgresql.org/mailpref/pgsql-hackers -- 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.126 diff -c -c -r1.126 help.c *** src/bin/psql/help.c 4 Apr 2008 18:00:25 -0000 1.126 --- src/bin/psql/help.c 14 May 2008 15:28:39 -0000 *************** *** 160,166 **** { FILE *output; ! output = PageOutput(69, pager); /* if you add/remove a line here, change the row count above */ --- 160,166 ---- { FILE *output; ! output = PageOutput(78, pager); /* if you add/remove a line here, change the row count above */ *************** *** 169,193 **** * in 80 columns >> " */ fprintf(output, _("General\n")); - fprintf(output, _(" \\c[onnect] [DBNAME|- USER|- HOST|- PORT|-]\n" - " connect to new database (currently \"%s\")\n"), - PQdb(pset.db)); - fprintf(output, _(" \\cd [DIR] change the current working directory\n")); fprintf(output, _(" \\copyright show PostgreSQL usage and distribution terms\n")); - fprintf(output, _(" \\encoding [ENCODING]\n" - " show or set client encoding\n")); fprintf(output, _(" \\h [NAME] help on syntax of SQL commands, * for all commands\n")); - fprintf(output, _(" \\prompt [TEXT] NAME\n" - " prompt user to set internal variable\n")); - fprintf(output, _(" \\password [USERNAME]\n" - " securely change the password for a user\n")); fprintf(output, _(" \\q quit psql\n")); - fprintf(output, _(" \\set [NAME [VALUE]]\n" - " set internal variable, or list all if no parameters\n")); - fprintf(output, _(" \\timing toggle timing of commands (currently %s)\n"), - 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, "\n"); fprintf(output, _("Query Buffer\n")); --- 169,177 ---- *************** *** 202,212 **** fprintf(output, "\n"); fprintf(output, _("Input/Output\n")); fprintf(output, _(" \\echo [STRING] write string to standard output\n")); fprintf(output, _(" \\i FILE execute commands from file\n")); fprintf(output, _(" \\o [FILE] send all query results to file or |pipe\n")); ! fprintf(output, _(" \\qecho [STRING]\n" ! " write string to query output stream (see \\o)\n")); fprintf(output, "\n"); fprintf(output, _("Informational\n")); --- 186,196 ---- fprintf(output, "\n"); fprintf(output, _("Input/Output\n")); + fprintf(output, _(" \\copy ... perform SQL COPY with data stream to the client host\n")); fprintf(output, _(" \\echo [STRING] write string to standard output\n")); fprintf(output, _(" \\i FILE execute commands from file\n")); fprintf(output, _(" \\o [FILE] send all query results to file or |pipe\n")); ! fprintf(output, _(" \\qecho [STRING] write string to query output stream (see \\o)\n")); fprintf(output, "\n"); fprintf(output, _("Informational\n")); *************** *** 241,248 **** fprintf(output, _(" \\f [STRING] show or set field separator for unaligned query output\n")); fprintf(output, _(" \\H toggle HTML output mode (currently %s)\n"), ON(pset.popt.topt.format == PRINT_HTML)); ! fprintf(output, _(" \\pset NAME [VALUE]\n" ! " set table output option\n" " (NAME := {format|border|expanded|fieldsep|footer|null|\n" " numericlocale|recordsep|tuples_only|title|tableattr|pager})\n")); fprintf(output, _(" \\t show only rows (currently %s)\n"), --- 225,231 ---- fprintf(output, _(" \\f [STRING] show or set field separator for unaligned query output\n")); fprintf(output, _(" \\H toggle HTML output mode (currently %s)\n"), ON(pset.popt.topt.format == PRINT_HTML)); ! fprintf(output, _(" \\pset NAME [VALUE] set table output option\n" " (NAME := {format|border|expanded|fieldsep|footer|null|\n" " numericlocale|recordsep|tuples_only|title|tableattr|pager})\n")); fprintf(output, _(" \\t show only rows (currently %s)\n"), *************** *** 252,259 **** ON(pset.popt.topt.expanded)); fprintf(output, "\n"); ! fprintf(output, _("Copy, Large Object\n")); ! fprintf(output, _(" \\copy ... perform SQL COPY with data stream to the client host\n")); fprintf(output, _(" \\lo_export LOBOID FILE\n" " \\lo_import FILE [COMMENT]\n" " \\lo_list\n" --- 235,262 ---- ON(pset.popt.topt.expanded)); fprintf(output, "\n"); ! fprintf(output, _("Connection\n")); ! fprintf(output, _(" \\c[onnect] [DBNAME|- USER|- HOST|- PORT|-]\n" ! " connect to new database (currently \"%s\")\n"), ! PQdb(pset.db)); ! fprintf(output, _(" \\encoding [ENCODING] show or set client encoding\n")); ! fprintf(output, _(" \\password [USERNAME] securely change the password for a user\n")); ! fprintf(output, "\n"); ! ! fprintf(output, _("External\n")); ! fprintf(output, _(" \\cd [DIR] change the current working directory\n")); ! fprintf(output, _(" \\timing toggle timing of commands (currently %s)\n"), ! ON(pset.timing)); ! fprintf(output, _(" \\! [COMMAND] execute command in shell or start interactive shell\n")); ! fprintf(output, "\n"); ! ! fprintf(output, _("Variable\n")); ! fprintf(output, _(" \\prompt [TEXT] NAME prompt user to set internal variable\n")); ! fprintf(output, _(" \\set [NAME [VALUE]] set internal variable, or list all if no parameters\n")); ! fprintf(output, _(" \\unset NAME unset (delete) internal variable\n")); ! fprintf(output, "\n"); ! ! fprintf(output, _("Large Object\n")); fprintf(output, _(" \\lo_export LOBOID FILE\n" " \\lo_import FILE [COMMENT]\n" " \\lo_list\n"