-
Notifications
You must be signed in to change notification settings - Fork 4
/
part1-3.xml
333 lines (333 loc) · 12.6 KB
/
part1-3.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
<?xml version="1.0" encoding="UTF-8"?>
<html>
<head>
<meta http-equiv="Content-Type" content="text/xml; charset=utf-8"/>
<title>Function Library</title>
<link rel="stylesheet" href="css/book.css" type="text/css"/>
</head>
<body>
<h2>
Function Library
</h2>
<p>
I've mentioned several times that the name provided to <a href="macros.xml#macro_nm" class="macro">Nm</a> doesn't
necessarily refer to the title of the manual in <a href="macros.xml#macro_dt" class="macro">Dt</a>. Let's study a
simple function library, using both <span class="func">hi</span> and <span class="func">hello</span>, which demonstrates
this concept.
</p>
<p>
A function library is a collection of object files, which consist mainly of programming functions, within a single file
called a library. On most <a class="term" href="glossary.xml#unix">UNIX</a> systems, you can find libraries installed
in <span class="path">/usr/lib</span> and/or <span class="path">/usr/local/lib</span>, ending in
<span class="file">.a</span>,
<span class="file">.la</span>,
<span class="file">.dylib</span>, or
<span class="file">.so</span> (followed by version numbers).
</p>
<p>
This example applies to any number of functions belonging to the same library — not necessarily all functions in
the library. In fact, one commonly finds large libraries spread over many manuals, each of which contain several
similar functions.
</p>
<p>
In general, it's not a good idea to document your library in one manpage: the best form is to have one manpage per
function (or associated functions).
Larger libraries will often have an <q>index</q>-style manpage, but that's different.
It's not a good idea because it requires the reader to grep through the page to find the function that interests them.
It might be easier for you to maintain one file when your API changes, but you might alienate users by requiring them to
jump through your manpage to find their function.
Keep the trade-off in mind!
</p>
<p>
For simplicity's sake, I'll call this C function library <span class="lib">libgreeting</span>, implying that the
installed library is called <span class="file">libgreeting.a</span> or <span class="file">libgreeting.so</span>. It
will consist of two header files, <span class="header">hi.h</span> and <span class="header">hello.h</span>, containing
the function prototypes for <span class="func">hi</span> and <span class="func">hello</span>, respectively.
</p>
<p>
Let's begin with the first few macros, which are also called the manual prologue.
</p>
<div class="mdocin">
.Dd May 30, 2011
<br />
.Dt GREETING 3
<br />
.Os
</div>
<p>
Note that I've changed the document title to be <span class="screen">GREETING</span> instead of choosing between
function names. This is because the manual documents the entire function library, not just one particular function. In
general, a function library should have its name not include the leading <q>lib</q>.
</p>
<p>
It's a good rule of thumb that the <a href="macros.xml#macro_dt" class="macro">Dt</a> title of your document matches
its filename.
</p>
<p>
Next, I'll list the names of the functions being documented. I also change the description of the manual to accomodate
for the functionality of both documented functions.
</p>
<div class="mdocin">
.Sh NAME
<br />
.Nm hello ,
<br />
.Nm hi
<br />
.Nd print greeting messages
</div>
<p>
Here I've used <a href="macros.xml#macro_nm" class="macro">Nm</a> twice to indicate that the manual documents two
functions. In doing so, I'll have to be careful when invoking <a href="macros.xml#macro_nm" class="macro">Nm</a> in
later parts of the manual, as it will produce <span class="screen">hello</span> if I don't specify a name, and this is
probably not desired (nor should it be depended upon, as I may re-order the names).
</p>
<p>
If we were only documenting a single function in a library, we would only assign <a href="macros.xml#macro_nm"
class="macro">Nm</a> and <a href="macros.xml#macro_nd" class="macro">Nd</a> to the relevant function and not
that of the library.
</p>
<p>
It's easiest to alphabetise the function names in the <span class="sec">NAME</span> section, but there are many ways to
order the names: order of importance, most often called, etc.
We must also be sure to comma-separate each name, leaving the last invocation without a comma. Let's look at the output so far.
</p>
<div class="mdocout">
<div class="mdoc-section">
<h1>NAME</h1>
<b class="mdoc-name">hello</b>,
<b class="mdoc-name">hi</b> — <span class="mdoc-desc">print greeting messages</span>
</div>
</div>
<p>
Even though that is hard to maintain and not very useful, some operating systems, for example FreeBSD and NetBSD,
require a <span class="sec">LIBRARY</span> section for base system libraries. For portable libraries,
do not include such a section.
</p>
<div class="mdocin">
.Sh LIBRARY
<br />
.Lb greeting
</div>
<p>
This uses the macro <a href="macros.xml#macro_lb" class="macro">Lb</a>, which accepts the name of the library
omitting the starting <q>lib</q>. This macro is not portable because the list of known library names is system
dependent, so it will produce different output on different systems, which is not desirable for a manual page.
</p>
<div class="mdocout">
<div class="mdoc-section">
<h1>NAME</h1>
<b class="mdoc-name">hello</b>,
<b class="mdoc-name">hi</b> — <span class="mdoc-desc">print greeting messages</span>
</div>
<div class="mdoc-section">
<h1>LIBRARY</h1>
<span class="mdoc-lib">library “greeting”</span>
</div>
</div>
<p>
The <span class="sec">SYNOPSIS</span> section will simply be a collection of the calling syntaxes for both functions,
which we've already studied. If we were only documenting one function, would list only that function here.
</p>
<div class="mdocin">
.Sh SYNOPSIS
<br />
.In hello.h
<br />
.Ft int
<br />
.Fo hello
<br />
.Fa "int C" "const char *prefix"
<br />
.Fc
<br />
.In hi.h
<br />
.Ft void
<br />
.Fn hi
</div>
<p>
Note that I've listed both include files prior to the function prototypes. This is familiar to C programmers, where
functions may have multiple include files that need a specific order. The functions are listed in the same order as
their <a href="macros.xml#macro_nm" class="macro">Nm</a> listing.
</p>
<p>
Let's examine the output so far.
</p>
<div class="mdocout">
<div class="mdoc-section">
<h1>NAME</h1>
<b class="mdoc-name">hello</b>,
<b class="mdoc-name">hi</b> — <span class="mdoc-desc">print greeting messages</span>
</div>
<div class="mdoc-section">
<h1>LIBRARY</h1>
<span class="mdoc-lib">library “greeting”</span>
</div>
<div class="mdoc-section">
<h1>SYNOPSIS</h1>
<b class="mdoc-includes">#include <<span class="mdoc-link-includes">hello.h</span>></b><br/>
<b class="mdoc-includes">#include <<span class="mdoc-link-includes">hi.h</span>></b><p></p>
<i class="mdoc-ftype">int</i><br/>
<b class="mdoc-fname">hello</b>(<i class="mdoc-farg">int C</i>, <i class="mdoc-farg">const char *prefix</i>);<p></p>
<i class="mdoc-ftype">void</i><br/>
<b class="mdoc-fname">hi</b>();
</div>
</div>
<p>
Already, a manual reader has lots of pertinent information: the name of the library, its header file, and the function
calling syntax. Let's continue in documenting the functions and their arguments, but this time, we'll do so in a
different style than before.
</p>
<p>
Instead of using lists, we describe each function as a free-form stream of text. We depend on the <span
class="sec">SYNOPSIS</span> to hint the reader as to the function argument types; there's no need to re-state
them.
</p>
<div class="mdocin">
.Sh DESCRIPTION
<br />
The
<br />
.Fn hi
<br />
and
<br />
.Fn hello
<br />
functions print out greeting messages.
<br />
.Pp
<br />
The
<br />
.Fn hi
<br />
function accepts no arguments and prints out
<br />
.Qq hello, world .
<br />
.Pp
<br />
The
<br />
.Fn hello
<br />
function accepts a value
<br />
.Fa C ,
<br />
which if non-zero indicates output should be uppercase; and
<br />
.Fa prefix ,
<br />
which, if non-NULL, shall be prefixed to the output.
<br />
The
<br />
.Fa prefix
<br />
argument, which may be NULL.
</div>
<p>
Notice how each sentence in this fragment ends on its own line, for example,
</p>
<div class="mdocin">
which, if non-NULL, shall be prefixed to the output.
<br />
The
<br />
.Fa prefix
</div>
<p>
By doing so, the formatter is able to recognise the end of sentence and correctly handle sentential spacing. In most
cases, this means adding two spaces between the period and subsequent text. From this follows a rule of thumb, <q>new
sentence, new line</q>.
</p>
<p>
In this <span class="sec">DESCRIPTION</span> we've captured what each function does and what its arguments are. What
remains are return values.
</p>
<div class="mdocin">
.Sh RETURN VALUES
<br />
The
<br />
.Fn hello
<br />
function returns 1 on success, 0 on failure.
</div>
<p>
If you're writing functions that returns -1 on failure (setting the <span class="var">errno</span>) and 0 on success
(such as a system call), then you can also use the <a href="macros.xml#macro_rv" class="macro">Rv</a> macro.
</p>
<p>
Let's collect these fragments into a single document and see if it's enough to use as a programming reference.
</p>
<div class="mdocout">
<div class="mdoc-section">
<h1>NAME</h1>
<b class="mdoc-name">hello</b>,
<b class="mdoc-name">hi</b> — <span class="mdoc-desc">print greeting messages</span>
</div>
<div class="mdoc-section">
<h1>LIBRARY</h1>
<span class="mdoc-lib">library “greeting”</span>
</div>
<div class="mdoc-section">
<h1>SYNOPSIS</h1>
<b class="mdoc-includes">#include <<span class="mdoc-link-includes">hello.h</span>></b>
<br/>
<b class="mdoc-includes">#include <<span class="mdoc-link-includes">hi.h</span>></b>
<p></p>
<i class="mdoc-ftype">int</i>
<br/>
<b class="mdoc-fname">hello</b>(<i class="mdoc-farg">int C</i>, <i class="mdoc-farg">const char *prefix</i>);
<p></p>
<i class="mdoc-ftype">void</i>
<br/>
<b class="mdoc-fname">hi</b>();
</div>
<div class="mdoc-section">
<h1>DESCRIPTION</h1>
The <b class="mdoc-fname">hi</b>() and <b class="mdoc-fname">hello</b>() functions print out greeting messages.
<p></p>
The <b class="mdoc-fname">hi</b>() function accepts no arguments and prints out “hello, world”.
<p></p>
The <b class="mdoc-fname">hello</b>() function accepts a value <i class="mdoc-farg">C</i>, which if non-zero indicates
output should be uppercase; and <i class="mdoc-farg">prefix</i>, which, if non-NULL, shall be prefixed to the output.
The <i class="mdoc-farg">prefix</i> argument, which may be NULL.
</div>
<div class="mdoc-section">
<h1>RETURN VALUES</h1>
The <b class="mdoc-fname">hello</b>() function returns 1 on success, 0 on failure.
</div>
</div>
<p>
We'll use our mental checklist as a guide. First we stipulated linking information with the <a
href="macros.xml#macro_lb" class="macro">Lb</a> macro. Then we introduced the calling syntax of each
function, naming their arguments. We also stipulated the necessary header files in the order they'd be included in
source files. In the <span class="sec">DESCRIPTION</span>, we described each function and its arguments in full.
Lastly, we documented return values in the <span class="sec">RETURN VALUES</span> section.
If the function does not return a value, there's no need to mention it.
</p>
<p>
From this information, a programmer should be able to interface with our library.
</p>
<table class="nav">
<tbody>
<tr>
<td class="nav-contents"><a href="toc.xml">Contents</a></td>
<td class="nav-next"><a href="part1-3-1.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-3.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>