Subject: Re: bug#51311: [PATCH] echo: update --help to document edge cases

From: Pádraig Brady <[email-masked]>
Date: Fri, 22 Oct 2021 15:21:44 +0100

On 21/10/2021 21:54, Bernhard Voelker wrote:
> On 10/21/21 15:14, Florent Flament wrote:
>> Pádraig Brady <[email-masked]> writes:
>>> +NOTE: printf(1) is a preferred alternative, with more standard option handling.\
> 
>> I believe that it misses the point. It is still not clear that the echo
>> command doesn't behave as one would expect for a few edge cases.
>>
>> Maybe something like this would be closer to what I'm trying to express:
>>
>> NOTE: printf(1) is a preferred alternative, which doesn't share echo's
>> inability to handle edge cases.
> 
> I'm not sure that just mentioning "edge cases" will remind people either
> that they are falling into such particular edge case.
> 
> Therefore, I'd prefer Padraig's shorter sentence: it expresses the matter
> positively while the latter proposal tries to explain via negative wording.
> 
> If we want to be more explicit, then we'd have to name examples where
> printf(1) is superior to echo(1) - or the shell's echo builtin.
> But IMO the whole point is two-fold: if someone doesn't have enough experience
> to understand the edge cases, then eventually the usage of printf with the
> often complex format specifiers is also too much.
> Finally, I think Padraig's suggestion had the best tradeoff between pointing
> out the matter and getting too much into details.

Thanks for all the input.
I've now pushed the following to address this:

https://git.sv.gnu.org/gitweb/?p=coreutils.git;a=commitdiff;h=f60a3981c

Notes:
  - Brevity in --help and man pages is a feature
  - I kept the existing NOTE: style in --help to avoid a separate [NOTES] in man
  - I only detailed the edge cases in the info manual,
      as directing users to printf(1) is the better most general option
  - It's easy to get to online info pages now by following the link
      at the bottom of all man pages

cheers,
Pádraig