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.
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
Attachments:
psql_help_dE.patchapplication/octet-stream; name=psql_help_dE.patchDownload
diff --git a/src/bin/psql/help.c b/src/bin/psql/help.c
index e750948..332c1ba 100644
--- a/src/bin/psql/help.c
+++ b/src/bin/psql/help.c
@@ -238,7 +238,7 @@ slashUsage(unsigned short int pager)
fprintf(output, _(" \\dd[S] [PATTERN] show object descriptions not displayed elsewhere\n"));
fprintf(output, _(" \\dD[S+] [PATTERN] list domains\n"));
fprintf(output, _(" \\ddp [PATTERN] list default privileges\n"));
- fprintf(output, _(" \\dE[S+] [PATTERN] list foreign tables\n"));
+ fprintf(output, _(" \\dE[S+] [PATTERN] list foreign relations\n"));
fprintf(output, _(" \\det[+] [PATTERN] list foreign tables\n"));
fprintf(output, _(" \\des[+] [PATTERN] list foreign servers\n"));
fprintf(output, _(" \\deu[+] [PATTERN] list user mappings\n"));
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
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 relationshelp.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 improvementthough.
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 intofprintf(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
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 forign 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
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 to forign servers. So, it seems more reasonable to me, to rename the latter.
\dE[S+] [PATTERN] list foreign tables
\det[+] [PATTERN] list foreign serversI 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