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