Re: [BUGS] Bug #718: request for improvement of /? to show /d+ /l+

(Sent to everyone this time)

What happened with the casts and conversions patch? Was it accepted? I
think it should be committed before changing all the \d commands - it'll be
easier.

Chris

----- Original Message -----
From: "Bruce Momjian" <pgman@candle.pha.pa.us>
To: "Harald Armin Massa" <ghum@gmx.net>
Cc: "PostgreSQL-patches" <pgsql-patches@postgresql.org>
Sent: Tuesday, December 10, 2002 1:25 PM
Subject: Re: [PATCHES] [BUGS] Bug #718: request for improvement of /? to
show /d+ /l+

Here is a new psql \? output format that I would like to add for 7.4.
It follows Harald Armin's suggested reformatting, which you can see
below.

Should I also reorder the psql manual page to match? I find the
grouping much easier to review.

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

-

General
\c[onnect] [DBNAME|- [USER]]
connect to new database (currently "test")
\q quit psql
\h [NAME] help on syntax of SQL commands, * for all commands
\copyright show PostgreSQL usage and distribution terms
\cd [DIR] change the current working directory
\! [COMMAND] execute command in shell or start interactive shell
\encoding [ENCODING] show or set client encoding
\set [NAME [VALUE]] set internal variable, or list all if no parameters
\unset NAME unset (delete) internal variable
\timing toggle timing of commands (currently off)

Query Buffer
\g [FILE] send query buffer to server (and results to file or |pipe)
\r reset (clear) the query buffer
\e [FILE] edit the query buffer (or file) with external editor
\i FILE execute commands from file
\p show the contents of the query buffer
\w [FILE] write query buffer to file
\o FILE send all query results to file or |pipe
\s [FILE] display history or save it to file

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
\dd [PATTERN] show comment for object
\dD [PATTERN] list domains
\df [PATTERN] list functions (add "+" for more detail)
\do [NAME] list operators
\dl list large objects, same as \lo_list
\dp [PATTERN] list table access privileges
\dT [PATTERN] list data types (add "+" for more detail)
\du [PATTERN] list users
\l list all databases (add "+" for more detail)
\z [PATTERN] list table access privileges (same as \dp)

Large Object, Copy
\lo_export
\lo_import
\lo_list
\lo_unlink large object operations
\copy ... perform SQL COPY with data stream to the client host

Formatting
\x toggle expanded output (currently off)
\a toggle between unaligned and aligned output mode
\f [STRING] show or set field separator for unaligned query output
\t show only rows (currently off)
\echo [STRING] write string to standard output
\qecho [STRING] write string to query output stream (see \o)

HTML Output
\H toggle HTML output mode (currently off)
\C [STRING] set table title, or unset if none
\T [STRING] set HTML <table> tag attributes, or unset if none
\pset NAME [VALUE] set table output option
(NAME := {format|border|expanded|fieldsep|null|recordsep|
tuples_only|title|tableattr|pager})

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

-

Harald Armin Massa wrote:

Sounds like a great idea --- a longer help version for psql. Yes,
please give it a try.

Bruce,

during ordering I found another "immediate" solution:

in the Output

\d TABLE describe table (or view, index, sequence)

just add

\d TABLE describe table (or view, index, sequence) add '+' for
extended

But there could really be an improvement of the psql help by grouping

the

commands after "Areas of interest" instead of sorting on alphabet. I

have

done a first try:

Servers, Connections
\c[onnect] [DBNAME|- [USER]]
connect to new database (currently "test")
\h NAME help on syntax of SQL commands, * for all commands
\g FILENAME send SQL command to server (and write results to file or
|pipe)
\copy ... perform SQL COPY with data stream to the client host
\cd [DIRNAME] change the current working directory
\! [COMMAND] execute command in shell or start interactive shell
\encoding ENCODING set client encoding
\set NAME VALUE set internal variable
\unset NAME unset (delete) internal variable
\q quit psql

Information Functions
\copyright show PostgreSQL usage and distribution terms
\d TABLE describe table (or view, index, sequence)
\d{t|i|s|v}... list tables/indexes/sequences/views (add + for extended)
\d{p|S|l} list access privileges, system tables, or large objects
\da list aggregate functions
\dd NAME show comment for table, type, function, or operator
\df list functions
\do list operators
\dT list data types
\l list all databases (add + for extended output)
\z list table access privileges
\d+ extended List
\l+

