[PATCH] Document echo \c behaviour

[Phil Pennock <zsh-workers+phil.pennock@spodhuis.org>]

[-- 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 --]