Re: psql and output from \? - Mailing list pgsql-hackers

I haven't seen a followup patch so I decided to work on it myself;
patch attached and applied to CVS.  Thanks.

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

Ian Barwick wrote:
>
> First off:
>   This is a suggestion for minor changes to the output generated by the \?
>   command in psql. While it is more of a documentation issue, it would
>   involve changing code (well, a few strings) - is this the right place for
>   raising the subject? I would be happy to submit a patch if the changes are
>   acceptable.
>
> Background:
>   In psql the \? command shows a summary of the available "slash" commands.
>   The syntax shown is however not always consistent (neither with the \?
>   command output nor with the psql manpage); eg.:
>
>   "\cd [DIRNAME]  change the current working directory"
>
>   implies that provision of a parameter is optional (correct), whereas
>
>   "\C TITLE       set table title"
>
>   implies that a title parameter is required. This is not in fact the case,
>   as executing \C without a parameter will unset any title previously set
>   with the same command. This behaviour is however correctly
>   documented in the manpage, which also shows the
>   command syntax as "\C [ title ]".
>
>   Similar is true of the following slash commands: \d \e \f \g \s \T
>
> Solution:
>   Appended is a list of relevant backslash commands, their current
>   description as produced by  \?, the respective manpage description (or
>   first part thereof) and suggested replacment for the \? description.
>   Assumption is that square brackets - as used elsewhere within the
>   \? output and the manpage documentation - imply optional parameters.
>
>
> Yours pedantically
>
> Ian Barwick
>
> Suggestions follow:
>
> \C
> -----------------------------------------------------------------------
>
> psql \?:
> \C TITLE       set table title
>
> man:
> \C [ title ]
>         Set the title of any tables being  printed  as  the
>         result  of  a  query  or unset any such title. (...)
>
> psql \? new:
> \C [ TITLE ]  set table title (or unset with no arguments)
>
>
> \d
> -----------------------------------------------------------------------
>
> psql \?:
> \d TABLE       describe table (or view, index, sequence)
>
> man:
> \d relation
>         Shows all columns of relation  (which  could  be  a
>         table,  view, index, or sequence), (...)
>
> psql \? new:
> \d [ RELATION ] describe relation (table, view, index or sequence)
>
>
> \e
> -----------------------------------------------------------------------
>
> psql \?:
> \e FILENAME    edit the current query buffer or file with external editor
>
> man
> \edit (or \e) [ filename ]
>         If filename is specified, the file is edited; (...)
>
> psql \? new:
> \e [ FILENAME ]  edit the current query buffer or file with external editor
>
>
> \f
> -----------------------------------------------------------------------
>
> psql \?:
> \f STRING      set field separator
>
> man:
> \f [ string ]
>         Sets the field separator for unaligned query output. (...)
>
> psql \? new:
> \f [ STRING ] show or set field separator
>
>
> \g
> -----------------------------------------------------------------------
>
> psql \?:
> \g FILENAME    send SQL command to server (and write results to file or |pipe)
>
> man:
> \g [ { filename | |command } ]
>         Sends the current query input buffer to the backend
>               and optionally saves  the  output  in  filename  or
>               pipes the output into a separate Unix shell to exe?
>               cute command. (...)
>
> psql \? new:
> \g [ FILE | |PIPE ] send SQL command to server (and write results to file or
>         |pipe)
>
>
> \s
> -----------------------------------------------------------------------
>
> psql \?:
> \s FILENAME    print history or save it to file
>
> man:
> \s [ filename ]
>               Print or save the command line history to filename.
>
> psql \? new:
> \s [ FILENAME ]   print command line history or save it to file
>
>
> \T
> -----------------------------------------------------------------------
>
> psql \?:
> \T TEXT        set HTML table tag attributes
>
> man:
> \T table_options
>         Allows you to specify options to be  placed  within
>         the  table  tag  in  HTML tabular output mode. (...)
>
> psql  \? new:
> \T [ TAG_ATTR ]   set HTML <table> tag attributes (or unset with no arguments)
>
>
> __END__
>
> ---------------------------(end of broadcast)---------------------------
> TIP 3: if posting/reading through Usenet, please send an appropriate
> subscribe-nomail command to majordomo@postgresql.org so that your
> message can get through to the mailing list cleanly
>

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026
? psql
Index: help.c
===================================================================
RCS file: /cvsroot/pgsql/src/bin/psql/help.c,v
retrieving revision 1.46
diff -c -r1.46 help.c
*** help.c    7 Mar 2002 17:54:42 -0000    1.46
--- help.c    11 Mar 2002 18:20:34 -0000
***************
*** 193,239 ****
      fprintf(fout, _(" \\c[onnect] [DBNAME|- [USER]]\n"
           "                connect to new database (currently \"%s\")\n"),
              PQdb(pset.db));
