bug#51311: [PATCH] echo: update --help to document edge cases
Pádraig Brady 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
bug#51311: [PATCH] echo: update --help to document edge cases
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
bug#51311: [PATCH] echo: update --help to document edge cases
On 21/10/2021 21:54, Bernhard Voelker wrote: On 10/21/21 15:14, Florent Flament wrote: Pádraig Brady 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
bug#51311: [PATCH] echo: update --help to document edge cases
Bernhard Voelker 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 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 # N! 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
bug#51311: [PATCH] echo: update --help to document edge cases
On 10/21/21 15:14, Florent Flament wrote: > Pádraig Brady 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
bug#51311: [PATCH] echo: update --help to document edge cases
Pádraig Brady 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
bug#51311: [PATCH] echo: update --help to document edge cases
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\
\\xHHbyte 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
>From 0aaa7e4ad33f9cf89d525bda0f9bfe3f9b092288 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?=
Date: Thu, 21 Oct 2021 13:05:47 +0100
Subject: [PATCH] doc: say that printf(1) is preferred over echo(1)
* src/echo.c (usage): Say printf(1) is preferred
due to being more standard.
* man/echo.x [SEE ALSO]: Reference printf(1).
---
man/echo.x | 2 ++
src/echo.c | 4
2 files changed, 6 insertions(+)
diff --git a/man/echo.x b/man/echo.x
index 9c4fa8131..61a36706b 100644
--- a/man/echo.x
+++ b/man/echo.x
@@ -2,3 +2,5 @@
echo \- display a line of text
[DESCRIPTION]
.\" Add any additional description here
+[SEE ALSO]
+printf(1)
diff --git a/src/echo.c b/src/echo.c
index 18513398a..d2262fa6b 100644
--- a/src/echo.c
+++ b/src/echo.c
@@ -80,6 +80,10 @@ If -e is in effect, the following sequences are recognized:\n\
\\xHHbyte with hexadecimal value HH (1 to 2 digits)\n\
"), stdout);
printf (USAGE_BUILTIN_WARNING, PROGRAM_NAME);
+ fputs (_("\n\
+NOTE: printf(1) is a preferred alternative, with more standard option handling.\
+\n\
+"), stdout);
emit_ancillary_info (PROGRAM_NAME);
exit (status);
}
--
2.26.2
bug#51311: [PATCH] echo: update --help to document edge cases
* 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\
\\xHHbyte 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
