Обсуждение: Improving psql slash usage help message

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

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