-
Notifications
You must be signed in to change notification settings - Fork 4
/
part1-2-1.xml
194 lines (194 loc) · 6.89 KB
/
part1-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
<?xml version="1.0" encoding="UTF-8"?>
<html>
<head>
<meta http-equiv="Content-Type" content="text/xml; charset=utf-8"/>
<title>Simple Function</title>
<link rel="stylesheet" href="css/book.css" type="text/css"/>
</head>
<body>
<h3>
Simple Function
</h3>
<p>
Let's study a simple C function, <span class="func">hi</span>, which prints <span class="screen">hello, world</span>
just like in prior sections. We begin with the familiar first macros.
</p>
<div class="mdocin">
.Dd May 30, 2011
<br />
.Dt HI 3
<br />
.Os
<br />
.Sh NAME
<br />
.Nm hi
<br />
.Nd print \(dqhello, world\(dq
</div>
<p>
All that's changed is the manual category, from <span class="cat">1</span> to <span class="cat">3</span>. We'll discuss
manual categories later in this book. Suffice to say that programming functions and libraries (not system calls!) are
in category <span class="cat">3</span>.
</p>
<p>
The calling syntax of our function is documented in the <span class="sec">SYNOPSIS</span> section. Assume that our
function prototype is within the header file <span class="file">hi.h</span> as <span class="screen">void
hi(void)</span>, which, in non-programming terms, declares that a function <span class="screen">hi</span>
accepts no arguments and does not return a value.
</p>
<div class="mdocin">
.Sh SYNOPSIS
<br />
.In hi.h
<br />
.Ft void
<br />
.Fn hi
</div>
<p>
This introduces three unfamiliar macros. The <a href="macros.xml#macro_in" class="macro">In</a> macro specifies an
include file that interfacing programmes will need to include. The <a href="macros.xml#macro_ft" class="macro">Ft</a>
and <a href="macros.xml#macro_fn" class="macro">Fn</a> macros collectively document the function (return) type and
function name. Since not all languages have return types, the <a href="macros.xml#macro_ft" class="macro">Ft</a>
macro is optional in this context.
</p>
<div class="mdocout">
<div class="mdoc-section">
<h1>SYNOPSIS</h1>
<b class="mdoc-includes">#include <<span class="mdoc-link-includes">hi.h</span>></b><p></p>
<i class="mdoc-ftype">void</i>
<br/>
<b class="mdoc-fname">hi</b>();
</div>
</div>
<p>
By now it comes as no surprise that <a href="macros.xml#macro_ft" class="macro">Ft</a> is scoped to the end of its
line, as is <a href="macros.xml#macro_fn" class="macro">Fn</a> in this example. In fact, both of these macros are
syntactically similar to the <a href="macros.xml#macro_ar" class="macro">Ar</a> and <a href="macros.xml#macro_fl"
class="macro">Fl</a> found in the first chapter: their scopes are closed by subsequent macros on the same line.
</p>
<p>
Since our function has no arguments or return values, all we need to do is add some bits in the <span
class="sec">DESCRIPTION</span> section to complete this manual.
</p>
<div class="mdocin">
.Dd May 30, 2011
<br />
.Dt HI 3
<br />
.Os
<br />
.Sh NAME
<br />
.Nm hi
<br />
.Nd print \(dqhello, world\(dq
<br />
.Sh SYNOPSIS
<br />
.In hi.h
<br />
.Ft void
<br />
.Fn hi
<br />
.Sh DESCRIPTION
<br />
The
<br />
.Fn hi
<br />
function prints
<br />
.Qq hello, world
<br />
and returns.
<br />
.Pp
<br />
It has no arguments.
</div>
<p>
Here, you'll notice a difference between a function and command manual. It's clear that we refer back to our invoked
command using <a href="macros.xml#macro_fn" class="macro">Fn</a> instead of <a href="macros.xml#macro_nm"
class="cmd">Nm</a>. Why is this? The <a href="macros.xml#macro_nm" class="macro">Nm</a> macro, when used in
the body of a manual, refers to the command name, <i>not</i> the manual name, as we used <a href="macros.xml#macro_nm"
class="macro">Nm</a> to annotate that utility name in the <span class="sec">SYNOPSIS</span>. In functions, we
use the <a href="macros.xml#macro_fn" class="macro">Fn</a> macro. The difference is that <a href="macros.xml#macro_fn"
class="macro">Fn</a> won't repeat the manual name if used without arguments. This complexity is simply the
result of poor planning in the <span class="lang">mdoc</span> language.
</p>
<p>
Let's visualise the output so far:
</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>
<b class="includes">#include <<span class="link-includes">hi.h</span>></b>
<p></p>
<i class="ftype">void</i>
<br />
<b class="fname">hi</b>();
</div>
<div class="mdoc-section">
<h1>DESCRIPTION</h1>
The <b class="fname">hi</b>() function prints “hello, world” and returns.
<p></p>
It has no arguments.
</div>
</div>
<p>
Lastly, let's stipulate the function return value in its own section, <span class="sec">RETURN VALUES</span>. This
mirrors the <span class="sec">EXIT STATUS</span> introduced for <span class="file">hello.1</span>. Although we don't
have a return value, it's good practise to include this section anyway.
</p>
<div class="mdocin">
.Sh RETURN VALUES
<br />
The
<br />
.Fn hi
<br />
function does not return a value.
</div>
<p>
Although this example is instructive, it's quite simple. Let's review our checklist before moving on.
</p>
<dl>
<dt>Did I describe the preprocessing and linking information?</dt>
<dd>Yes, a header file. There is no linking information.</dd>
<dt>Did I describe the calling syntax of each function and variable?</dt>
<dd>Yes, the <span class="func">hi</span> function.</dd>
<dt>Did I describe the type of each function and variable?</dt>
<dd>Yes, as <span class="func">hi</span> has neither type nor value.</dd>
<dt>Did I describe each argument in each calling syntax?</dt>
<dd>This does not apply, as it has none.</dd>
<dt>Did I describe each function's operation?</dt>
<dd>Yes, in that it prints <span class="screen">hello, world</span>.</dd>
<dt>Did I describe each function's side effects?</dt>
<dd>This does not apply, as it has none.</dd>
</dl>
<p>
Very few real-world functions are so simple. In the next section, we introduce a more practical function with types and
arguments.
</p>
<table class="nav">
<tbody>
<tr>
<td class="nav-contents"><a href="toc.xml">Contents</a></td>
<td class="nav-next"><a href="part1-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/part1-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>