-
Notifications
You must be signed in to change notification settings - Fork 4
/
part1-1.xml
87 lines (87 loc) · 4.01 KB
/
part1-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
<?xml version="1.0" encoding="UTF-8"?>
<html>
<head>
<meta http-equiv="Content-Type" content="text/xml; charset=utf-8"/>
<title>Commands</title>
<link rel="stylesheet" href="css/book.css" type="text/css"/>
</head>
<body>
<h2 id="commands">
Commands
</h2>
<p>
Commands are the way in which a user operates her computer. Already I've noted the <a href="commands.xml#cmd_man"
class="cmd">man</a> command: if you've interacted with a UNIX system, you've probably run at least <span
class="cmdline">man intro</span> or <span class="cmdline">man man</span> to learn about your system.
</p>
<p>
In this chapter, I'll discuss how to document these commands with <span class="lang">mdoc</span>.
</p>
<p>
This may be unfamiliar if you're accustomed to graphical interfaces — all of our examples will refer to
command-line, text-based commands. If your target environment isn't a UNIX system, it's a good idea to read these
examples anyway, as as they will expose the rudimentary structure of the <span class="lang">mdoc</span> language. As
mentioned before, reading an introductory text on UNIX will help avoid confusion.
</p>
<p>
Let's begin by making a mental checklist for the criteria that make a good manual for a command. This checklist arises
by inverting what a manual reader expects in opening a manual: what does the command do and how do I operate it?
</p>
<ul>
<li>
Do I describe the calling syntax of the command?
</li>
<li>
Do I describe each flag and argument of the command?
</li>
<li>
Do I describe the command's operation?
</li>
<li>
Do I describe the command's exit status?
</li>
<li>
Do I describe referenced files and environment variables?
</li>
</ul>
<p>
Above all, the best litmus test is whether a colleague or friend can read your manual and be able to use your command
without any assistance on your part. Don't be discouraged by how this can take several tries to get right!
</p>
<p>
I'll begin with a simple command, <span class="cmd">hi</span>, which prints <span class="screen">hello, world</span> to
the screen. I'll then add some command-line arguments to this command. By the time you finish this chapter, you should
have a grasp of <span class="lang">mdoc</span> syntax and some of its more widely-used macros.
</p>
<p>
In this text, I'll refer to the invocation of commands as <span class="cmdline"><span class="cmd">cmd</span> <span
class="cmdopt"><span class="cmdflag">flag</span> <span class="cmdarg">farg</span></span> <span
class="cmdarg">arg</span></span>. Here, <span class="cmd">cmd</span> refers to the command invocation
name, <span class="cmdflag">flag</span> is a flag (or switch) to that command, <span class="cmdarg">farg</span> is an
argument to a flag (not all flags have arguments), and <span class="cmdarg">arg</span> is an argument to the command.
</p>
<p>
The dash in front of <span class="cmdflag">flag</span> indicates a flag, while the square brackets around <span
class="cmdopt"><span class="cmdflag">flag</span> <span class="cmdarg">farg</span></span> indicate an optional
part of the invocation. Since <span class="cmdarg">arg</span> is not bracketed, it is a mandatory part of the
invocation.
</p>
<p>
This convention is formalised by the <a class="term" href="glossary.xml#posix">POSIX</a>.1-2008 standard (Base
Definitions, sec. 12.1), so you can expect to see it often in the UNIX world.
</p>
<table class="nav">
<tbody>
<tr>
<td class="nav-contents"><a href="toc.xml">Contents</a></td>
<td class="nav-next"><a href="part1-1-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-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>