From: Pádraig Brady <P@draigBrady.com>
Date: Mon, 12 Jan 2026 00:12:35 +0000 (+0000)
Subject: doc: paste: add more detail on operation and options
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9a8b09f025746ff3e31c34b1b3f0943451035107;p=thirdparty%2Fcoreutils.git

doc: paste: add more detail on operation and options

* src/paste.c (usage): Mention how lines are processed
with and without the -s option.  Also mention that -d
supports backslash escapes.
* doc/coreutils.texi (paste invocation): Likewise.
Also detail the backslash escapes, noting which are non-POSIX.
---

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index e8b24f7680..64e731f06d 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -6214,7 +6214,10 @@ many fields and want to print all but a few of them.
 @cindex merging files
 
 @command{paste} writes to standard output lines consisting of sequentially
-corresponding lines of each given file, separated by a TAB character.
+corresponding lines of each given file, separated by a delimiter character
+(default is the TAB character).
+The newline of every line except the line from the last input file
+is replaced with a delimiter character.
 Standard input is used for a file name of @samp{-} or if no input files
 are given.
 
@@ -6272,8 +6275,10 @@ The program accepts the following options.  Also see @ref{Common options}.
 
 @optItem{paste,-s,}
 @optItemx{paste,--serial,}
-Paste the lines of one file at a time rather than one line from each
-file.  Using the above example data:
+Paste the lines of one file at a time rather than one line from each file.
+The newline of every line except the last line in each input file
+is replaced with a delimiter character.
+Using the above example data:
 
 @example
 $ paste -s num2 let3
@@ -6285,8 +6290,27 @@ a       b       c
 @optItemx{paste,--delimiter,=@var{delim-list}}
 Consecutively use the characters in @var{delim-list} instead of
 TAB to separate merged lines.  When @var{delim-list} is
-exhausted, start again at its beginning.  Using the above example data:
+exhausted, start again at its beginning.
 
+The following backslash escape sequences are recognized
+in @var{delim-list}:
+
+@table @samp
+@item \0 The empty string (not the NUL character)
+@item \n newline
+@item \t TAB
+@item \\ A backslash
+@item \b backspace (GNU extension)
+@item \f form feed (GNU extension)
+@item \r carriage return (GNU extension)
+@item \v vertical tab (GNU extension)
+@end table
+
+It is an error if no character follows an unescaped backslash.
+As a GNU extension, a backslash followed by a character not listed
+above is interpreted as that character.
+
+Using the above example data:
 @example
 $ paste -d '%_' num2 let3 num2
 1%a_1
diff --git a/src/paste.c b/src/paste.c
index c61ac9f0fe..f48f57f6be 100644
--- a/src/paste.c
+++ b/src/paste.c
@@ -427,17 +427,27 @@ Usage: %s [OPTION]... [FILE]...\n\
       fputs (_("\
 Write lines consisting of the sequentially corresponding lines from\n\
 each FILE, separated by TABs, to standard output.\n\
+The newline of every line except the line from the last file\n\
+is replaced with a TAB.\n\
 "), stdout);
 
       emit_stdin_note ();
       emit_mandatory_arg_note ();
 
       fputs (_("\
-  -d, --delimiters=LIST   reuse characters from LIST instead of TABs\n\
-  -s, --serial            paste one file at a time instead of in parallel\n\
+  -d, --delimiters=LIST\n\
+         reuse characters from LIST instead of TABs;\n\
+         backslash escapes are supported\n\
 "), stdout);
       fputs (_("\
-  -z, --zero-terminated    line delimiter is NUL, not newline\n\
+  -s, --serial\n\
+         paste one file at a time instead of in parallel; the newline of\n\
+         every line except the last line in each file is replaced with a TAB\
+\n\
+"), stdout);
+      fputs (_("\
+  -z, --zero-terminated\n\
+         line delimiter is NUL, not newline\n\
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);