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

[Glenn Golden]

Florent Flament <contact@florentflament.com> [October 21, 2021 07:14 -0600]:
>
> Pádraig Brady <P@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.
>

2c: How about just adding a brief "NOTE" (or "CAVEAT") section to echo.1,
explicitly addressing the wart and advocating for printf(1) as well?

-----------------------------------------------------------------------------
NOTE
  For historical and back-compatibility reasons, certain bare option-like
  strings cannot be emitted without setting POSIXLY_CORRECT, and the bare
  string '-n' cannot be emitted at all.  Prefixing or suffixing such strings
  with quoted whitespace (e.g. ' -n') can be used as a workaround for this
  peculiarity.  More generally, printf(1) is recommended as a more modern
  and flexible replacement for tasks historically performed by echo(1).
-----------------------------------------------------------------------------

Something like this seems to get the job done: Briefly states the issue,
why it exists, provides a workaround, and cheerleads for modernization. 

("And what would you expect to pay for all this...?")

- gdg