Thread: Improving psql slash usage help message
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.
\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
URL : www.highgo.ca
ADDR: 10318 WHALLEY BLVD, Surrey, BC
CELL：+923335449950 EMAIL: mailto:hamid.akhtar@highgo.ca
SKYPE: engineeredvirus
Attachment
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.
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
URL : www.highgo.ca
ADDR: 10318 WHALLEY BLVD, Surrey, BC
CELL：+923335449950 EMAIL: mailto:hamid.akhtar@highgo.ca
SKYPE: engineeredvirus
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
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
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
URL : www.highgo.ca
ADDR: 10318 WHALLEY BLVD, Surrey, BC
CELL：+923335449950 EMAIL: mailto:hamid.akhtar@highgo.ca
SKYPE: engineeredvirus
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
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
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
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