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
257
258
259
260
261
262
263
264
265
266
267
|
<!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>Writing Macros (The GNU Troff Manual)</title>
<meta name="description" content="Writing Macros (The GNU Troff Manual)">
<meta name="keywords" content="Writing Macros (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="GNU-troff-Reference.html" rel="up" title="GNU troff Reference">
<link href="Page-Motions.html" rel="next" title="Page Motions">
<link href="Conditionals-and-Loops.html" rel="prev" title="Conditionals and Loops">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
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="section-level-extent" id="Writing-Macros">
<div class="nav-panel">
<p>
Next: <a href="Page-Motions.html" accesskey="n" rel="next">Page Motions</a>, Previous: <a href="Conditionals-and-Loops.html" accesskey="p" rel="prev">Conditionals and Loops</a>, Up: <a href="GNU-troff-Reference.html" accesskey="u" rel="up">GNU <code class="code">troff</code> Reference</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>
<h3 class="section" id="Writing-Macros-1">5.24 Writing Macros</h3>
<a class="index-entry-id" id="index-writing-macros"></a>
<a class="index-entry-id" id="index-macros_002c-writing"></a>
<p>A <em class="dfn">macro</em> is a stored collection of text and control lines that can
be interpolated multiple times. Use macros to define common operations.
Macros are called in the same way that requests are invoked. While
requests exist for the purpose of creating macros, simply calling an
undefined macro, or interpolating it as a string, will cause it to be
defined as empty. See <a class="xref" href="Identifiers.html">Identifiers</a>.
</p>
<dl class="first-deffn">
<dt class="deffn" id="index-_002ede"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.de</code></strong> <var class="def-var-arguments">name [<span class="r"><i class="slanted">end</i></span>]</var><a class="copiable-link" href='#index-_002ede'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-de"></a>
<p>Define a macro <var class="var">name</var>, replacing the definition of any existing
request, macro, string, or diversion called <var class="var">name</var>. If
<var class="var">name</var> already exists as an alias, the target of the alias is
redefined; recall <a class="ref" href="Strings.html">Strings</a>. GNU <code class="code">troff</code> enters copy
mode,<a class="footnote" id="DOCF97" href="groff.html_fot.html#FOOT97"><sup>97</sup></a> storing subsequent input lines as the
macro definition. If the optional second argument is not specified, the
definition ends with the control line ‘<samp class="samp">..</samp>’ (two dots).
Alternatively, <var class="var">end</var> identifies a macro whose call syntax at the
start of a control line ends the definition of <var class="var">name</var>; <var class="var">end</var> is
then called normally. A macro definition must end in the same
conditional block (if any) in which it began (see <a class="pxref" href="Conditional-Blocks.html">Conditional Blocks</a>). Spaces or tabs are permitted after the control character in
the line containing this ending token (either ‘<samp class="samp">.</samp>’ or
‘<samp class="samp"><var class="var">end</var></samp>’), but a tab immediately after the token prevents its
recognition as the end of a macro definition. The macro <var class="var">end</var> can
be called with arguments.<a class="footnote" id="DOCF98" href="groff.html_fot.html#FOOT98"><sup>98</sup></a>
</p>
<p>Here is a small example macro called ‘<samp class="samp">P</samp>’ that causes a break and
inserts some vertical space. It could be used to separate paragraphs.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.de P
. br
. sp .8v
..
</pre></div></div>
<p>We can define one macro within another. Attempting to nest ‘<samp class="samp">..</samp>’
navely will end the outer definition because the inner definition
isn’t interpreted as such until the outer macro is later interpolated.
We can use an end macro instead. Each level of nesting should use a
unique end macro.
</p>
<p>An end macro need not be defined until it is called. This fact enables
a nested macro definition to begin inside one macro and end inside
another. Consider the following example.<a class="footnote" id="DOCF99" href="groff.html_fot.html#FOOT99"><sup>99</sup></a>
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.de m1
. de m2 m3
you
..
.de m3
Hello,
Joe.
..
.de m4
do
..
.m1
know?
. m3
What
.m4
.m2
⇒ Hello, Joe. What do you know?
</pre></div></div>
<p>A nested macro definition <em class="emph">can</em> be terminated with ‘<samp class="samp">..</samp>’ and
nested macros <em class="emph">can</em> reuse end macros, but these control lines must
be escaped multiple times for each level of nesting. The necessity of
this escaping and the utility of nested macro definitions will become
clearer when we employ macro parameters and consider the behavior of
copy mode in detail.
</p></dd></dl>
<p><code class="code">de</code> defines a macro that inherits the compatibility mode
enablement status of its context (see <a class="pxref" href="Implementation-Differences.html">Implementation Differences</a>).
Often it is desirable to make a macro that uses <code class="code">groff</code> features
callable from contexts where compatibility mode is on; for instance,
when writing extensions to a historical macro package. To achieve this,
compatibility mode needs to be switched off while such a macro is
interpreted—without disturbing that state when it is finished.
</p>
<dl class="first-deffn">
<dt class="deffn" id="index-_002ede1"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.de1</code></strong> <var class="def-var-arguments">name [<span class="r"><i class="slanted">end</i></span>]</var><a class="copiable-link" href='#index-_002ede1'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-de1"></a>
<p>The <code class="code">de1</code> request defines a macro to be interpreted with
compatibility mode disabled. When <var class="var">name</var> is called, compatibility
mode enablement status is saved; it is restored when the call completes.
Observe the extra backlash before the interpolation of register
‘<samp class="samp">xxx</samp>’; we’ll explore this subject in <a class="ref" href="Copy-Mode.html">Copy Mode</a>.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.nr xxx 12345
.de aa
The value of xxx is \\n[xxx].
. br
..
.de1 bb
The value of xxx is \\n[xxx].
..
.cp 1
.aa
error→ warning: register '[' not defined
⇒ The value of xxx is 0xxx].
.bb
⇒ The value of xxx is 12345.
</pre></div></div>
</dd></dl>
<dl class="first-deffn">
<dt class="deffn" id="index-_002edei"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.dei</code></strong> <var class="def-var-arguments">name [<span class="r"><i class="slanted">end</i></span>]</var><a class="copiable-link" href='#index-_002edei'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-dei"></a>
</dd><dt class="deffnx def-cmd-deffn" id="index-_002edei1"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.dei1</code></strong> <var class="def-var-arguments">name [<span class="r"><i class="slanted">end</i></span>]</var><a class="copiable-link" href='#index-_002edei1'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-dei1"></a>
<p>The <code class="code">dei</code> request defines a macro with its name and end
macro indirected through strings. That is, it interpolates strings
named <var class="var">name</var> and <var class="var">end</var> before performing the definition.
</p>
<p>The following examples are equivalent.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.ds xx aa
.ds yy bb
.dei xx yy
</pre></div></div>
<div class="example">
<div class="group"><pre class="example-preformatted">.de aa bb
</pre></div></div>
<p>The <code class="code">dei1</code> request bears the same relationship to <code class="code">dei</code> as
<code class="code">de1</code> does to <code class="code">de</code>; it temporarily turns compatibility mode
off when <var class="var">name</var> is called.
</p></dd></dl>
<dl class="first-deffn">
<dt class="deffn" id="index-_002eam"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.am</code></strong> <var class="def-var-arguments">name [<span class="r"><i class="slanted">end</i></span>]</var><a class="copiable-link" href='#index-_002eam'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-am"></a>
</dd><dt class="deffnx def-cmd-deffn" id="index-_002eam1"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.am1</code></strong> <var class="def-var-arguments">name [<span class="r"><i class="slanted">end</i></span>]</var><a class="copiable-link" href='#index-_002eam1'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-am1"></a>
</dd><dt class="deffnx def-cmd-deffn" id="index-_002eami"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.ami</code></strong> <var class="def-var-arguments">name [<span class="r"><i class="slanted">end</i></span>]</var><a class="copiable-link" href='#index-_002eami'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-ami"></a>
</dd><dt class="deffnx def-cmd-deffn" id="index-_002eami1"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.ami1</code></strong> <var class="def-var-arguments">name [<span class="r"><i class="slanted">end</i></span>]</var><a class="copiable-link" href='#index-_002eami1'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-ami1"></a>
<a class="index-entry-id" id="index-appending-to-a-macro-_0028am_0029"></a>
<a class="index-entry-id" id="index-macro_002c-appending-to-_0028am_0029"></a>
<p><code class="code">am</code> appends subsequent input lines to macro <var class="var">name</var>, extending
its definition, and otherwise working as <code class="code">de</code> does.
</p>
<p>To make the previously defined ‘<samp class="samp">P</samp>’ macro set indented instead of
block paragraphs, add the necessary code to the existing macro.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.am P
.ti +5n
..
</pre></div></div>
<p>The other requests are analogous to their ‘<samp class="samp">de</samp>’ counterparts. The
<code class="code">am1</code> request turns off compatibility mode during interpretation of
the appendment. The <code class="code">ami</code> request appends indirectly, meaning that
strings <var class="var">name</var> and <var class="var">end</var> are interpolated with the resulting
names used before appending. The <code class="code">ami1</code> request is similar to
<code class="code">ami</code>, disabling compatibility mode during interpretation of the
appended lines.
</p></dd></dl>
<a class="index-entry-id" id="index-trace_002etmac"></a>
<p>Using <samp class="file">trace.tmac</samp>, you can trace calls to <code class="code">de</code>,
<code class="code">de1</code>, <code class="code">am</code>, and <code class="code">am1</code>. You can also use the
<code class="code">backtrace</code> request at any point desired to troubleshoot tricky
spots (see <a class="pxref" href="Debugging.html">Debugging</a>).
</p>
<p>See <a class="xref" href="Strings.html">Strings</a>, for the <code class="code">als</code>, <code class="code">rm</code>, and <code class="code">rn</code> requests to
create an alias of, remove, and rename a macro, respectively.
</p>
<a class="index-entry-id" id="index-object-creation"></a>
<p>Macro identifiers share their name space with requests, strings, and
diversions; see <a class="ref" href="Identifiers.html">Identifiers</a>. The <code class="code">am</code>, <code class="code">as</code>, <code class="code">da</code>,
<code class="code">de</code>, <code class="code">di</code>, and <code class="code">ds</code> requests (together with their
variants) create a new object only if the name of the macro, diversion,
or string is currently undefined or if it is defined as a request;
normally, they modify the value of an existing object. See <a class="xref" href="Strings.html#als">the
description of the <code class="code">als</code> request</a>, for pitfalls when redefining a
macro that is aliased.
</p>
<dl class="first-deffn">
<dt class="deffn" id="index-_002ereturn"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.return</code></strong> <var class="def-var-arguments">[<span class="r"><i class="slanted">anything</i></span>]</var><a class="copiable-link" href='#index-_002ereturn'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-return"></a>
<p>Exit a macro, immediately returning to the caller. If called with an
argument <var class="var">anything</var>, exit twice—the current macro and the macro
one level higher. This is used to define a wrapper macro for
<code class="code">return</code> in <samp class="file">trace.tmac</samp>.
</p></dd></dl>
<ul class="mini-toc">
<li><a href="Parameters.html" accesskey="1">Parameters</a></li>
<li><a href="Copy-Mode.html" accesskey="2">Copy Mode</a></li>
</ul>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Page-Motions.html">Page Motions</a>, Previous: <a href="Conditionals-and-Loops.html">Conditionals and Loops</a>, Up: <a href="GNU-troff-Reference.html">GNU <code class="code">troff</code> Reference</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>
|
