-
Notifications
You must be signed in to change notification settings - Fork 4
/
part2-1-4.xml
301 lines (300 loc) · 14.1 KB
/
part2-1-4.xml
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
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
<?xml version="1.0" encoding="UTF-8"?>
<html>
<head>
<meta http-equiv="Content-Type" content="text/xml; charset=utf-8"/>
<title>Macros</title>
<link rel="stylesheet" href="css/book.css" type="text/css"/>
</head>
<body>
<h3 id="macros">
Macros
</h3>
<p>
So far we've considered several different types of macros. A macro is usually a terse, two or three-character sequence
specified on a <a href="part2-1-1.xml#macro_line">macro line</a>. In this section I formalise the various types of
macros, categorised by their scope rules. As with many other languages, macros instructions are either scoped to one
line (following a single instruction), which I call in-line; or to multiple lines (bracketed between instructions),
which I call blocked. Block macros are usually invoked on a line of their own, as with <a class="macro"
href="macros.xml#macro_bd">Bd</a>, but may also be invoked within a line.
</p>
<p>
Generally speaking, a macro is syntactically defined as having a macro name, and optionally flags and with optional flag
arguments. The arguments to a macro depend on its scope rules.
</p>
<div class="mdocsyntax">
<span class="macro">Name</span>
<span class="macroopt">
<span class="macroflag">Flag</span>
<span class="macroopt">
<span class="macroarg">Arg</span>
</span>
</span>
</div>
<p>
The hyphen <span class="screen">-</span> indicates a macro flag only when the preceding macro accepts arguments.
</p>
<h4 id="inline_macros">
In-line Macro
</h4>
<p>
An in-line macro's arguments are scoped to the current line. Its scope may also be closed out by subsequent macros: an
in-line macro can never contain a nested macro. For a complete reference, see <a class="external"
href="http://mdocml.bsd.lv/man/mdoc.7.html#x496e2d6c696e65">In-Line</a> macros in the <a class="external lang"
href="http://mdocml.bsd.lv/man/mdoc.7.html">mdoc</a> reference.
</p>
<div class="mdocsyntax">
<span class="macro">Name</span>
<span class="macroopt">
<span class="macroflag">Flag</span>
<span class="macroopt">
<span class="macroarg">Flag Arg</span>
</span>
</span>
<span class="macroopt">
<span class="macroarg">Arg...</span>
</span>
</div>
<p>
Not all in-line macros accept arguments, and some in-line macros accept a fixed number of arguments.
</p>
<p>
For example, the regular way of structuring command-line arguments, as described initially in the <a
href="part1-2-2.xml#elaborate_function">Elaborate Function</a> guide, is a command flag, followed by flag
arguments, followed by regular arguments. We can put most invocation forms on one line as follows.
</p>
<div class="mdocsyntax">
.<span style="border: 1px dashed green; padding: 2px;"><a class="macro" href="macros.xml#macro_op">Op</a>
<span style="border: 1px solid blue;"><a class="macro" href="macros.xml#macro_ar">Fl</a>
<span class="macroarg">W</span></span>
<span style="border: 1px solid blue;"><a class="macro" href="macros.xml#macro_ns">Ns</a></span>
<span style="border: 1px solid blue;"><a class="macro" href="macros.xml#macro_ar">Ar</a>
<span class="macroarg">level</span></span>
</span>
</div>
<p>
In this example, <a href="macros.xml#macro_ar" class="macro">Ar</a>, <a href="macros.xml#macro_fl"
class="macro">Fl</a>, and <a href="macros.xml#macro_ns" class="macro">Ns</a> are in-line macros. The <a
href="macros.xml#macro_op" class="macro">Op</a> is a block partial-implicit. The <a
href="macros.xml#macro_fl" class="macro">Fl</a> macro opens within the <a href="macros.xml#macro_op"
class="macro">Op</a> and is closed by the <a href="macros.xml#macro_ns" class="macro">Ns</a>, which accepts no
arguments at all. This suppresses the space between the flag and its arguments (this alternative style is used at
times, but discouraged). The arguments are opened by <a href="macros.xml#macro_ar" class="macro">Ar</a> and close at
the end of the line.
</p>
<p>
The following is an example of macros with a fixed number of arguments:
</p>
<div class="mdocsyntax">
.<span style="border: 1px solid blue;"><a class="macro" href="macros.xml#macro_xr">Xr</a>
<span class="macroarg">mandoc</span>
<span class="macroarg">1</span></span>
<span style="border: 1px solid blue;"><a class="macro" href="macros.xml#macro_ap">Ap</a></span>
s
</div>
<p>
The <a class="macro" href="macros.xml#macro_xr">Xr</a> macro accepts the <span class="macroarg">mandoc</span> and
<span class="macroarg">1</span> arguments, then reverts to accepting text. The <a class="macro"
href="macros.xml#macro_ap">Ap</a> accepts no arguments, so it immediately reverts to the trailing text.
</p>
<p>
Finally, an example of an in-line macro accepting flags follows:
</p>
<div class="mdocsyntax">
.<span style="border: 1px solid blue;"><a class="macro" href="macros.xml#macro_st">St</a>
<span class="macroflag">ansiC</span></span>
</div>
<p>
The argument to <a class="macro" href="macros.xml#macro_st">St</a> specifies the standard to be printed.
</p>
<h4 id="block_partial_implicit">
Block Partial Implicit
</h4>
<p>
A block partial macro is similar to an <a href="#inline_macros">in-line macro</a> in that its scope is restricted to the
current line: it is <i>implicitly</i> closed by the end of line (as opposed to <a href="#block_partial_explicit">block
partial explicit</a> macros) and <i>partial</i> in that it only extends to the current line (as opposed to <a
href="#block_full_implicit">block full implicit</a> macros). Unlike an in-line macro, it accepts nested macros
(hence <i>block</i> macro). For a complete reference, see <a class="external"
href="http://mdocml.bsd.lv/man/mdoc.7.html#x426c6f636b207061727469616c2d696d706c69636974">Block Partial Implicit</a>
macros in the <a class="external lang" href="http://mdocml.bsd.lv/man/mdoc.7.html">mdoc</a> reference.
</p>
<div class="mdocsyntax">
<span class="macro">Name</span>
<span class="macroopt">
<span class="macroflag">Flag</span>
<span class="macroopt">
<span class="macroarg">Flag Arg</span>
</span>
</span>
<span class="macroopt">
<span class="macroarg">Arg|Macro...</span>
</span>
</div>
<p>
The scope of a partial block macro is always closed by the end of the line; any macros between it and the end of line
are interpreted as nested macros. We began this book with the block partial implicit macro <a class="macro"
href="macros.xml#macro_qq">Qq</a>. The nested qualities of this macro category may be seen by embedding <a
class="macro" href="macros.xml#macro_qq">Qq</a> and <a class="macro" href="macros.xml#macro_pq">Pq</a>
</p>
<div class="mdocsyntax">
.<span style="border: 1px dashed green; padding: 2px;"><a class="macro" href="macros.xml#macro_pq">Pq</a>
<span style="border: 1px solid blue;"><a class="macro" href="macros.xml#macro_qq">Qq</a>
<span class="macroarg">Parenthesised quotation .</span>
</span>
</span>
</div>
<p>
Be warned. If you open but do not close a <a href="#block_partial_explicit">block partial explicit</a> macro before the
end of the line, behaviour is not always well-defined as the scope is broken.
</p>
<h4 id="block_full_implicit">
Block Full Implicit
</h4>
<p>
A macro seen early on, the <a class="macro" href="macros.xml#macro_sh">Sh</a> macro, is block full implicit. Unlike
<a href="#block_partial_implicit">block partial implicit</a> macros, these consist of multiple lines (they are
<i>blocks</i>) and treat the line arguments and multi-line arguments differently (<i>full</i>).
For a complete reference, see <a class="external"
href="http://mdocml.bsd.lv/man/mdoc.7.html#x426c6f636b2066756c6c2d696d706c69636974">Block Full Implicit</a>
macros in the <a class="external lang" href="http://mdocml.bsd.lv/man/mdoc.7.html">mdoc</a> reference.
</p>
<div class="mdocsyntax">
.<span class="macro">Begin</span>
<span class="macroopt">
<span class="macroflag">Flag</span>
<span class="macroopt">
<span class="macroarg">Flag Arg</span>
</span>
</span>
<span class="macroopt">
<span class="macroarg">Arg...</span>
</span>
<br />
<span class="macroopt">
<span class="macroarg">Arg...</span>
</span>
</div>
<p>
The scope of <span class="macro">Begin</span> is closed out implicitly — by one of several possible macros or the
end of file. The notion of a <i>full</i> macro is obvious when considering <a class="macro"
href="macros.xml#macro_sh">Sh</a>:
</p>
<div class="mdocsyntax">
<div style="border: 1px solid blue; padding: 2px;">
.<span style="border: 1px dashed green;"><a class="macro" href="macros.xml#macro_st">Sh</a>
<span class="macroargs">SECTION 1</span></span>
<br style="margin: 2px;" />
<span style="border: 1px dashed green;">Sectional text.</span>
</div>
<div style="border: 1px solid blue; padding: 2px;">
.<span style="border: 1px dashed green;"><a class="macro" href="macros.xml#macro_st">Sh</a>
<span class="macroargs">SECTION 2</span></span>
<br style="margin: 2px;" />
<span style="border: 1px dashed green;">Sectional text.</span>
</div>
</div>
<p>
In this, the macro must separately decorate its line arguments and multi-line arguments. In this case, the line
arguments must be bolded while the multi-line arguments must be indented. The <a class="macro"
href="macros.xml#macro_sh">Sh</a> macro is closed out by a subsequent <a class="macro"
href="macros.xml#macro_sh">Sh</a> or the end of file. Compare this to <a class="macro"
href="macros.xml#macro_ss">Ss</a>, which closes out with a subsequent <a class="macro"
href="macros.xml#macro_sh">Sh</a>, <a class="macro" href="macros.xml#macro_ss">Ss</a>, or end of file.
</p>
<h4 id="block_partial_explicit">
Block Partial Explicit
</h4>
<p>
The simplest multi-line macro is the block partial explicit, which is opened and closed by two separate
(<i>explicit</i>) macros. It is <i>partial</i> because it does not differentiate between arguments on the current line
or subsequent lines, as opposed to <a href="#block_full_explicit">block full explicit</a> macros. The pair of macros
involved in a full block macro are called the beginning and ending macros.
For a complete reference, see <a class="external"
href="http://mdocml.bsd.lv/man/mdoc.7.html#x426c6f636b207061727469616c2d6578706c69636974">Block Partial Explicit</a>
macros in the <a class="external lang" href="http://mdocml.bsd.lv/man/mdoc.7.html">mdoc</a> reference.
</p>
<div class="mdocsyntax">
.<span class="macro">Begin</span>
<span class="macroopt">
<span class="macroflag">Flag</span>
<span class="macroopt">
<span class="macroarg">Flag Arg</span>
</span>
</span>
<span class="macroopt">
<span class="macroarg">Arg...</span>
</span>
<br />
<span class="macroopt">
<span class="macroarg">Arg...</span>
</span>
<br />
.<span class="macro">End</span>
</div>
<p>
One must be careful, in full block macros, not to break the scope of other block macros, or behaviour is undefined.
</p>
<p>
We have not yet considered a block partial explicit macro pair in this book. But we can do so by considering <a
href="macros.xml#macro_oo" class="macro">Oo</a> and <a class="macro" href="macros.xml#macro_oc">Oc</a>. This pair of
macros, for option open and option close, extend the behaviour of <a href="macros.xml#macro_op" class="macro">Op</a>
to multiple lines.
</p>
<div class="mdocsyntax">
.<a class="macro" href="macros.xml#macro_fl">Fl</a>
<span class="macroarg">W</span>
<a class="macro" href="macros.xml#macro_oo">Oo</a>
<br />
<span class="macroarg">warn</span>|<span class="macroarg">error</span>|<span class="macroarg">fatal</span>
<br />
.<a class="macro" href="macros.xml#macro_oc">Oc</a>
</div>
<h4 id="block_full_explicit">
Block Full Explicit
</h4>
<p>
The block full explicit macros are <i>full</i> in the sense that arguments on the macro line and arguments following are
treated differently (like <a href="#block_full_implicit">block full implicit</a> macros). The earliest example of this
is the <a href="macros.xml#macro_bl" class="macro">Bl</a>. These macros are <i>explicitly</i> closed by a closing
macro and may contain nested macros. For a complete reference, see <a class="external"
href="http://mdocml.bsd.lv/man/mdoc.7.html#x426c6f636b2066756c6c2d6578706c69636974">Block Full Explicit</a> macros
in the <a class="external lang" href="http://mdocml.bsd.lv/man/mdoc.7.html">mdoc</a> reference.
</p>
<p>
Consider the <a href="macros.xml#macro_bd" class="macro">Bd</a> macro, which does not accept line arguments (most
block full explicit macros do not accept line arguments). It is manually closed by <a href="macros.xml#macro_ed"
class="macro">Ed</a>.
</p>
<div class="mdocsyntax">
<div style="border: 1px solid blue; padding: 2px;">
.<span style="border: 1px dashed green;"><a class="macro" href="macros.xml#macro_bd">Bd</a>
<span class="macroflag">ragged</span>
<span class="macroflag">offset</span>
<span class="macroargs">indent</span></span>
<div style="border: 1px dashed green; margin: 2px;">
Display text.
<br />
More display text.
</div>
.<a class="macro" href="macros.xml#macro_ed">Ed</a>
</div>
</div>
<p>
In this example, the text between the <a class="macro" href="macros.xml#macro_bd">Bd</a> and <a class="macro"
href="macros.xml#macro_ed">Ed</a> are treated specially.
</p>
<table class="nav">
<tbody>
<tr>
<td class="nav-contents"><a href="toc.xml">Contents</a></td>
<td class="nav-next"><a href="part2-1-5.xml">Next</a></td>
<td class="nav-home"><a href="http://manpages.bsd.lv/index.html">Home</a></td>
<td class="nav-history"><a href="http://manpages.bsd.lv/cgi-bin/cvsweb/part2-1-4.xml?cvsroot=manpages">History</a></td>
</tr>
</tbody>
</table>
<p class="edits">
Last edited by $Author$ on $Date$. Copyright © 2011, Kristaps Dzonsons. CC BY-SA.
</p>
</body>
</html>