-
Notifications
You must be signed in to change notification settings - Fork 4
/
part1-1-1.xml
337 lines (336 loc) · 12.5 KB
/
part1-1-1.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
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
<?xml version="1.0" encoding="UTF-8"?>
<html>
<head>
<meta http-equiv="Content-Type" content="text/xml; charset=utf-8"/>
<title>Simple Command</title>
<link rel="stylesheet" href="css/book.css" type="text/css"/>
</head>
<body>
<h3>
Simple Command
</h3>
<p>
Consider a simple UNIX command <span class="cmd">hi</span> that prints <span class="screen">hello, world</span> and
exits. Let's create a manual page <span class="file">hi.1</span> documenting this command. In this example, I'll begin
with the full manual. In later examples, we'll build up the manual piece by piece.
</p>
<div class="mdocin">
.Dd May 30, 2011
<br />
.Dt HI 1
<br />
.Os
<br />
.Sh NAME
<br />
.Nm hi
<br />
.Nd print \(dqhello, world\(dq
<br />
.Sh SYNOPSIS
<br />
.Nm
<br />
.Sh DESCRIPTION
<br />
Print
<br />
.Qq hello, world
<br />
and exit.
</div>
<p>
How to display this manual page depends on the system you're using.
</p>
<p>
Traditionally, the command for formatting UNIX manuals for a <a class="term" href="glossary.xml#terminal">terminal</a>
is <a class="cmd" href="commands.xml#cmd_nroff">nroff</a>. For now, let's stick with that.
</p>
<p>
To display output, you must invoke <a href="commands.xml#cmd_nroff" class="cmd">nroff</a> as <span class="cmdline">nroff
-mandoc file</span>. The <span class="cmdflag">mandoc</span> flag indicates that input is in <span
class="lang">mdoc</span>. Hereafter, I'll refer to <a href="commands.xml#cmd_nroff" class="cmd">nroff</a>
simply as <q>the formatter</q> to avoid confusion, as there are many available <span class="lang">mdoc</span>
formatters.
</p>
<div class="mdocout">
<div class="mdoc-section">
<h1>NAME</h1>
<b class="mdoc-name">hi</b> — <span class="mdoc-desc">print "hello, world"</span>
</div>
<div class="mdoc-section">
<h1>SYNOPSIS</h1>
<table class="mdoc-synopsis">
<col style="width: 2.00ex;"/>
<col/>
<tbody>
<tr>
<td>
hi
</td>
<td>
</td>
</tr>
</tbody>
</table>
</div>
<div class="mdoc-section">
<h1>DESCRIPTION</h1>
Print “hello, world” and exit.
</div>
</div>
<p>
Let's start by studying the input and output. We can see most of the text translated into output, for instance, the
capitalised <span class="screen">NAME</span> input is left-justified and in bold text. Same with <span class="screen">
SYNOPSIS</span> and <span class="screen">DESCRIPTION</span>, although the <span class="screen">.Sh</span> text
before this terms is missing. We can even see the output sentence <span class="screen">Print "hello, world" and
exit</span> spread over lines 10–12:
</p>
<div class="mdocin">
Print
<br />
.Qq hello, world
<br />
and exit.
</div>
<p>
Let's take a closer look at this fragment.
</p>
<p>
The <span class="screen">.Qq</span> is part of <span class="lang">mdoc</span>'s instruction syntax. Input lines
beginning with a dot are instructions to the formatter called mdoc macros, or just macros for short. The macro name is
a terse two or three-character word following the dot, for example, <a href="macros.xml#macro_qq" class="macro">Qq</a>.
The name of a macro tersely hints at its function. The words following the <a href="macros.xml#macro_qq"
class="macro">Qq</a> to the end of line are arguments in the scope of the macro.
</p>
<p>
Scope, a technical term in the field of programming languages, refers to the body of input within the context of an
instruction or variable. In <span class="lang">mdoc</span>, a macro's scope is the block of text and instructions in
the formatting context of that macro. Looking at the input and output, we can infer the scope of <a
href="macros.xml#macro_qq" class="macro">Qq</a> by seeing what's surrounded by quotes (the formatting, in this
case).
</p>
<div class="mdocin">
.Qq <span style="border: thin solid blue;">hello, world</span>
</div>
<div class="mdocout">
<div class="mdoc-section">
Print “<span style="border: thin solid blue;">hello, world</span>” and exit.
</div>
</div>
<p>
As we explore more and more macros in this book, we'll see that each macro follows one of a handful of scope rules.
It's already clear that <a href="macros.xml#macro_qq" class="macro">Qq</a> is limited in scope to its invocation line.
But notice that the formatter recognised the content between <a href="macros.xml#macro_sh" class="macro">Sh</a> macros
as requiring indentation. So it's clear that <span class="lang">mdoc</span> also has a concept of multi-line scope. In
fact, <a href="macros.xml#macro_sh" class="macro">Sh</a> has both line arguments, for the name of the section; and
multi-line arguments, for section content.
</p>
<div class="mdocin">
.Sh SECTION 1
<br />
Section text.
<br />
.Sh SECTION 2
<br />
New section text.
</div>
<p>
Furthermore, the existence of <a href="macros.xml#macro_qq" class="macro">Qq</a> within the <a
href="macros.xml#macro_sh" class="macro">Sh</a> scope means that scopes may be nested. In the next section
we'll see how multiple macros may even be specified on a single line.
</p>
<div class="mdocin">
.Sh SECTION 1
<br />
Section text.
<br />
.Sh SECTION 2
<br />
.Qq Section text nested in a quote.
</div>
<p>
We can visualise this scoping as follows, with an <span style="border: 1px dashed green; padding: 1px;">outer scope</span>
and <span style="border: 1px solid blue; padding: 1px;">inner scope</span>:
</p>
<div class="mdocin" style="border: 1px dashed green; padding: 2px;">
.Sh SECTION 2
<br />
.Qq <span style="border: 1px solid blue;">Section text nested in a quote.</span>
</div>
<p>
Now let's return to <span class="file">hi.1</span> with this new knowledge of macros and scopes.
</p>
<p>
We see seven macros in total, <a href="macros.xml#macro_dd" class="macro">Dd</a>, <a href="macros.xml#macro_dt"
class="macro">Dt</a>, <a href="macros.xml#macro_os" class="macro">Os</a>, <a href="macros.xml#macro_sh"
class="macro">Sh</a>, <a href="macros.xml#macro_nm" class="macro">Nm</a>, <a href="macros.xml#macro_nd"
class="macro">Nd</a>, and <a href="macros.xml#macro_qq" class="macro">Qq</a>. We know now that <a
href="macros.xml#macro_qq" class="macro">Qq</a> encloses its arguments in double-quotes, <a
href="macros.xml#macro_sh" class="macro">Sh</a> begins a named section with indented multi-line arguments.
</p>
<p>
Of the remaining macros, <a href="macros.xml#macro_dd" class="macro">Dd</a> accepts the last modification date of the
manual in <q>month day, year</q> format. <a href="macros.xml#macro_dt" class="macro">Dt</a> refers to the manual's
title, <span class="screen">HI</span>, and its category, <span class="cat">1</span>.
Numbered manual categories are UNIX conventions, but applicable to any operating system. We'll explore more standard
categories throughout this book. Note that <span class="screen">HI</span> is uppercase: by convention, <a
href="macros.xml#macro_dt" class="macro">Dt</a> should always accept a capitalised document title. We'll talk
more about titles and sections in later chapters of this book. For now, let's assume that a category number identifies
the topic of the manual, where <span class="cat">1</span> refers to utilities.
</p>
<p>
Next, <a href="macros.xml#macro_os" class="macro">Os</a> indicates the operating system of the system running the
formatter. If left unspecified, the formatter will return the current operating system (e.g., <span
class="screen">OpenBSD 4.9</span>, <span class="screen">Linux 2.6.32-5</span>, or <span class="screen">Microsoft
Windows XP</span>).
</p>
<div class="mdocin">
.Dd May 30, 2011
<br />
.Dt HI 1
<br />
.Os \" Current operating system.
</div>
<p>
Note that text following the <span class="screen">\"</span> marker is an <span class="lang">mdoc</span> comment,
which has the following syntax:
</p>
<div class="mdocin">
Text. \" Comment to end of the line.
<br />
.\" Extending across the full line.
</div>
<p>
Comments are line-scoped, like <a href="macros.xml#macro_qq" class="macro">Qq</a>:
</p>
<div class="mdocin">
.\" <span style="border: thin solid blue;">.Sh NAME</span>
</div>
<p>
Moving along, <a href="macros.xml#macro_nm" class="macro">Nm</a> accepts the manual's name. This differs from the
title, <a href="macros.xml#macro_dt" class="macro">Dt</a>, in that a single manual may document multiple components.
We'll see examples of this in later chapters. Finally, <a href="macros.xml#macro_nd" class="macro">Nd</a> accepts a
brief, one-line description of the command.
</p>
<div class="mdocin">
.Sh NAME
<br />
.Nm hi
<br />
.Nd print \(dqhello, world\(dq
</div>
<p>
You can see that we re-invoke <a href="macros.xml#macro_nm" class="macro">Nm</a> in the <span
class="sec">SYNOPSIS</span>, only without arguments. The formatter is smart enough to fill in its argument
with the last supplied argument, in this case being <span class="screen">hi</span>.
</p>
<p>
Since our simple command has no command-line arguments, its invocation is simply the command name.
</p>
<div class="mdocin">
.Sh SYNOPSIS
<br />
.Nm
</div>
<p>
Piecing this all together, we now have the following.
</p>
<div class="mdocin">
.Dd May 30, 2011
<br />
.Dt HI 1
<br />
.Os
<br />
.Sh NAME
<br />
.Nm hi
<br />
.Nd print \(dqhello, world\(dq
<br />
.Sh SYNOPSIS
<br />
.Nm
<br />
.Sh DESCRIPTION
<br />
Print
<br />
.Qq hello, world
<br />
and exit.
</div>
<p>
In this example, you've noticed that <span class="screen">\(dqhello, world\(dq</span> has the same behaviour of the <a
href="macros.xml#macro_qq" class="macro">Qq</a> invocation. In <span class="lang">mdoc</span>, quotation
marks signify literal strings. Thus, we used an escape character <span class="screen">\(dq</span> to render <span
class="screen">"</span>.
</p>
<p>
You may ask why not just use <a href="macros.xml#macro_qq" class="macro">Qq</a>, such as
</p>
<div class="mdocin">
.Nd print
<br />
.Qq hello, world
</div>
<p>
For the time being, assume that <a href="macros.xml#macro_nd" class="macro">Nd</a> must have its scope on the
invocation line. Strictly-speaking, we could have written
</p>
<div class="mdocin">
.Nd print "hello, world"
</div>
<p>
but this encourages dangerous behaviour in assuming that quoted arguments may not affect output. This isn't always the
case! We'll see later how quoted terms on macro lines change the grouping of arguments — at times non-intuitively.
</p>
<p>
Before moving on to the next section, let's look quickly over our checklist for a well-formed manual.
</p>
<dl>
<dt>Did I describe the calling syntax of the command?</dt>
<dd>Yes. It was only the name of the macro (no arguments or flags).</dd>
<dt>Did I describe each flag and argument of the command?</dt>
<dd>There were none, so yes.</dd>
<dt>Did I describe the command's operation?</dt>
<dd>Yes, it prints <span class="screen">hello, world</span> and exits.</dd>
<dt>Did I describe the command's exit status?</dt>
<dd>No, we only mentioned that it exits.</dd>
<dt>Did I describe referenced files and environment variables?</dt>
<dd>This is not applicable.</dd>
</dl>
<p>
To the effect of the exit status, let's modify the <span class="sec">DESCRIPTION</span> slightly for clarity.
</p>
<div class="mdocin">
.Sh DESCRIPTION
<br />
Print
<br />
.Qq hello, world
<br />
and exit 0.
</div>
<p>
Of course, our command must actually do so! For simplicity's sake, let's assume that this is the case.
</p>
<p>
With our simple, well-documented example in mind, let's move on to a more realistic UNIX command.
</p>
<table class="nav">
<tbody>
<tr>
<td class="nav-contents"><a href="toc.xml">Contents</a></td>
<td class="nav-next"><a href="part1-1-2.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/part1-1-1.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>