-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathpreface.xml
119 lines (119 loc) · 5.22 KB
/
preface.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
<?xml version="1.0" encoding="UTF-8"?>
<html>
<head>
<meta http-equiv="Content-Type" content="text/xml; charset=utf-8"/>
<title>Preface</title>
<link rel="stylesheet" href="css/book.css" type="text/css"/>
</head>
<body>
<h1>
Preface
</h1>
<blockquote>
<p>
A utility without a manual is of no utility at all.
</p>
</blockquote>
<p>
This is a guide for writing UNIX manuals in the <span class="lang">mdoc</span> language. If you're new to writing UNIX
manuals, or you want to learn about best practises for high-quality manuals, this book may benefit your work.
</p>
<p>
To those unfamiliar with <a class="term" href="glossary.xml#unix">UNIX</a>, <span class="lang">mdoc</span> is a
language for documenting utilities, programming functions, file and wire formats, hardware device interfaces, and so on.
By a language I mean a structured, machine-readable document format such as <a class="term" href="glossary.xml#html">
HTML</a>, the primary language of web pages; or <a class="term" href="glossary.xml#rtf">RTF</a>, used by word
processors. <a href="commands.xml#cmd_man" class="cmd">man</a> is the utility for querying documents in <span
class="lang">mdoc</span> and other languages, collectively called <a class="term"
href="glossary.xml#man_pages">man pages</a>.
</p>
<p>
The following, for example, is a fragment of <a href="commands.xml#cmd_man" class="cmd">man</a> output for the <a
href="commands.xml#cmd_cat" class="cmd">cat</a> command.
</p>
<div class="mdocout">
<div class="mdoc-section">
<h1>NAME</h1>
<b class="mdoc-name">cat</b> — <span class="mdoc-desc">concatenate and print files</span></div>
<div class="mdoc-section">
<h1>SYNOPSIS</h1>
<table class="mdoc-synopsis">
<col style="width: 3.00ex;"/>
<col/>
<tbody>
<tr>
<td>
cat
</td>
<td>
[<span class="mdoc-opt"><b class="mdoc-flag">-benstuv</b></span>]
[<span class="mdoc-opt"><i class="mdoc-arg">file ...</i></span>]
</td>
</tr>
</tbody>
</table>
</div>
<div class="mdoc-section">
<h1>DESCRIPTION</h1>
The <b class="mdoc-name">cat</b> utility reads files sequentially, writing them to the standard output. The <i
class="mdoc-arg">file</i> operands are processed in command-line order. If <i class="mdoc-arg">file</i>
is a single dash (‘​-') or absent, <b class="mdoc-name">cat</b> reads from
the standard input.
</div>
</div>
<p>
Why <span class="lang">mdoc</span>? After all, there are plenty of other UNIX manual languages out there, from the
historical <span class="lang">man</span> to <a class="term" href="glossary.xml#docbook">DocBook</a>. In short, <span
class="lang">mdoc</span> is:
</p>
<ul>
<li>
portable, as any modern UNIX system can format it without needing clumsy toolchains;
</li>
<li>
expressive, capturing the semantic content of manpages instead of just presentation cues;
</li>
<li>
concise, making line-based source control painless; and
</li>
<li>
well-documented, well-supported, and actively maintained by a community of knowledgable developers.
</li>
</ul>
<p>
No other format can boast all of these points at once.
</p>
<p>
In fact, although I've mentioned UNIX several times already, <span class="lang">mdoc</span> isn't exclusively tied to
UNIX. Although UNIX and <span class="lang">mdoc</span> are historically linked, open source <span
class="lang">mdoc</span> tools exist for any operating system. Furthermore, the documentation capabilities of
<span class="lang">mdoc</span> apply to computing systems in general — not just UNIX.
</p>
<p>
In this book, however, I'll assume you are casually familiar with <a href="commands.xml#cmd_man" class="cmd">man</a> and
its output. This will allow us to focus on manuals with the same formatted output in mind. Thus, if you're unfamiliar
with the <a href="commands.xml#cmd_man" class="cmd">man</a> utility, this is a good time to read an introductory text on
the subject (such as a UNIX beginner's guide), or at the very least, read the output of <span class="cmdline">man
man</span> (the manual page of the <a href="commands.xml#cmd_man" class="cmd">man</a> command).
</p>
<p>
This is not a canonical reference! The <span class="lang">mdoc</span> language is not standardised. For official
reference, consult the manual distributed with your target computer system with <span class="cmdline">man mdoc</span>.
This work primarily addresses the elements of <span class="lang">mdoc</span> common to any UNIX deployment, noting
common pitfalls in portability.
</p>
<table class="nav">
<tbody>
<tr>
<td class="nav-contents"><a href="toc.xml">Contents</a></td>
<td class="nav-next"><a href="part1.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/preface.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>