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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 51311 in the body.
You can then email your comments to 51311 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: Florent Flament <contact <at> florentflament.com>
To: bug-coreutils <at> gnu.org
Cc: bob <at> proulx.com
Subject: [PATCH] echo: update --help to document edge cases
Date: Wed, 20 Oct 2021 23:50:47 +0200

* src/echo.c (usage): Document edge cases when displaying arbitrary
strings with the echo command.
---
 src/echo.c | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/echo.c b/src/echo.c
index 18513398a..73b44660b 100644
--- a/src/echo.c
+++ b/src/echo.c
@@ -78,6 +78,14 @@ If -e is in effect, the following sequences are recognized:\n\
   fputs (_("\
   \\0NNN   byte with octal value NNN (1 to 3 digits)\n\
   \\xHH    byte with hexadecimal value HH (1 to 2 digits)\n\
+"), stdout);
+  fputs (_("\
+\n\
+NOTE: The echo command doesn't behave gracefully when displaying\n\
+arbitrary strings. For example, it can't display the string \"-n\" and\n\
+requires the STRICTLY_POSIX flag to display \"-e\" or \"-E\". Therefore,\n\
+if you need to display arbitrary strings please use the printf command\n\
+instead.\n\
 "), stdout);
   printf (USAGE_BUILTIN_WARNING, PROGRAM_NAME);
   emit_ancillary_info (PROGRAM_NAME);
-- 
2.25.1

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

From: Pádraig Brady <P <at> draigBrady.com>
To: Florent Flament <contact <at> florentflament.com>, 51311-done <at> debbugs.gnu.org
Cc: bob <at> proulx.com
Subject: Re: bug#51311: [PATCH] echo: update --help to document edge cases
Date: Thu, 21 Oct 2021 13:11:25 +0100

[Message part 1 (text/plain, inline)]

On 20/10/2021 22:50, Florent Flament wrote:
> 
> * src/echo.c (usage): Document edge cases when displaying arbitrary
> strings with the echo command.
> ---
>   src/echo.c | 8 ++++++++
>   1 file changed, 8 insertions(+)
> 
> diff --git a/src/echo.c b/src/echo.c
> index 18513398a..73b44660b 100644
> --- a/src/echo.c
> +++ b/src/echo.c
> @@ -78,6 +78,14 @@ If -e is in effect, the following sequences are recognized:\n\
>     fputs (_("\
>     \\0NNN   byte with octal value NNN (1 to 3 digits)\n\
>     \\xHH    byte with hexadecimal value HH (1 to 2 digits)\n\
> +"), stdout);
> +  fputs (_("\
> +\n\
> +NOTE: The echo command doesn't behave gracefully when displaying\n\
> +arbitrary strings. For example, it can't display the string \"-n\" and\n\
> +requires the STRICTLY_POSIX flag to display \"-e\" or \"-E\". Therefore,\n\
> +if you need to display arbitrary strings please use the printf command\n\
> +instead.\n\
>   "), stdout);
>     printf (USAGE_BUILTIN_WARNING, PROGRAM_NAME);
>     emit_ancillary_info (PROGRAM_NAME);

This is too verbose.
BTW the env var is POSIXLY_CORRECT, not STRICTLY_POSIX.
Anyway I don't think we should mention that in the man page anyway.
I'll push the attached later, which just says printf(1) is preferred.

cheers,
Pádraig

[echo-printf.patch (text/x-patch, attachment)]

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

From: Florent Flament <contact <at> florentflament.com>
To: Pádraig Brady <P <at> draigBrady.com>
Cc: 51311-done <at> debbugs.gnu.org, bob <at> proulx.com
Subject: Re: bug#51311: [PATCH] echo: update --help to document edge cases
Date: Thu, 21 Oct 2021 15:14:08 +0200

Pádraig Brady <P <at> draigBrady.com> writes:

> BTW the env var is POSIXLY_CORRECT, not STRICTLY_POSIX.

Nice catch !

> Anyway I don't think we should mention that in the man page anyway.
> I'll push the attached later, which just says printf(1) is preferred.

I think the man page should warn users about possible bad usages of the
command. Just saying that 'printf' is preferred doesn't tell why,
therefore people won't use it IMHO.

> +  fputs (_("\n\
> +NOTE: printf(1) is a preferred alternative, with more standard option handling.\
> +\n\
> +"), stdout);

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.

Regards,
Florent

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

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: Florent Flament <contact <at> florentflament.com>,
 Pádraig Brady <P <at> draigBrady.com>
