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
|
<!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>Calling Macros (The GNU Troff Manual)</title>
<meta name="description" content="Calling Macros (The GNU Troff Manual)">
<meta name="keywords" content="Calling 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="Formatter-Instructions.html" rel="up" title="Formatter Instructions">
<link href="Using-Escape-Sequences.html" rel="next" title="Using Escape Sequences">
<link href="Invoking-Requests.html" rel="prev" title="Invoking Requests">
<style type="text/css">
<!--
div.example {margin-left: 3.2em}
kbd.key {font-style: normal}
-->
</style>
</head>
<body lang="en">
<div class="subsection-level-extent" id="Calling-Macros">
<div class="nav-panel">
<p>
Next: <a href="Using-Escape-Sequences.html" accesskey="n" rel="next">Using Escape Sequences</a>, Previous: <a href="Invoking-Requests.html" accesskey="p" rel="prev">Invoking Requests</a>, Up: <a href="Formatter-Instructions.html" accesskey="u" rel="up">Formatter Instructions</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="Calling-Macros-1">5.6.3 Calling Macros</h4>
<a class="index-entry-id" id="index-calling-macros"></a>
<a class="index-entry-id" id="index-macro-arguments"></a>
<a class="index-entry-id" id="index-arguments-to-macros"></a>
<p>If a macro of the desired name does not exist when called, it is
created, assigned an empty definition, and a warning in category
‘<samp class="samp">mac</samp>’ is emitted. Calling an undefined macro <em class="emph">does</em> end a
macro definition naming it as its end macro (see <a class="pxref" href="Writing-Macros.html">Writing Macros</a>).
</p>
<a class="index-entry-id" id="index-spaces_002c-in-a-macro-argument"></a>
<p>To embed spaces <em class="emph">within</em> a macro argument, enclose the argument in
neutral double quotes <code class="code">"</code>. Horizontal motion escape sequences are
sometimes a better choice for arguments to be formatted as text.
</p>
<p>Consider calls to a hypothetical section heading macro ‘<samp class="samp">uh</samp>’.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.uh The Mouse Problem
.uh "The Mouse Problem"
.uh The\~Mouse\~Problem
.uh The\ Mouse\ Problem
</pre></div></div>
<a class="index-entry-id" id="index-_005c_007e_002c-difference-from-_005cSP"></a>
<a class="index-entry-id" id="index-_005cSP_002c-difference-from-_005c_007e"></a>
<p>The first line calls <code class="code">uh</code> with three arguments: ‘<samp class="samp">The</samp>’,
‘<samp class="samp">Mouse</samp>’, and ‘<samp class="samp">Problem</samp>’. The remainder call the <code class="code">uh</code>
macro with one argument, ‘<samp class="samp">The Mouse Problem</samp>’. The last solution,
using escaped spaces, can be found in documents prepared for
<abbr class="acronym">AT&T</abbr> <code class="code">troff</code>. It can cause surprise when text is
adjusted, because <code class="code">\<kbd class="key">SP</kbd></code> inserts a <em class="emph">fixed-width</em>,
non-breaking space. GNU <code class="code">troff</code>’s <code class="code">\~</code> escape sequence
inserts an adjustable, non-breaking space.<a class="footnote" id="DOCF44" href="groff.html_fot.html#FOOT44"><sup>44</sup></a>
</p>
<a class="index-entry-id" id="index-_0022_002c-embedding-in-a-macro-argument"></a>
<a class="index-entry-id" id="index-double-quote_002c-embedding-in-a-macro-argument"></a>
<a class="index-entry-id" id="index-_005c_002c-embedding-in-a-macro-argument"></a>
<a class="index-entry-id" id="index-backslash_002c-embedding-in-a-macro-argument"></a>
<p>The foregoing raises the question of how to embed neutral double quotes
or backslashes in macro arguments when <em class="emph">those</em> characters are
desired as literals. In GNU <code class="code">troff</code>, the special character escape
sequence <code class="code">\[rs]</code> produces a backslash and <code class="code">\[dq]</code> a neutral
double quote.
</p>
<p>In GNU <code class="code">troff</code>’s <abbr class="acronym">AT&T</abbr> compatibility mode, these
characters remain available as <code class="code">\(rs</code> and <code class="code">\(dq</code>,
respectively. <abbr class="acronym">AT&T</abbr> <code class="code">troff</code> did not consistently define
these special characters,
but its descendants can be made to support them. See <a class="xref" href="Device-and-Font-Description-Files.html">Device and Font Description Files</a>.
</p>
<p>If even that is not feasible, options remain. To obtain a literal
escape character in a macro argument, you can simply type it if you
change or disable the escape character first. See <a class="xref" href="Using-Escape-Sequences.html">Using Escape Sequences</a>. Otherwise, you must escape the escape character repeatedly
to a context-dependent extent. See <a class="xref" href="Copy-Mode.html">Copy Mode</a>.
</p>
<p>For the (neutral) double quote, you have recourse to an obscure
syntactical feature of <abbr class="acronym">AT&T</abbr> <code class="code">troff</code>. Because a double
quote can begin a macro argument, the formatter keeps track of whether
the current argument was started thus, and doesn’t require a space after
the double quote that ends it.<a class="footnote" id="DOCF45" href="groff.html_fot.html#FOOT45"><sup>45</sup></a> In
the argument list to a macro, a double quote that <em class="emph">isn’t</em> preceded
by a space <em class="emph">doesn’t</em> start a macro argument. If not preceded by a
double quote that began an argument, this double quote becomes part of
the argument. Furthermore, within a quoted argument, a pair of adjacent
double quotes becomes a literal double quote.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.de eq
. tm arg1:\\$1 arg2:\\$2 arg3:\\$3
. tm arg4:\\$4 arg5:\\$5 arg6:\\$6
.. \" 4 backslashes on the next line
.eq a" "b c" "de"f\\\\g" h""i "j""k"
error→ arg1:a" arg2:b c arg3:de
error→ arg4:f\g" arg5:h""i arg6:j"k
</pre></div></div>
<p>Apart from the complexity of the rules, this traditional solution has
the disadvantage that double quotes don’t survive repeated argument
expansion in <abbr class="acronym">AT&T</abbr> <code class="code">troff</code> or GNU <code class="code">troff</code>’s
compatibility mode. This can frustrate efforts to pass such arguments
intact through multiple macro calls.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.cp 1
.de eq
. tm arg1:\\$1 arg2:\\$2 arg3:\\$3
. tm arg4:\\$4 arg5:\\$5 arg6:\\$6
..
.de xe
. eq \\$1 \\$2 \\$3 \\$4 \\$5 \\$6
.. \" 8 backslashes on the next line
.xe a" "b c" "de"f\\\\\\\\g" h""i "j""k"
error→ arg1:a" arg2:b arg3:c
error→ arg4:de arg5:f\g" arg6:h""i
</pre></div></div>
<a class="index-entry-id" id="index-input-level"></a>
<a class="index-entry-id" id="index-level_002c-input"></a>
<a class="index-entry-id" id="index-interpolation-depth"></a>
<a class="index-entry-id" id="index-depth_002c-interpolation"></a>
<p>Outside of compatibility mode, GNU <code class="code">troff</code> doesn’t exhibit this
problem because it tracks the nesting depth of interpolations.
See <a class="xref" href="Implementation-Differences.html">Implementation Differences</a>.
</p>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Using-Escape-Sequences.html">Using Escape Sequences</a>, Previous: <a href="Invoking-Requests.html">Invoking Requests</a>, Up: <a href="Formatter-Instructions.html">Formatter Instructions</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>
|