!     fprintf(fout, _(" \\C TITLE       set table title\n"));
!     fprintf(fout, _(" \\cd [DIRNAME]  change the current working directory\n"));
      fprintf(fout, _(" \\copy ...      perform SQL COPY with data stream to the client host\n"));
      fprintf(fout, _(" \\copyright     show PostgreSQL usage and distribution terms\n"));
!     fprintf(fout, _(" \\d TABLE       describe table (or view, index, sequence)\n"));
      fprintf(fout, _(" \\d{t|i|s|v}... list tables/indexes/sequences/views\n"));
      fprintf(fout, _(" \\d{p|S|l}      list access privileges, system tables, or large objects\n"));
      fprintf(fout, _(" \\da            list aggregate functions\n"));
!     fprintf(fout, _(" \\dd NAME       show comment for table, type, function, or operator\n"));
      fprintf(fout, _(" \\df            list functions\n"));
      fprintf(fout, _(" \\do            list operators\n"));
      fprintf(fout, _(" \\dT            list data types\n"));
!     fprintf(fout, _(" \\du [PATTERN]  Lists all configured users or only those that match pattern\n"));
!     fprintf(fout, _(" \\e FILENAME    edit the current query buffer or file with external editor\n"));
      fprintf(fout, _(" \\echo TEXT     write text to standard output\n"));
      fprintf(fout, _(" \\encoding ENCODING  set client encoding\n"));
!     fprintf(fout, _(" \\f STRING      set field separator\n"));
!     fprintf(fout, _(" \\g FILENAME    send SQL command to server (and write results to file or |pipe)\n"));
      fprintf(fout, _(" \\h NAME        help on syntax of SQL commands, * for all commands\n"));
      fprintf(fout, _(" \\H             toggle HTML output mode (currently %s)\n"),
              ON(pset.popt.topt.format == PRINT_HTML));
!     fprintf(fout, _(" \\i FILENAME    execute commands from file\n"));
      fprintf(fout, _(" \\l             list all databases\n"));
      fprintf(fout, _(" \\lo_export, \\lo_import, \\lo_list, \\lo_unlink\n"
!                     "                large object operations\n"));
!     fprintf(fout, _(" \\o FILENAME    send all query results to file or |pipe\n"));
      fprintf(fout, _(" \\p             show the content of the current query buffer\n"));
      fprintf(fout, _(" \\pset VAR      set table output option (VAR := {format|border|expanded|\n"
!                     "                fieldsep|null|recordsep|tuples_only|title|tableattr|pager})\n"));
      fprintf(fout, _(" \\q             quit psql\n"));
      fprintf(fout, _(" \\qecho TEXT    write text to query output stream (see \\o)\n"));
      fprintf(fout, _(" \\r             reset (clear) the query buffer\n"));
!     fprintf(fout, _(" \\s FILENAME    print history or save it to file\n"));
      fprintf(fout, _(" \\set NAME VALUE  set internal variable\n"));
      fprintf(fout, _(" \\t             show only rows (currently %s)\n"),
              ON(pset.popt.topt.tuples_only));
!     fprintf(fout, _(" \\T TEXT        set HTML table tag attributes\n"));
      fprintf(fout, _(" \\timing        toggle timing of queries (currently %s)\n"),
              ON(pset.timing));
      fprintf(fout, _(" \\unset NAME    unset (delete) internal variable\n"));