Query Buffer
\r reset (clear) the query buffer
\e FILENAME edit the current query buffer or file with external

editor

\i FILENAME execute commands from file
\p show the content of the current query buffer
\w FILENAME write current query buffer to file

Large Object
\lo_export, \lo_import, \lo_list, \lo_unlink
large object operations

Output and Formatting
\o FILENAME send all query results to file or |pipe
\a toggle between unaligned and aligned output mode
\f STRING set field separator
\t show only rows (currently off)
\x toggle expanded output (currently off)
\echo TEXT write text to standard output
\qecho TEXT write text to query output stream (see \o)
\s FILENAME print history or save it to file
\C TITLE set table title
\H toggle HTML output mode (currently off)
\T TEXT set HTML table tag attributes
\pset VAR set table output option (VAR := {format|border|expanded|

fieldsep|null|recordsep|tuples_only|title|tableattr|pager})

--
Bruce Momjian                        |  http://candle.pha.pa.us
pgman@candle.pha.pa.us               |  (610) 359-1001
+  If your life is a hard drive,     |  13 Roberts Road
+  Christ can be your backup.        |  Newtown Square, Pennsylvania

19073

On Tuesday 10 December 2002 22:25, Bruce Momjian wrote:

Here is a new psql \? output format that I would like to add for 7.4.
It follows Harald Armin's suggested reformatting, which you can see
below.

Should I also reorder the psql manual page to match? I find the
grouping much easier to review.

Me too. Suggestion: of the \pset options, only "tableattr" (corresponding to
"\T") exclusively affects HTML output (I think) - "\pset" would belong better
under "Formatting". "\C" on the other hand is also non-HTML specific
(corresponds to "\pset title" ).

Ian Barwick
barwick@gmx.net

OK, new output attached. Does the HTML section look silly now with only
two entries?

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

Ian Barwick wrote:

On Tuesday 10 December 2002 22:25, Bruce Momjian wrote:

Here is a new psql \? output format that I would like to add for 7.4.
It follows Harald Armin's suggested reformatting, which you can see
below.

Should I also reorder the psql manual page to match? I find the
grouping much easier to review.

Me too. Suggestion: of the \pset options, only "tableattr" (corresponding to
"\T") exclusively affects HTML output (I think) - "\pset" would belong better
under "Formatting". "\C" on the other hand is also non-HTML specific
(corresponds to "\pset title" ).

Ian Barwick
barwick@gmx.net

Formatting
\x toggle expanded output (currently off)
\a toggle between unaligned and aligned output mode
\f [STRING] show or set field separator for unaligned query output
\t show only rows (currently off)
\echo [STRING] write string to standard output
\qecho [STRING] write string to query output stream (see \o)

HTML Output
\H toggle HTML output mode (currently off)
\C [STRING] set table title, or unset if none
\T [STRING] set HTML <table> tag attributes, or unset if none
\pset NAME [VALUE] set table output option
(NAME := {format|border|expanded|fieldsep|null|recordsep|
tuples_only|title|tableattr|pager})

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

On Wednesday 11 December 2002 00:06, Bruce Momjian wrote:

OK, new output attached. Does the HTML section look silly now with only
two entries?

Not really, IMHO at least.

(I suppose we could invent some more HTML options to pad
it out if necessary. Optional DOCTYPE declarations or upper / lower
case tags spring to mind ;-) ) <- this is not a serious suggestion.

Ian Barwick
barwick@gmx.net

"Christopher Kings-Lynne" <chriskl@familyhealth.com.au> writes:

What happened with the casts and conversions patch?

Nothing yet. I think we're still debating how to spell the command to
invoke it ...

regards, tom lane

Bruce Momjian <pgman@candle.pha.pa.us> writes:

OK, new output attached. Does the HTML section look silly now with only
two entries?

Yeah. I think it should be folded into "Formatting", since it really is
only an output-formatting option.

I have a problem with the "Query Buffer" section, also: I don't think
\i, \o, etc have anything to do with the query buffer. Could we split
this section into "Query Buffer" (\g \r \e \p \w) and "I/O Redirection"
(\i \o \s), or something like that? Perhaps \copy could go into the
redirection section too, rather than suffering a shotgun wedding with
the large-object commands.

regards, tom lane

On Tue, Dec 10, 2002 at 11:27:05PM -0500, Tom Lane wrote:

Bruce Momjian <pgman@candle.pha.pa.us> writes:

OK, new output attached. Does the HTML section look silly now with only
two entries?

