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

[Florent Flament]

Bernhard Voelker <mail@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@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