gbranden pushed a commit to branch master
in repository groff.
commit 3e93e39518a9c6adc44c77c8f88d05564189ec30
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sun Apr 26 16:13:25 2026 -0500
[doc,man]: Update, resync escape sequences stuff.
* Note escape character's (selective) function as a syntactical
quotation character in copy mode.
* Break Texinfo input lines in a roff-friendly way.
---
doc/groff.texi.in | 84 +++++++++++++++++++++++++++++++++++++------------------
man/groff.7.man | 32 +++++++++++++--------
2 files changed, 77 insertions(+), 39 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index a92753e0f..78e97e1bf 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -8450,32 +8450,59 @@ because it tracks the nesting depth of interpolations.
@cindex using escape sequences
@cindex escape sequences
-Whereas requests must occur on control lines, escape sequences can occur
-intermixed with text and may appear in arguments to requests, macros,
+Whereas requests must occur on control lines,
+escape sequences can occur intermixed with text
+and may appear in arguments to requests,
+macros,
and other escape sequences.
@esindex \
-An escape sequence is introduced by the escape character, a backslash
-@code{\} (but see the @code{ec} request below). The next character
-selects the escape's function.
-
-Escape sequences vary in length. Some take an argument, and of those,
+An escape sequence is introduced by the escape character,
+a backslash
+@code{\}
+(but see the
+@code{ec}
+request below).
+The next character selects the escape's function.
+
+Escape sequences vary in length.
+Some take an argument,
+and of those,
some have different syntactical forms for a one-character,
-two-character, or arbitrary-length argument. Others accept @emph{only}
-an arbitrary-length argument. In the former scheme, a one-character
-argument follows the function character immediately, an opening
-parenthesis @samp{(} introduces a two-character argument (no closing
-parenthesis is used), and an argument of arbitrary length is enclosed in
-brackets @samp{[]}. In the latter scheme, the user selects a delimiter
-character. A few escape sequences are idiosyncratic, and support both
-of the foregoing conventions (@code{\s}), designate their own
-termination sequence (@code{\?}), consume input until the next newline
-(@code{\!}, @code{\"}, @code{\#}), or support an additional modifier
-character (@code{\s} again, and @code{\n}). In no case can an escape
-sequence parameter contain an unescaped newline. As with requests, use
-of some escape sequences in source documents may interact poorly with a
-macro package you use; consult its documentation to learn of ``safe''
-sequences or alternative facilities it provides to achieve the desired
-result.
+two-character, or arbitrary-length argument.
+Others accept
+@emph{only}
+an arbitrary-length argument.
+In the former scheme,
+a one-character argument follows the function character immediately,
+an opening parenthesis
+@samp{(}
+introduces a two-character argument
+(no closing parenthesis is used),
+and an argument of arbitrary length is enclosed in brackets
+@samp{[]}.
+In the latter scheme,
+the user selects a delimiter character.
+A few escape sequences are idiosyncratic,
+and support both of the foregoing conventions
+(@code{\s}),
+designate their own termination sequence
+(@code{\?}),
+consume input until the next newline
+(@code{\!},
+@code{\"},
+@code{\#}),
+or support an additional modifier character
+(@code{\s}
+again,
+and
+@code{\n}).
+In no case can an escape sequence parameter
+contain an unescaped newline.
+As with requests,
+use of some escape sequences in source documents
+may interact poorly with a macro package you use;
+consult its documentation to learn of ``safe'' sequences
+or alternative facilities it provides to achieve the desired result.
If the character that follows the escape character
does not identify a valid operation,
@@ -8484,6 +8511,9 @@ the formatter ignores the escape character.@footnote{GNU
emits a warning in category
@samp{escape}.
@xref{Warnings}.}
+In copy mode,
+the escape character can be used to quote the escape or control
+characters.@footnote{@xref{Copy Mode}.}
@Example
$ groff -T ps -ww
@@ -8496,10 +8526,10 @@ said \P.\&\~Pseudo Pachyderm.
@result{} I have @slanted{12 white elephants,} said P. Pseudo Pachyderm.
@endExample
-Escape sequence interpolation is of higher precedence than escape
-sequence argument interpretation. This rule affords flexibility in
-using escape sequences to construct parameters to other escape
-sequences.
+Escape sequence interpolation is of higher precedence
+than escape sequence argument interpretation.
+This rule affords flexibility in using escape sequences
+to construct parameters to other escape sequences.
@c END Keep (roughly) parallel with section "Escape sequences" of
@c groff(7).
diff --git a/man/groff.7.man b/man/groff.7.man
index d5ccc0f25..8f2505179 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -1769,8 +1769,8 @@ Texinfo manual for the complex macro argument quoting
rules of AT&T
.\" BEGIN Keep (roughly) parallel with groff.texi node "Using Escape
.\" Sequences".
Whereas requests must occur on control lines,
-escape sequences can occur intermixed with text and may appear in
-arguments to requests,
+escape sequences can occur intermixed with text
+and may appear in arguments to requests,
macros,
and other escape sequences.
.
@@ -1822,12 +1822,13 @@ again,
and
.BR \|\[rs]n ).
.
-In no case can an escape sequence parameter contain an unescaped
-newline.
-.\" As with requests, use of some escape sequences in source documents
-.\" may interact poorly with a macro package you use; consult its
-.\" documentation to learn of ``safe'' sequences or alternative
-.\" facilities it provides to achieve the desired result.
+In no case can an escape sequence parameter
+contain an unescaped newline.
+.\" As with requests,
+.\" use of some escape sequences in source documents
+.\" may interact poorly with a macro package you use;
+.\" consult its documentation to learn of ``safe'' sequences
+.\" or alternative facilities it provides to achieve the desired result.
.
.
.P
@@ -1843,15 +1844,22 @@ emits a warning in category
See section \[lq]Warnings\[rq] in
.MR @g@troff @MAN1EXT@ .)
.
+In copy mode,
+the escape character can be used to quote the escape or control
+characters.
+.
+(See subsection \[lq]Copy mode\[rq] below.)
+.
.
.P
-Escape sequence interpolation is of higher precedence than escape
-sequence argument interpretation.
+Escape sequence interpolation is of higher precedence
+than escape sequence argument interpretation.
.
-This rule affords flexibility in using escape sequences to construct
-parameters to other escape sequences.
+This rule affords flexibility in using escape sequences
+to construct parameters to other escape sequences.
.
.
+.\" This summary paragraph is unique to the man page.
.P
The escape character can be interpolated
.RB ( \[rs]e ).
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
