Re: proposal: psql –help reflecting service or URI usage

> On Feb 28, 2021, at 10:10 AM, Paul Förster <paul(dot)foerster(at)gmail(dot)com> wrote:
>
> Hi Mark,
>
>> On 28. Feb, 2021, at 17:54, Mark Dilger <mark(dot)dilger(at)enterprisedb(dot)com> wrote:
>>
>> "definited" is a typo.
>
> yes, definitely a typo, sorry. Thanks for pointing this out.
>
>> Should this say "as defined in pg_service.conf"? That's the default, but the user might have $PGSERVICEFILE set to something else. Perhaps you could borrow the wording of other options and use "(default: as defined in pg_service.conf)", or something like that, but of course being careful to still fit in the line length limit.
>
> I agree to all, thanks. What is the line length limit?

The output from --help should fit in a terminal window with only 80 characters width. For example, in src/bin/scripts/createuser.c the line about --interactive is wrapped:

> printf(_(" -S, --no-superuser role will not be superuser (default)\n"));
> printf(_(" -V, --version output version information, then exit\n"));
> printf(_(" --interactive prompt for missing role name and attributes rather\n"
> " than using defaults\n"));
> printf(_(" --replication role can initiate replication\n"));

You can find counter-examples where applications do not follow this rule. pg_isready is one of them.

>> Other client applications follow the same pattern as psql, so if this change were adopted, it should apply to all of them.
>
> well, psql is central and IMHO the best place to start. I'd have to try out all of them then. What I do know, though, is that pg_isready does not understand a URI (why is that?), which is very unfortunate. So, I'd have to try them all out and supply patches for them all?

There is a pattern in the client applications that the --help output is less verbose than the docs (see, for example, https://www.postgresql.org/docs/13/reference-client.html). Your proposed patch makes psql's --help output a bit more verbose about this issue while leaving the other applications less so, without any obvious reason for the difference.

> Still, supporting a feature and not documenting it in its help is IMHO not a good idea.

Ok.

>> Your proposal seems like something that would have been posted to the list before, possibly multiple times. Any chance you could dig up past conversations on this subject and post links here for context?
>
> I don't know any past discussions here. I only subscribed today to psql-hackers. It might have been mentioned on psql-general, though. But I'm not sure. This idea popped into my mind just yesterday when I was playing around with psql and URIs and noticed that psql –help doesn't show them.

I mentioned looking at the mailing list archives, but neglected to give you a link: https://www.postgresql.org/list/

Over the years, many proposals get made and debated, with some accepted and some rejected. The rejected proposals often have some merit, and get suggested again, only to get rejected for the same reasons as the previous times they were suggested. So searching the archives before posting a patch can sometimes be enlightening. The difficulty in my experience is knowing what words and phrases to search for. It can be a bit time consuming trying to find a prior discussion on a topic.

I don't know of any specific discussion which rejected your patch idea.

—
Mark Dilger
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company