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
|
.\" This is an util-linux manual page example in troff format.
.\"
.\" .TH macro is expecting following arguments:
.\" title section date footer header
.\" The title is usually command name.
.\" The section must match with file name extension.
.\" The date tells month and year when last update happen.
.\" The footer is fixed to "util-linux".
.\" The header is textual string of section
.\" 1 "User Commands"
.\" 2 "System calls"
.\" 3 "Programmer's Manual"
.\" 4 "Special Files"
.\" 5 "File Formats"
.\" 6 "Games"
.\" 7 "Miscellanea"
.\" 8 "System Administration"
.\"
.\" Please read `man 7 groff_man' howto use various macros.
.\"
.TH EXAMPLE "1" "August 2011" "util-linux" "User Commands"
.SH NAME
example \- an util-linux man page howto
.SH SYNOPSIS
.B example
[options]
.I argument
.SH DESCRIPTION
All manual pages need some sort of description. Write such here.
.SH OPTIONS
.TP
\fB\-n\fR, \fB\-\-no\-argument\fR
This option does not use argument.
.TP
\fB\-o\fR, \fB\-\-optional\fR[\fI=argument\fR]
Tell in description an
.I argument
is optional, and what happens when is or is not given. Notice that
.I argument
is not abbreviated, like in usage function. Assuming usage function would
define argument to be
.IR num ,
the manual page should say
.IR number .
.TP
\fB\-r\fR, \fB\-\-required\fR \fIargument\fR
Tell in description option
.I argument
is required.
.TP
\fB\-V\fR, \fB\-\-version\fR
Display version information and exit.
.TP
\fB\-h\fR, \fB\-\-help\fR
Display help and exit.
.SH NOTES
Tell details what users might need to know. For example kernel feature or
version requirements.
.PP
The man page groff input lines should not exceed 80 characters length.
.PP
Do not leave empty lines to groff input. If you need break or paragraph use
appropriate groff macros. See
.BR groff_man (7)
how to use man page macros.
.PP
Use of
.I italic
which is underlined in terminal, and
.B bold
are not strictly defined. As some sort of convention
.I arguments
use italic, and the
.B other highlights
are bold.
.\"
.\" The manual page comments are undervalued way of adding clarifications
.\" quite not belong to the manual, questions, TODO items etc. Feel free
.\" to use them.
.\"
.PP
When in the source a new sentence begins somewhere midline, it should use a
double space before its initial letter. This is done because groff uses double
spaces last sentence ends to end of line, and next begins from new line.
Unless double spaces are used in middle of of line the spacing style is
inconsistent.
.SH ENVIRONMENT
Tell which environment variables affect, and how, to execution of the command.
.TP
.B EXAMPLE_PATH
Configuration file path. Notice that a well-known environment variables such as
.B HOME
does not need explanation.
.SH FILES
Tell which file(s) command uses.
.TP
.B $EXAMPLE_PATH
.TQ
.B $HOME/.example.conf
.TQ
.B /etc/example.conf
What are these files, which order and will the evaluation end or continue if a
file is found. In case the explanation is not simple write separated Special
Files manual page that tells about syntax, meaning of key-value settings etc.
The file manual page needs to be referred in
.B SEE ALSO
section.
.TP
.B /var/log/example.log
Another file.
.SH EXAMPLES
Write typical and/or clever use examples here. The bellow examples are stupid,
and you should never write them to real man page.
.TP
.B example -h
Output help screen.
.TP
.B example -V
Output version information.
.SH "EXIT STATUS"
This section can be removed if command has only two return values,
.B 0
for success and
.B 1
for failure. Use of
.B sysexits.h
return values must be mentioned, but does not need to be explained.
.PP
.RS
.PD 0
.TP
.B 0
success
.TP
.B 1
failure
.TP
.B 2
tell why this could happen
.TP
.B 3
etc
.PD
.RE
.SH AUTHORS
.MT rjh@\:example.org
Random J. Hacker
.ME
.br
.MT fred@\:example.com
Fred Foobar
.ME
.SH "SEE ALSO"
.BR groff_man (7),
.BR foo (1),
.BR bar (8)
.SH AVAILABILITY
The example command is part of the util-linux package and is available from
.UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
Linux Kernel Archive
.UE .
|
