Better title output for psql \dt \di etc. commands

Please find attached a patch to enable more intuitive titles when using
psql and doing the following actions:

\dt \di \dv \dm \ds \dE

In other words, everything in listTables()

We still default to "List or relations", but if we know that the user has
requested exactly one specific type of relation, we use that instead. So
instead of

greg=# \dv
List of relations
Schema | Name | Type | Owner
--------+-------------------------+------+-------
public | pg_stat_statements | view | greg
public | pg_stat_statements_info | view | greg

we get:

greg=# \dv
List of views
Schema | Name | Type | Owner
--------+-------------------------+------+-------
public | pg_stat_statements | view | greg
public | pg_stat_statements_info | view | greg
(2 rows)

The same applies for "misses" as well:

greg=# \di
Did not find any indexes.

greg=# \di foo*
Did not find any indexes named "foo*".

I thought about keeping that last one as singular, as it is replacing "Did
not find any relation named", but not only does it make more sense as a
plural given that wildcards can produce multiple relations, it makes the
code cleaner. :)

Inspired by a recent thread[0] over in pgsql-bugs entitled "Bug in psql".
(while not a bug, it is certainly a welcome enhancement, IMHO).

Cheers,
Greg

[0]
https://www.postgresql.org/message-id/CADrHaBEVSYwemoJWtry2%2B82KHy9tZirH2PVfi-uD96R5J8FCsw%40mail.gmail.com

Greg Sabino Mullane <htamfids(at)gmail(dot)com> writes:
> Please find attached a patch to enable more intuitive titles when using
> psql and doing the following actions:
> \dt \di \dv \dm \ds \dE
> In other words, everything in listTables()
> We still default to "List or relations", but if we know that the user has
> requested exactly one specific type of relation, we use that
> instead.

As presented, I think this fails the translatability guideline about
"Do not construct sentences at run-time" [1]. You could get around
that by selecting one of several whole title strings, though.

For myself, if we were going to do something like this, I'd kind
of like to cover more cases:

greg=# \dti
List of tables and indexes

But I'm really not sure how to maintain translatability without
a combinatorial explosion. It's fairly easy to see how we might
produce output like

greg=# \dtvi
List of tables, views, indexes

but "List of", "tables", "views", and "indexes" would all have
to be separately translated, and I fear that might not hang
together well.

regards, tom lane

[1] https://www.postgresql.org/docs/devel/nls-programmer.html#NLS-GUIDELINES

On Mon, Feb 3, 2025 at 1:07 PM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> As presented, I think this fails the translatability guideline

Thanks, good point. Please find attached a slightly more verbose version
that should be better for translations.

For myself, if we were going to do something like this, I'd kind of like to
> cover more cases:
>
> greg=# \dti
> List of tables and indexes
>

I toyed with that for a bit, but as you say, without generating a ton of
combinations to translate, we'd have to fall back on run-time
constructions. Neither is ideal. I also realized that I almost never type
"\dti". Very common for me are \d and \dt and \dv etc. but combinations are
something I never bother with. At that point, I just do a \d. I think given
how rare (granted, anecdotally) those combinations are, it's okay if we
expose people to the "r" word.

Cheers,
Greg

--
Crunchy Data - https://www.crunchydata.com
Enterprise Postgres Software Products & Tech Support

Greg Sabino Mullane <htamfids(at)gmail(dot)com> writes:
> I toyed with that for a bit, but as you say, without generating a ton of
> combinations to translate, we'd have to fall back on run-time
> constructions. Neither is ideal. I also realized that I almost never type
> "\dti". Very common for me are \d and \dt and \dv etc. but combinations are
> something I never bother with. At that point, I just do a \d. I think given
> how rare (granted, anecdotally) those combinations are, it's okay if we
> expose people to the "r" word.

Fair. This is already a step forward, so it doesn't have to be
perfect.

Looking at the code, I'm not thrilled with the strspn() coding
method. I'd much rather it relied on the bool flags we already
computed (showTables etc). I'm wondering about adding a step like

int ntypes = (int) showTables + (int) showIndexes + ...

