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