Cc: 51311-done <at> debbugs.gnu.org, bob <at> proulx.com
Subject: Re: bug#51311: [PATCH] echo: update --help to document edge cases
Date: Thu, 21 Oct 2021 22:54:08 +0200

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.

Have a nice day,
Berny

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

From: Florent Flament <contact <at> florentflament.com>
To: Bernhard Voelker <mail <at> bernhard-voelker.de>
Cc: 51311-done <at> debbugs.gnu.org, P <at> draigBrady.com, bob <at> proulx.com
Subject: Re: bug#51311: [PATCH] echo: update --help to document edge cases
Date: Fri, 22 Oct 2021 09:51:18 +0200

Bernhard Voelker <mail <at> bernhard-voelker.de> writes:
> On 10/21/21 15:14, Florent Flament wrote:
>> 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.

I agree that my sentence is not good, because "edge cases" is too
vague. And so far I haven't been able to find a good one liner to
express echo's drawbacks.

> Pádraig Brady <P <at> draigBrady.com> writes:
>> +NOTE: printf(1) is a preferred alternative, with more standard option handling.\
>
> Therefore, I'd prefer Padraig's shorter sentence: it expresses the matter
> positively while the latter proposal tries to explain via negative
> wording.

I believe that "with more standard option handling" is too vague as
well, and doesn't convey the issue with echo.

> 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.

I agree. Examples could make the point clearer.

> 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.

I believe that GNU users don't understand echo's drawbacks because they
aren't documented. Therefore users need to have enough experience to
have been confronted to undocumented echo related issues. I don't
believe that the printf command is complex. It is not used because users
are not aware that it exists, or don't understand why it is a better
alternative to echo.

> Finally, I think Padraig's suggestion had the best tradeoff between pointing
> out the matter and getting too much into details.

It is an improvement over current situation, but I would argue to go a
little bit further.

I can understand that one would want to keep the command's help message
short to avoid drowning the user into details. However, when a user
types "man echo", he/she wants to have details about the command's
behavior. I see the man page as the reference documentation of the
command, and I expect to find all of its drawbacks that have been
identified so far. I see the info documentation as a reference book that
centralizes the information a user would need to properly use the
operating system, possibly with more details, examples and anecdotes.

Therefore, I would argue for a slightly updated version of Pádraig's
sentence in echo's help message:

  NOTE: printf(1) is a preferred alternative (see echo(1) man page).

Then I would add the note that Glenn and Franck proposed to echo's man
page:

  For historical and back-compatibility reasons, certain bare option-like
  strings cannot be passed to echo as non-option arguments. The only way
  to echo the string '-n', for instance, is to specify the dash in either
  octal or hexadecimal representation (e.g. 'echo -e "\x2dn"'). It is
  therefore not advisable to use echo(1) for printing unknown or variable
  arguments. More generally, printf(1) is recommended as a more modern
  and flexible replacement for tasks historically performed by echo(1).

Ideally, The "echo invocation" info page should be updated as well with
a similar note, and possibly with some examples.

Here's a (slightly updated) example from Bob Proulx. Do you expect this
behavior when running this and typing "-n" as its input ?

      printf "What do you want me to say? "
      IFS= read -r phrase
      echo $phrase  # Noooo!

      printf "What do you want me to say? "
      IFS= read -r phrase
      printf "%b\n" "$phrase"  # Yes!

  The above shows input from an untrusted source.  It's "tainted".  It
  should not be used without caution.

I believe that these kind of details are what makes the difference
betwen ok software and great software. Also, I think that such an update
may prevent programmers from going into troubles, and maybe help them
fix existing code.

Have a great day,
Florent

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

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

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: Pádraig Brady <P <at> draigBrady.com>,
 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 16:58:33 +0200

On 10/22/21 16:21, Pádraig Brady wrote:
> 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

Thanks, I like it.

FWIW the biggest trap for users is still that in ~95% of the cases it is the
shell's builtin which gets called instead of that of the coreutils.
Hence, we've been improving the documentation for the users which
unsuspectingly read coreutils 'man echo' instead of that of the shell.

Have a nice day,
Berny

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

From: Florent Flament <contact <at> florentflament.com>
To: Pádraig Brady <P <at> draigBrady.com>
Cc: 51311 <at> debbugs.gnu.org, mail <at> bernhard-voelker.de
Subject: Re: bug#51311: [PATCH] echo: update --help to document edge cases
Date: Fri, 22 Oct 2021 21:22:25 +0200

Pádraig Brady <P <at> draigBrady.com> writes:
> 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

Thanks Pádraig, this is a great update.

Cheers,
Florent

Previous Next

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