> On Mar 6, 2021, at 5:55 AM, Paul Förster <paul.foers...@gmail.com> wrote:
>
> Hi Mark,
>
> sorry for the delay.
>
>> On 01. Mar, 2021, at 17:02, Mark Dilger <mark.dil...@enterprisedb.com> wrote:
>>
>> 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:
>
> I see.
>
>> You can find counter-examples where applications do not follow this rule.
>> pg_isready is one of them.
>
> yes, I noticed that.
>
>> 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.
>
> I could do the other tools too, that wouldn't be a problem. But I'm not good
> at writing docs. And I found that the man pages would have to be adapted too,
> which would be a big one for me as I'm no man guru.
Fortunately, the man pages and html docs are generated from the same sources.
Those sources are written in sgml, and the tools to build the docs must be
installed. From the top directory, execute `make docs` and if it complains
about missing tools you will need to install them. (The build target is
'docs', but the directory containing the docs is named 'doc'.)
>> 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've searched the archives for quite some time and found tons of hits for the
> search term "help". But that's useless because all people ask for "help". :-)
> Beside that, I found nothing which even remotely discussed the topic.
>
> But I generally see your points so I drop the proposal. It was only an idea
> after all :-) Thanks for your input.
Oh, I'm quite sorry to hear that. The process of getting a patch accepted,
especially the first time you submit one, can be discouraging. But the
community greatly benefits from new contributors joining the effort, so I'd
much rather you not withdraw the idea.
If you need help with certain portions of the submission, such as editing the
docs, I can help with that.
—
Mark Dilger
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company
