Thread: Improving psql slash usage help message

Improving psql slash usage help message

From
Hamid Akhtar
Date:
psql slash usage show two options for listing foreign tables.

  \dE[S+] [PATTERN]      list foreign tables
  \det[+] [PATTERN]      list foreign tables

This seems a little odd especially when the output of both of these commands is different.

postgres=# \dE+
           List of relations
 Schema | Name |     Type      | Owner  
--------+------+---------------+--------
 public | foo  | foreign table | highgo
(1 row)

postgres=# \det
  List of foreign tables
 Schema | Table | Server  
--------+-------+---------
 public | foo   | orc_srv
(1 row)


"\dE" displays the list with a "List of relations" heading whereas "\det" displays "List of foreign tables". So, to differentiate the two, I suggest to change the help message for "\dE" to:

  \dE[S+] [PATTERN]      list foreign relations

One could argue that both essentially mean the same thing, however, considering "\dE+" also outputs size, it makes sense IMHO to make this change (as PG documentation: relation is essentially a mathematical term for table). Attached is the patch that makes this change.

Regards.

--
Highgo Software (Canada/China/Pakistan)
URL : www.highgo.ca
ADDR: 10318 WHALLEY BLVD, Surrey, BC
CELL:+923335449950  EMAIL: mailto:hamid.akhtar@highgo.ca
SKYPE: engineeredvirus
Attachment

Re: Improving psql slash usage help message

From
"David G. Johnston"
Date:
On Sat, Apr 25, 2020 at 12:29 PM Hamid Akhtar <hamid.akhtar@gmail.com> wrote:

"\dE" displays the list with a "List of relations" heading whereas "\det" displays "List of foreign tables". So, to differentiate the two, I suggest to change the help message for "\dE" to:

  \dE[S+] [PATTERN]      list foreign relations

One could argue that both essentially mean the same thing, however, considering "\dE+" also outputs size, it makes sense IMHO to make this change (as PG documentation: relation is essentially a mathematical term for table). Attached is the patch that makes this change.

help.c and the documentation need to be synchronized a bit more than this single issue.

Calling it "foreign relation" for \dE and "foreign table" for \det does convey that there is a difference - not sure it a huge improvement though.  The "\d[Eimstv]" family of meta-commands should, in the help, probably be moved together to show the fact that they are basically "list relation names [of this type only]" while "\det" is "list foreign table info".

David J.

Re: Improving psql slash usage help message

From
Hamid Akhtar
Date:


On Sun, Apr 26, 2020 at 1:03 AM David G. Johnston <david.g.johnston@gmail.com> wrote:
On Sat, Apr 25, 2020 at 12:29 PM Hamid Akhtar <hamid.akhtar@gmail.com> wrote:

"\dE" displays the list with a "List of relations" heading whereas "\det" displays "List of foreign tables". So, to differentiate the two, I suggest to change the help message for "\dE" to:

  \dE[S+] [PATTERN]      list foreign relations

One could argue that both essentially mean the same thing, however, considering "\dE+" also outputs size, it makes sense IMHO to make this change (as PG documentation: relation is essentially a mathematical term for table). Attached is the patch that makes this change.

help.c and the documentation need to be synchronized a bit more than this single issue.

Calling it "foreign relation" for \dE and "foreign table" for \det does convey that there is a difference - not sure it a huge improvement though.  The "\d[Eimstv]" family of meta-commands should, in the help, probably be moved together to show the fact that they are basically "list relation names [of this type only]" while "\det" is "list foreign table info".

I think from a user perspective, grouping these wouldn't be helpful. For example, it may cause FDW related commands to be spread through out the help. Currently, those are nicely grouped together, which makes life relatively easy IMO.
 

David J.



--
Highgo Software (Canada/China/Pakistan)
URL : www.highgo.ca
ADDR: 10318 WHALLEY BLVD, Surrey, BC
CELL:+923335449950  EMAIL: mailto:hamid.akhtar@highgo.ca
SKYPE: engineeredvirus

Re: Improving psql slash usage help message

From
ahsan hadi
Date:
The following review has been posted through the commitfest application:
make installcheck-world:  tested, passed
Implements feature:       not tested
Spec compliant:           not tested
Documentation:            tested, passed

This small documentation patch makes the document more accurate for psql terminal help.

The new status of this patch is: Waiting on Author

Re: Improving psql slash usage help message

From
Tom Lane
Date:
Hamid Akhtar <hamid.akhtar@gmail.com> writes:
> On Sun, Apr 26, 2020 at 1:03 AM David G. Johnston <
> david.g.johnston@gmail.com> wrote:
>> On Sat, Apr 25, 2020 at 12:29 PM Hamid Akhtar <hamid.akhtar@gmail.com>
>> wrote:
>>> "\dE" displays the list with a "List of relations" heading whereas "\det"
>>> displays "List of foreign tables". So, to differentiate the two, I suggest
>>> to change the help message for "\dE" to:
>>> \dE[S+] [PATTERN]      list foreign relations

>> help.c and the documentation need to be synchronized a bit more than this
>> single issue.
>> Calling it "foreign relation" for \dE and "foreign table" for \det does
>> convey that there is a difference - not sure it a huge improvement though.
>> The "\d[Eimstv]" family of meta-commands should, in the help, probably be
>> moved together to show the fact that they are basically "list relation
>> names [of this type only]" while "\det" is "list foreign table info".

