]>
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 | .\" |
4b72fb64 | 5 | .\" %%%LICENSE_START(verbatim) |
ba83bc0d MK |
6 | .\" Permission is granted to make and distribute verbatim copies of this |
7 | .\" manual provided the copyright notice and this permission notice are | |
8 | .\" preserved on all copies. | |
9 | .\" | |
10 | .\" Permission is granted to copy and distribute modified versions of this | |
11 | .\" manual under the conditions for verbatim copying, provided that the | |
12 | .\" entire resulting derived work is distributed under the terms of a | |
13 | .\" permission notice identical to this one. | |
14 | .\" | |
15 | .\" Since the Linux kernel and libraries are constantly changing, this | |
16 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
17 | .\" responsibility for errors or omissions, or for damages resulting from | |
18 | .\" the use of the information contained herein. The author(s) may not | |
19 | .\" have taken the same level of care in the production of this manual, | |
20 | .\" which is licensed free of charge, as they might when working | |
21 | .\" professionally. | |
22 | .\" | |
23 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
24 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 25 | .\" %%%LICENSE_END |
988db661 MK |
26 | .\" |
27 | .\" 2007-05-30 created by mtk, using text from old man.7 plus | |
04bc8827 | 28 | .\" rewrites and additional text. |
ba83bc0d | 29 | .\" |
159f0403 | 30 | .TH MAN-PAGES 7 2013-02-24 "Linux" "Linux Programmer's Manual" |
ba83bc0d MK |
31 | .SH NAME |
32 | man-pages \- conventions for writing Linux man pages | |
33 | .SH SYNOPSIS | |
34 | .B man | |
35 | .RI [ section ] | |
36 | .I title | |
37 | .SH DESCRIPTION | |
38 | This page describes the conventions that should be employed | |
39 | when writing man pages for the Linux \fIman-pages\fP project, | |
7aa48d58 MK |
40 | which documents the user-space API provided by the Linux kernel |
41 | and the GNU C library. | |
42 | The project thus provides most of the pages in Section 2, | |
b072a788 | 43 | as well as many of the pages that appear |
7aa48d58 | 44 | in Sections 3, 4, 5, and 7 of the man pages on a Linux system. |
ba83bc0d MK |
45 | The conventions described on this page may also be useful |
46 | for authors writing man pages for other projects. | |
c634028a | 47 | .SS Sections of the manual pages |
ba83bc0d MK |
48 | .PP |
49 | The manual Sections are traditionally defined as follows: | |
ba83bc0d MK |
50 | .TP 10 |
51 | .B 1 Commands (Programs) | |
52 | Those commands that can be executed by the user from within | |
53 | a shell. | |
54 | .TP | |
55 | .B 2 System calls | |
56 | Those functions which must be performed by the kernel. | |
57 | .TP | |
58 | .B 3 Library calls | |
59 | Most of the | |
60 | .I libc | |
61 | functions. | |
62 | .TP | |
63 | .B 4 Special files (devices) | |
64 | Files found in | |
65 | .IR /dev . | |
66 | .TP | |
67 | .B 5 File formats and conventions | |
68 | The format for | |
69 | .I /etc/passwd | |
70 | and other human-readable files. | |
71 | .TP | |
72 | .B 6 Games | |
73 | .TP | |
d6aaae47 | 74 | .B 7 Overview, conventions, and miscellaneous |
ba83bc0d MK |
75 | Overviews of various topics, conventions and protocols, |
76 | character set standards, and miscellaneous other things. | |
77 | .TP | |
78 | .B 8 System management commands | |
79 | Commands like | |
80 | .BR mount (8), | |
81 | many of which only root can execute. | |
82 | .\" .TP | |
83 | .\" .B 9 Kernel routines | |
84 | .\" This is an obsolete manual section. | |
85 | .\" Once it was thought a good idea to document the Linux kernel here, | |
86 | .\" but in fact very little has been documented, and the documentation | |
87 | .\" that exists is outdated already. | |
88 | .\" There are better sources of | |
89 | .\" information for kernel developers. | |
ba83bc0d MK |
90 | .SS Macro package |
91 | New manual pages should be marked up using the | |
add00eab | 92 | .B groff an.tmac |
ba83bc0d MK |
93 | package described in |
94 | .BR man (7). | |
988db661 | 95 | This choice is mainly for consistency: the vast majority of |
ba83bc0d MK |
96 | existing Linux manual pages are marked up using these macros. |
97 | .SS Conventions for source file layout | |
988db661 | 98 | Please limit source code line length to no more than about 75 characters |
ba83bc0d MK |
99 | wherever possible. |
100 | This helps avoid line-wrapping in some mail clients when patches are | |
101 | submitted inline. | |
102 | ||
103 | New sentences should be started on new lines. | |
104 | This makes it easier to see the effect of patches, | |
105 | which often operate at the level of individual sentences. | |
106 | .SS Title line | |
107 | The first command in a man page should be a \fBTH\fP command: | |
108 | .RS | |
109 | .sp | |
110 | .B \&.TH | |
0daa9e92 | 111 | .I "title section date source manual" |
ba83bc0d MK |
112 | .sp |
113 | .RE | |
114 | where: | |
115 | .RS | |
116 | .TP 10 | |
117 | .I title | |
118 | The title of the man page, written in all caps (e.g., | |
119 | .IR MAN-PAGES ). | |
120 | .TP | |
121 | .I section | |
122 | The section number in which the man page should be placed (e.g., | |
123 | .IR 7 ). | |
124 | .TP | |
125 | .I date | |
5503c85e | 126 | The date of the last revision\(emremember to change this every time a |
04bc8827 MK |
127 | change is made to the man page, |
128 | since this is the most general way of doing version control. | |
ba83bc0d MK |
129 | Dates should be written in the form YYYY-MM-DD. |
130 | .TP | |
131 | .I source | |
132 | The source of the command, function, or system call. | |
ca92ce95 | 133 | |
ba83bc0d MK |
134 | For those few \fIman-pages\fP pages in Sections 1 and 8, |
135 | probably you just want to write | |
136 | .IR GNU . | |
ca92ce95 | 137 | |
ba83bc0d MK |
138 | For system calls, just write |
139 | .IR "Linux" . | |
140 | (An earlier practice was to write the version number | |
141 | of the kernel from which the manual page was being written/checked. | |
142 | However, this was never done consistently, and so was | |
143 | probably worse than including no version number. | |
144 | Henceforth, avoid including a version number.) | |
ca92ce95 | 145 | |
988db661 | 146 | For library calls that are part of glibc or one of the |
ba83bc0d MK |
147 | other common GNU libraries, just use |
148 | .IR "GNU C Library" ", " GNU , | |
149 | or an empty string. | |
ca92ce95 | 150 | |
ba83bc0d MK |
151 | For Section 4 pages, use |
152 | .IR "Linux" . | |
ca92ce95 | 153 | |
ba83bc0d MK |
154 | In cases of doubt, just write |
155 | .IR Linux ", or " GNU . | |
156 | .TP | |
157 | .I manual | |
988db661 | 158 | The title of the manual (e.g., for Section 2 and 3 pages in |
ba83bc0d MK |
159 | the \fIman-pages\fP package, use |
160 | .IR "Linux Programmer's Manual" ). | |
161 | .RE | |
162 | .SS Sections within a manual page | |
163 | The list below shows conventional or suggested sections. | |
988db661 | 164 | Most manual pages should include at least the |
ba83bc0d MK |
165 | .B highlighted |
166 | sections. | |
04bc8827 | 167 | Arrange a new manual page so that sections |
ba83bc0d MK |
168 | are placed in the order shown in the list. |
169 | .in +0.5i | |
170 | .nf | |
171 | ||
172 | \fBNAME\fP | |
173 | \fBSYNOPSIS\fP | |
1f901dc4 | 174 | CONFIGURATION [Normally only in Section 4] |
ba83bc0d MK |
175 | \fBDESCRIPTION\fP |
176 | OPTIONS [Normally only in Sections 1, 8] | |
177 | EXIT STATUS [Normally only in Sections 1, 8] | |
178 | RETURN VALUE [Normally only in Sections 2, 3] | |
179 | .\" May 07: Few current man pages have an ERROR HANDLING section,,, | |
180 | .\" ERROR HANDLING, | |
181 | ERRORS [Typically only in Sections 2, 3] | |
182 | .\" May 07: Almost no current man pages have a USAGE section,,, | |
988db661 | 183 | .\" USAGE, |
25a46448 | 184 | .\" DIAGNOSTICS, |
ba83bc0d MK |
185 | .\" May 07: Almost no current man pages have a SECURITY section,,, |
186 | .\" SECURITY, | |
187 | ENVIRONMENT | |
188 | FILES | |
189 | VERSIONS [Normally only in Sections 2, 3] | |
190 | CONFORMING TO | |
191 | NOTES | |
192 | BUGS | |
193 | EXAMPLE | |
dcbc136a MK |
194 | .\" AUTHORS sections are discouraged |
195 | .\" AUTHORS [Discouraged] | |
ba83bc0d MK |
196 | \fBSEE ALSO\fP |
197 | ||
198 | .fi | |
199 | .in | |
200 | .IR "Where a traditional heading would apply" ", " "please use it" ; | |
201 | this kind of consistency can make the information easier to understand. | |
988db661 | 202 | If you must, you can create your own |
ba83bc0d MK |
203 | headings if they make things easier to understand (this can |
204 | be especially useful for pages in Sections 4 and 5). | |
205 | However, before doing this, consider whether you could use the | |
206 | traditional headings, with some subsections (\fI.SS\fP) within | |
207 | those sections. | |
208 | ||
988db661 | 209 | The following list elaborates on the contents of each of |
ba83bc0d MK |
210 | the above sections. |
211 | .TP 14 | |
212 | .B NAME | |
213 | The name of this manual page. | |
988db661 | 214 | See |
ba83bc0d MK |
215 | .BR man (7) |
216 | for important details of the line(s) that should follow the | |
25a46448 | 217 | \fB.SH NAME\fP command. |
472926d8 MK |
218 | All words in this line (including the word immediately |
219 | following the "\\\-") should be in lowercase, | |
220 | except where English or technical terminological convention | |
221 | dictates otherwise. | |
ba83bc0d MK |
222 | .TP |
223 | .B SYNOPSIS | |
224 | briefly describes the command or function's interface. | |
225 | For commands, this shows the syntax of the command and its arguments | |
226 | (including options); | |
04bc8827 MK |
227 | boldface is used for as-is text and italics are used to |
228 | indicate replaceable arguments. | |
ba83bc0d MK |
229 | Brackets ([]) surround optional arguments, vertical bars (|) |
230 | separate choices, and ellipses (\&...) can be repeated. | |
231 | For functions, it shows any required data declarations or | |
232 | .B #include | |
233 | directives, followed by the function declaration. | |
d0e676ff MK |
234 | |
235 | Where a feature test macro must be defined in order to obtain | |
236 | the declaration of a function (or a variable) from a header file, | |
237 | then the SYNOPSIS should indicate this, as described in | |
238 | .BR feature_test_macros (7). | |
e48efc84 | 239 | .\" FIXME . Say something here about compiler options |
ba83bc0d | 240 | .TP |
c9890844 MK |
241 | .B CONFIGURATION |
242 | Configuration details for a device. | |
243 | This section normally only appears in Section 4 pages. | |
244 | .TP | |
ba83bc0d MK |
245 | .B DESCRIPTION |
246 | gives an explanation of what the program, function, or format does. | |
247 | Discuss how it interacts with files and standard input, and what it | |
248 | produces on standard output or standard error. | |
249 | Omit internals and implementation details unless they're critical for | |
250 | understanding the interface. | |
251 | Describe the usual case; | |
252 | for information on command-line options of a program use the | |
253 | .B OPTIONS | |
254 | section. | |
255 | .\" If there is some kind of input grammar or complex set of subcommands, | |
256 | .\" consider describing them in a separate | |
257 | .\" .B USAGE | |
258 | .\" section (and just place an overview in the | |
259 | .\" .B DESCRIPTION | |
260 | .\" section). | |
261 | .TP | |
262 | .B OPTIONS | |
988db661 | 263 | describes the command-line options accepted by a |
ba83bc0d MK |
264 | program and how they change its behavior. |
265 | This section should only appear for Section 1 and 8 manual pages. | |
266 | .\" .TP | |
267 | .\" .B USAGE | |
268 | .\" describes the grammar of any sublanguage this implements. | |
ba83bc0d MK |
269 | .TP |
270 | .B EXIT STATUS | |
271 | lists the possible exit status values of a program and | |
272 | the conditions that cause these values to be returned. | |
273 | This section should only appear for Section 1 and 8 manual pages. | |
274 | .TP | |
275 | .B RETURN VALUE | |
276 | For Section 2 and 3 pages, this section gives a | |
277 | list of the values the library routine will return to the caller | |
278 | and the conditions that cause these values to be returned. | |
279 | .TP | |
280 | .B ERRORS | |
281 | For Section 2 and 3 manual pages, this is a list of the | |
282 | values that may be placed in | |
283 | .I errno | |
284 | in the event of an error, along with information about the cause | |
285 | of the errors. | |
09f49246 | 286 | .IR "The error list should be in alphabetical order" . |
ba83bc0d MK |
287 | .TP |
288 | .B ENVIRONMENT | |
289 | lists all environment variables that affect the program or function | |
290 | and how they affect it. | |
291 | .TP | |
292 | .B FILES | |
293 | lists the files the program or function uses, such as | |
294 | configuration files, startup files, | |
295 | and files the program directly operates on. | |
296 | Give the full pathname of these files, and use the installation | |
297 | process to modify the directory part to match user preferences. | |
298 | For many programs, the default installation location is in | |
299 | .IR /usr/local , | |
300 | so your base manual page should use | |
301 | .I /usr/local | |
302 | as the base. | |
303 | .\" May 07: Almost no current man pages have a DIAGNOSTICS section; | |
304 | .\" "RETURN VALUE" or "EXIT STATUS" is preferred. | |
305 | .\" .TP | |
306 | .\" .B DIAGNOSTICS | |
307 | .\" gives an overview of the most common error messages and how to | |
308 | .\" cope with them. | |
309 | .\" You don't need to explain system error messages | |
310 | .\" or fatal signals that can appear during execution of any program | |
311 | .\" unless they're special in some way to the program. | |
312 | .\" | |
313 | .\" May 07: Almost no current man pages have a SECURITY section. | |
314 | .\".TP | |
315 | .\".B SECURITY | |
316 | .\"discusses security issues and implications. | |
317 | .\"Warn about configurations or environments that should be avoided, | |
318 | .\"commands that may have security implications, and so on, especially | |
319 | .\"if they aren't obvious. | |
320 | .\"Discussing security in a separate section isn't necessary; | |
321 | .\"if it's easier to understand, place security information in the | |
322 | .\"other sections (such as the | |
323 | .\" .B DESCRIPTION | |
324 | .\" or | |
325 | .\" .B USAGE | |
326 | .\" section). | |
327 | .\" However, please include security information somewhere! | |
328 | .TP | |
329 | .B VERSIONS | |
330 | A brief summary of the Linux kernel or glibc versions where a | |
331 | system call or library function appeared, | |
332 | or changed significantly in its operation. | |
294544e7 MK |
333 | As a general rule, every new interface should |
334 | include a VERSIONS section in its manual page. | |
335 | Unfortunately, | |
336 | many existing manual pages don't include this information | |
337 | (since there was no policy to do so when they were written). | |
338 | Patches to remedy this are welcome, | |
339 | but, from the perspective of programmers writing new code, | |
340 | this information probably only matters in the case of kernel | |
341 | interfaces that have been added in Linux 2.4 or later | |
342 | (i.e., changes since kernel 2.2), | |
343 | and library functions that have been added to glibc since version 2.1 | |
344 | (i.e., changes since glibc 2.0). | |
345 | ||
346 | The | |
347 | .BR syscalls (2) | |
f4b5a0b0 MK |
348 | manual page also provides information about kernel versions |
349 | in which various system calls first appeared. | |
ba83bc0d MK |
350 | .TP |
351 | .B CONFORMING TO | |
04bc8827 MK |
352 | describes any standards or conventions that relate to the function |
353 | or command described by the manual page. | |
354 | For a page in Section 2 or 3, | |
355 | this section should note the POSIX.1 | |
356 | version(s) that the call conforms to, | |
357 | and also whether the call is specified in C99. | |
358 | (Don't worry too much about other standards like SUS, SUSv2, and XPG, | |
359 | or the SVr4 and 4.xBSD implementation standards, | |
360 | unless the call was specified in those standards, | |
361 | but isn't in the current version of POSIX.1.) | |
362 | (See | |
363 | .BR standards (7).) | |
364 | ||
988db661 MK |
365 | If the call is not governed by any standards but commonly |
366 | exists on other systems, note them. | |
8382f16d | 367 | If the call is Linux-specific, note this. |
ebc2edd1 MK |
368 | |
369 | If this section consists of just a list of standards | |
370 | (which it commonly does), | |
371 | terminate the list with a period (\(aq.\(aq). | |
ba83bc0d MK |
372 | .TP |
373 | .B NOTES | |
374 | provides miscellaneous notes. | |
f8843c2e | 375 | For Section 2 and 3 man pages you may find it useful to include |
ba83bc0d MK |
376 | subsections (\fBSS\fP) named \fILinux Notes\fP and \fIGlibc Notes\fP. |
377 | .TP | |
378 | .B BUGS | |
379 | lists limitations, known defects or inconveniences, | |
380 | and other questionable activities. | |
381 | .TP | |
382 | .B EXAMPLE | |
383 | provides one or more examples describing how this function, file or | |
384 | command is used. | |
04bc8827 MK |
385 | For details on writing example programs, |
386 | see \fIExample Programs\fP below. | |
ba83bc0d | 387 | .TP |
dcbc136a | 388 | .B AUTHORS |
f8843c2e | 389 | lists authors of the documentation or program. |
dcbc136a | 390 | \fBUse of an AUTHORS section is strongly discouraged\fP. |
ba83bc0d MK |
391 | Generally, it is better not to clutter every page with a list |
392 | of (over time potentially numerous) authors; | |
393 | if you write or significantly amend a page, | |
394 | add a copyright notice as a comment in the source file. | |
0cc32b69 | 395 | If you are the author of a device driver and want to include |
f8843c2e | 396 | an address for reporting bugs, place this under the BUGS section. |
ba83bc0d MK |
397 | .TP |
398 | .B SEE ALSO | |
7e1d89c9 | 399 | provides a comma-separated list of related man pages, |
ebc2edd1 | 400 | ordered by section number and |
976093f0 | 401 | then alphabetically by name, possibly followed by |
ba83bc0d | 402 | other related pages or documents. |
ebc2edd1 | 403 | Do not terminate this with a period. |
c92b6bb5 MK |
404 | .IP |
405 | Where the SEE ALSO list contains many long manual page names, | |
406 | to improve the visual result of the output, it may be useful to employ the | |
407 | .I .ad l | |
408 | (don't right justify) | |
409 | and | |
410 | .I .nh | |
97776844 | 411 | (don't hyphenate) |
c92b6bb5 | 412 | directives. |
4eaa04c5 | 413 | Hyphenation of individual page names can be prevented |
c92b6bb5 | 414 | by preceding words with the string "\\%". |
ba83bc0d MK |
415 | .SS Font conventions |
416 | .PP | |
417 | For functions, the arguments are always specified using italics, | |
418 | .IR "even in the SYNOPSIS section" , | |
419 | where the rest of the function is specified in bold: | |
420 | .PP | |
ba83bc0d | 421 | .BI " int myfunction(int " argc ", char **" argv ); |
ba83bc0d | 422 | .PP |
027ebd3c MK |
423 | Variable names should, like argument names, be specified in italics. |
424 | .PP | |
fc573e5f MK |
425 | Filenames (whether pathnames, or references to files in the |
426 | .I /usr/include | |
427 | directory) | |
428 | are always in italics (e.g., | |
429 | .IR <stdio.h> ), | |
ba83bc0d MK |
430 | except in the SYNOPSIS section, where included files are in bold (e.g., |
431 | .BR "#include <stdio.h>" ). | |
f36234fa MK |
432 | When referring to a standard include file under |
433 | .IR /usr/include , | |
434 | specify the header file surrounded by angle brackets, | |
435 | in the usual C way (e.g., | |
ab9616d3 | 436 | .IR <stdio.h> ). |
ba83bc0d MK |
437 | .PP |
438 | Special macros, which are usually in upper case, are in bold (e.g., | |
439 | .BR MAXINT ). | |
440 | Exception: don't boldface NULL. | |
441 | .PP | |
442 | When enumerating a list of error codes, the codes are in bold (this list | |
443 | usually uses the | |
444 | .B \&.TP | |
445 | macro). | |
446 | .PP | |
027ebd3c MK |
447 | Complete commands should, if long, |
448 | be written as in an indented line on their own, for example | |
449 | .in +4n | |
450 | .nf | |
451 | ||
452 | man 7 man-pages | |
453 | ||
454 | .fi | |
455 | .in | |
a4f844c6 | 456 | If the command is short, then it can be included inline in the text, |
027ebd3c MK |
457 | in italic format, for example, |
458 | .IR "man 7 man-pages" . | |
24b74457 | 459 | In this case, it may be worth using nonbreaking spaces |
31a6818e | 460 | ("\e\ ") at suitable places in the command. |
027ebd3c MK |
461 | Command options should be written in italics, e.g., |
462 | .IR \-l . | |
463 | .PP | |
464 | Expressions, if not written on a separate indented line, should | |
465 | be specified in italics. | |
24b74457 | 466 | Again, the use of nonbreaking spaces may be appropriate |
027ebd3c MK |
467 | if the expression is inlined with normal text. |
468 | .PP | |
ba83bc0d | 469 | Any reference to the subject of the current manual page |
f8843c2e MK |
470 | should be written with the name in bold. |
471 | If the subject is a function (i.e., this is a Section 2 or 3 page), | |
988db661 | 472 | then the name should be followed by a pair of parentheses |
f8843c2e MK |
473 | in Roman (normal) font. |
474 | For example, in the | |
475 | .BR fcntl (2) | |
476 | man page, references to the subject of the page would be written as: | |
477 | .BR fcntl (). | |
ba83bc0d MK |
478 | The preferred way to write this in the source file is: |
479 | .nf | |
480 | ||
f8843c2e | 481 | .BR fcntl () |
ba83bc0d MK |
482 | |
483 | .fi | |
484 | (Using this format, rather than the use of "\\fB...\\fP()" | |
485 | makes it easier to write tools that parse man page source files.) | |
486 | .PP | |
487 | Any reference to another man page | |
488 | should be written with the name in bold, | |
489 | \fIalways\fP followed by the section number, | |
490 | formatted in Roman (normal) font, without any | |
491 | separating spaces (e.g., | |
492 | .BR intro (2)). | |
493 | The preferred way to write this in the source file is: | |
494 | .nf | |
495 | ||
496 | .BR intro (2) | |
497 | ||
498 | .fi | |
499 | (Including the section number in cross references lets tools like | |
500 | .BR man2html (1) | |
501 | create properly hyperlinked pages.) | |
55f7ee2a | 502 | .SS Spelling |
9daed026 | 503 | Starting with release 2.59, |
55f7ee2a MK |
504 | .I man-pages |
505 | follows American spelling conventions; | |
506 | please write all new pages and patches according to these conventions. | |
159f0403 MK |
507 | .SS Capitalization |
508 | In subsection ("SS") headings | |
509 | capitalize the first word in heading, but otherwise use lower case, | |
510 | except where English usage (e.g., proper nouns) or programming | |
511 | language requirements (e.g., identifier names) dictate otherwise. | |
c634028a | 512 | .SS Example programs and shell sessions |
988db661 | 513 | Manual pages can include example programs demonstrating how to |
ba83bc0d MK |
514 | use a system call or library function. |
515 | However, note the following: | |
516 | .TP 3 | |
517 | * | |
518 | Example programs should be written in C. | |
519 | .TP | |
520 | * | |
521 | An example program is only necessary and useful if it demonstrates | |
522 | something beyond what can easily be provided in a textual | |
523 | description of the interface. | |
524 | An example program that does nothing | |
525 | other than call an interface usually serves little purpose. | |
526 | .TP | |
527 | * | |
c04c44f8 MK |
528 | Example programs should be fairly short (preferably less than 100 lines; |
529 | ideally less than 50 lines). | |
ba83bc0d MK |
530 | .TP |
531 | * | |
532 | Example programs should do error checking after system calls and | |
533 | library function calls. | |
534 | .TP | |
535 | * | |
536 | Example programs should be complete, and compile without | |
5b8dbfd4 | 537 | warnings when compiled with \fIcc\ \-Wall\fP. |
ba83bc0d MK |
538 | .TP |
539 | * | |
540 | Where possible and appropriate, example programs should allow | |
d9bfdb9c | 541 | experimentation, by varying their behavior based on inputs |
ba83bc0d MK |
542 | (ideally from command-line arguments, or alternatively, via |
543 | input read by the program). | |
544 | .TP | |
545 | * | |
546 | Example programs should be laid out according to Kernighan and | |
5998eb25 | 547 | Ritchie style, with 4-space indents. |
ba83bc0d | 548 | (Avoid the use of TAB characters in source code!) |
ba83bc0d MK |
549 | .PP |
550 | For some examples of what example programs should look like, see | |
551 | .BR wait (2) | |
552 | and | |
553 | .BR pipe (2). | |
b8463199 MK |
554 | |
555 | If you include a shell session demonstrating the use of a program | |
556 | or other system feature, boldface the user input text, | |
557 | to distinguish it from output produced by the system. | |
28f65644 | 558 | .SS Indentation of structure definitions, shell session logs, etc. |
d762e018 | 559 | When structure definitions, shell session logs, and so on are included |
28f65644 MK |
560 | in running text, indent them by 4 spaces (i.e., a block enclosed by |
561 | .I ".in\ +4n" | |
562 | and | |
563 | .IR ".in" ). | |
ba83bc0d MK |
564 | .SH EXAMPLE |
565 | For canonical examples of how man pages in the | |
0daa9e92 | 566 | .I man-pages |
ba83bc0d MK |
567 | package should look, see |
568 | .BR pipe (2) | |
569 | and | |
570 | .BR fcntl (2). | |
571 | .SH SEE ALSO | |
572 | .BR man (1), | |
573 | .BR man2html (1), | |
976093f0 MK |
574 | .BR groff (7), |
575 | .BR groff_man (7), | |
ba83bc0d MK |
576 | .BR man (7), |
577 | .BR mdoc (7) |