psql and output from \?

Ian Barwick writes:

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.

Nicely observed. Please send in a patch. Accurate documentation is
important.

psql \? new:
\C [ TITLE ] set table title (or unset with no arguments)

I don't think we use spaces between the brackets and the text anywhere
else in console-formatted output, so we might not want to start here.

Also, the part in the parentheses is ambiguous. Maybe "(without
arguments: unset)".

psql \? new:
\d [ RELATION ] describe relation (table, view, index or sequence)

Comma before "or".

psql \? new:
\e [ FILENAME ] edit the current query buffer or file with external editor

Maybe drop the "current". (This was not introduced by you, but you might
as well do it.)

Something that's also annoyed me for a while is that the PLACEHOLDER
strings are inconsistent in whether they describe the data type or the
semantics of the argument. I think the data type is ultimately more
useful, as the semantics come from the documentation string by definition.

So instead of \C TITLE maybe better \C STRING, and instead of \d TABLE use
\d IDENTIFIER (or maybe NAME). The latter has two advantages: First
you're not passing \d a table descriptor, if there was such a thing. And
second, it informs the user that the SQL identifier quoting rules will
apply to the argument. I guess FILENAME and DIRNAME are ok as "data
types", but all the other stuff can go, I think.

--
Peter Eisentraut peter_e@gmx.net

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

Peter Eisentraut wrote:

Ian Barwick writes:

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.

Nicely observed. Please send in a patch. Accurate documentation is
important.

Done.

Also, the part in the parentheses is ambiguous. Maybe "(without
arguments: unset)".

I made it consistent with others, no parens.

