Re: psql \? help display - Mailing list pgsql-hackers

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"