Yeah. I think it should be folded into "Formatting", since it really is
only an output-formatting option.

I have a problem with the "Query Buffer" section, also: I don't think
\i, \o, etc have anything to do with the query buffer. Could we split

In fact, I wish \i _did_ interact with the query buffer: it'd make \e
a lot more useful, IMHO.

Ross

cast patch is in the queue. I will manually apply your \? changes.

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

Christopher Kings-Lynne wrote:

(Sent to everyone this time)

What happened with the casts and conversions patch? Was it accepted? I
think it should be committed before changing all the \d commands - it'll be
easier.

Chris

----- Original Message -----
From: "Bruce Momjian" <pgman@candle.pha.pa.us>
To: "Harald Armin Massa" <ghum@gmx.net>
Cc: "PostgreSQL-patches" <pgsql-patches@postgresql.org>
Sent: Tuesday, December 10, 2002 1:25 PM
Subject: Re: [PATCHES] [BUGS] Bug #718: request for improvement of /? to
show /d+ /l+

Here is a new psql \? output format that I would like to add for 7.4.
It follows Harald Armin's suggested reformatting, which you can see
below.

Should I also reorder the psql manual page to match? I find the
grouping much easier to review.

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

-

General
\c[onnect] [DBNAME|- [USER]]
connect to new database (currently "test")
\q quit psql
\h [NAME] help on syntax of SQL commands, * for all commands
\copyright show PostgreSQL usage and distribution terms
\cd [DIR] change the current working directory
\! [COMMAND] execute command in shell or start interactive shell
\encoding [ENCODING] show or set client encoding
\set [NAME [VALUE]] set internal variable, or list all if no parameters
\unset NAME unset (delete) internal variable
\timing toggle timing of commands (currently off)

Query Buffer
\g [FILE] send query buffer to server (and results to file or |pipe)
\r reset (clear) the query buffer
\e [FILE] edit the query buffer (or file) with external editor
\i FILE execute commands from file
\p show the contents of the query buffer
\w [FILE] write query buffer to file
\o FILE send all query results to file or |pipe
\s [FILE] display history or save it to file

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
\dd [PATTERN] show comment for object
\dD [PATTERN] list domains
\df [PATTERN] list functions (add "+" for more detail)
\do [NAME] list operators
\dl list large objects, same as \lo_list
\dp [PATTERN] list table access privileges
\dT [PATTERN] list data types (add "+" for more detail)
\du [PATTERN] list users
\l list all databases (add "+" for more detail)
\z [PATTERN] list table access privileges (same as \dp)

Large Object, Copy
\lo_export
\lo_import
\lo_list
\lo_unlink large object operations
\copy ... perform SQL COPY with data stream to the client host

Formatting
\x toggle expanded output (currently off)
\a toggle between unaligned and aligned output mode
\f [STRING] show or set field separator for unaligned query output
\t show only rows (currently off)
\echo [STRING] write string to standard output
\qecho [STRING] write string to query output stream (see \o)

HTML Output
\H toggle HTML output mode (currently off)
\C [STRING] set table title, or unset if none
\T [STRING] set HTML <table> tag attributes, or unset if none
\pset NAME [VALUE] set table output option
(NAME := {format|border|expanded|fieldsep|null|recordsep|
tuples_only|title|tableattr|pager})

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

-

Harald Armin Massa wrote:

Sounds like a great idea --- a longer help version for psql. Yes,
please give it a try.

Bruce,

during ordering I found another "immediate" solution:

in the Output

\d TABLE describe table (or view, index, sequence)

just add

\d TABLE describe table (or view, index, sequence) add '+' for
extended

But there could really be an improvement of the psql help by grouping

the

commands after "Areas of interest" instead of sorting on alphabet. I

have

done a first try:

Servers, Connections
\c[onnect] [DBNAME|- [USER]]
connect to new database (currently "test")
\h NAME help on syntax of SQL commands, * for all commands
\g FILENAME send SQL command to server (and write results to file or
|pipe)
\copy ... perform SQL COPY with data stream to the client host
\cd [DIRNAME] change the current working directory
\! [COMMAND] execute command in shell or start interactive shell
\encoding ENCODING set client encoding
\set NAME VALUE set internal variable
\unset NAME unset (delete) internal variable
\q quit psql

