[PATCH] Document echo \c behaviour

[PATCH] Document echo \c behaviour

[Phil Pennock]

[-- Attachment #1: Type: text/plain, Size: 1845 bytes --]

Report on IRC asking about a behaviour difference between bash and zsh
led me down a rabbit hole.  While bash does the same thing as zsh when
given "echo -e", the behaviour was not documented in our man-pages and
was counter-intuitive.

    echo "foo\cbar" baz bat

Only the "foo" is output, with no final newline.

Commit logs show revision b77b51c in 2005 made this explicit, to "handle
\c escapes as per POSIX (truncating the output at the \c)".

SUSv4 XCU at <http://pubs.opengroup.org/onlinepubs/9699919799/> states:

 > \c
 > Suppress the <newline> that otherwise follows the final argument in
 > the output. All characters following the '\c' in the arguments shall
 > be ignored.

I think that this is worth documenting.  Patch tested with "make" in
Doc/ and results look fine.
---
 Doc/Zsh/builtins.yo | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index 7b04d0648..4caefd5ba 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -453,7 +453,7 @@ tt(echo) recognizes the following escape sequences:
 startsitem()
 sitem(tt(\a))(bell character)
 sitem(tt(\b))(backspace)
-sitem(tt(\c))(suppress final newline)
+sitem(tt(\c))(suppress subsequent characters and final newline)
 sitem(tt(\e))(escape)
 sitem(tt(\f))(form feed)
 sitem(tt(\n))(linefeed (newline))
@@ -467,6 +467,9 @@ sitem(tt(\u)var(NNNN))(unicode character code in hexadecimal)
 sitem(tt(\U)var(NNNNNNNN))(unicode character code in hexadecimal)
 endsitem()
 
+POSIX requires for tt(echo) that "All characters following the tt(\c) in the
+arguments shall be ignored".
+
 pindex(BSD_ECHO, use of)
 The tt(-E) flag, or the tt(BSD_ECHO) option, can be used to disable
 these escape sequences.  In the latter case, tt(-e) flag can be used to
-- 
2.11.0


[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] Document echo \c behaviour

[Daniel Shahaf]

Phil Pennock wrote on Mon, Jan 09, 2017 at 15:32:09 -0500:
> SUSv4 XCU at <http://pubs.opengroup.org/onlinepubs/9699919799/> states:

That's the landing page; 'echo' is at
http://pubs.opengroup.org/onlinepubs/9699919799/utilities/echo.html

>  > \c
>  > Suppress the <newline> that otherwise follows the final argument in
>  > the output. All characters following the '\c' in the arguments shall
>  > be ignored.
> 
> I think that this is worth documenting.  Patch tested with "make" in
> Doc/ and results look fine.

Thanks; I pushed the first hunk.  I didn't push the second one because
I don't think it's required.  If you disagree then make your case ;-).

Thanks for the patch!

Daniel

P.S. Overly-literal-reading corner: doesn't "All characters following...
will be ignored" mean that «echo 'foo\cbar' 'baz' 'qux'» should be
equivalent to «echo 'foo\cbar' '' ''»?  I.e., print «foo» followed by
two trailing spaces?

Re: [PATCH] Document echo \c behaviour

[Phil Pennock]

On 2017-01-10 at 03:52 +0000, Daniel Shahaf wrote:
> Thanks; I pushed the first hunk.  I didn't push the second one because
> I don't think it's required.  If you disagree then make your case ;-).

The behaviour is bug-ass crazy nuts and needs justification.  Every
other escape sequence is a character which is inserted; \c was always
a special case for "suppress the following newline", but "truncate
_everything_ else" from an _escape_ sequence is ... face-palm worthy.

It warrants explanation as to why it's so counter-intuitive.

> P.S. Overly-literal-reading corner: doesn't "All characters following...
> will be ignored" mean that «echo 'foo\cbar' 'baz' 'qux'» should be
> equivalent to «echo 'foo\cbar' '' ''»?  I.e., print «foo» followed by
> two trailing spaces?

Sounds right.  Take it up with the Austin Group.  I believe that Bart is
masochistic enough to pay attention in those arenas and might be willing
to raise it as a spec bug.

(I tried following AG for a while, and ran away)

Re: [PATCH] Document echo \c behaviour

[Daniel Shahaf]

Phil Pennock wrote on Tue, Jan 10, 2017 at 09:39:31 +0000:
> On 2017-01-10 at 03:52 +0000, Daniel Shahaf wrote:
> > Thanks; I pushed the first hunk.  I didn't push the second one because
> > I don't think it's required.  If you disagree then make your case ;-).
> 
> The behaviour is bug-ass crazy nuts and needs justification.  Every
> other escape sequence is a character which is inserted; \c was always
> a special case for "suppress the following newline", but "truncate
> _everything_ else" from an _escape_ sequence is ... face-palm worthy.
> 
> It warrants explanation as to why it's so counter-intuitive.

In that case, I would word it differently; for example:

diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index af336ef..091bd49 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -467,6 +467,9 @@ sitem(tt(\u)var(NNNN))(unicode character code in hexadecimal)
 sitem(tt(\U)var(NNNNNNNN))(unicode character code in hexadecimal)
 endsitem()
 
+Note that tt(\c), unlike all other escapes, discards all following characters
+as well.
+
 pindex(BSD_ECHO, use of)
 The tt(-E) flag, or the tt(BSD_ECHO) option, can be used to disable
 these escape sequences.  In the latter case, tt(-e) flag can be used to

However, I still don't think repetition is needed.  The purpose of the
manual is to document the shell's behaviour, and the sitem() line on
master acheives that.  It's not as if people are going to run into this
behaviour unexpectedly; nobody has ever written
.
    c=${"${:-abcdefghijklmnopqrstuvwxyz}"[RANDOM % 26]}
    s="foo\\$cbar"
    eval "echo \"$s\"" | grep -q bar
    assert($? == 0)
.
in production code. ;-)

Let's see what others think.

> > P.S. Overly-literal-reading corner: doesn't "All characters following...
> > will be ignored" mean that «echo 'foo\cbar' 'baz' 'qux'» should be
> > equivalent to «echo 'foo\cbar' '' ''»?  I.e., print «foo» followed by
> > two trailing spaces?
> 
> Sounds right.

For comparison, the 'printf' spec has plugged this hole:

            * '\c' , which shall not be written and shall cause printf to
              ignore any remaining characters in the string operand containing
              it, any remaining string operands, and any additional characters
              in the format operand

> Take it up with the Austin Group.  I believe that Bart is
> masochistic enough to pay attention in those arenas and might be willing
> to raise it as a spec bug.
> 
> (I tried following AG for a while, and ran away)

Understood.

Cheers,

Daniel