From: Michael Witten <mfwitten@gmail.com>
Date: Fri, 27 Nov 2020 02:03:33 +0000
Subject: [PATCH] docs: Describe how 'screen' processes some C-style escape sequences

The description is placed in:

  * The texinfo node "Startup Files".
  * The man page.

The description is based on the following function:

  process.c:5360: Parse()

An example is also given in the description of the 'stuff' command.
---
 src/doc/screen.1       | 42 +++++++++++++++++++++++++++++-
 src/doc/screen.texinfo | 59 ++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 98 insertions(+), 3 deletions(-)

diff --git a/src/doc/screen.1 b/src/doc/screen.1
index ecd5632..f37ddb6 100644
--- a/src/doc/screen.1
+++ b/src/doc/screen.1
@@ -809,6 +809,10 @@ session.
 Commands are listed one per line, with empty lines being ignored.
 A command's arguments are separated by tabs or spaces, and may be
 surrounded by single or double quotes.
+Some C-style escapes may be used to input special characters, such
+as
+.I \en
+for a newline character (see below).
 A `#' turns the rest of the line into a comment, except in quotes.
 Unintelligible lines are warned about and ignored.
 Commands may contain references to environment variables. The 
@@ -819,6 +823,38 @@ versions, as now the '$'-character has to be protected with '\e' if no
 variable substitution shall be performed. A string in single-quotes is also
 protected from variable substitution.
 .PP
+When
+.I screen
+parses input in search of a command, it looks for a few C-style escape
+sequences, each of which is translated into a single character, as
+specified in the table below;
+this provides the user with a comfortable means by which to specify an
+uncomfortable character:
+.TS
+center tab(@);
+lB lB lB
+l lw24 l .
+Escape@Character@ASCII
+\fI\en\fP@newline@0x0A (LF; line feed)
+\fI\er\fP@carriage return@0x0D (CR)
+\fI\et\fP@horizontal tab@0x09 (HT)
+\fI\e\e\fP@backslash@0x5C
+\fI\e'\fP@single quote@0x27
+\fI\e"\fP@double quote@0x22
+\fI\e$\fP@dollar sign@0x24
+\fI\e#\fP@number sign, hash, pound@0x23
+\fI\e^\fP@caret@0x5E
+\fI\e\fP\f[BI]X\fP or \fI\e\fP\f[BI]XY\fP or \fI\e\fP\f[BI]XYZ\fP@T{
+octal code point (each of \fBX\fP, \fBY\fP, and \fBZ\fP is an octal digit;
+they specify an octal number that is the code point of the desired character.
+T}
+.TE
+.PP
+Within a double-quoted string, an escape sequence is still interpreted
+as specified above.  However, within a single-quoted string, an escape
+sequence is not interpreted; any escape sequence within a single-quoted
+string is used verbatim.
+.PP
 Two configuration files are shipped as examples with your screen distribution:
 \*Qetc/screenrc\*U and \*Qetc/etcscreenrc\*U. They contain a number of
 useful examples for various commands.
@@ -3429,7 +3465,11 @@ status messages to any corner of the screen. \fBtop\fR is the same as \fBup\fR,
 .PP
 Stuff the string
 .I string
-in the input buffer of the current window.
+into the input buffer of the current window; use a C-style escape
+sequence to specify a newline:
+.IP
+stuff "echo 'Hello,\enWorld!'"\en
+.PP
 This is like the \*Qpaste\*U command but with much less overhead.
 Without a parameter, screen will prompt for a string to stuff.
 You cannot paste
diff --git a/src/doc/screen.texinfo b/src/doc/screen.texinfo
index 18689a1..9de391c 100644
--- a/src/doc/screen.texinfo
+++ b/src/doc/screen.texinfo
@@ -509,7 +509,9 @@ files are used to set options, bind commands to keys, and to
 automatically establish one or more windows at the beginning of
 your @code{screen} session.  Commands are listed one per line, with
 empty lines being ignored.  A command's arguments are separated by tabs
-or spaces, and may be surrounded by single or double quotes.  A @samp{#}
+or spaces, and may be surrounded by single or double quotes.  Some C-style
+escapes may be used to input special characters, such as @samp{\n} for
+a newline character (see below).  A @samp{#}
 turns the rest of the line into a comment, except in quotes.
 Unintelligible lines are warned about and ignored.  Commands may contain
 references to environment variables.  The syntax is the shell-like
@@ -518,6 +520,53 @@ with previous @code{screen} versions, as now the '$'-character has to be
 protected with '\' if no variable substitution is intended. A string in 
 single-quotes is also protected from variable substitution.
 
+When @code{screen} parses input in search of a command, it looks for a
+few C-style escape sequences, each of which is translated into a
+single character, as specified in the table below; this provides the
+user with a comfortable means by which to specify an uncomfortable
+character:
+
+@multitable {@samp{\X} or @samp{\XY} or @samp{\XYZ}} {number sign, hash, pound} {0x0A (LF; line feed)}
+@headitem Escape @tab Character @tab ASCII
+@item @samp{\n}
+@tab newline
+@tab 0x0A (LF; line feed)
+@item @samp{\r}
+@tab carriage return
+@tab 0x0D (CR)
+@item @samp{\t}
+@tab horizontal tab
+@tab 0x09 (HT)
+@item @samp{\\}
+@tab backslash
+@tab 0x5C
+@item @samp{\'}
+@tab single quote
+@tab 0x27
+@item @samp{\"}
+@tab double quote
+@tab 0x22
+@item @samp{\$}
+@tab dollar sign
+@tab 0x24
+@item @samp{\#}
+@tab number sign, hash, pound
+@tab 0x23
+@item @samp{\^}
+@tab caret
+@tab 0x5E
+@item @samp{\X} or @samp{\XY} or @samp{\XYZ}
+@tab octal code point (each of 'X', 'Y', and 'Z' is an octal digit;
+they specify an octal number that is the code point of the desired
+character.
+@tab
+@end multitable
+
+Within a double-quoted string, an escape sequence is still interpreted
+as specified above.  However, within a single-quoted string, an escape
+sequence is not interpreted; any escape sequence within a single-quoted
+string is used verbatim.
+
 Two configuration files are shipped as examples with your screen
 distribution: @file{etc/screenrc} and @file{etc/etcscreenrc}. They
 contain a number of useful examples for various commands.
@@ -3872,7 +3921,13 @@ paste buffer exists once for every user.
 
 @deffn Command stuff [string]
 (none)@*
-Stuff the string @var{string} in the input buffer of the current window.
+Stuff the string @var{string} into the input buffer of the current window;
+use a C-style escape sequence to specify a newline:
+
+@example
+stuff "echo 'Hello,\nWorld!'"\n
+@end example
+
 This is like the @code{paste} command, but with much less overhead.
 Without a paramter, @code{screen} will prompt for a string to stuff.
 You cannot paste large buffers with the @code{stuff} command. It is most
-- 
2.22.0

