-
Notifications
You must be signed in to change notification settings - Fork 4
/
part1-1-3.xml
278 lines (278 loc) · 9.37 KB
/
part1-1-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
<?xml version="1.0" encoding="UTF-8"?>
<html>
<head>
<meta http-equiv="Content-Type" content="text/xml; charset=utf-8"/>
<title>Case Study</title>
<link rel="stylesheet" href="css/book.css" type="text/css"/>
</head>
<body>
<h3 id="case_study_cmd">
Case Study
</h3>
<p>
I now introduce a case study of a real-world manual, in particular the <a href="commands.xml#cmd_echo"
class="cmd">echo</a> utility from <a class="term" href="glossary.xml#openbsd">OpenBSD</a>. The original file
may be viewed on-line at <a class="external"
href="http://www.openbsd.org/cgi-bin/cvsweb/src/bin/echo/echo.1">src/bin/echo/echo.1</a>, file version 1.20. I
choose this mainly because of its simplicity.
</p>
<div class="mdocin">
.\" $​OpenBSD: echo.1,v 1.20 2010/09/03 09:53:20 jmc Exp $​
<br />
.\" $​NetBSD: echo.1,v 1.7 1995/03/21 09:04:26 cgd Exp $​
</div>
<p>
These initial comments are automatically created by the source-control system <a href="commands.xml#cmd_cvs"
class="cmd">cvs</a>, which fills in information about the last editor. I'll talk about revision control and
those funny dollar-sign enclosures in <a href="part3.xml">Part 3</a>. These particular comments indicate that the file
was initially imported from <a class="term" href="glossary.xml#netbsd">NetBSD</a> in 1995, where it was last edited by
<span class="screen">cgd</span> (a system name, not the user's real name). It was last edited in OpenBSD, its current
form, by <span class="screen">jmc</span> in 2010.
</p>
<p>
If you're keeping your manual under source control, it's usually a good idea to begin your file with a similar line.
</p>
<div class="mdocin">
.\" $​Id$
</div>
<p>
A tab character separates the comment marker from the text. Again, this will be covered later in this book —
don't worry if it looks strange.
</p>
<div class="mdocin">
.\" Copyright (c) 1990, 1993
<br />
.\" The Regents of the University of California. All rights reserved.
<br />
.\"
<br />
.\" This code is derived from software contributed to Berkeley by
<br />
.\" the Institute of Electrical and Electronics Engineers, Inc.
<br />
.\"
<br />
.\" Redistribution and use in source and binary forms, with or without
<br />
.\" modification, are permitted provided that the following conditions
<br />
.\" are met:
<br />
.\" 1. Redistributions of source code must retain the above copyright
<br />
.\" notice, this list of conditions and the following disclaimer.
<br />
.\" 2. Redistributions in binary form must reproduce the above copyright
<br />
.\" notice, this list of conditions and the following disclaimer in the
<br />
.\" documentation and/or other materials provided with the distribution.
<br />
.\" 3. Neither the name of the University nor the names of its contributors
<br />
.\" may be used to endorse or promote products derived from this software
<br />
.\" without specific prior written permission.
<br />
.\"
<br />
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
<br />
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
<br />
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
<br />
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
<br />
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
<br />
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
<br />
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
<br />
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
<br />
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
<br />
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
<br />
.\" SUCH DAMAGE.
</div>
<p>
This long comment is the license and copyright of the source file. Of course, our use of this source file is compatible
with the license, as may be read from the text itself!
</p>
<div class="mdocin">
.\" @(#)echo.1 8.1 (Berkeley) 7/22/93
</div>
<p>
This comment is of historical note. The <span class="screen">@(#)</span> sequence was inserted by the <a
href="commands.xml#cmd_sccs" class="cmd">sccs</a> utility (Source Code Control System). Although this utility
is part of <a class="term" href="glossary.xml#posix">POSIX</a>.1-2008, it has mostly been replaced by <a
href="commands.xml#cmd_cvs" class="cmd">cvs</a>. You'll probably never encounter this string in your own
manuals, so it's safe to disregard.
</p>
<p>
At this point the manual content itself begins.
</p>
<div class="mdocin">
.Dd $​Mdocdate: September 3 2010 ​$
<br />
.Dt ECHO 1
<br />
.Os
</div>
<p>
This indicates that the manual's title is <span class="screen">ECHO</span> in category <span class="cat">1</span>
(utilities) for the current installed operating system. The <span class="screen">$​Mdocdate$</span> enclosure is
similar to that as defined at the top of the file with <span class="screen">$​OpenBSD$</span>.
</p>
<div class="mdocin">
.Sh NAME
<br />
.Nm echo
<br />
.Nd write arguments to the standard output
</div>
<p>
This documents a single command, the <a href="commands.xml#cmd_echo" class="cmd">echo</a> command, which does as
mentioned.
</p>
<div class="mdocin">
.Sh SYNOPSIS
<br />
.Nm echo
<br />
.Op Fl n
<br />
.Op Ar string ...
</div>
<p>
The command accepts a single optional flag, <span class="cmdflag">n</span>, and an arbitrary number of optional
arguments <span class="cmdarg">string</span>. Note that re-stating the command name for the <a
href="macros.xml#macro_nm" class="macro">Nm</a> is superfluous in this case.
</p>
<div class="mdocin">
.Sh DESCRIPTION
<br />
The
<br />
.Nm
<br />
utility writes any specified operands, separated by single blank
<br />
.Pq Sq \ \&
<br />
characters and followed by a newline
<br />
.Pq Sq \en
<br />
character, to the standard
<br />
output.
<br />
When no operands are given, only the newline is written.
</div>
<p>
The <span class="sec">DESCRIPTION</span> opens with a brief explanation of the utility and its output. The strange set
of backslash-escaped characters <span class="screen">\ \&</span> is required to make the doubly-nested macros <a
href="macros.xml#macro_pq" class="macro">Pq</a> and <a href="macros.xml#macro_sq" class="macro">Sq</a>
(parenthesise and single-quote, respectively) correctly enclose a single space.
</p>
<div class="mdocin">
.Pp
<br />
The options are as follows:
<br />
.Bl -tag -width Ds
<br />
.It Fl n
<br />
Do not print the trailing newline character.
<br />
.El
</div>
<p>
This follows the standard form of documenting flags and arguments as a term/definition list. Each one — in this
case only one — is documented in alphabetical order.
</p>
<div class="mdocin">
.Sh EXIT STATUS
<br />
.Ex -std echo
</div>
<p>
Notes the standard exit sequence. Note that the argument to <a href="macros.xml#macro_ex" class="macro">Ex</a> is
superfluous, as only one command is listed for the manual.
</p>
<div class="mdocin">
.Sh SEE ALSO
<br />
.Xr csh 1 ,
<br />
.Xr ksh 1 ,
<br />
.Xr printf 1
</div>
<p>
Although these weren't cited in other sections of the manual, the author felt it necessary to link to them. This is
probably because both <span class="screen">csh</span> and <span class="screen">ksh</span> include internal
implementations of a function by the same name.
</p>
<div class="mdocin">
.Sh STANDARDS
<br />
The
<br />
.Nm
<br />
utility is compliant with the
<br />
.St -p1003.1-2008
<br />
specification.
<br />
.Pp
<br />
The flag
<br />
.Op Fl n
<br />
is an extension to that specification.
<br />
.Pp
<br />
.Nm
<br />
also exists as a built-in to
<br />
.Xr csh 1
<br />
and
<br />
.Xr ksh 1 ,
<br />
though with a different syntax.
</div>
<p>
This last section fully describes the utility's conformance to the <a class="term" href="glossary.xml#posix">POSIX</a>
standard, which is very important to those writing portable utilities. The <a href="macros.xml#macro_st"
class="macro">St</a> macro expands into the relevant standard's full name, <span class="screen">IEEE Std
1003.1-2008 (“POSIX.1”)</span>. For a full list of standards, consult your local documentation for
the macro.
</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.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-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>