(the explicit coercions to int probably aren't necessary)
and then the code could look like

(ntypes != 1) ? _("List of relations") :
(showTables) ? _("List of tables") :
(showIndexes) ? _("List of indexes") :
...

"ntypes" could also be used to simplify the logic that forces
all the flags on, up at the top of the function.

regards, tom lane

On Mon, Feb 03, 2025 at 03:12:57PM -0500, Tom Lane wrote:
> Greg Sabino Mullane <htamfids(at)gmail(dot)com> writes:
>> I toyed with that for a bit, but as you say, without generating a ton of
>> combinations to translate, we'd have to fall back on run-time
>> constructions. Neither is ideal. I also realized that I almost never type
>> "\dti". Very common for me are \d and \dt and \dv etc. but combinations are
>> something I never bother with. At that point, I just do a \d. I think given
>> how rare (granted, anecdotally) those combinations are, it's okay if we
>> expose people to the "r" word.
>
> Fair. This is already a step forward, so it doesn't have to be
> perfect.

+1. I don't use combinations like \dti regularly, either.

--
nathan

I like the ntypes idea: please find attached version 3 which implements it.
I wrote it slightly differently as I did not want to leave any chance of it
escaping the if else blocks without a match.

Cheers,
Greg

--
Crunchy Data - https://www.crunchydata.com
Enterprise Postgres Software Products & Tech Support

Greg Sabino Mullane <htamfids(at)gmail(dot)com> writes:
> I like the ntypes idea: please find attached version 3 which implements it.
> I wrote it slightly differently as I did not want to leave any chance of it
> escaping the if else blocks without a match.

Hmm, I was envisioning being a little more in-your-face about the
no-match case, because that would surely represent somebody failing
to update the code correctly when adding a new relation kind.
So I was imagining something like the attached.

One problem with it is that while we can leave "List of ???" out
of the set of translatable strings easily, we can't currently
do that for the argument of pg_log_error because it's automatically
a gettext trigger. I'd rather not burden translators with figuring
out what to do with that. Is it worth creating pg_log_error_internal,
equivalently to elog and errmsg_internal in the backend?

BTW, I updated the regression tests for this, and that bears out
your argument that one-type commands are the majority. There
are still a couple "List of relations", but not many.

regards, tom lane

On Mon, Feb 3, 2025 at 5:38 PM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> One problem with it is that while we can leave "List of ???" out of the
> set of translatable strings easily, we can't currently do that for the
> argument of pg_log_error because it's automatically a gettext trigger. I'd
> rather not burden translators with figuring out what to do with that. Is
> it worth creating pg_log_error_internal, equivalently to elog and
> errmsg_internal in the backend?
>

I don't think so, unless there are other uses of it waiting. For this
particular item, I'm still of the opinion that leaving it as "List of
relations" is a pretty good default for some future somebody who forgets to
update the lists of relation types. New types are certainly not going to
happen often. Better "List of relations" than a release where everybody and
their cousin starts asking what "List of ???" means.

BTW, I updated the regression tests for this, and that bears out your
> argument that one-type commands are the majority. There are still a couple
> "List of relations", but not many.
>

Thank you for that, I should have done that in my original patch.

Cheers,
Greg

P.S. I found it amusing to see in some quick grepping that pg_controldata
has a msgstr of "???". So far no language has managed to translate it into
something else.

--
Crunchy Data - https://www.crunchydata.com
Enterprise Postgres Software Products & Tech Support

Greg Sabino Mullane <htamfids(at)gmail(dot)com> writes:
> ... For this
> particular item, I'm still of the opinion that leaving it as "List of
> relations" is a pretty good default for some future somebody who forgets to
> update the lists of relation types. New types are certainly not going to
> happen often. Better "List of relations" than a release where everybody and
> their cousin starts asking what "List of ???" means.

Hopefully an oversight like that wouldn't make it to release. But
hiding it by putting out an ordinary-looking title might help it
avoid detection for a long time.

> P.S. I found it amusing to see in some quick grepping that pg_controldata
> has a msgstr of "???". So far no language has managed to translate it into
> something else.

There are several pre-existing "???" strings in describe.c too,
for similar this-shouldn't-happen cases. I'm not proposing
something that's far outside our existing practice.

regards, tom lane

On 2025-Feb-03, Tom Lane wrote:

> One problem with it is that while we can leave "List of ???" out
> of the set of translatable strings easily, we can't currently
> do that for the argument of pg_log_error because it's automatically
> a gettext trigger. I'd rather not burden translators with figuring
> out what to do with that. Is it worth creating pg_log_error_internal,
> equivalently to elog and errmsg_internal in the backend?

At this point I would just add a "translator:" comment that explains
that the ??? bit is for unexpected cases and can be translated in the
same way.

--
Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/
"The problem with the future is that it keeps turning into the present"
(Hobbes)

=?utf-8?Q?=C3=81lvaro?= Herrera <alvherre(at)alvh(dot)no-ip(dot)org> writes:
> At this point I would just add a "translator:" comment that explains
> that the ??? bit is for unexpected cases and can be translated in the
> same way.

Hmm, do we have a standard policy or comment wording about that?
I looked for "translator: ... unexpected" and didn't find any
existing comments of that sort.

regards, tom lane

On 2025-Feb-04, Tom Lane wrote:

> =?utf-8?Q?=C3=81lvaro?= Herrera <alvherre(at)alvh(dot)no-ip(dot)org> writes:
> > At this point I would just add a "translator:" comment that explains
> > that the ??? bit is for unexpected cases and can be translated in the
> > same way.
>
> Hmm, do we have a standard policy or comment wording about that?
> I looked for "translator: ... unexpected" and didn't find any
> existing comments of that sort.

I don't remember cases of messages of that kind marked for translation,
so I'm not surprised that we don't have any such comments. Those would
typically be elog() or the errfoo_internal() cases, I think.

--
Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/
"El sudor es la mejor cura para un pensamiento enfermo" (Bardia)

=?utf-8?Q?=C3=81lvaro?= Herrera <alvherre(at)alvh(dot)no-ip(dot)org> writes:
> On 2025-Feb-04, Tom Lane wrote:
>> =?utf-8?Q?=C3=81lvaro?= Herrera <alvherre(at)alvh(dot)no-ip(dot)org> writes:
>>> At this point I would just add a "translator:" comment that explains
>>> that the ??? bit is for unexpected cases and can be translated in the
>>> same way.

>> Hmm, do we have a standard policy or comment wording about that?
>> I looked for "translator: ... unexpected" and didn't find any
>> existing comments of that sort.

> I don't remember cases of messages of that kind marked for translation,
> so I'm not surprised that we don't have any such comments. Those would
> typically be elog() or the errfoo_internal() cases, I think.

Yeah, that's what I would have thought.

The implementation I had in mind was to just invent a
pg_log_error_internal() macro alias for pg_log_error().
That'd take about two lines counting the explanatory comment.
This approach would fail to suppress the cost of gettext's
trying to look up the string, but surely we aren't concerned
about that here --- we just want to not burden translators
with the string. (I need to check that gettext isn't smart
enough to see through a macro, though. If it is, a static
inline function should do.)

regards, tom lane

On 2025-Feb-04, Tom Lane wrote:

> The implementation I had in mind was to just invent a
> pg_log_error_internal() macro alias for pg_log_error().
> That'd take about two lines counting the explanatory comment.
> This approach would fail to suppress the cost of gettext's
> trying to look up the string, but surely we aren't concerned
> about that here --- we just want to not burden translators
> with the string.

Yeah, okay, that seems good enough for me. I agree that the cost of an
unnecessary gettext() call is negligible.

--
Álvaro Herrera Breisgau, Deutschland — https://www.EnterpriseDB.com/

=?utf-8?Q?=C3=81lvaro?= Herrera <alvherre(at)alvh(dot)no-ip(dot)org> writes:
> On 2025-Feb-04, Tom Lane wrote:
>> The implementation I had in mind was to just invent a
>> pg_log_error_internal() macro alias for pg_log_error().
>> That'd take about two lines counting the explanatory comment.
>> This approach would fail to suppress the cost of gettext's
>> trying to look up the string, but surely we aren't concerned
>> about that here --- we just want to not burden translators
>> with the string.

> Yeah, okay, that seems good enough for me. I agree that the cost of an
> unnecessary gettext() call is negligible.

Sounds good, I'll proceed along those lines.

regards, tom lane