gbranden pushed a commit to branch master
in repository groff.
commit ba6f3e36cb95fed7c2c5a0225366961c2f53b7a6
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sun Dec 7 01:27:30 2025 -0600
[doc,man]: Adjust pedagogy in "Copy mode".
Take a leaf from bash(1)'s playbook and characterize the escape
character as sometimes operating as a _quotation_ character.
In a recursive interpretation process, "escaping" a token refers to
"getting out" of the current interpretation context so that the token is
interpreted in an enclosing one; "quoting" refers to "pushing down" or
"hiding" some input from the current interpretation context so that a
token gets interpreted only in an inferior context.
It's kind of a shame that we use the same input token to represent both
of these processes, which are not only distinguishable but opposite in
meaning. But, hey, man--it was the seventies.
"I tied an onion to my belt, which was the style at the time."
---
doc/groff.texi.in | 140 ++++++++++++++++++++++++++++++++++++++++++------------
man/groff.7.man | 74 +++++++++++++++++++----------
2 files changed, 158 insertions(+), 56 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 4a3811c0f..4ac45da3e 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -15558,12 +15558,28 @@ processed immediately upon recognition, can be termed
@Defesc {\\\\, , , }
@cindex @code{\\}, interpretation in copy mode
-The escape character, @code{\} by default, can escape itself. This
-enables you to control whether a given @code{\n}, @code{\g}, @code{\$},
-@code{\*}, @code{\V}, or @code{\?} escape sequence is interpreted at the
-time the macro containing it is defined, or later when the macro is
-called.@footnote{Compare this to the @code{\def} and @code{\edef}
-commands in @TeX{}.}
+@cindex @code{\\}, as quotation character
+@cindex quoting the escape character with @code{\\}
+@cindex quoting the control character with @code{\\}
+The escape character
+(@code{\}
+by default)
+when used before itself
+@dfn{quotes}
+an escape character for later interpreation
+in an enclosing context.
+Escape character quotation enables you to control
+whether the formatter interprets a given
+@code{\n},
+@code{\g},
+@code{\$},
+@code{\*},
+@code{\V},
+or
+@code{\?}
+escape sequence at the time the macro containing it is defined,
+or later when the macro is called.@footnote{Compare this to the
+@code{\def} and @code{\edef} commands in @TeX{}.}
@Example
.nr x 20
@@ -15576,22 +15592,42 @@ commands in @TeX{}.}
@result{} 20 10
@endExample
-You can think of @code{\\} as a ``delayed'' backslash; it is the escape
-character followed by a backslash from which the escape character has
-removed its special meaning. Consequently, @samp{\\} is not an escape
-sequence in the usual sense. In any escape sequence @samp{\@var{X}}
-that GNU @code{troff} does not recognize, the escape character is
-ignored and @var{X} is output. An unrecognized escape sequence causes
-a warning in category @samp{escape}, with two exceptions---@samp{\\} is
-the first.
+You can think of
+@code{\\}
+as a ``delayed'' backslash;
+it is the escape character
+followed by a backslash
+from which the escape character
+has removed its special meaning.
+Consequently,
+@samp{\\}
+is not best considered an escape sequence,
+but a quoted escape character.
+In any escape sequence
+@samp{\@var{X}}
+that
+GNU
+@code{troff} @c GNU
+does not recognize,
+the formatter discards the escape character and outputs
+@var{X}.
+An unrecognized escape sequence causes a warning in category
+@samp{escape},
+with two exceptions---@samp{\\}
+is the first.
@endDefesc
@cindex @code{\.}, interpretation in copy mode
@Defesc {\\., , , }
-@code{\.} escapes the control character. It is similar to @code{\\} in
-that it isn't a true escape sequence. It is used to permit nested macro
-definitions to end without a named macro call to conclude them. Without
-a syntax for escaping the control character, this would not be possible.
+@code{\.}
+quotes the control character.
+It is similar to
+@code{\\}
+in that it isn't a true escape sequence.
+It is used to permit nested macro definitions to end
+without a named macro call to conclude them.
+Without a syntax for quoting the control character,
+this would not be possible.
@Example
.de m1
@@ -15612,11 +15648,29 @@ The first backslash is consumed while the macro is
read, and the second
is interpreted when macro @code{m1} is called.
@endDefesc
-@code{roff} documents should not use the @code{\\} or @code{\.}
-character sequences outside of copy mode; they serve only to obfuscate
-the input. Use @code{\e} to represent the escape character,
-@code{\[rs]} to obtain a backslash glyph, and @code{\&} before @samp{.}
-and @samp{'} where GNU @code{troff} expects them as control characters
+Outside of copy mode,
+@code{roff}
+documents should not use the
+@code{\\}
+or
+@code{\.}
+character sequences;
+they serve only to obfuscate the input.
+Use
+@code{\e}
+to represent the escape character,
+@code{\[rs]}
+to obtain a backslash glyph,
+and
+@code{\&}
+before
+@samp{.}
+and
+@samp{'}
+where
+GNU
+@code{troff} @c GNU
+expects them as control characters
if you mean to use them literally (recall @ref{Requests and Macros}).
@cindex nesting depth, of escape sequences in macro definitions
@@ -15642,13 +15696,39 @@ This understeer is getting
@result{} This understeer is getting out of hand.
@endExample
-Each escape character is interpreted twice---once in copy mode, when the
-macro is defined, and once in interpretation mode, when the macro is
-called. As seen above, this fact leads to exponential growth in the
-quantity of escape characters required to delay interpolation of
-@code{\n}, @code{\g}, @code{\$}, @code{\*}, @code{\V}, and @code{\?} at
-each nesting level, which can be daunting. GNU @code{troff} offers a
-solution.
+As seen above,
+the formatter interpets each escape character in multiple contexts;
+once,
+when populating the macro or string,
+where the first
+@samp{\}
+serves its quotation function\[em]thus
+only one
+@samp{\}
+is stored in the definition.
+(Verify this fact with the
+@code{pm}
+request.)
+The formatter interprets the second
+@samp{\}
+as an escape character
+(assuming the escape character hasn't been changed in the meantime)
+each time it interpolates the macro or string definition.
+This fact leads to exponential growth
+in the quantity of escape characters
+required to quote and thereby delay interpolation of
+@code{\n},
+@code{\g},
+@code{\$},
+@code{\*},
+@code{\V},
+and
+@code{\?}
+at each nesting level,
+which can be daunting.
+GNU
+@code{troff} @c GNU
+offers a solution.
@Defesc {\\E, , , }
@code{\E} represents an escape character that is not interpreted in copy
diff --git a/man/groff.7.man b/man/groff.7.man
index 5ababe4f3..1ad2d72a9 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -8311,12 +8311,16 @@ can be termed
.
.
.P
-The escape character,
-.B \[rs]
-by default,
-can escape itself.
+The escape character
+.RB ( \[rs]
+by default)
+when used before itself
+.I quotes
+an escape character for later interpreation
+in an enclosing context.
.
-This enables you to control whether a given
+Escape character quotation enables you to control
+whether the formatter interprets a given
.BR \[rs]n ,
.BR \[rs]g ,
.BR \[rs]$ ,
@@ -8324,8 +8328,7 @@ This enables you to control whether a given
.BR \[rs]V ,
or
.B \[rs]?\&
-escape sequence is interpreted at the time the macro containing it is
-defined,
+escape sequence at the time the macro containing it is defined,
or later when the macro is called.
.
.
@@ -8338,16 +8341,16 @@ character has removed its special meaning.
.
Consequently,
.B \[rs]\[rs]
-is not an escape sequence in the usual sense.
+is not best considered an escape sequence,
+but a quoted escape character.
.
In any escape sequence
.BI \[rs] X
that
.I @g@troff
does not recognize,
-the escape character is ignored and
-.IR X \~is
-output.
+the formatter discards the escape character and outputs
+.I X.
.
An unrecognized escape sequence causes a warning in category
.RB \%\[lq] escape \[rq],
@@ -8357,20 +8360,21 @@ being one.
.
The other is
.BR \[rs]. ,
-which escapes the control character.
+which quotes the control character.
.
-It is used to permit nested macro definitions to end without a named
-macro call to conclude them.
+It is used to permit nested macro definitions to end
+without a named macro call to conclude them.
.
-Without a syntax for escaping the control character,
+Without a syntax for quoting the control character,
this would not be possible.
.
+Outside of copy mode,
.I roff
documents should not use the
.B \[rs]\[rs]
or
.B \[rs].\&
-character sequences outside of copy mode;
+character sequences;
they serve only to obfuscate the input.
.
Use
@@ -8386,7 +8390,8 @@ and
.B \[aq]
where
.I @g@troff
-expects them as control characters if you mean to use them literally.
+expects them as control characters
+if you mean to use them literally.
.
.
.br
@@ -8394,15 +8399,32 @@ expects them as control characters if you mean to use
them literally.
.P
Macro definitions can be nested to arbitrary depth.
.
-In
-.RB \[lq] \|\[rs]\[rs] \[rq],
-each escape character is interpreted twice\[em]once in copy mode,
-when the macro is defined,
-and once in interpretation mode,
-when the macro is called.
-.
-This fact leads to exponential growth in the quantity of escape
-characters required to delay interpolation of
+Given the input character sequence
+.RB \[lq] \|\[rs]\[rs] \[rq]
+in a macro or string definition,
+the formatter interpets each escape character in multiple contexts;
+once,
+when populating the macro or string,
+where the first
+.RB \[lq] \[rs] \[rq]
+serves its quotation function\[em]thus
+only one
+.RB \[lq] \[rs] \[rq]
+is stored in the definition.
+.
+(Verify this fact with the
+.B pm
+request.)
+.
+The formatter interprets the second
+.RB \[lq] \[rs] \[rq]
+as an escape character
+(assuming the escape character hasn't been changed in the meantime)
+each time it interpolates the macro or string definition.
+.
+This fact leads to exponential growth
+in the quantity of escape characters
+required to quote and thereby delay interpolation of
.BR \[rs]n ,
.BR \[rs]g ,
.BR \[rs]$ ,
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
