1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
|
<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.0.3, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<!-- This manual documents GNU troff version 1.23.0.
Copyright 1994-2023 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
copy of the license is included in the section entitled "GNU Free
Documentation License". -->
<title>Copy Mode (The GNU Troff Manual)</title>
<meta name="description" content="Copy Mode (The GNU Troff Manual)">
<meta name="keywords" content="Copy Mode (The GNU Troff Manual)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Request-Index.html" rel="index" title="Request Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Writing-Macros.html" rel="up" title="Writing Macros">
<link href="Parameters.html" rel="prev" title="Parameters">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
kbd.key {font-style: normal}
span.r {font-family: initial; font-weight: normal; font-style: normal}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
-->
</style>
</head>
<body lang="en">
<div class="subsection-level-extent" id="Copy-Mode">
<div class="nav-panel">
<p>
Previous: <a href="Parameters.html" accesskey="p" rel="prev">Parameters</a>, Up: <a href="Writing-Macros.html" accesskey="u" rel="up">Writing Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Request-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h4 class="subsection" id="Copy-Mode-1">5.24.2 Copy Mode</h4>
<a class="index-entry-id" id="index-copy-mode"></a>
<a class="index-entry-id" id="index-copy-mode-1"></a>
<a class="index-entry-id" id="index-mode_002c-copy"></a>
<a class="index-entry-id" id="index-mode_002c-copy-1"></a>
<a class="index-entry-id" id="index-_005cn_002c-when-reading-text-for-a-macro"></a>
<a class="index-entry-id" id="index-_005c_0024_002c-when-reading-text-for-a-macro"></a>
<a class="index-entry-id" id="index-_005c_002a_002c-when-reading-text-for-a-macro"></a>
<a class="index-entry-id" id="index-_005cRET_002c-when-reading-text-for-a-macro"></a>
<p>When GNU <code class="code">troff</code> processes certain requests, most importantly those
which define or append to a macro or string, it does so in <em class="dfn">copy
mode</em>: it copies the characters of the definition into a dedicated
storage region, interpolating the escape sequences <code class="code">\n</code>, <code class="code">\g</code>,
<code class="code">\$</code>, <code class="code">\*</code>, <code class="code">\V</code>, and <code class="code">\?</code> normally; interpreting
<code class="code">\<kbd class="key">RET</kbd></code> immediately; discarding comments <code class="code">\"</code> and
<code class="code">\#</code>; interpolating the current leader, escape, or tab character
with <code class="code">\a</code>, <code class="code">\e</code>, and <code class="code">\t</code>, respectively; and storing all
other escape sequences in an encoded form.
</p>
<a class="index-entry-id" id="index-interpretation-mode"></a>
<a class="index-entry-id" id="index-mode_002c-interpretation"></a>
<p>The complement of copy mode—a <code class="code">roff</code> formatter’s behavior when
not defining or appending to a macro, string, or diversion—where all
macros are interpolated, requests invoked, and valid escape sequences
processed immediately upon recognition, can be termed
<em class="dfn">interpretation mode</em>.
</p>
<dl class="first-deffn">
<dt class="deffn" id="index-_005c_005c-1"><span class="category-def">Escape sequence: </span><span><strong class="def-name"><code class="t">\\</code><span class="r"><i class="slanted"></i></span><code class="t"></code></strong><a class="copiable-link" href='#index-_005c_005c-1'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-_005c_005c"></a>
<p>The escape character, <code class="code">\</code> by default, can escape itself. This
enables you to control whether a given <code class="code">\n</code>, <code class="code">\g</code>, <code class="code">\$</code>,
<code class="code">\*</code>, <code class="code">\V</code>, or <code class="code">\?</code> escape sequence is interpreted at the
time the macro containing it is defined, or later when the macro is
called.<a class="footnote" id="DOCF101" href="groff.html_fot.html#FOOT101"><sup>101</sup></a>
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.nr x 20
.de y
.nr x 10
\&\nx
\&\\nx
..
.y
⇒ 20 10
</pre></div></div>
<p>You can think of <code class="code">\\</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 class="samp">\\</samp>’ is not an escape
sequence in the usual sense. In any escape sequence ‘<samp class="samp">\<var class="var">X</var></samp>’
that GNU <code class="code">troff</code> does not recognize, the escape character is
ignored and <var class="var">X</var> is output. An unrecognized escape sequence causes
a warning in category ‘<samp class="samp">escape</samp>’, with two exceptions—‘<samp class="samp">\\</samp>’ is
the first.
</p></dd></dl>
<a class="index-entry-id" id="index-_005c_005c_002c-when-reading-text-for-a-macro"></a>
<dl class="first-deffn">
<dt class="deffn" id="index-_005c_002e-1"><span class="category-def">Escape sequence: </span><span><strong class="def-name"><code class="t">\.</code><span class="r"><i class="slanted"></i></span><code class="t"></code></strong><a class="copiable-link" href='#index-_005c_002e-1'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-_005c_002e"></a>
<p><code class="code">\.</code> escapes the control character. It is similar to <code class="code">\\</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.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.de m1
foo
.
. de m2
bar
\\..
.
..
.m1
.m2
⇒ foo bar
</pre></div></div>
<p>The first backslash is consumed while the macro is read, and the second
is interpreted when macro <code class="code">m1</code> is called.
</p></dd></dl>
<p><code class="code">roff</code> documents should not use the <code class="code">\\</code> or <code class="code">\.</code>
character sequences outside of copy mode; they serve only to obfuscate
the input. Use <code class="code">\e</code> to represent the escape character,
<code class="code">\[rs]</code> to obtain a backslash glyph, and <code class="code">\&</code> before ‘<samp class="samp">.</samp>’
and ‘<samp class="samp">'</samp>’ where GNU <code class="code">troff</code> expects them as control characters
if you mean to use them literally (recall <a class="ref" href="Requests-and-Macros.html">Requests and Macros</a>).
</p>
<p>Macro definitions can be nested to arbitrary depth. The mechanics of
parsing the escape character have significant consequences for this
practice.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.de M1
\\$1
. de M2
\\\\$1
. de M3
\\\\\\\\$1
\\\\..
. M3 hand.
\\..
. M2 of
..
This understeer is getting
.M1 out
⇒ This understeer is getting out of hand.
</pre></div></div>
<p>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 class="code">\n</code>, <code class="code">\g</code>, <code class="code">\$</code>, <code class="code">\*</code>, <code class="code">\V</code>, and <code class="code">\?</code> at
each nesting level, which can be daunting. GNU <code class="code">troff</code> offers a
solution.
</p>
<dl class="first-deffn">
<dt class="deffn" id="index-_005cE-1"><span class="category-def">Escape sequence: </span><span><strong class="def-name"><code class="t">\E</code><span class="r"><i class="slanted"></i></span><code class="t"></code></strong><a class="copiable-link" href='#index-_005cE-1'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-_005cE"></a>
<p><code class="code">\E</code> represents an escape character that is not interpreted in copy
mode. You can use it to ease the writing of nested macro definitions.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.de M1
. nop \E$1
. de M2
. nop \E$1
. de M3
. nop \E$1
\\\\..
. M3 better.
\\..
. M2 bit
..
This vehicle handles
.M1 a
⇒ This vehicle handles a bit better.
</pre></div></div>
<p>Observe that because <code class="code">\.</code> is not a true escape sequence, we can’t
use <code class="code">\E</code> to keep ‘<samp class="samp">..</samp>’ from ending a macro definition
prematurely. If the multiplicity of backslashes complicates
maintenance, use end macros.
</p>
<p><code class="code">\E</code> is also convenient to define strings containing escape
sequences that need to work when used in copy mode (for example, as
macro arguments), or which will be interpolated at varying macro nesting
depths. We might define strings to begin and end superscripting
as follows.<a class="footnote" id="DOCF102" href="groff.html_fot.html#FOOT102"><sup>102</sup></a>
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.ds { \v'-.9m\s'\En[.s]*7u/10u'+.7m'
.ds } \v'-.7m\s0+.9m'
</pre></div></div>
<p>When the <code class="code">ec</code> request is used to redefine the escape character,
<code class="code">\E</code> also makes it easier to distinguish the semantics of an escape
character from the other meaning(s) its character might have. Consider
the use of an unusual escape character, ‘<samp class="samp">-</samp>’.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.nr a 1
.ec -
.de xx
--na
..
.xx
⇒ -na
</pre></div></div>
<p>This result may surprise you; some people expect ‘<samp class="samp">1</samp>’ to be output
since register ‘<samp class="samp">a</samp>’ has clearly been defined with that value. What
has happened? The robotic replacement of ‘<samp class="samp">\</samp>’ with ‘<samp class="samp">-</samp>’ has led
us astray. You might recognize the sequence ‘<samp class="samp">--</samp>’ more readily with
the default escape character as ‘<samp class="samp">\-</samp>’, the special character escape
sequence for the minus sign glyph.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.nr a 1
.ec -
.de xx
-Ena
..
.xx
⇒ 1
</pre></div></div>
</dd></dl>
</div>
<hr>
<div class="nav-panel">
<p>
Previous: <a href="Parameters.html">Parameters</a>, Up: <a href="Writing-Macros.html">Writing Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Request-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
