]>
Commit | Line | Data |
---|---|---|
ba83bc0d MK |
1 | .\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler |
2 | .\" (faith@cs.unc.edu and dwheeler@ida.org) | |
c11b1abf | 3 | .\" and (C) Copyright 2007 Michael Kerrisk <mtk.manpages@gmail.com> |
ba83bc0d | 4 | .\" |
93015253 | 5 | .\" %%%LICENSE_START(VERBATIM) |
ba83bc0d MK |
6 | .\" Permission is granted to make and distribute verbatim copies of this |
7 | .\" manual provided the copyright notice and this permission notice are | |
8 | .\" preserved on all copies. | |
9 | .\" | |
10 | .\" Permission is granted to copy and distribute modified versions of this | |
11 | .\" manual under the conditions for verbatim copying, provided that the | |
12 | .\" entire resulting derived work is distributed under the terms of a | |
13 | .\" permission notice identical to this one. | |
14 | .\" | |
15 | .\" Since the Linux kernel and libraries are constantly changing, this | |
16 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
17 | .\" responsibility for errors or omissions, or for damages resulting from | |
18 | .\" the use of the information contained herein. The author(s) may not | |
19 | .\" have taken the same level of care in the production of this manual, | |
20 | .\" which is licensed free of charge, as they might when working | |
21 | .\" professionally. | |
22 | .\" | |
23 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
24 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 25 | .\" %%%LICENSE_END |
988db661 MK |
26 | .\" |
27 | .\" 2007-05-30 created by mtk, using text from old man.7 plus | |
04bc8827 | 28 | .\" rewrites and additional text. |
ba83bc0d | 29 | .\" |
e8426ca2 | 30 | .TH MAN-PAGES 7 2020-04-11 "Linux" "Linux Programmer's Manual" |
ba83bc0d MK |
31 | .SH NAME |
32 | man-pages \- conventions for writing Linux man pages | |
33 | .SH SYNOPSIS | |
34 | .B man | |
35 | .RI [ section ] | |
36 | .I title | |
37 | .SH DESCRIPTION | |
38 | This page describes the conventions that should be employed | |
39 | when writing man pages for the Linux \fIman-pages\fP project, | |
7aa48d58 MK |
40 | which documents the user-space API provided by the Linux kernel |
41 | and the GNU C library. | |
42 | The project thus provides most of the pages in Section 2, | |
0b920015 MK |
43 | many of the pages that appear in Sections 3, 4, and 7, |
44 | and a few of the pages that appear in Sections 1, 5, and 8 | |
45 | of the man pages on a Linux system. | |
ba83bc0d MK |
46 | The conventions described on this page may also be useful |
47 | for authors writing man pages for other projects. | |
c634028a | 48 | .SS Sections of the manual pages |
ba83bc0d MK |
49 | .PP |
50 | The manual Sections are traditionally defined as follows: | |
0019177e | 51 | .TP |
db6642bd | 52 | .B 1 User commands (Programs) |
3921205d | 53 | Commands that can be executed by the user from within |
ba83bc0d MK |
54 | a shell. |
55 | .TP | |
56 | .B 2 System calls | |
3921205d | 57 | Functions which wrap operations performed by the kernel. |
ba83bc0d MK |
58 | .TP |
59 | .B 3 Library calls | |
db6642bd SA |
60 | All library functions excluding the system call wrappers |
61 | (Most of the | |
ba83bc0d | 62 | .I libc |
db6642bd | 63 | functions). |
ba83bc0d MK |
64 | .TP |
65 | .B 4 Special files (devices) | |
66 | Files found in | |
db6642bd SA |
67 | .I /dev |
68 | which allow to access to devices through the kernel. | |
ba83bc0d | 69 | .TP |
095f40d5 | 70 | .B 5 File formats and configuration files |
db6642bd | 71 | Describes various human-readable file formats and configuration files. |
ba83bc0d MK |
72 | .TP |
73 | .B 6 Games | |
db6642bd | 74 | Games and funny little programs available on the system. |
ba83bc0d | 75 | .TP |
d6aaae47 | 76 | .B 7 Overview, conventions, and miscellaneous |
db6642bd SA |
77 | Overviews or descriptions of various topics, conventions and protocols, |
78 | character set standards, the standard filesystem layout, and miscellaneous | |
79 | other things. | |
ba83bc0d MK |
80 | .TP |
81 | .B 8 System management commands | |
82 | Commands like | |
83 | .BR mount (8), | |
84 | many of which only root can execute. | |
85 | .\" .TP | |
86 | .\" .B 9 Kernel routines | |
87 | .\" This is an obsolete manual section. | |
88 | .\" Once it was thought a good idea to document the Linux kernel here, | |
89 | .\" but in fact very little has been documented, and the documentation | |
90 | .\" that exists is outdated already. | |
91 | .\" There are better sources of | |
92 | .\" information for kernel developers. | |
ba83bc0d MK |
93 | .SS Macro package |
94 | New manual pages should be marked up using the | |
add00eab | 95 | .B groff an.tmac |
ba83bc0d MK |
96 | package described in |
97 | .BR man (7). | |
988db661 | 98 | This choice is mainly for consistency: the vast majority of |
ba83bc0d MK |
99 | existing Linux manual pages are marked up using these macros. |
100 | .SS Conventions for source file layout | |
988db661 | 101 | Please limit source code line length to no more than about 75 characters |
ba83bc0d MK |
102 | wherever possible. |
103 | This helps avoid line-wrapping in some mail clients when patches are | |
104 | submitted inline. | |
ba83bc0d | 105 | .SS Title line |
aeb9b6a6 MK |
106 | The first command in a man page should be a |
107 | .B TH | |
108 | command: | |
6545cc56 | 109 | .PP |
ba83bc0d | 110 | .RS |
ba83bc0d | 111 | .B \&.TH |
0daa9e92 | 112 | .I "title section date source manual" |
ba83bc0d | 113 | .RE |
6545cc56 | 114 | .PP |
ba83bc0d MK |
115 | where: |
116 | .RS | |
117 | .TP 10 | |
118 | .I title | |
119 | The title of the man page, written in all caps (e.g., | |
120 | .IR MAN-PAGES ). | |
121 | .TP | |
122 | .I section | |
123 | The section number in which the man page should be placed (e.g., | |
124 | .IR 7 ). | |
125 | .TP | |
126 | .I date | |
1c4b22fb MK |
127 | The date of the last nontrivial change that was made to the man page. |
128 | (Within the | |
129 | .I man-pages | |
0094f2b0 | 130 | project, the necessary updates to these timestamps are handled |
1c4b22fb MK |
131 | automatically by scripts, so there is no need to manually update |
132 | them as part of a patch.) | |
ba83bc0d MK |
133 | Dates should be written in the form YYYY-MM-DD. |
134 | .TP | |
135 | .I source | |
136 | The source of the command, function, or system call. | |
5711c04f | 137 | .IP |
ba83bc0d MK |
138 | For those few \fIman-pages\fP pages in Sections 1 and 8, |
139 | probably you just want to write | |
140 | .IR GNU . | |
5711c04f | 141 | .IP |
ba83bc0d MK |
142 | For system calls, just write |
143 | .IR "Linux" . | |
144 | (An earlier practice was to write the version number | |
145 | of the kernel from which the manual page was being written/checked. | |
146 | However, this was never done consistently, and so was | |
147 | probably worse than including no version number. | |
148 | Henceforth, avoid including a version number.) | |
5711c04f | 149 | .IP |
988db661 | 150 | For library calls that are part of glibc or one of the |
ba83bc0d MK |
151 | other common GNU libraries, just use |
152 | .IR "GNU C Library" ", " GNU , | |
153 | or an empty string. | |
5711c04f | 154 | .IP |
ba83bc0d MK |
155 | For Section 4 pages, use |
156 | .IR "Linux" . | |
5711c04f | 157 | .IP |
ba83bc0d MK |
158 | In cases of doubt, just write |
159 | .IR Linux ", or " GNU . | |
160 | .TP | |
161 | .I manual | |
988db661 | 162 | The title of the manual (e.g., for Section 2 and 3 pages in |
ba83bc0d MK |
163 | the \fIman-pages\fP package, use |
164 | .IR "Linux Programmer's Manual" ). | |
165 | .RE | |
166 | .SS Sections within a manual page | |
167 | The list below shows conventional or suggested sections. | |
988db661 | 168 | Most manual pages should include at least the |
ba83bc0d MK |
169 | .B highlighted |
170 | sections. | |
04bc8827 | 171 | Arrange a new manual page so that sections |
ba83bc0d | 172 | are placed in the order shown in the list. |
9c40f2b9 MK |
173 | .PP |
174 | .in +4n | |
ba83bc0d | 175 | .nf |
ba83bc0d MK |
176 | \fBNAME\fP |
177 | \fBSYNOPSIS\fP | |
1f901dc4 | 178 | CONFIGURATION [Normally only in Section 4] |
ba83bc0d MK |
179 | \fBDESCRIPTION\fP |
180 | OPTIONS [Normally only in Sections 1, 8] | |
181 | EXIT STATUS [Normally only in Sections 1, 8] | |
182 | RETURN VALUE [Normally only in Sections 2, 3] | |
183 | .\" May 07: Few current man pages have an ERROR HANDLING section,,, | |
184 | .\" ERROR HANDLING, | |
185 | ERRORS [Typically only in Sections 2, 3] | |
186 | .\" May 07: Almost no current man pages have a USAGE section,,, | |
988db661 | 187 | .\" USAGE, |
25a46448 | 188 | .\" DIAGNOSTICS, |
ba83bc0d MK |
189 | .\" May 07: Almost no current man pages have a SECURITY section,,, |
190 | .\" SECURITY, | |
191 | ENVIRONMENT | |
192 | FILES | |
193 | VERSIONS [Normally only in Sections 2, 3] | |
a2dace6b | 194 | ATTRIBUTES [Normally only in Sections 2, 3] |
ba83bc0d MK |
195 | CONFORMING TO |
196 | NOTES | |
197 | BUGS | |
198 | EXAMPLE | |
dcbc136a | 199 | .\" AUTHORS sections are discouraged |
fa1e3231 | 200 | AUTHORS [Discouraged] |
c91a4f14 | 201 | REPORTING BUGS [Not used in man-pages] |
fa1e3231 | 202 | COPYRIGHT [Not used in man-pages] |
ba83bc0d | 203 | \fBSEE ALSO\fP |
9c40f2b9 | 204 | .fi |
ba83bc0d | 205 | .in |
e646a1ba | 206 | .PP |
ba83bc0d MK |
207 | .IR "Where a traditional heading would apply" ", " "please use it" ; |
208 | this kind of consistency can make the information easier to understand. | |
988db661 | 209 | If you must, you can create your own |
ba83bc0d MK |
210 | headings if they make things easier to understand (this can |
211 | be especially useful for pages in Sections 4 and 5). | |
212 | However, before doing this, consider whether you could use the | |
213 | traditional headings, with some subsections (\fI.SS\fP) within | |
214 | those sections. | |
5711c04f | 215 | .PP |
988db661 | 216 | The following list elaborates on the contents of each of |
ba83bc0d | 217 | the above sections. |
0019177e | 218 | .TP |
ba83bc0d MK |
219 | .B NAME |
220 | The name of this manual page. | |
5711c04f | 221 | .IP |
988db661 | 222 | See |
ba83bc0d MK |
223 | .BR man (7) |
224 | for important details of the line(s) that should follow the | |
25a46448 | 225 | \fB.SH NAME\fP command. |
472926d8 | 226 | All words in this line (including the word immediately |
d1a71985 | 227 | following the "\e\-") should be in lowercase, |
472926d8 MK |
228 | except where English or technical terminological convention |
229 | dictates otherwise. | |
ba83bc0d MK |
230 | .TP |
231 | .B SYNOPSIS | |
9042e249 | 232 | A brief summary of the command or function's interface. |
5711c04f | 233 | .IP |
ba83bc0d MK |
234 | For commands, this shows the syntax of the command and its arguments |
235 | (including options); | |
04bc8827 MK |
236 | boldface is used for as-is text and italics are used to |
237 | indicate replaceable arguments. | |
ba83bc0d MK |
238 | Brackets ([]) surround optional arguments, vertical bars (|) |
239 | separate choices, and ellipses (\&...) can be repeated. | |
240 | For functions, it shows any required data declarations or | |
241 | .B #include | |
242 | directives, followed by the function declaration. | |
5711c04f | 243 | .IP |
d0e676ff MK |
244 | Where a feature test macro must be defined in order to obtain |
245 | the declaration of a function (or a variable) from a header file, | |
246 | then the SYNOPSIS should indicate this, as described in | |
247 | .BR feature_test_macros (7). | |
e48efc84 | 248 | .\" FIXME . Say something here about compiler options |
ba83bc0d | 249 | .TP |
c9890844 MK |
250 | .B CONFIGURATION |
251 | Configuration details for a device. | |
5711c04f | 252 | .IP |
33a0ccb2 | 253 | This section normally appears only in Section 4 pages. |
c9890844 | 254 | .TP |
ba83bc0d | 255 | .B DESCRIPTION |
9042e249 | 256 | An explanation of what the program, function, or format does. |
5711c04f | 257 | .IP |
ba83bc0d MK |
258 | Discuss how it interacts with files and standard input, and what it |
259 | produces on standard output or standard error. | |
260 | Omit internals and implementation details unless they're critical for | |
261 | understanding the interface. | |
262 | Describe the usual case; | |
263 | for information on command-line options of a program use the | |
264 | .B OPTIONS | |
265 | section. | |
266 | .\" If there is some kind of input grammar or complex set of subcommands, | |
267 | .\" consider describing them in a separate | |
268 | .\" .B USAGE | |
269 | .\" section (and just place an overview in the | |
270 | .\" .B DESCRIPTION | |
271 | .\" section). | |
5711c04f | 272 | .IP |
3c4e1fb2 MK |
273 | When describing new behavior or new flags for |
274 | a system call or library function, | |
275 | be careful to note the kernel or C library version | |
276 | that introduced the change. | |
277 | The preferred method of noting this information for flags is as part of a | |
278 | .B .TP | |
279 | list, in the following form (here, for a new system call flag): | |
280 | .RS 22 | |
281 | .TP | |
282 | .BR XYZ_FLAG " (since Linux 3.7)" | |
283 | Description of flag... | |
284 | .RE | |
285 | .IP | |
3d1ee497 | 286 | Including version information is especially useful to users |
3c4e1fb2 MK |
287 | who are constrained to using older kernel or C library versions |
288 | (which is typical in embedded systems, for example). | |
ba83bc0d MK |
289 | .TP |
290 | .B OPTIONS | |
9042e249 | 291 | A description of the command-line options accepted by a |
ba83bc0d | 292 | program and how they change its behavior. |
5711c04f | 293 | .IP |
33a0ccb2 | 294 | This section should appear only for Section 1 and 8 manual pages. |
ba83bc0d MK |
295 | .\" .TP |
296 | .\" .B USAGE | |
297 | .\" describes the grammar of any sublanguage this implements. | |
ba83bc0d MK |
298 | .TP |
299 | .B EXIT STATUS | |
9042e249 | 300 | A list of the possible exit status values of a program and |
ba83bc0d | 301 | the conditions that cause these values to be returned. |
5711c04f | 302 | .IP |
33a0ccb2 | 303 | This section should appear only for Section 1 and 8 manual pages. |
ba83bc0d MK |
304 | .TP |
305 | .B RETURN VALUE | |
306 | For Section 2 and 3 pages, this section gives a | |
307 | list of the values the library routine will return to the caller | |
308 | and the conditions that cause these values to be returned. | |
309 | .TP | |
310 | .B ERRORS | |
311 | For Section 2 and 3 manual pages, this is a list of the | |
312 | values that may be placed in | |
313 | .I errno | |
314 | in the event of an error, along with information about the cause | |
315 | of the errors. | |
5711c04f | 316 | .IP |
520caa55 MK |
317 | Where several different conditions produce the same error, |
318 | the preferred approach is to create separate list entries | |
319 | (with duplicate error names) for each of the conditions. | |
320 | This makes the separate conditions clear, may make the list easier to read, | |
321 | and allows metainformation | |
322 | (e.g., kernel version number where the condition first became applicable) | |
323 | to be more easily marked for each condition. | |
5711c04f | 324 | .IP |
09f49246 | 325 | .IR "The error list should be in alphabetical order" . |
ba83bc0d MK |
326 | .TP |
327 | .B ENVIRONMENT | |
9042e249 | 328 | A list of all environment variables that affect the program or function |
ba83bc0d MK |
329 | and how they affect it. |
330 | .TP | |
331 | .B FILES | |
9042e249 | 332 | A list of the files the program or function uses, such as |
ba83bc0d MK |
333 | configuration files, startup files, |
334 | and files the program directly operates on. | |
5711c04f | 335 | .IP |
ba83bc0d MK |
336 | Give the full pathname of these files, and use the installation |
337 | process to modify the directory part to match user preferences. | |
338 | For many programs, the default installation location is in | |
339 | .IR /usr/local , | |
340 | so your base manual page should use | |
341 | .I /usr/local | |
342 | as the base. | |
343 | .\" May 07: Almost no current man pages have a DIAGNOSTICS section; | |
344 | .\" "RETURN VALUE" or "EXIT STATUS" is preferred. | |
345 | .\" .TP | |
346 | .\" .B DIAGNOSTICS | |
347 | .\" gives an overview of the most common error messages and how to | |
348 | .\" cope with them. | |
349 | .\" You don't need to explain system error messages | |
350 | .\" or fatal signals that can appear during execution of any program | |
351 | .\" unless they're special in some way to the program. | |
352 | .\" | |
353 | .\" May 07: Almost no current man pages have a SECURITY section. | |
354 | .\".TP | |
355 | .\".B SECURITY | |
356 | .\"discusses security issues and implications. | |
357 | .\"Warn about configurations or environments that should be avoided, | |
358 | .\"commands that may have security implications, and so on, especially | |
359 | .\"if they aren't obvious. | |
360 | .\"Discussing security in a separate section isn't necessary; | |
361 | .\"if it's easier to understand, place security information in the | |
362 | .\"other sections (such as the | |
363 | .\" .B DESCRIPTION | |
364 | .\" or | |
365 | .\" .B USAGE | |
366 | .\" section). | |
367 | .\" However, please include security information somewhere! | |
368 | .TP | |
746e0af1 | 369 | .B ATTRIBUTES |
361b7ac7 MK |
370 | A summary of various attributes of the function(s) documented on this page. |
371 | See | |
372 | .BR attributes (7) | |
373 | for further details. | |
746e0af1 | 374 | .TP |
ba83bc0d MK |
375 | .B VERSIONS |
376 | A brief summary of the Linux kernel or glibc versions where a | |
377 | system call or library function appeared, | |
378 | or changed significantly in its operation. | |
5711c04f | 379 | .IP |
294544e7 MK |
380 | As a general rule, every new interface should |
381 | include a VERSIONS section in its manual page. | |
382 | Unfortunately, | |
383 | many existing manual pages don't include this information | |
384 | (since there was no policy to do so when they were written). | |
385 | Patches to remedy this are welcome, | |
386 | but, from the perspective of programmers writing new code, | |
33a0ccb2 | 387 | this information probably matters only in the case of kernel |
294544e7 MK |
388 | interfaces that have been added in Linux 2.4 or later |
389 | (i.e., changes since kernel 2.2), | |
390 | and library functions that have been added to glibc since version 2.1 | |
391 | (i.e., changes since glibc 2.0). | |
5711c04f | 392 | .IP |
294544e7 MK |
393 | The |
394 | .BR syscalls (2) | |
f4b5a0b0 MK |
395 | manual page also provides information about kernel versions |
396 | in which various system calls first appeared. | |
ba83bc0d MK |
397 | .TP |
398 | .B CONFORMING TO | |
9042e249 | 399 | A description of any standards or conventions that relate to the function |
04bc8827 | 400 | or command described by the manual page. |
5711c04f | 401 | .IP |
7849287b MK |
402 | The preferred terms to use for the various standards are listed as |
403 | headings in | |
404 | .BR standards (7). | |
5711c04f | 405 | .IP |
04bc8827 MK |
406 | For a page in Section 2 or 3, |
407 | this section should note the POSIX.1 | |
408 | version(s) that the call conforms to, | |
409 | and also whether the call is specified in C99. | |
410 | (Don't worry too much about other standards like SUS, SUSv2, and XPG, | |
411 | or the SVr4 and 4.xBSD implementation standards, | |
412 | unless the call was specified in those standards, | |
413 | but isn't in the current version of POSIX.1.) | |
5711c04f | 414 | .IP |
988db661 MK |
415 | If the call is not governed by any standards but commonly |
416 | exists on other systems, note them. | |
8382f16d | 417 | If the call is Linux-specific, note this. |
5711c04f | 418 | .IP |
ebc2edd1 MK |
419 | If this section consists of just a list of standards |
420 | (which it commonly does), | |
421 | terminate the list with a period (\(aq.\(aq). | |
ba83bc0d MK |
422 | .TP |
423 | .B NOTES | |
9042e249 | 424 | Miscellaneous notes. |
5711c04f | 425 | .IP |
f8843c2e | 426 | For Section 2 and 3 man pages you may find it useful to include |
ba83bc0d | 427 | subsections (\fBSS\fP) named \fILinux Notes\fP and \fIGlibc Notes\fP. |
5711c04f | 428 | .IP |
3a8bef11 | 429 | In Section 2, use the heading |
0722a578 | 430 | .I "C library/kernel differences" |
3a8bef11 | 431 | to mark off notes that describe the differences (if any) between |
ef4f4031 | 432 | the C library wrapper function for a system call and |
3a8bef11 | 433 | the raw system call interface provided by the kernel. |
ba83bc0d MK |
434 | .TP |
435 | .B BUGS | |
9042e249 | 436 | A list of limitations, known defects or inconveniences, |
ba83bc0d MK |
437 | and other questionable activities. |
438 | .TP | |
439 | .B EXAMPLE | |
9042e249 | 440 | One or more examples demonstrating how this function, file or |
ba83bc0d | 441 | command is used. |
5711c04f | 442 | .IP |
04bc8827 | 443 | For details on writing example programs, |
1caf9454 | 444 | see \fIExample programs\fP below. |
ba83bc0d | 445 | .TP |
dcbc136a | 446 | .B AUTHORS |
9042e249 | 447 | A list of authors of the documentation or program. |
5711c04f | 448 | .IP |
dcbc136a | 449 | \fBUse of an AUTHORS section is strongly discouraged\fP. |
ba83bc0d MK |
450 | Generally, it is better not to clutter every page with a list |
451 | of (over time potentially numerous) authors; | |
452 | if you write or significantly amend a page, | |
453 | add a copyright notice as a comment in the source file. | |
0cc32b69 | 454 | If you are the author of a device driver and want to include |
f8843c2e | 455 | an address for reporting bugs, place this under the BUGS section. |
ba83bc0d | 456 | .TP |
c91a4f14 MK |
457 | .B REPORTING BUGS |
458 | The | |
459 | .IR man-pages | |
460 | project doesn't use a REPORTING BUGS section in manual pages. | |
461 | Information on reporting bugs is instead supplied in the | |
462 | script-generated COLOPHON section. | |
463 | However, various projects do use a REPORTING BUGS section. | |
464 | it is recommended to place it near the foot of the page. | |
465 | .TP | |
88c9c16a MK |
466 | .B COPYRIGHT |
467 | The | |
468 | .IR man-pages | |
469 | project doesn't use a COPYRIGHT section in manual pages. | |
470 | Copyright information is instead maintained in the page source. | |
471 | In pages where this section is present, | |
472 | it is recommended to place it near the foot of the page, just above SEE ALSO. | |
473 | .TP | |
ba83bc0d | 474 | .B SEE ALSO |
9042e249 | 475 | A comma-separated list of related man pages, possibly followed by |
ba83bc0d | 476 | other related pages or documents. |
5711c04f | 477 | .IP |
9042e249 | 478 | The list should be ordered by section number and |
2b917159 | 479 | then alphabetically by name. |
d2d136f7 | 480 | Do not terminate this list with a period. |
c92b6bb5 MK |
481 | .IP |
482 | Where the SEE ALSO list contains many long manual page names, | |
483 | to improve the visual result of the output, it may be useful to employ the | |
484 | .I .ad l | |
485 | (don't right justify) | |
486 | and | |
487 | .I .nh | |
97776844 | 488 | (don't hyphenate) |
c92b6bb5 | 489 | directives. |
4eaa04c5 | 490 | Hyphenation of individual page names can be prevented |
d1a71985 | 491 | by preceding words with the string "\e%". |
5711c04f | 492 | .IP |
aeb666ce MK |
493 | Given the distributed, autonomous nature of FOSS projects |
494 | and their documentation, it is sometimes necessary\(emand in many cases | |
495 | desirable\(emthat the SEE ALSO section includes references to | |
496 | manual pages provided by other projects. | |
7849287b | 497 | .SH STYLE GUIDE |
9730fd84 MK |
498 | The following subsections describe the preferred style for the |
499 | .IR man-pages | |
7849287b MK |
500 | project. |
501 | For details not covered below, the Chicago Manual of Style | |
9730fd84 MK |
502 | is usually a good source; |
503 | try also grepping for preexisting usage in the project source tree. | |
7849287b MK |
504 | .SS Use of gender-neutral language |
505 | As far as possible, use gender-neutral language in the text of man | |
aa89a58e | 506 | pages. |
7849287b | 507 | Use of "they" ("them", "themself", "their") as a gender-neutral singular |
9730fd84 | 508 | pronoun is acceptable. |
c0ada844 | 509 | .\" |
741abfa1 | 510 | .SS Formatting conventions for manual pages describing commands |
ba83bc0d | 511 | .PP |
741abfa1 | 512 | For manual pages that describe a command (typically in Sections 1 and 8), |
c0ada844 MK |
513 | the arguments are always specified using italics, |
514 | .IR "even in the SYNOPSIS section" . | |
5711c04f | 515 | .PP |
c0ada844 MK |
516 | The name of the command, and its options, should |
517 | always be formatted in bold. | |
518 | .\" | |
519 | .SS Formatting conventions for manual pages describing functions | |
520 | For manual pages that describe functions (typically in Sections 2 and 3), | |
521 | the arguments are always specified using italics, | |
ba83bc0d MK |
522 | .IR "even in the SYNOPSIS section" , |
523 | where the rest of the function is specified in bold: | |
524 | .PP | |
ba83bc0d | 525 | .BI " int myfunction(int " argc ", char **" argv ); |
ba83bc0d | 526 | .PP |
027ebd3c | 527 | Variable names should, like argument names, be specified in italics. |
5711c04f | 528 | .PP |
c0ada844 MK |
529 | Any reference to the subject of the current manual page |
530 | should be written with the name in bold followed by | |
531 | a pair of parentheses in Roman (normal) font. | |
532 | For example, in the | |
533 | .BR fcntl (2) | |
534 | man page, references to the subject of the page would be written as: | |
535 | .BR fcntl (). | |
536 | The preferred way to write this in the source file is: | |
9c40f2b9 MK |
537 | .PP |
538 | .EX | |
c0ada844 | 539 | .BR fcntl () |
9c40f2b9 MK |
540 | .EE |
541 | .PP | |
d1a71985 | 542 | (Using this format, rather than the use of "\efB...\efP()" |
c0ada844 MK |
543 | makes it easier to write tools that parse man page source files.) |
544 | .\" | |
4dfeb670 MK |
545 | .SS Use semantic newlines |
546 | In the source of a manual page, | |
547 | new sentences should be started on new lines, | |
548 | and long sentences should split into lines at clause breaks | |
549 | (commas, semicolons, colons, and so on). | |
550 | This convention, sometimes known as "semantic newlines", | |
551 | makes it easier to see the effect of patches, | |
552 | which often operate at the level of individual sentences or sentence clauses. | |
553 | .\" | |
c0ada844 | 554 | .SS Formatting conventions (general) |
4dfeb670 | 555 | .PP |
724ca69c MK |
556 | Paragraphs should be separated by suitable markers (usually either |
557 | .I .PP | |
558 | or | |
559 | .IR .IP ). | |
560 | Do | |
561 | .I not | |
562 | separate paragraphs using blank lines, as this results in poor rendering | |
563 | in some output formats (such as PostScript and PDF). | |
564 | .PP | |
9730fd84 | 565 | Filenames (whether pathnames, or references to header files) |
fc573e5f MK |
566 | are always in italics (e.g., |
567 | .IR <stdio.h> ), | |
ba83bc0d MK |
568 | except in the SYNOPSIS section, where included files are in bold (e.g., |
569 | .BR "#include <stdio.h>" ). | |
9730fd84 | 570 | When referring to a standard header file include, |
f36234fa MK |
571 | specify the header file surrounded by angle brackets, |
572 | in the usual C way (e.g., | |
ab9616d3 | 573 | .IR <stdio.h> ). |
ba83bc0d | 574 | .PP |
efaef3da | 575 | Special macros, which are usually in uppercase, are in bold (e.g., |
ba83bc0d MK |
576 | .BR MAXINT ). |
577 | Exception: don't boldface NULL. | |
578 | .PP | |
579 | When enumerating a list of error codes, the codes are in bold (this list | |
580 | usually uses the | |
581 | .B \&.TP | |
582 | macro). | |
5711c04f | 583 | .PP |
027ebd3c | 584 | Complete commands should, if long, |
9730fd84 MK |
585 | be written as an indented line on their own, |
586 | with a blank line before and after the command, for example | |
e646a1ba | 587 | .PP |
027ebd3c | 588 | .in +4n |
e646a1ba | 589 | .EX |
c30acaeb | 590 | man 7 man\-pages |
e646a1ba | 591 | .EE |
027ebd3c | 592 | .in |
e646a1ba | 593 | .PP |
a4f844c6 | 594 | If the command is short, then it can be included inline in the text, |
027ebd3c MK |
595 | in italic format, for example, |
596 | .IR "man 7 man-pages" . | |
24b74457 | 597 | In this case, it may be worth using nonbreaking spaces |
31a6818e | 598 | ("\e\ ") at suitable places in the command. |
10850212 MK |
599 | Command options should be written in italics (e.g., |
600 | .IR \-l ). | |
027ebd3c MK |
601 | .PP |
602 | Expressions, if not written on a separate indented line, should | |
603 | be specified in italics. | |
24b74457 | 604 | Again, the use of nonbreaking spaces may be appropriate |
027ebd3c | 605 | if the expression is inlined with normal text. |
5711c04f | 606 | .PP |
c0ada844 | 607 | When showing example shell sessions, user input should be formatted in bold, for example |
019d9ee8 | 608 | .PP |
c0ada844 | 609 | .in +4n |
019d9ee8 MK |
610 | .EX |
611 | $ \fBdate\fP | |
612 | Thu Jul 7 13:01:27 CEST 2016 | |
613 | .EE | |
c0ada844 | 614 | .in |
019d9ee8 | 615 | .PP |
ba83bc0d MK |
616 | .PP |
617 | Any reference to another man page | |
618 | should be written with the name in bold, | |
aeb9b6a6 MK |
619 | .I always |
620 | followed by the section number, | |
ba83bc0d MK |
621 | formatted in Roman (normal) font, without any |
622 | separating spaces (e.g., | |
623 | .BR intro (2)). | |
624 | The preferred way to write this in the source file is: | |
9c40f2b9 MK |
625 | .PP |
626 | .EX | |
ba83bc0d | 627 | .BR intro (2) |
9c40f2b9 MK |
628 | .EE |
629 | .PP | |
ba83bc0d MK |
630 | (Including the section number in cross references lets tools like |
631 | .BR man2html (1) | |
632 | create properly hyperlinked pages.) | |
5711c04f | 633 | .PP |
7849287b MK |
634 | Control characters should be written in bold face, |
635 | with no quotes; for example, | |
636 | .BR ^X . | |
55f7ee2a | 637 | .SS Spelling |
9daed026 | 638 | Starting with release 2.59, |
55f7ee2a | 639 | .I man-pages |
91e4f660 | 640 | follows American spelling conventions |
7849287b | 641 | (previously, there was a random mix of British and American spellings); |
55f7ee2a | 642 | please write all new pages and patches according to these conventions. |
5711c04f | 643 | .PP |
7849287b MK |
644 | Aside from the well-known spelling differences, |
645 | there are a few other subtleties to watch for: | |
646 | .IP * 3 | |
28aac7d7 | 647 | American English tends to use the forms "backward", "upward", "toward", |
7849287b | 648 | and so on |
28aac7d7 | 649 | rather than the British forms "backwards", "upwards", "towards", and so on. |
7849287b MK |
650 | .SS BSD version numbers |
651 | The classical scheme for writing BSD version numbers is | |
652 | .IR x.yBSD , | |
653 | where | |
654 | .I x.y | |
655 | is the version number (e.g., 4.2BSD). | |
656 | Avoid forms such as | |
657 | .IR "BSD 4.3" . | |
159f0403 | 658 | .SS Capitalization |
7849287b | 659 | In subsection ("SS") headings, |
efaef3da | 660 | capitalize the first word in the heading, but otherwise use lowercase, |
159f0403 MK |
661 | except where English usage (e.g., proper nouns) or programming |
662 | language requirements (e.g., identifier names) dictate otherwise. | |
09e311c5 | 663 | For example: |
5711c04f | 664 | .PP |
9c40f2b9 | 665 | .EX |
9730fd84 | 666 | .SS Unicode under Linux |
9c40f2b9 | 667 | .EE |
787dd4ad | 668 | .\" |
f78ed33a | 669 | .SS Indentation of structure definitions, shell session logs, and so on |
7849287b MK |
670 | When structure definitions, shell session logs, and so on are included |
671 | in running text, indent them by 4 spaces (i.e., a block enclosed by | |
672 | .I ".in\ +4n" | |
673 | and | |
d6dceb1a MK |
674 | .IR ".in" ), |
675 | format them using the | |
676 | .I .EX | |
677 | and | |
678 | .I EE | |
679 | macros, and surround them with suitable paragraph markers (either | |
680 | .I .PP | |
681 | or | |
682 | .IR .IP ). | |
683 | For example: | |
684 | .PP | |
685 | .in +4n | |
686 | .EX | |
687 | .PP | |
688 | .in +4n | |
689 | .EX | |
690 | int | |
691 | main(int argc, char *argv[]) | |
692 | { | |
693 | return 0; | |
694 | } | |
695 | .EE | |
696 | .in | |
697 | .PP | |
698 | .EE | |
699 | .in | |
7849287b MK |
700 | .SS Preferred terms |
701 | The following table lists some preferred terms to use in man pages, | |
702 | mainly to ensure consistency across pages. | |
7849287b MK |
703 | .TS |
704 | l l l | |
705 | --- | |
706 | l l l. | |
707 | Term Avoid using Notes | |
708 | ||
709 | bit mask bitmask | |
710 | built-in builtin | |
711 | Epoch epoch T{ | |
712 | For the UNIX Epoch (00:00:00, 1 Jan 1970 UTC) | |
713 | T} | |
714 | filename file name | |
9730fd84 | 715 | filesystem file system |
7849287b MK |
716 | hostname host name |
717 | inode i-node | |
a6ce0ba5 | 718 | lowercase lower case, lower-case |
777411ae | 719 | nonzero non-zero |
7849287b MK |
720 | pathname path name |
721 | pseudoterminal pseudo-terminal | |
722 | privileged port T{ | |
723 | reserved port, | |
724 | system port | |
725 | T} | |
726 | real-time T{ | |
727 | realtime, | |
4a6cd1db | 728 | real time |
7849287b MK |
729 | T} |
730 | run time runtime | |
731 | saved set-group-ID T{ | |
732 | saved group ID, | |
733 | saved set-GID | |
734 | T} | |
735 | saved set-user-ID T{ | |
736 | saved user ID, | |
737 | saved set-UID | |
738 | T} | |
739 | set-group-ID set-GID, setgid | |
740 | set-user-ID set-UID, setuid | |
741 | superuser T{ | |
742 | super user, | |
743 | super-user | |
744 | T} | |
644ee9c7 MK |
745 | superblock T{ |
746 | super block, | |
747 | super-block | |
748 | T} | |
7849287b MK |
749 | timestamp time stamp |
750 | timezone time zone | |
a6ce0ba5 | 751 | uppercase upper case, upper-case |
e03fae06 | 752 | usable useable |
7849287b MK |
753 | user space userspace |
754 | username user name | |
8d4b8846 MK |
755 | x86-64 x86_64 T{ |
756 | Except if referring to result of "uname\ \-m" or similar | |
757 | T} | |
7849287b MK |
758 | zeros zeroes |
759 | .TE | |
4a6cd1db DP |
760 | .PP |
761 | See also the discussion | |
9730fd84 MK |
762 | .IR "Hyphenation of attributive compounds" |
763 | below. | |
7849287b MK |
764 | .SS Terms to avoid |
765 | The following table lists some terms to avoid using in man pages, | |
766 | along with some suggested alternatives, | |
767 | mainly to ensure consistency across pages. | |
7849287b MK |
768 | .TS |
769 | l l l | |
770 | --- | |
771 | l l l. | |
772 | Avoid Use instead Notes | |
773 | ||
9730fd84 MK |
774 | 32bit 32-bit T{ |
775 | same for 8-bit, 16-bit, etc. | |
776 | T} | |
7849287b MK |
777 | current process calling process T{ |
778 | A common mistake made by kernel programmers when writing man pages | |
779 | T} | |
780 | manpage T{ | |
781 | man page, manual page | |
782 | T} | |
783 | minus infinity negative infinity | |
784 | non-root unprivileged user | |
785 | non-superuser unprivileged user | |
786 | nonprivileged unprivileged | |
787 | OS operating system | |
788 | plus infinity positive infinity | |
789 | pty pseudoterminal | |
7849287b MK |
790 | tty terminal |
791 | Unices UNIX systems | |
792 | Unixes UNIX systems | |
793 | .TE | |
7849287b | 794 | .SS Trademarks |
aa89a58e MK |
795 | Use the correct spelling and case for trademarks. |
796 | The following is a list of the correct spellings of various | |
7849287b | 797 | relevant trademarks that are sometimes misspelled: |
5711c04f | 798 | .PP |
7849287b MK |
799 | DG/UX |
800 | HP-UX | |
801 | UNIX | |
802 | UnixWare | |
803 | .SS NULL, NUL, null pointer, and null character | |
804 | A | |
805 | .IR "null pointer" | |
806 | is a pointer that points to nothing, | |
807 | and is normally indicated by the constant | |
808 | .IR NULL . | |
809 | On the other hand, | |
810 | .I NUL | |
811 | is the | |
812 | .IR "null byte", | |
813 | a byte with the value 0, represented in C via the character constant | |
814 | .IR \(aq\e0\(aq . | |
5711c04f | 815 | .PP |
7849287b MK |
816 | The preferred term for the pointer is "null pointer" or simply "NULL"; |
817 | avoid writing "NULL pointer". | |
5711c04f | 818 | .PP |
7849287b MK |
819 | The preferred term for the byte is "null byte". |
820 | Avoid writing "NUL", since it is too easily confused with "NULL". | |
821 | Avoid also the terms "zero byte" and "null character". | |
822 | The byte that terminates a C string should be described | |
823 | as "the terminating null byte"; | |
824 | strings may be described as "null-terminated", | |
825 | but avoid the use of "NUL-terminated". | |
826 | .SS Hyperlinks | |
827 | For hyperlinks, use the | |
828 | .IR .UR / .UE | |
829 | macro pair | |
830 | (see | |
831 | .BR groff_man (7)). | |
832 | This produces proper hyperlinks that can be used in a web browser, | |
833 | when rendering a page with, say: | |
5711c04f | 834 | .PP |
7849287b MK |
835 | BROWSER=firefox man -H pagename |
836 | .SS Use of e.g., i.e., etc., a.k.a., and similar | |
9ab7f611 BR |
837 | In general, the use of abbreviations such as "e.g.", "i.e.", "etc.", |
838 | "cf.", and "a.k.a." should be avoided, | |
839 | in favor of suitable full wordings | |
840 | ("for example", "that is", "compare to", "and so on", "also known as"). | |
5711c04f | 841 | .PP |
7849287b MK |
842 | The only place where such abbreviations may be acceptable is in |
843 | .I short | |
844 | parenthetical asides (e.g., like this one). | |
5711c04f | 845 | .PP |
7849287b MK |
846 | Always include periods in such abbreviations, as shown here. |
847 | In addition, "e.g." and "i.e." should always be followed by a comma. | |
848 | .SS Em-dashes | |
9730fd84 | 849 | The way to write an em-dash\(emthe glyph that appears |
d1a71985 | 850 | at either end of this subphrase\(emin *roff is with the macro "\e(em". |
9730fd84 MK |
851 | (On an ASCII terminal, an em-dash typically renders as two hyphens, |
852 | but in other typographical contexts it renders as a long dash.) | |
7849287b MK |
853 | Em-dashes should be written |
854 | .I without | |
855 | surrounding spaces. | |
856 | .SS Hyphenation of attributive compounds | |
aa89a58e | 857 | Compound terms should be hyphenated when used attributively |
4a6cd1db | 858 | (i.e., to qualify a following noun). Some examples: |
5711c04f | 859 | .PP |
9730fd84 | 860 | 32-bit value |
7849287b MK |
861 | command-line argument |
862 | floating-point number | |
863 | run-time check | |
864 | user-space function | |
865 | wide-character string | |
866 | .SS Hyphenation with multi, non, pre, re, sub, and so on | |
867 | The general tendency in modern English is not to hyphenate | |
868 | after prefixes such as "multi", "non", "pre", "re", "sub", and so on. | |
869 | Manual pages should generally follow this rule when these prefixes are | |
870 | used in natural English constructions with simple suffixes. | |
871 | The following list gives some examples of the preferred forms: | |
5711c04f | 872 | .PP |
7849287b MK |
873 | interprocess |
874 | multithreaded | |
875 | multiprocess | |
876 | nonblocking | |
877 | nondefault | |
878 | nonempty | |
879 | noninteractive | |
880 | nonnegative | |
881 | nonportable | |
882 | nonzero | |
883 | preallocated | |
884 | precreate | |
885 | prerecorded | |
886 | reestablished | |
887 | reinitialize | |
888 | rearm | |
889 | reread | |
890 | subcomponent | |
891 | subdirectory | |
892 | subsystem | |
5711c04f | 893 | .PP |
7849287b MK |
894 | Hyphens should be retained when the prefixes are used in nonstandard |
895 | English words, with trademarks, proper nouns, acronyms, or compound terms. | |
896 | Some examples: | |
5711c04f | 897 | .PP |
7849287b MK |
898 | non-ASCII |
899 | non-English | |
900 | non-NULL | |
901 | non-real-time | |
5711c04f | 902 | .PP |
7849287b MK |
903 | Finally, note that "re-create" and "recreate" are two different verbs, |
904 | and the former is probably what you want. | |
9f0e82b4 MK |
905 | .SS Real minus character |
906 | Where a real minus character is required (e.g., for numbers such as \-1, | |
e789e07c BR |
907 | for man page cross references such as |
908 | .BR utf\-8 (7), | |
9730fd84 MK |
909 | or when writing options that have a leading dash, such as in |
910 | .IR "ls\ \-l"), | |
4a6cd1db | 911 | use the following form in the man page source: |
5711c04f | 912 | .PP |
d1a71985 | 913 | \e\- |
5711c04f | 914 | .PP |
7849287b MK |
915 | This guideline applies also to code examples. |
916 | .SS Character constants | |
917 | To produce single quotes that render well in both ASCII and UTF-8, | |
918 | use the following form for character constants in the man page source: | |
5711c04f | 919 | .PP |
d1a71985 | 920 | \e(aqC\e(aq |
5711c04f | 921 | .PP |
7849287b MK |
922 | where |
923 | .I C | |
924 | is the quoted character. | |
925 | This guideline applies also to character constants used in code examples. | |
c634028a | 926 | .SS Example programs and shell sessions |
9730fd84 | 927 | Manual pages may include example programs demonstrating how to |
ba83bc0d MK |
928 | use a system call or library function. |
929 | However, note the following: | |
f78f2def | 930 | .IP * 3 |
ba83bc0d | 931 | Example programs should be written in C. |
f78f2def | 932 | .IP * |
33a0ccb2 | 933 | An example program is necessary and useful only if it demonstrates |
ba83bc0d MK |
934 | something beyond what can easily be provided in a textual |
935 | description of the interface. | |
936 | An example program that does nothing | |
937 | other than call an interface usually serves little purpose. | |
f78f2def | 938 | .IP * |
c04c44f8 MK |
939 | Example programs should be fairly short (preferably less than 100 lines; |
940 | ideally less than 50 lines). | |
f78f2def | 941 | .IP * |
ba83bc0d MK |
942 | Example programs should do error checking after system calls and |
943 | library function calls. | |
f78f2def | 944 | .IP * |
ba83bc0d | 945 | Example programs should be complete, and compile without |
5b8dbfd4 | 946 | warnings when compiled with \fIcc\ \-Wall\fP. |
f78f2def | 947 | .IP * |
ba83bc0d | 948 | Where possible and appropriate, example programs should allow |
d9bfdb9c | 949 | experimentation, by varying their behavior based on inputs |
ba83bc0d MK |
950 | (ideally from command-line arguments, or alternatively, via |
951 | input read by the program). | |
f78f2def | 952 | .IP * |
ba83bc0d | 953 | Example programs should be laid out according to Kernighan and |
5998eb25 | 954 | Ritchie style, with 4-space indents. |
ba83bc0d | 955 | (Avoid the use of TAB characters in source code!) |
b1f800c6 | 956 | The following command can be used to format your source code to |
d0b8a20c | 957 | something close to the preferred style: |
5711c04f | 958 | .IP |
d0b8a20c | 959 | indent \-npro \-kr \-i4 \-ts4 \-sob \-l72 \-ss \-nut \-psl prog.c |
f78f2def | 960 | .IP * |
4a6cd1db | 961 | For consistency, all example programs should terminate using either of: |
5711c04f | 962 | .IP |
7849287b MK |
963 | exit(EXIT_SUCCESS); |
964 | exit(EXIT_FAILURE); | |
5711c04f | 965 | .IP |
7849287b | 966 | Avoid using the following forms to terminate a program: |
5711c04f | 967 | .IP |
7849287b MK |
968 | exit(0); |
969 | exit(1); | |
970 | return n; | |
971 | .IP * | |
f78f2def MK |
972 | If there is extensive explanatory text before the |
973 | program source code, mark off the source code | |
d50ee7fb | 974 | with a subsection heading |
f78f2def MK |
975 | .IR "Program source" , |
976 | as in: | |
5711c04f | 977 | .IP |
f78f2def | 978 | .SS Program source |
5711c04f | 979 | .IP |
f78f2def MK |
980 | Always do this if the explanatory text includes a shell session log. |
981 | .PP | |
982 | If you include a shell session log demonstrating the use of a program | |
983 | or other system feature: | |
984 | .IP * 3 | |
985 | Place the session log above the source code listing | |
986 | .IP * | |
987 | Indent the session log by four spaces. | |
988 | .IP * | |
989 | Boldface the user input text, | |
990 | to distinguish it from output produced by the system. | |
ba83bc0d MK |
991 | .PP |
992 | For some examples of what example programs should look like, see | |
993 | .BR wait (2) | |
994 | and | |
995 | .BR pipe (2). | |
996 | .SH EXAMPLE | |
997 | For canonical examples of how man pages in the | |
0daa9e92 | 998 | .I man-pages |
ba83bc0d MK |
999 | package should look, see |
1000 | .BR pipe (2) | |
1001 | and | |
1002 | .BR fcntl (2). | |
1003 | .SH SEE ALSO | |
1004 | .BR man (1), | |
1005 | .BR man2html (1), | |
5e511b39 | 1006 | .BR attributes (7), |
976093f0 MK |
1007 | .BR groff (7), |
1008 | .BR groff_man (7), | |
ba83bc0d MK |
1009 | .BR man (7), |
1010 | .BR mdoc (7) |