fprintf(fout, _(" \\f [SEPARATOR] set field separator, or unset if none\n")

psql \? new:
\d [ RELATION ] describe relation (table, view, index or sequence)

Comma before "or".

Already done.

psql \? new:
\e [ FILENAME ] edit the current query buffer or file with external editor

Maybe drop the "current". (This was not introduced by you, but you might
as well do it.)

I removed current in all \? cases when describing query buffer.

Something that's also annoyed me for a while is that the PLACEHOLDER
strings are inconsistent in whether they describe the data type or the
semantics of the argument. I think the data type is ultimately more
useful, as the semantics come from the documentation string by definition.

So instead of \C TITLE maybe better \C STRING, and instead of \d TABLE use
\d IDENTIFIER (or maybe NAME). The latter has two advantages: First
you're not passing \d a table descriptor, if there was such a thing. And
second, it informs the user that the SQL identifier quoting rules will
apply to the argument. I guess FILENAME and DIRNAME are ok as "data
types", but all the other stuff can go, I think.

I can understand a more formal indicator in the documentation, but for
\? it is really just quick help, and showing SEPARATOR rather than the more
generic STRING is clearer, I think.

-- 
  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

On Monday 11 March 2002 19:21, Bruce Momjian wrote:

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

I hang my head in shame and plead an unfortunate period
of downtime due to an unplanned affliction with work :-(

"Unfortunately" after submitting my suggestions I took a look at
the source code (should have done it the other way round)
and found a few more (minor) discrepancies between what
\? says and what the various slash commands do.

This mainly affects the various \d commands, many (but not
all) of which take a regular expression ("pattern") as an optional
argument. Particularly the following \? output:

...
\d{t|i|s|v}... list tables/indexes/sequences/views
\d{p|S|l} list access privileges, system tables, or large objects
...

is misleading, because \dp and \dl can only be used on their own,
whereas any combination of i, s, t, v and / or S can be used together:
\dtvS is valid, whereas \dpSl is not. Also, \d{t|i|s|v|S} and \dp accept
a regular expression as an argument, \dl does not.

So with no further ado I humbly submit the attached patch, which builds on
your patch and tidies up / harmonises the \? output.

(If the patch itself is problematic, please let me know why and how I can
fix it, it's the first patch I've submitted for PostgreSQL).

Yours

Ian Barwick

On Monday 11 March 2002 19:26, Bruce Momjian wrote:

Peter Eisentraut wrote:

Something that's also annoyed me for a while is that the PLACEHOLDER
strings are inconsistent in whether they describe the data type or the
semantics of the argument. I think the data type is ultimately more
useful, as the semantics come from the documentation string by
definition.

So instead of \C TITLE maybe better \C STRING, and instead of \d TABLE
use \d IDENTIFIER (or maybe NAME). The latter has two advantages: First
you're not passing \d a table descriptor, if there was such a thing. And
second, it informs the user that the SQL identifier quoting rules will
apply to the argument. I guess FILENAME and DIRNAME are ok as "data
types", but all the other stuff can go, I think.

I can understand a more formal indicator in the documentation, but for
\? it is really just quick help, and showing SEPARATOR rather than the more
generic STRING is clearer, I think.

My first reaction would be "now what counts as a separator?", because it
sounds like some kind of special character, whereas with STRING it's
clear to me I can use any set of characters I like.

This is not an issue I would lose sleep over however.

Ian Barwick

My first reaction would be "now what counts as a separator?", because it
sounds like some kind of special character, whereas with STRING it's
clear to me I can use any set of characters I like.

This is not an issue I would lose sleep over however.

OK, we will use your patch version. I like "PATTERN".

-- 
  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

Ian Barwick writes:

So with no further ado I humbly submit the attached patch, which builds on
your patch and tidies up / harmonises the \? output.

That looks a lot better. A few things, though:

The change to \a seems to be wrong-headed.

The line for \du speaks of "configured" users. There are no
"unconfigured" users.

\set should be \set [NAME [VALUE]], or strictly speaking even \set [NAME
[VALUE [...]]].

Some lines seem to be in excess of 80 characters.

I guess some of these weren't introduces by you, but if someone is going
to fix this, he might as well take care of these.

--
Peter Eisentraut peter_e@gmx.net

On Tuesday 12 March 2002 00:34, Peter Eisentraut wrote:

Ian Barwick writes:

So with no further ado I humbly submit the attached patch, which builds
on your patch and tidies up / harmonises the \? output.

That looks a lot better. A few things, though:

The change to \a seems to be wrong-headed.

What do you mean by "wrong-headed"?
That it should read "toggle aligned output mode" ?
(Would be more logical).

The line for \du speaks of "configured" users. There are no
"unconfigured" users.

That line was from the patch by Rod Taylor (March 1, 2002). Didn't think
to change it. Does "list users" do the job? BTW psql-ref.sgml also
says "Lists all configured users (...)"

\set should be \set [NAME [VALUE]], or strictly speaking even \set [NAME
[VALUE [...]]].

True. I actually started out with:

\set [NAME [STRING]] set internal variable (no name: list all; no string: '')

which is (almost) accurate but verbose.

Some lines seem to be in excess of 80 characters.

Longest line is 74 columns (or 77 with the \set line above).

I guess some of these weren't introduces by you, but if someone is going
to fix this, he might as well take care of these.

Will submit another patch in the morning (it's late here).

Ian Barwick

Ian Barwick writes:

The change to \a seems to be wrong-headed.

What do you mean by "wrong-headed"?

It's fine as it is and the change makes it less fine.

The line for \du speaks of "configured" users. There are no
"unconfigured" users.

That line was from the patch by Rod Taylor (March 1, 2002). Didn't think
to change it. Does "list users" do the job? BTW psql-ref.sgml also
says "Lists all configured users (...)"

That is equally incorrect then. "list users" is fine.

--
Peter Eisentraut peter_e@gmx.net

The line for \du speaks of "configured" users. There are no
"unconfigured" users.

That line was from the patch by Rod Taylor (March 1, 2002). Didn't

think

to change it. Does "list users" do the job? BTW psql-ref.sgml also
says "Lists all configured users (...)"

Thats exactly where I took the line from.

On Tuesday 12 March 2002 01:25, Rod Taylor wrote:

(I wrote)

That line was from the patch by Rod Taylor (March 1, 2002). Didn't

think

to change it. Does "list users" do the job? BTW psql-ref.sgml also
says "Lists all configured users (...)"

Thats exactly where I took the line from.

Aha. My apologies, should have been an obvious conclusion.

Ian Barwick

I guess some of these weren't introduces by you, but if someone is going
to fix this, he might as well take care of these.

Will submit another patch in the morning (it's late here).

Ian, do you have another version of this patch ready?

-- 
  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

On Thursday 14 March 2002 22:40, Bruce Momjian wrote:

I guess some of these weren't introduces by you, but if someone is
going to fix this, he might as well take care of these.

Will submit another patch in the morning (it's late here).

Ian, do you have another version of this patch ready?

Patch attached (diff against CVS, replacing previous patch).

Ian Barwick

Your patch has been added to the PostgreSQL unapplied patches list at:

http://candle.pha.pa.us/cgi-bin/pgpatches

I will try to apply it within the next 48 hours.

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

Ian Barwick wrote:

On Thursday 14 March 2002 22:40, Bruce Momjian wrote:

I guess some of these weren't introduces by you, but if someone is
going to fix this, he might as well take care of these.

Will submit another patch in the morning (it's late here).

Ian, do you have another version of this patch ready?

Patch attached (diff against CVS, replacing previous patch).

Ian Barwick

[ Attachment, skipping... ]

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

http://archives.postgresql.org

-- 
  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

Patch applied. Thanks.

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

Ian Barwick wrote:

On Thursday 14 March 2002 22:40, Bruce Momjian wrote:

I guess some of these weren't introduces by you, but if someone is
going to fix this, he might as well take care of these.

Will submit another patch in the morning (it's late here).

Ian, do you have another version of this patch ready?

Patch attached (diff against CVS, replacing previous patch).

Ian Barwick

[ Attachment, skipping... ]

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

http://archives.postgresql.org

-- 
  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