!     fprintf(fout, _(" \\w FILENAME    write current query buffer to file\n"));
      fprintf(fout, _(" \\x             toggle expanded output (currently %s)\n"),
              ON(pset.popt.topt.expanded));
      fprintf(fout, _(" \\z             list table access privileges\n"));
--- 193,239 ----
      fprintf(fout, _(" \\c[onnect] [DBNAME|- [USER]]\n"
           "                connect to new database (currently \"%s\")\n"),
              PQdb(pset.db));
!     fprintf(fout, _(" \\C [TITLE]     set table title, or unset with no title\n"));
!     fprintf(fout, _(" \\cd [DIR]      change the current working directory\n"));
      fprintf(fout, _(" \\copy ...      perform SQL COPY with data stream to the client host\n"));
      fprintf(fout, _(" \\copyright     show PostgreSQL usage and distribution terms\n"));
!     fprintf(fout, _(" \\d [TABLE]     describe table (or view, index, sequence)\n"));
      fprintf(fout, _(" \\d{t|i|s|v}... list tables/indexes/sequences/views\n"));
      fprintf(fout, _(" \\d{p|S|l}      list access privileges, system tables, or large objects\n"));
      fprintf(fout, _(" \\da            list aggregate functions\n"));
!     fprintf(fout, _(" \\dd [NAME]     show comment for table, type, function, or operator\n"));
      fprintf(fout, _(" \\df            list functions\n"));
      fprintf(fout, _(" \\do            list operators\n"));
      fprintf(fout, _(" \\dT            list data types\n"));
!     fprintf(fout, _(" \\du [PATTERN]  lists all configured users or only those that match pattern\n"));
!     fprintf(fout, _(" \\e [FILE]      edit the current query buffer or file with external editor\n"));
      fprintf(fout, _(" \\echo TEXT     write text to standard output\n"));
      fprintf(fout, _(" \\encoding ENCODING  set client encoding\n"));
!     fprintf(fout, _(" \\f [SEPARATOR] set field separator, or unset if none\n"));
!     fprintf(fout, _(" \\g [FILE]      send SQL command to server (and write results to file or |pipe)\n"));
      fprintf(fout, _(" \\h NAME        help on syntax of SQL commands, * for all commands\n"));
      fprintf(fout, _(" \\H             toggle HTML output mode (currently %s)\n"),
              ON(pset.popt.topt.format == PRINT_HTML));
!     fprintf(fout, _(" \\i FILE        execute commands from file\n"));
      fprintf(fout, _(" \\l             list all databases\n"));
      fprintf(fout, _(" \\lo_export, \\lo_import, \\lo_list, \\lo_unlink\n"
!                     "                 large object operations\n"));
!     fprintf(fout, _(" \\o FILE        send all query results to file or |pipe\n"));
      fprintf(fout, _(" \\p             show the content of the current query buffer\n"));
      fprintf(fout, _(" \\pset VAR      set table output option (VAR := {format|border|expanded|\n"
!                     "                 fieldsep|null|recordsep|tuples_only|title|tableattr|pager})\n"));
      fprintf(fout, _(" \\q             quit psql\n"));
      fprintf(fout, _(" \\qecho TEXT    write text to query output stream (see \\o)\n"));
      fprintf(fout, _(" \\r             reset (clear) the query buffer\n"));
!     fprintf(fout, _(" \\s [FILE]      print history or save it to file\n"));
      fprintf(fout, _(" \\set NAME VALUE  set internal variable\n"));
      fprintf(fout, _(" \\t             show only rows (currently %s)\n"),
              ON(pset.popt.topt.tuples_only));
!     fprintf(fout, _(" \\T [TAG_ATTR]  set HTML table tag attributes, or unset if none\n"));
      fprintf(fout, _(" \\timing        toggle timing of queries (currently %s)\n"),
              ON(pset.timing));
      fprintf(fout, _(" \\unset NAME    unset (delete) internal variable\n"));
!     fprintf(fout, _(" \\w FILE        write current query buffer to file\n"));
      fprintf(fout, _(" \\x             toggle expanded output (currently %s)\n"),
              ON(pset.popt.topt.expanded));
      fprintf(fout, _(" \\z             list table access privileges\n"));