GNU bug report logs - #51311
[PATCH] echo: update --help to document edge cases

Previous Next

Full log

Message #22 received at 51311 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Bernhard Voelker <mail <at> bernhard-voelker.de>,
 Florent Flament <contact <at> florentflament.com>
Cc: 51311 <at> debbugs.gnu.org
Subject: Re: bug#51311: [PATCH] echo: update --help to document edge cases
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 <P <at> draigBrady.com> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.