FWIW, I agree with David on this point.  I find it bizarre and unhelpful
that slashUsage shows \dt, \di, etc as separate commands and fails to
indicate that they can be combined.  We could merge these entries into

    fprintf(output, _("  \\d[tivmsE][S+] [PATRN] list relations of specified type(s)\n"));

which would both remind people that they can give more than one type,
and shorten the already-overly-long list.

> I think from a user perspective, grouping these wouldn't be helpful. For
> example, it may cause FDW related commands to be spread through out the
> help.

That seems quite irrelevant to this proposal.

            regards, tom lane



Re: Improving psql slash usage help message

From
Hamid Akhtar
Date:
So are you suggesting to not fix this or do a more detailed review and assess what other psql messages can be grouped together.

On Sun, Jul 12, 2020 at 8:15 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
Hamid Akhtar <hamid.akhtar@gmail.com> writes:
> On Sun, Apr 26, 2020 at 1:03 AM David G. Johnston <
> david.g.johnston@gmail.com> wrote:
>> On Sat, Apr 25, 2020 at 12:29 PM Hamid Akhtar <hamid.akhtar@gmail.com>
>> wrote:
>>> "\dE" displays the list with a "List of relations" heading whereas "\det"
>>> displays "List of foreign tables". So, to differentiate the two, I suggest
>>> to change the help message for "\dE" to:
>>> \dE[S+] [PATTERN]      list foreign relations

>> help.c and the documentation need to be synchronized a bit more than this
>> single issue.
>> Calling it "foreign relation" for \dE and "foreign table" for \det does
>> convey that there is a difference - not sure it a huge improvement though.
>> The "\d[Eimstv]" family of meta-commands should, in the help, probably be
>> moved together to show the fact that they are basically "list relation
>> names [of this type only]" while "\det" is "list foreign table info".

FWIW, I agree with David on this point.  I find it bizarre and unhelpful
that slashUsage shows \dt, \di, etc as separate commands and fails to
indicate that they can be combined.  We could merge these entries into

        fprintf(output, _("  \\d[tivmsE][S+] [PATRN] list relations of specified type(s)\n"));

which would both remind people that they can give more than one type,
and shorten the already-overly-long list.

> I think from a user perspective, grouping these wouldn't be helpful. For
> example, it may cause FDW related commands to be spread through out the
> help.

That seems quite irrelevant to this proposal.

                        regards, tom lane


--
Highgo Software (Canada/China/Pakistan)
URL : www.highgo.ca
ADDR: 10318 WHALLEY BLVD, Surrey, BC
CELL:+923335449950  EMAIL: mailto:hamid.akhtar@highgo.ca
SKYPE: engineeredvirus

Re: Improving psql slash usage help message

From
Tom Lane
Date:
Hamid Akhtar <hamid.akhtar@gmail.com> writes:
> So are you suggesting to not fix this or do a more detailed review and
> assess what other psql messages can be grouped together.

I was just imagining merging the entries for the commands that are
implemented by listTables().  If you see something else that would
be worth doing, feel free to suggest it, but that wasn't what I was
thinking of.

            regards, tom lane



Re: Improving psql slash usage help message

From
Peter Eisentraut
Date:
On 2020-07-21 17:10, Tom Lane wrote:
> Hamid Akhtar <hamid.akhtar@gmail.com> writes:
>> So are you suggesting to not fix this or do a more detailed review and
>> assess what other psql messages can be grouped together.
> 
> I was just imagining merging the entries for the commands that are
> implemented by listTables().  If you see something else that would
> be worth doing, feel free to suggest it, but that wasn't what I was
> thinking of.

It used to be like that, but it was changed here: 
9491c82f7103d62824d3132b8c7dc44609f2f56b

I'm not sure which way is better.  Right now, a question like "how do I 
list all indexes" is easily answered by the help output.  Under the 
other scheme, it's hidden behind a layer of metasyntax.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services



Re: Improving psql slash usage help message

From
Anastasia Lubennikova
Date:
Status update for a commitfest entry.
This thread was inactive for a while. Is anyone going to continue working on it?

My two cents on the topic: 
I don’t see it as a big problem in the first place. In the source code, \dE refers to foreign tables and \de refers to
forignservers. So, it seems more reasonable to me, to rename the latter.
 
  \dE[S+] [PATTERN]      list foreign tables
  \det[+] [PATTERN]      list foreign servers

I also do not support merging the entries for different commands. I think that current help output is easier to read.

The new status of this patch is: Waiting on Author

Re: Improving psql slash usage help message

From
Anastasia Lubennikova
Date:
On 02.11.2020 18:02, Anastasia Lubennikova wrote:
> Status update for a commitfest entry.
> This thread was inactive for a while. Is anyone going to continue working on it?
>
> My two cents on the topic:
> I don’t see it as a big problem in the first place. In the source code, \dE refers to foreign tables and \de refers
toforign servers. So, it seems more reasonable to me, to rename the latter.
 
>    \dE[S+] [PATTERN]      list foreign tables
>    \det[+] [PATTERN]      list foreign servers
>
> I also do not support merging the entries for different commands. I think that current help output is easier to
read.
>
> The new status of this patch is: Waiting on Author


Status update for a commitfest entry.

This entry was inactive during this CF, so I've marked it as returned 
with feedback. Feel free to resubmit an updated version to a future 
commitfest.

-- 
Anastasia Lubennikova
Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company