Information Functions
\copyright show PostgreSQL usage and distribution terms
\d TABLE describe table (or view, index, sequence)
\d{t|i|s|v}... list tables/indexes/sequences/views (add + for extended)
\d{p|S|l} list access privileges, system tables, or large objects
\da list aggregate functions
\dd NAME show comment for table, type, function, or operator
\df list functions
\do list operators
\dT list data types
\l list all databases (add + for extended output)
\z list table access privileges
\d+ extended List
\l+

Query Buffer
\r reset (clear) the query buffer
\e FILENAME edit the current query buffer or file with external

editor

\i FILENAME execute commands from file
\p show the content of the current query buffer
\w FILENAME write current query buffer to file

Large Object
\lo_export, \lo_import, \lo_list, \lo_unlink
large object operations

Output and Formatting
\o FILENAME send all query results to file or |pipe
\a toggle between unaligned and aligned output mode
\f STRING set field separator
\t show only rows (currently off)
\x toggle expanded output (currently off)
\echo TEXT write text to standard output
\qecho TEXT write text to query output stream (see \o)
\s FILENAME print history or save it to file
\C TITLE set table title
\H toggle HTML output mode (currently off)
\T TEXT set HTML table tag attributes
\pset VAR set table output option (VAR := {format|border|expanded|

fieldsep|null|recordsep|tuples_only|title|tableattr|pager})

--
Bruce Momjian                        |  http://candle.pha.pa.us
pgman@candle.pha.pa.us               |  (610) 359-1001
+  If your life is a hard drive,     |  13 Roberts Road
+  Christ can be your backup.        |  Newtown Square, Pennsylvania

19073

---------------------------(end of broadcast)---------------------------
TIP 6: Have you searched our list archives?

http://archives.postgresql.org

---------------------------(end of broadcast)---------------------------
TIP 2: you can get off all lists at once with the unregister command
(send "unregister YourEmailAddressHere" to majordomo@postgresql.org)

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

Tom Lane wrote:

Bruce Momjian <pgman@candle.pha.pa.us> writes:

OK, new output attached. Does the HTML section look silly now with only
two entries?

Yeah. I think it should be folded into "Formatting", since it really is
only an output-formatting option.

I have a problem with the "Query Buffer" section, also: I don't think
\i, \o, etc have anything to do with the query buffer. Could we split
this section into "Query Buffer" (\g \r \e \p \w) and "I/O Redirection"
(\i \o \s), or something like that? Perhaps \copy could go into the
redirection section too, rather than suffering a shotgun wedding with
the large-object commands.

OK, I have created an "I/O Redirection" section and moved \i and \o
into there. I didn't think \s (history) belonged there. I also
couldn't see \copy as I/O redirection. (It is a shotgun wedding,
though.)

I have moved Formatting above the "shotgun wedding."

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

Tom Lane wrote:

Bruce Momjian <pgman@candle.pha.pa.us> writes:

OK, new output attached. Does the HTML section look silly now with only
two entries?

Yeah. I think it should be folded into "Formatting", since it really is
only an output-formatting option.

I have a problem with the "Query Buffer" section, also: I don't think
\i, \o, etc have anything to do with the query buffer. Could we split
this section into "Query Buffer" (\g \r \e \p \w) and "I/O Redirection"
(\i \o \s), or something like that? Perhaps \copy could go into the
redirection section too, rather than suffering a shotgun wedding with
the large-object commands.

Oh, I also folded HTML into Formatting as you suggested.

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

Bruce Momjian writes:

OK, I have created an "I/O Redirection" section and moved \i and \o
into there. I didn't think \s (history) belonged there. I also
couldn't see \copy as I/O redirection. (It is a shotgun wedding,
though.)

How about just "Input/Output" without any redirection?

And also put the things in each group in some sensible order.

And I think that a two-space indent would look better. Possibly because
it is consistent with other help output.

Take a look at psql --help. It has much of this already done.

--
Peter Eisentraut peter_e@gmx.net

Peter Eisentraut wrote:

Bruce Momjian writes:

OK, I have created an "I/O Redirection" section and moved \i and \o
into there. I didn't think \s (history) belonged there. I also
couldn't see \copy as I/O redirection. (It is a shotgun wedding,
though.)

How about just "Input/Output" without any redirection?

Good idea.

And also put the things in each group in some sensible order.

Oh, you like them alphabetical within sections --- done.

And I think that a two-space indent would look better. Possibly because
it is consistent with other help output.

Done.

Take a look at psql --help. It has much of this already done.

New output attached. Change applied.

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073