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
|
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
<!-- Process this file with docbook-to-man to generate an nroff manual
page: `docbook-to-man manpage.sgml > manpage.1'. You may view
the manual page with: `docbook-to-man manpage.sgml | nroff -man |
less'. A typical entry in a Makefile or Makefile.am is:
manpage.1: manpage.sgml
docbook-to-man $< > $@
-->
<!-- This example was constructed by Colin Watson
<email>cjwatson@debian.org</email>, based on a man page template
provided by Tom Christiansen <email>tchrist@jhereg.perl.com</email>
and a DocBook man page example by Craig Small
<email>csmall@debian.org</email>.
-->
<!-- Fill in the various UPPER CASE things here. -->
<!ENTITY manfirstname "<firstname>FIRSTNAME</firstname>">
<!ENTITY mansurname "<surname>SURNAME</surname>">
<!-- Please adjust the date whenever revising the manpage. -->
<!ENTITY mandate "<date>DATE</date>">
<!-- SECTION should be 1-8, maybe with subsection. Other parameters are
allowed: see man(7), man(1). -->
<!ENTITY mansection "<manvolnum>SECTION</manvolnum>">
<!ENTITY manemail "<email>EMAIL</email>">
<!ENTITY manusername "USERNAME">
<!ENTITY manucpackage "<refentrytitle>UCPACKAGE</refentrytitle>">
<!ENTITY manpackage "PACKAGE">
]>
<refentry>
<refentryinfo>
<address>
&manemail;
</address>
<author>
&manfirstname;
&mansurname;
</author>
<copyright>
<year>2002</year>
<holder>&manusername;</holder>
</copyright>
&mandate;
</refentryinfo>
<refmeta>
&manucpackage;
&mansection;
</refmeta>
<refnamediv>
<refname>&manpackage;</refname>
<refpurpose>program to do something</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>&manpackage;</command>
<group choice="req"><arg>this</arg><arg>that</arg></group>
<group choice="opt"><arg>-flags</arg></group>
<group choice="opt">
<arg>-o <replaceable>option</replaceable></arg>
</group>
<arg>argument</arg>
<arg rep="repeat" choice="opt"><replaceable>more</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>Long drawn-out discussion of <command>&manpackage;</command>.
It's a good idea to break this up into subsections, like these:</para>
<refsect2>
<title>A Sample Subsection</title>
<para></para>
</refsect2>
<refsect2>
<title>Yet Another Sample Subsection</title>
<para>References to the
<citerefentry>
<refentrytitle>foo</refentrytitle><manvolnum>SECTION</manvolnum>
</citerefentry> (or other) manual page should use the
<markup><citerefentry></markup> element as here.
</para>
<para>Each paragraph within a section is contained within a
<markup><para></markup> tag.</para>
</refsect2>
</refsect1>
<refsect1>
<title>OPTIONS</title>
<para>Some people make this separate from the description.</para>
<variablelist>
<varlistentry>
<term><option>this</option>|<option>that</option></term>
<listitem>
<para>The user MUST specify either <option>this</option> or
<option>that</option> to run the program. The { and } braces
mean one of the enclosed is required. The bar (|) separates
exclusive options (i.e. you cannot have both at once.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-o</option></term>
<listitem>
<para>Pass the user-supplied <replaceable>option</replaceable> to
<command>foo</command> to change its behaviour. The fact that
<replaceable>option</replaceable> is underlined or in italics
means that the user replaces it with a valid value for this
option. The [ and ] brackets mean it isn't required.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>argument</option></term>
<listitem>
<para>The last <option>argument</option> is required, because it
is not in brackets.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>more</option></term>
<listitem>
<para>means that the user can optionally specify additional
arguments at the end. The ellipses (...) indicate one or more of
this parameter is allowed.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>RETURN VALUE</title>
<para>What the program or function returns if successful.</para>
</refsect1>
<refsect1>
<title>ERRORS</title>
<para>Return codes, either exit status or errno settings.</para>
</refsect1>
<refsect1>
<title>EXAMPLES</title>
<para>Give some example uses of the program.</para>
</refsect1>
<refsect1>
<title>ENVIRONMENT</title>
<para>Environment variables this program might care about.</para>
</refsect1>
<refsect1>
<title>FILES</title>
<para>All files used by the program. Typical usage is like this:</para>
<variablelist>
<varlistentry>
<term><filename>/usr/man</filename></term>
<listitem><para>default man tree</para></listitem>
</varlistentry>
<varlistentry>
<term><filename>/usr/man/man*/*.*</filename></term>
<listitem><para>unformatted (nroff source) man pages</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>NOTES</title>
<para>Miscellaneous commentary.</para>
</refsect1>
<refsect1>
<title>CAVEATS</title>
<para>Things to take special care with, sometimes called WARNINGS.</para>
</refsect1>
<refsect1>
<title>DIAGNOSTICS</title>
<para>All the possible error messages the program can print out, what
they mean, and how to correct them if applicable.</para>
</refsect1>
<refsect1>
<title>BUGS</title>
<para>Things that are broken or just don't work quite right.</para>
</refsect1>
<refsect1>
<title>RESTRICTIONS</title>
<para>Bugs you don't plan to fix. :-)</para>
</refsect1>
<refsect1>
<title>AUTHOR</title>
<para>Who wrote it (or AUTHORS if multiple).</para>
</refsect1>
<refsect1>
<title>HISTORY</title>
<para>Programs derived from other sources sometimes have this.</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>Other man pages to check out, like man(1), man(7), mandb(8),
catman(8).</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
|
