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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<!-- Copyright (c) 2008 Stijn van Dongen -->
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<meta name="keywords" content="manual">
<style type="text/css">
body {
text-align: justify;
color: #001111;
background: white;
margin-left: 8%;
margin-right: 8%;
font-family: Helvetica, Univers, Verdana, sans-serif;
}
p.default {
font-family: Helvetica, Univers, Verdana, sans-serif;
text-align: justify;
}
p.L53 { font-size: 30pt; }
p.L52 { font-size: 20pt; }
p.L51 { font-size: 15pt; }
p.L50 { font-size: 12pt; }
p.L49 { font-size: 10pt; }
p.L48 { font-size: 9pt; }
p.L47 { font-size: 8pt; }
td {
font-family: Helvetica, Univers, Verdana, sans-serif;
text-align: justify;
}
h3 { margin-top:1em; }
h2 { margin-top:2em; }
.left { text-align: left; align: left; }
.right { text-align: right; align: right; }
.center { text-align: center; align: center; }
.nowrap { white-space: nowrap; }
a:link { text-decoration: none; }
a:active { text-decoration: none; }
a:visited { text-decoration: none; }
a:link { color: #1111aa; }
a:active { color: #1111aa; }
a:visited { color: #111166; }
a.local:link { color: #11aa11; }
a.local:active { color: #11aa11; }
a.local:visited { color: #116611; }
a.intern:link { color: #1111aa; }
a.intern:active { color: #1111aa; }
a.intern:visited { color: #111166; }
a.extern:link { color: #aa1111; }
a.extern:active { color: #aa1111; }
a.extern:visited { color: #661111; }
a.quiet:link { color: black; }
a.quiet:active { color: black; }
a.quiet:visited { color: black; }
div.copy
{ font-size: 12pt;
font-family: monospace;
text-align: left;
white-space: pre;
margin-left: 2em;
margin-top: 1em;
margin-bottom: 1em;
}
div.indent
{ margin-left: 8%;
margin-right: 0%;
}
</style>
<title>The PUD manual page mini-language</title>
</head>
<body>
<p style="text-align:right">
4 Sep 2008
<a class="local" href="pud-man.ps"><b>pud-man</b></a>
1.002, 08-248
</p>
<div style="margin-top:1em">
<table
cellspacing="0" border=0
cellpadding="0" summary="itemize">
<tr><td width=48 valign="top" class="left nowrap">1.</td><td width=8> </td><td><div style="text-align:justify">
<a class="intern" href="#name">NAME</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">2.</td><td width=8> </td><td><div style="text-align:justify">
<a class="intern" href="#description">DESCRIPTION</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">3.</td><td width=8> </td><td><div style="text-align:justify">
<a class="intern" href="#macros">MACROS</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">4.</td><td width=8> </td><td><div style="text-align:justify">
<a class="intern" href="#seealso">SEE ALSO</a>
</div></td></tr>
</table>
</div>
<a name="name"></a>
<h2>NAME</h2>
<p class="default L50" style="margin-bottom:0">
pud-man - A description of the Portable Unix Documentation Language for writing manual pages</p>
<a name="description"></a>
<h2>DESCRIPTION</h2>
<p class="default L50" style="margin-bottom:0">
This document describes the Portable Unix Documentation (PUD) manual
page mini-language. PUD-man is built on top of the macro interpreter
zoem. A PUD document is generally well-structured, relatively free of
formatting statements, compact to write and easily extendable. It can
be converted to both troff and html, for viewing in terminals and
browsers. High quality Postscript and plain text formats can be derived
from the troff output.</p>
<p class="default L50" style="margin-bottom:0">
Write your own manual pages by copying the example page
<a class="local" href="buzzz.azm">buzzz.azm</a>
and modifying it to your needs. If you are documenting <i>foo</i>,
the usual approach is to create <i>foo.azm</i>, and from that
create <i>foo.1</i> and <i>foo.html</i> as follows:</p>
<pre> zoem -i foo -d html
zoem -i foo -d html
zoem -i foo -d roff -o foo.1
zoem -i foo -d roff -o foo.1</pre>
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
This generates files foo.html and foo.1.
Each device is run twice to be certain that references
are found and linked. PostScript and text versions
can be made from <tt>foo.1</tt> as follows:</p>
<pre> groff -man foo.1 > foo.ps
groff -t -e -mandoc -Tascii foo.1 | col -bx > foo.txt</pre>
<p class="default L50" style="margin-bottom:0">
Note though that <tt>foo.1</tt> does not use any groff specific
extensions; it should be acceptable input to ancient roffs as well,
exceptions imply a bug in the PUD man macros.</p>
<p class="default L50" style="margin-bottom:0">
The PUD manual page macro package
automatically imports a set of generic macros from the
pud-base and pud-ref packages. The <a class="local" href="pud-base.html">pud-base</a>
and <a class="local" href="pud-ref.html">pud-ref</a> manual pages
document those macros, which are also essential for writing manual
pages. The most important are</p>
<div style="margin-top:1em">
<table
cellspacing="0" border=0
cellpadding="0" summary="itemize">
<tr><td width=32 valign="top" class=right>i)</td><td width=8> </td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
The <i>itemize</i> environment
(used as <tt>\begin{itemize}[{options}] ... \end{itemize}</tt>)
and its associated macros
<tt>\item#1</tt>, <tt>\items#1</tt>, <tt>\item</tt>
<tt>\itemskip</tt>, <tt>\intermezzo</tt>, and others.</p>
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr><tr><td width=32 valign="top" class=right>ii)</td><td width=8> </td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
The font style/appearance macros <tt>\bf#1</tt>, <tt>\it#1</tt>, <tt>\tt#1</tt>,
<tt>\v#1</tt>,
the font size macros <tt>\ftinc#2</tt> and <tt>\ftdec#2</tt>.</p>
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr><tr><td width=32 valign="top" class=right>iii)</td><td width=8> </td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
The paragraph mark <tt>\par</tt> (required for each paragraph).</p>
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr><tr><td width=32 valign="top" class=right>iv)</td><td width=8> </td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
The verbatim macros <tt>\verbatim#1</tt> and <tt>\verbatix#1</tt>.</p>
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr><tr><td width=32 valign="top" class=right>v)</td><td width=8> </td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
The link macros <tt>\httpref#1</tt>, <tt>\sibref#2</tt>, <tt>\iref#2</tt>,
<tt>\lref#2</tt>, <tt>\aref#2</tt>.</p>
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr><tr><td width=32 valign="top" class=right>vi)</td><td width=8> </td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
In <a class="local" href="pud-ref.html">pud-ref</a> the pair of <tt>\reference#2</tt> and <tt>\refer#1</tt>.</p>
</div></td></tr>
</table>
</div>
<p class="default L50" style="margin-bottom:0">
For the authorative listing consult the <a class="local" href="pud-base.html">pud-base</a>
manual page. The listing above includes a silly demonstration of some
itemize features such as alignment and automatic numbering. Read the
<a class="local" href="../doc/zum.html">Zoem User Manual</a> for a better understanding of
zoem macro packages and the design of zoem.</p>
<a name="macros"></a>
<h2>MACROS</h2>
<div style="margin-top:1em">
<table
cellspacing="0" border=0
cellpadding="0" summary="itemize">
<tr><td colspan=3 class=left><tt>\"man::author"</tt></td></tr><tr><td colspan=3 class=left><tt>\"man::day"</tt></td></tr><tr><td colspan=3 class=left><tt>\"man::html-title"</tt></td></tr><tr><td colspan=3 class=left><tt>\"man::month"</tt></td></tr><tr><td colspan=3 class=left><tt>\"man::name"</tt></td></tr><tr><td colspan=3 class=left><tt>\"man::section"</tt></td></tr><tr><td colspan=3 class=left><tt>\"man::cat"</tt></td></tr><tr><td colspan=3 class=left><tt>\"man::tag"</tt></td></tr><tr><td colspan=3 class=left><tt>\"man::year"</tt></td></tr><tr><td width=32> </td><td width=8> </td><td><div style="text-align:justify">
These have to be set to appropriate values before the
macro <tt>\"man::preamble"</tt> is used.
See the example page <a class="local" href="buzzz.azm">buzzz.azm</a>.
<p class="default L50">
The <tt>\"man::cat"</tt> macro can be used to set the centered heading
found in all UNIX roff manual pages. If not set, a heading is
derived from the <tt>\"man::section"</tt> macro.
Below is the listing of default headers. It can probably be improved.
<pre> 1 USER COMMANDS
2 SYSTEM CALLS
3 LIBRARY CALLS
4 SPECIAL FILES
5 FILE FORMATS
6 GAMES
7 MACRO PACKAGES
8 SYSTEM ADMINISTRATION
9 KERNEL ROUTINES</pre>
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr><tr><td colspan=3 class=left><tt>\"man::preamble"</tt></td></tr><tr><td colspan=3 class=left><tt>\"man::postamble"</tt></td></tr><tr><td width=32> </td><td width=8> </td><td><div style="text-align:justify">
Before any text or macro resulting in output occurs, the
macro <tt>\"man::preamble"</tt> has to be used.
This macro may certainly be preceded by <tt>\def#2</tt> uses
and variants thereof. See the macros listed in the
previous entry and the example page <a class="local" href="buzzz.azm">buzzz.azm</a>.
<p class="default L50">
The last textual item in a manual page must be the macro
<tt>\"man::postamble"</tt>.
See the example page <a class="local" href="buzzz.azm">buzzz.azm</a>.
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr><tr><td colspan=3 class=left><tt>\sec#2</tt></td></tr><tr><td colspan=3 class=left><tt>\secref#1</tt></td></tr><tr><td width=32> </td><td width=8> </td><td><div style="text-align:justify">
Start a section, refer to a section. The first argument of <tt>\sec#2</tt> is
the anchor for that section, the second argument is the title. The macro
<tt>\secref#1</tt> takes an anchor and outputs the title of the associated
section.
<p class="default L50">
The NAME section should be written like the example below, taken
from the zoem interpreter manual.
<pre>
\sec{name}{NAME}
\NAME{zoem}{interpreter for the Zoem macro/programming language.}</pre>
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Usage of the NAME macro ensures that the troff output
complies with the format expected by <b>apropos</b>.</p>
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr><tr><td colspan=3 class=left><tt>\defopt#2</tt></td></tr><tr><td colspan=3 class=left><tt>\defopt#3</tt></td></tr><tr><td colspan=3 class=left><tt>\defkvp#3</tt></td></tr><tr><td width=32> </td><td width=8> </td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Write entry in the options section. typical usage is within an <tt>\item#1</tt>
macro. For all macros the first argument is the option being described,
and the last argument is a short string describing the option. This string
is printed in case the macro <tt>\"man::defstyle"</tt> is set to <tt>long</tt>. The
macro <tt>\defopt#3</tt> is used for options taking arguments; the second
argument is the name describing the argument.
The macro <tt>\defkvp#3</tt> is used for long options of the form
<tt>--mode=str</tt>, which you would enter as
<tt>\defkvp{mode}{str}{set foo mode}</tt>. Long options of the form
<tt>--verbose</tt> are simply entered using <tt>\defopt#2</tt>.</p>
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr><tr><td colspan=3><tt>\optref#2</tt></td></tr><tr><td width=32> </td><td width=8> </td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Refer to an option. The first argument is the option, the second argument
is the text associated with the link. This text will indeed be linking
in html, but nothing special will happen in troff - the text is printed
as is.</p>
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr><tr><td colspan=3 class=left><tt>\synoptopt#2</tt></td></tr><tr><td colspan=3 class=left><tt>\synoptopt#3</tt></td></tr><tr><td colspan=3 class=left><tt>\synreqopt#2</tt></td></tr><tr><td colspan=3 class=left><tt>\synreqopt#3</tt></td></tr><tr><td width=32> </td><td width=8> </td><td><div style="text-align:justify">
Write entries in the synopsis section. This assumes that somewhere
an option was created using one of the <tt>defopt</tt> family members
described below.
<p class="default L50" style="margin-bottom:0">
For all 'syn' options the first argument is simply the option itself. From
this argument the anchor is reconstructed that was created by one of the
<tt>defopt</tt> macros. The last argument is always a short string describing
the option. It depends on the style chosen, i.e. whether
<tt>\"man::synstyle"</tt> is <tt>long</tt> or <tt>short</tt>, whether this string shows up
or not. The macros in this group that take two arguments describe unary
options that take no argument. The macros taking three arguments describe
options that do take an argument.</p>
<p class="default L50" style="margin-bottom:0">
Here is an example from the zoem manual page:</p>
<pre>\synoptopt{--trace}{trace mode, default}
\synoptopt{--trace-all-long}{long trace mode}
\synoptopt{--trace-all-short}{short trace mode}
\synoptopt{--trace-regex}{trace regexes}
\synoptopt{--show-tracebits}{show trace bits}
\synoptopt{-trace}{k}{trace mode, explicit}
\synoptopt{--stats}{show symbol table stats after run}</pre>
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr><tr><td colspan=3 class=left><tt>\"man::synstyle"</tt></td></tr><tr><td colspan=3 class=left><tt>\"man::defstyle"</tt></td></tr><tr><td width=32> </td><td width=8> </td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Before importing the manual macros, set these to your prefered
style. Each of these should be set either to <tt>short</tt> or <tt>long</tt>.</p>
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr><tr><td colspan=3 class=left><tt>\genopt#1</tt></td></tr><tr><td colspan=3 class=left><tt>\genopt#2</tt></td></tr><tr><td colspan=3 class=left><tt>\genarg#1</tt></td></tr><tr><td colspan=3 class=left><tt>\useopt#1</tt></td></tr><tr><td colspan=3 class=left><tt>\useopt#2</tt></td></tr><tr><td colspan=3 class=left><tt>\usearg#1</tt></td></tr><tr><td colspan=3 class=left><tt>\genkvp#2</tt></td></tr><tr><td colspan=3 class=left><tt>\usekvp#2</tt></td></tr><tr><td width=32> </td><td width=8> </td><td><div style="text-align:justify">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
These are for creating a consistent style when refering to options. One is
free to disregard these altogether. They are meant as convenience, but some
may find the extra typing annoying.</p>
<p class="default L50" style="margin-bottom:0">
The idea is that the 'gen' macros are used when generic mention is
made of an option and possibly its argument.
The 'use' macros are used when explicit usage is mentioned.
An example is the following:</p>
<div style="
margin-left:3mm;
">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
Modes can be chosen using <b>-mode</b> <i>str</i> where <i>str</i> is any of
<b>small</b>, <b>medium</b>, or <b>large</b>. Use
<b>-mode</b> <b>small</b> if your hardware is outdated.</p>
<p class="default L50" style="margin-bottom:0">
Use <b>--milage</b>=<i>str</i> to set the milage, e.g. <b>--milage</b>=<b>high</b>
or <b>--milage</b>=<b>astronomical</b>.</p>
</div>
</div></td></tr>
</table>
</div>
<a name="seealso"></a>
<h2>SEE ALSO</h2>
<p class="default L50" style="margin-bottom:0">
The <a class="local" href="pud.html">pud</a> manual page gives an overview of PUD.</p>
</body>
</html>
|
