-
Notifications
You must be signed in to change notification settings - Fork 4
/
part2-2-1.xml
300 lines (300 loc) · 13.1 KB
/
part2-2-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
<?xml version="1.0" encoding="UTF-8"?>
<html>
<head>
<meta http-equiv="Content-Type" content="text/xml; charset=utf-8"/>
<title>Prologue</title>
<link rel="stylesheet" href="css/book.css" type="text/css"/>
</head>
<body>
<h3>
Prologue
</h3>
<p>
The prologue consists at most of the <a href="macros.xml#macro_dd" class="macro">Dd</a>, <a
href="macros.xml#macro_dt" class="macro">Dt</a>, and <a href="macros.xml#macro_os" class="macro">Os</a>
macros. These always occur at the beginning of a manual.
</p>
<div class="mdocin">
.Dd May 26 2011
<br />
.Dt MDOC 7
<br />
.Os
</div>
<p>
The only firm requirement of the <span class="lang">mdoc</span> prologue is that the <a href="macros.xml#macro_dd"
class="macro">Dd</a> macro comes first: many formatting systems will read up to the first macro to determine the
formatting language. If <a href="macros.xml#macro_dd" class="macro">Dd</a> is not encountered first, the <span
class="lang">mdoc</span> format may not be recognised.
</p>
<p>
Following the <a href="macros.xml#macro_dd" class="macro">Dd</a>, the prologue is conventionally ordered as first <a
href="macros.xml#macro_dt" class="macro">Dt</a> and then <a href="macros.xml#macro_os" class="macro">Os</a>.
The <a href="macros.xml#macro_os" class="macro">Os</a> macro is usually left without arguments, meaning that the
manual applies to the current system.
</p>
<p>
After parsing the document prologue, the following is known:
</p>
<ul>
<li>The date of last modification.</li>
<li>The canonical title of the manual.</li>
<li>The manual category (<q>manual section</q>).</li>
<li>Whether the manual relates to a particular hardware architecture.</li>
<li>The relevant operating system.</li>
</ul>
<h4>
Date
</h4>
<p>
The date is specified by the <a href="macros.xml#macro_dd" class="macro">Dd</a> macro.
</p>
<div class="mdocsyntax">
.<a href="macros.xml#macro_dd" class="macro">Dd</a> <span class="macroarg">date</span>
</div>
<p>
While no particular date format is required, it's best to use the <span class="screen">month day, year</span> format,
where <span class="screen">month</span> is the month in English; <span class="screen">day</span> is the day of month;
and <span class="screen">year</span> is the four-digit year. Arbitrary white-space may separate the tokens, which may
also be quoted.
</p>
<p>
Example of canonical form:
</p>
<div class="mdocin">
.Dd June 03, 1991
</div>
<p>
Example of not zero-padded digit form:
</p>
<div class="mdocin">
.Dd June 3, 1991
</div>
<p>
Example of quoted-string form:
</p>
<div class="mdocin">
.Dd "June 3, 1991"
</div>
<p>
All of the above examples will normalise to the third of June, 1991. It's especially important that the month be in
English, as not all operating systems support localisation.
</p>
<p>
Some formatters also support a special date format as follows:
</p>
<div class="mdocin">
.Dd $Mdocdate$
</div>
<p>
This is usually used in conjunction with source-code control systems that automatically change the date. Consult your
formatter's manual for whether it supports this feature.
</p>
<h4>
Title
</h4>
<p>
A manual's title identifies the entire manual document. It is always specified in uppercase as the first argument of
the <a href="macros.xml#macro_dt" class="macro">Dt</a> macro, which conventionally follows the initial <a
href="macros.xml#macro_dd" class="macro">Dd</a> macro.
</p>
<div class="mdocsyntax">
.<a href="macros.xml#macro_dt" class="macro">Dt</a> <span class="macroarg">TITLE</span> <span
class="macroarg">category</span> <span class="macroopt"><span class="macroarg">architecture</span></span>
</div>
<p>
The title usually corresponds to the file-name of the document, but this is not necessarily the case.
</p>
<p>
In the case of a single-component manual, such as the manual for a single UNIX command or programming function, the
title corresponds to the manual name as specified with the <span class="sec">SYNOPSIS</span> <a
href="macros.xml#macro_nm" class="macro">Nm</a> macro argument.
</p>
<p>
In the event of multiple components, such as a programming library, the title usually corresponds to the library name.
If multiple commands are specified, such as with aliased names, the canonical form should be used.
</p>
<p>
Example of a title for the <a href="commands.xml#cmd_ls" class="cmd">ls</a> utility:
</p>
<div class="mdocin">
.Dt LS 1
</div>
<p>
Example of a title for the <span class="lib">libgreeting</span> function library, consisting of the <span
class="func">hi</span> and <span class="func">hello</span> functions:
</p>
<div class="mdocin">
.Dt GREETING 3
</div>
<p>
If the title is left unspecified by omitting the <a href="macros.xml#macro_dt" class="macro">Dt</a> macro, behaviour
is undefined. Usually a formatter will default to an empty string or <span class="screen">LOCAL</span>. In general,
however, a manual without <a href="macros.xml#macro_dt" class="macro">Dt</a> may be considered incomplete.
</p>
<h4>
Category
</h4>
<p>
The category of a manual, sometimes called the manual section, specifies the type of component a manual describes. It
is specified in the second argument of the <a href="macros.xml#macro_dt" class="macro">Dt</a> macro.
</p>
<div class="mdocsyntax">
.<a href="macros.xml#macro_dt" class="macro">Dt</a> <span class="macroarg">TITLE</span> <span
class="macroarg">category</span> <span class="macroopt"><span class="macroarg">architecture</span></span>
</div>
<p>
These categories are dictated by convention extending to the Version 1 AT&T UNIX <a class="term"
href="glossary.xml#unix_programmers_manual">Programmer's Manual</a>.
</p>
<blockquote cite="http://www.cs.bell-labs.com/who/dmr/1stEdman.html">
<p>
This manual is divided into seven sections:
</p>
<ol style="list-style-type: upper-roman">
<li>Commands</li>
<li>System calls</li>
<li>Subroutines</li>
<li>Special files</li>
<li>File formats</li>
<li>User-maintained programs</li>
<li>Miscellaneous</li>
</ol>
<p>
Commands are programs intended to be invoked directly by the user, in contradistinction to subroutines, which
are intended to be called by the user's programs. Commands generally reside in directory <span
class="under">bin</span> (for binary programs).
</p>
</blockquote>
<p>
These sections have been expanded and formalised in the intervening years, amounting to the following modern conventions.
</p>
<dl>
<dt><span class="cat">1</span>: user utilities.</dt>
<dd>
Most commands fall under this category. A user utility is usable by all operators of a UNIX system. Common
examples: <a href="commands.xml#cmd_ls" class="cmd">ls</a>, <a href="commands.xml#cmd_man" class="cmd">man</a>,
<a href="commands.xml#cmd_cat" class="cmd">cat</a>.
</dd>
<dt><span class="cat">2</span>: system calls.</dt>
<dd>
These are a special class of programming function, usually in C, that do not need header file or linking
information. Common examples: <span class="func">open</span>, <span class="func">close</span>, <span
class="func">write</span>.
</dd>
<dt><span class="cat">3</span>: user programming functions.</dt>
<dd>
Most functions fall under this category. A user programming function is available as standalone or library
function, although some, such as the C library, need not be explicitly linked. Common examples: <span
class="func">strcpy</span>, <span class="func">isascii</span>.
</dd>
<dt><span class="cat">4</span>: device interfaces.</dt>
<dd>
This category is not as common as categories <span class="cat">1</span>–<span class="cat">3</span>; in
fact, not all systems use this section at all. When used, it consists of manuals for hardware device drivers.
These manuals are usually tied to a particular architecture.
</dd>
<dt><span class="cat">5</span>: file formats.</dt>
<dd>
This category is not as common as categories <span class="cat">1</span>–<span class="cat">3</span>. When
used, it consists of structure text file documentation. Common example: <span class="file">passwd</span>.
</dd>
<dt><span class="cat">6</span>: games (and user utility miscellanea).</dt>
<dd>
This category is not as common as categories <span class="cat">1</span>–<span class="cat">3</span>, many
systems do not come pre-supplied with games. When used, it refers to games or arcana utilities.
</dd>
<dt><span class="cat">7</span>: miscellaneous.</dt>
<dd>
Introductory materials or general text. This category is common, but its contents vary from system to system.
</dd>
<dt><span class="cat">8</span>: administrative utilities.</dt>
<dd>
This consists of utilities for system administration, which may not be accessible or executable by general users
(see category <span class="cat">1</span>). Common examples: <a href="commands.xml#cmd_dump"
class="cmd">dump</a>, <a href="commands.xml#cmd_restore" class="cmd">restore</a>, <a
href="commands.xml#cmd_fsck" class="cmd">fsck</a>.
</dd>
<dt><span class="cat">9</span>: kernel programming functions.</dt>
<dd>
This category is found on few operating systems. Where applicable, it consists of those functions used in
operating system internal development (<q>kernel</q> development).
</dd>
</dl>
<p>
There are several refinements to the numerical category convention. Perl, Fortran, and Tcl libraries are often grouped
under category <span class="cat">3p</span>, <span class="cat">3f</span>, and <span class="cat">3tcl</span>,
respectively. Perl modules may also fall under <span class="cat">3pm</span>. Tcl libraries are also found in the <span
class="cat">n</span> category.
</p>
<p>
Although some common libraries are traditionally referred to with a custom suffix, such as <span class="cat">3ssl</span>
for the OpenSSL library, this notation is heavily discouraged.
</p>
<p>
Manuals for the X Window System, traditionally bundled with UNIX systems, are categorised under <span
class="cat">X11</span>. Manuals for the popular X11R6 distribution of the X Window System may also be listed
under <span class="cat">X11R6</span>.
</p>
<p>
The <span class="cat">paper</span> category historically consisted of longer papers, the <span class="cat">draft</span>
category consists of draft manuals, <span class="cat">unass</span> consists of uncategorised manuals, and <span
class="cat">local</span> consists of local system documentation. These categories are rarely used and should be
avoided for portable, readable manuals.
</p>
<h4>
Architecture
</h4>
<p>
Some manuals, especially those in category <span class="cat">4</span> or <span class="cat">9</span>, relate only to a
particular hardware architecture. This is a useful specifier in the machine-dependent manuals for category <span
class="cat">9</span> manuals.
</p>
<p>
These use the optional third argument of the <a href="macros.xml#macro_dt" class="macro">Dt</a> macro.
</p>
<div class="mdocsyntax">
.<a href="macros.xml#macro_dt" class="macro">Dt</a> <span class="macroarg">TITLE</span> <span
class="macroarg">category</span> <span class="macroopt"><span class="macroarg">architecture</span></span>
</div>
<p>
For a list of possible architectures, consult your local documentation. A safe example is <span
class="screen">i386</span>, for 32-bit x86-based systems; or <span class="screen">amd64</span> for 64-bit AMD
systems.
</p>
<p>
A device referring to a particular architecture uses this to explicitly note its relevant architecture. In normal
manuals, this should not be used.
</p>
<h4>
Operating System
</h4>
<p>
Similar to architecture, some manuals only pertain to a particular operating system. This system may be specified to
the <a href="macros.xml#macro_os" class="macro">Os</a> macro of the prologue.
</p>
<div class="mdocsyntax">
.<a href="macros.xml#macro_os" class="macro">Os</a> <span class="macroopt"><span class="macroarg">system</span></span>
</div>
<p>
If <span class="macroarg">system</span> is unspecified, the manual is assumed to apply to any operating system.
</p>
<p>
This form is useful when multiple operating systems have access to local-network administrative manuals, such as in a
networked file-system environment. Otherwise, it is rarely used.
</p>
<table class="nav">
<tbody>
<tr>
<td class="nav-contents"><a href="toc.xml">Contents</a></td>
<td class="nav-next"><a href="part2-2-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/part2-2-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>