bug-coreutils
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Pádraig Brady
Subject: bug#51311: [PATCH] echo: update --help to document edge cases
Date: Fri, 22 Oct 2021 15:21:44 +0100
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:84.0) Gecko/20100101 Thunderbird/84.0

On 21/10/2021 21:54, Bernhard Voelker wrote:
On 10/21/21 15:14, Florent Flament wrote:
Pádraig Brady <P@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





reply via email to

[Prev in Thread] Current Thread [Next in Thread]