1MAN-PAGES(7) Linux Programmer's Manual MAN-PAGES(7)
2
3
4
6 man-pages - conventions for writing Linux man pages
7
9 man [section] title
10
12 This page describes the conventions that should be employed when writ‐
13 ing man pages for the Linux man-pages project, which documents the
14 user-space API provided by the Linux kernel and the GNU C library. The
15 project thus provides most of the pages in Section 2, many of the pages
16 that appear in Sections 3, 4, and 7, and a few of the pages that appear
17 in Sections 1, 5, and 8 of the man pages on a Linux system. The con‐
18 ventions described on this page may also be useful for authors writing
19 man pages for other projects.
20
21 Sections of the manual pages
22 The manual Sections are traditionally defined as follows:
23
24 1 User commands (Programs)
25 Commands that can be executed by the user from within a shell.
26
27 2 System calls
28 Functions which wrap operations performed by the kernel.
29
30 3 Library calls
31 All library functions excluding the system call wrappers (Most
32 of the libc functions).
33
34 4 Special files (devices)
35 Files found in /dev which allow to access to devices through the
36 kernel.
37
38 5 File formats and configuration files
39 Describes various human-readable file formats and configuration
40 files.
41
42 6 Games
43 Games and funny little programs available on the system.
44
45 7 Overview, conventions, and miscellaneous
46 Overviews or descriptions of various topics, conventions and
47 protocols, character set standards, the standard filesystem lay‐
48 out, and miscellaneous other things.
49
50 8 System management commands
51 Commands like mount(8), many of which only root can execute.
52
53 Macro package
54 New manual pages should be marked up using the groff an.tmac package
55 described in man(7). This choice is mainly for consistency: the vast
56 majority of existing Linux manual pages are marked up using these
57 macros.
58
59 Conventions for source file layout
60 Please limit source code line length to no more than about 75 charac‐
61 ters wherever possible. This helps avoid line-wrapping in some mail
62 clients when patches are submitted inline.
63
64 Title line
65 The first command in a man page should be a TH command:
66
67 .TH title section date source manual
68
69 The arguments of the command are as follows:
70
71 title The title of the man page, written in all caps (e.g., MAN-
72 PAGES).
73
74 section
75 The section number in which the man page should be placed (e.g.,
76 7).
77
78 date The date of the last nontrivial change that was made to the man
79 page. (Within the man-pages project, the necessary updates to
80 these timestamps are handled automatically by scripts, so there
81 is no need to manually update them as part of a patch.) Dates
82 should be written in the form YYYY-MM-DD.
83
84 source The source of the command, function, or system call.
85
86 For those few man-pages pages in Sections 1 and 8, probably you
87 just want to write GNU.
88
89 For system calls, just write Linux. (An earlier practice was to
90 write the version number of the kernel from which the manual
91 page was being written/checked. However, this was never done
92 consistently, and so was probably worse than including no ver‐
93 sion number. Henceforth, avoid including a version number.)
94
95 For library calls that are part of glibc or one of the other
96 common GNU libraries, just use GNU C Library, GNU, or an empty
97 string.
98
99 For Section 4 pages, use Linux.
100
101 In cases of doubt, just write Linux, or GNU.
102
103 manual The title of the manual (e.g., for Section 2 and 3 pages in the
104 man-pages package, use Linux Programmer's Manual).
105
106 Sections within a manual page
107 The list below shows conventional or suggested sections. Most manual
108 pages should include at least the highlighted sections. Arrange a new
109 manual page so that sections are placed in the order shown in the list.
110
111 NAME
112 SYNOPSIS
113 CONFIGURATION [Normally only in Section 4]
114 DESCRIPTION
115 OPTIONS [Normally only in Sections 1, 8]
116 EXIT STATUS [Normally only in Sections 1, 8]
117 RETURN VALUE [Normally only in Sections 2, 3]
118 ERRORS [Typically only in Sections 2, 3]
119 ENVIRONMENT
120 FILES
121 VERSIONS [Normally only in Sections 2, 3]
122 ATTRIBUTES [Normally only in Sections 2, 3]
123 CONFORMING TO
124 NOTES
125 BUGS
126 EXAMPLES
127 AUTHORS [Discouraged]
128 REPORTING BUGS [Not used in man-pages]
129 COPYRIGHT [Not used in man-pages]
130 SEE ALSO
131
132 Where a traditional heading would apply, please use it; this kind of
133 consistency can make the information easier to understand. If you
134 must, you can create your own headings if they make things easier to
135 understand (this can be especially useful for pages in Sections 4 and
136 5). However, before doing this, consider whether you could use the
137 traditional headings, with some subsections (.SS) within those sec‐
138 tions.
139
140 The following list elaborates on the contents of each of the above sec‐
141 tions.
142
143 NAME The name of this manual page.
144
145 See man(7) for important details of the line(s) that should fol‐
146 low the .SH NAME command. All words in this line (including the
147 word immediately following the "\-") should be in lowercase, ex‐
148 cept where English or technical terminological convention dic‐
149 tates otherwise.
150
151 SYNOPSIS
152 A brief summary of the command or function's interface.
153
154 For commands, this shows the syntax of the command and its argu‐
155 ments (including options); boldface is used for as-is text and
156 italics are used to indicate replaceable arguments. Brackets
157 ([]) surround optional arguments, vertical bars (|) separate
158 choices, and ellipses (...) can be repeated. For functions, it
159 shows any required data declarations or #include directives,
160 followed by the function declaration.
161
162 Where a feature test macro must be defined in order to obtain
163 the declaration of a function (or a variable) from a header
164 file, then the SYNOPSIS should indicate this, as described in
165 feature_test_macros(7).
166
167 CONFIGURATION
168 Configuration details for a device.
169
170 This section normally appears only in Section 4 pages.
171
172 DESCRIPTION
173 An explanation of what the program, function, or format does.
174
175 Discuss how it interacts with files and standard input, and what
176 it produces on standard output or standard error. Omit inter‐
177 nals and implementation details unless they're critical for un‐
178 derstanding the interface. Describe the usual case; for infor‐
179 mation on command-line options of a program use the OPTIONS sec‐
180 tion.
181
182 When describing new behavior or new flags for a system call or
183 library function, be careful to note the kernel or C library
184 version that introduced the change. The preferred method of
185 noting this information for flags is as part of a .TP list, in
186 the following form (here, for a new system call flag):
187
188 XYZ_FLAG (since Linux 3.7)
189 Description of flag...
190
191 Including version information is especially useful to users who
192 are constrained to using older kernel or C library versions
193 (which is typical in embedded systems, for example).
194
195 OPTIONS
196 A description of the command-line options accepted by a program
197 and how they change its behavior.
198
199 This section should appear only for Section 1 and 8 manual
200 pages.
201
202 EXIT STATUS
203 A list of the possible exit status values of a program and the
204 conditions that cause these values to be returned.
205
206 This section should appear only for Section 1 and 8 manual
207 pages.
208
209 RETURN VALUE
210 For Section 2 and 3 pages, this section gives a list of the val‐
211 ues the library routine will return to the caller and the condi‐
212 tions that cause these values to be returned.
213
214 ERRORS For Section 2 and 3 manual pages, this is a list of the values
215 that may be placed in errno in the event of an error, along with
216 information about the cause of the errors.
217
218 Where several different conditions produce the same error, the
219 preferred approach is to create separate list entries (with du‐
220 plicate error names) for each of the conditions. This makes the
221 separate conditions clear, may make the list easier to read, and
222 allows metainformation (e.g., kernel version number where the
223 condition first became applicable) to be more easily marked for
224 each condition.
225
226 The error list should be in alphabetical order.
227
228 ENVIRONMENT
229 A list of all environment variables that affect the program or
230 function and how they affect it.
231
232 FILES A list of the files the program or function uses, such as con‐
233 figuration files, startup files, and files the program directly
234 operates on.
235
236 Give the full pathname of these files, and use the installation
237 process to modify the directory part to match user preferences.
238 For many programs, the default installation location is in
239 /usr/local, so your base manual page should use /usr/local as
240 the base.
241
242 ATTRIBUTES
243 A summary of various attributes of the function(s) documented on
244 this page. See attributes(7) for further details.
245
246 VERSIONS
247 A brief summary of the Linux kernel or glibc versions where a
248 system call or library function appeared, or changed signifi‐
249 cantly in its operation.
250
251 As a general rule, every new interface should include a VERSIONS
252 section in its manual page. Unfortunately, many existing manual
253 pages don't include this information (since there was no policy
254 to do so when they were written). Patches to remedy this are
255 welcome, but, from the perspective of programmers writing new
256 code, this information probably matters only in the case of ker‐
257 nel interfaces that have been added in Linux 2.4 or later (i.e.,
258 changes since kernel 2.2), and library functions that have been
259 added to glibc since version 2.1 (i.e., changes since glibc
260 2.0).
261
262 The syscalls(2) manual page also provides information about ker‐
263 nel versions in which various system calls first appeared.
264
265 CONFORMING TO
266 A description of any standards or conventions that relate to the
267 function or command described by the manual page.
268
269 The preferred terms to use for the various standards are listed
270 as headings in standards(7).
271
272 For a page in Section 2 or 3, this section should note the
273 POSIX.1 version(s) that the call conforms to, and also whether
274 the call is specified in C99. (Don't worry too much about other
275 standards like SUS, SUSv2, and XPG, or the SVr4 and 4.xBSD im‐
276 plementation standards, unless the call was specified in those
277 standards, but isn't in the current version of POSIX.1.)
278
279 If the call is not governed by any standards but commonly exists
280 on other systems, note them. If the call is Linux-specific,
281 note this.
282
283 If this section consists of just a list of standards (which it
284 commonly does), terminate the list with a period ('.').
285
286 NOTES Miscellaneous notes.
287
288 For Section 2 and 3 man pages you may find it useful to include
289 subsections (SS) named Linux Notes and Glibc Notes.
290
291 In Section 2, use the heading C library/kernel differences to
292 mark off notes that describe the differences (if any) between
293 the C library wrapper function for a system call and the raw
294 system call interface provided by the kernel.
295
296 BUGS A list of limitations, known defects or inconveniences, and
297 other questionable activities.
298
299 EXAMPLES
300 One or more examples demonstrating how this function, file or
301 command is used.
302
303 For details on writing example programs, see Example programs
304 below.
305
306 AUTHORS
307 A list of authors of the documentation or program.
308
309 Use of an AUTHORS section is strongly discouraged. Generally,
310 it is better not to clutter every page with a list of (over time
311 potentially numerous) authors; if you write or significantly
312 amend a page, add a copyright notice as a comment in the source
313 file. If you are the author of a device driver and want to in‐
314 clude an address for reporting bugs, place this under the BUGS
315 section.
316
317 REPORTING BUGS
318 The man-pages project doesn't use a REPORTING BUGS section in
319 manual pages. Information on reporting bugs is instead supplied
320 in the script-generated COLOPHON section. However, various
321 projects do use a REPORTING BUGS section. it is recommended to
322 place it near the foot of the page.
323
324 COPYRIGHT
325 The man-pages project doesn't use a COPYRIGHT section in manual
326 pages. Copyright information is instead maintained in the page
327 source. In pages where this section is present, it is recom‐
328 mended to place it near the foot of the page, just above SEE
329 ALSO.
330
331 SEE ALSO
332 A comma-separated list of related man pages, possibly followed
333 by other related pages or documents.
334
335 The list should be ordered by section number and then alphabeti‐
336 cally by name. Do not terminate this list with a period.
337
338 Where the SEE ALSO list contains many long manual page names, to
339 improve the visual result of the output, it may be useful to em‐
340 ploy the .ad l (don't right justify) and .nh (don't hyphenate)
341 directives. Hyphenation of individual page names can be pre‐
342 vented by preceding words with the string "\%".
343
344 Given the distributed, autonomous nature of FOSS projects and
345 their documentation, it is sometimes necessary—and in many cases
346 desirable—that the SEE ALSO section includes references to man‐
347 ual pages provided by other projects.
348
350 The following subsections describe the preferred style for the man-
351 pages project. For details not covered below, the Chicago Manual of
352 Style is usually a good source; try also grepping for preexisting usage
353 in the project source tree.
354
355 Use of gender-neutral language
356 As far as possible, use gender-neutral language in the text of man
357 pages. Use of "they" ("them", "themself", "their") as a gender-neutral
358 singular pronoun is acceptable.
359
360 Formatting conventions for manual pages describing commands
361 For manual pages that describe a command (typically in Sections 1 and
362 8), the arguments are always specified using italics, even in the SYN‐
363 OPSIS section.
364
365 The name of the command, and its options, should always be formatted in
366 bold.
367
368 Formatting conventions for manual pages describing functions
369 For manual pages that describe functions (typically in Sections 2 and
370 3), the arguments are always specified using italics, even in the SYN‐
371 OPSIS section, where the rest of the function is specified in bold:
372
373 int myfunction(int argc, char **argv);
374
375 Variable names should, like argument names, be specified in italics.
376
377 Any reference to the subject of the current manual page should be writ‐
378 ten with the name in bold followed by a pair of parentheses in Roman
379 (normal) font. For example, in the fcntl(2) man page, references to
380 the subject of the page would be written as: fcntl(). The preferred
381 way to write this in the source file is:
382
383 .BR fcntl ()
384
385 (Using this format, rather than the use of "\fB...\fP()" makes it eas‐
386 ier to write tools that parse man page source files.)
387
388 Use semantic newlines
389 In the source of a manual page, new sentences should be started on new
390 lines, and long sentences should split into lines at clause breaks
391 (commas, semicolons, colons, and so on). This convention, sometimes
392 known as "semantic newlines", makes it easier to see the effect of
393 patches, which often operate at the level of individual sentences or
394 sentence clauses.
395
396 Formatting conventions (general)
397 Paragraphs should be separated by suitable markers (usually either .PP
398 or .IP). Do not separate paragraphs using blank lines, as this results
399 in poor rendering in some output formats (such as PostScript and PDF).
400
401 Filenames (whether pathnames, or references to header files) are always
402 in italics (e.g., <stdio.h>), except in the SYNOPSIS section, where in‐
403 cluded files are in bold (e.g., #include <stdio.h>). When referring to
404 a standard header file include, specify the header file surrounded by
405 angle brackets, in the usual C way (e.g., <stdio.h>).
406
407 Special macros, which are usually in uppercase, are in bold (e.g., MAX‐
408 INT). Exception: don't boldface NULL.
409
410 When enumerating a list of error codes, the codes are in bold (this
411 list usually uses the .TP macro).
412
413 Complete commands should, if long, be written as an indented line on
414 their own, with a blank line before and after the command, for example
415
416 man 7 man-pages
417
418 If the command is short, then it can be included inline in the text, in
419 italic format, for example, man 7 man-pages. In this case, it may be
420 worth using nonbreaking spaces ("\ ") at suitable places in the com‐
421 mand. Command options should be written in italics (e.g., -l).
422
423 Expressions, if not written on a separate indented line, should be
424 specified in italics. Again, the use of nonbreaking spaces may be ap‐
425 propriate if the expression is inlined with normal text.
426
427 When showing example shell sessions, user input should be formatted in
428 bold, for example
429
430 $ date
431 Thu Jul 7 13:01:27 CEST 2016
432
433 Any reference to another man page should be written with the name in
434 bold, always followed by the section number, formatted in Roman (nor‐
435 mal) font, without any separating spaces (e.g., intro(2)). The pre‐
436 ferred way to write this in the source file is:
437
438 .BR intro (2)
439
440 (Including the section number in cross references lets tools like
441 man2html(1) create properly hyperlinked pages.)
442
443 Control characters should be written in bold face, with no quotes; for
444 example, ^X.
445
446 Spelling
447 Starting with release 2.59, man-pages follows American spelling conven‐
448 tions (previously, there was a random mix of British and American
449 spellings); please write all new pages and patches according to these
450 conventions.
451
452 Aside from the well-known spelling differences, there are a few other
453 subtleties to watch for:
454
455 * American English tends to use the forms "backward", "upward", "to‐
456 ward", and so on rather than the British forms "backwards", "up‐
457 wards", "towards", and so on.
458
459 BSD version numbers
460 The classical scheme for writing BSD version numbers is x.yBSD, where
461 x.y is the version number (e.g., 4.2BSD). Avoid forms such as BSD 4.3.
462
463 Capitalization
464 In subsection ("SS") headings, capitalize the first word in the head‐
465 ing, but otherwise use lowercase, except where English usage (e.g.,
466 proper nouns) or programming language requirements (e.g., identifier
467 names) dictate otherwise. For example:
468
469 .SS Unicode under Linux
470
471 Indentation of structure definitions, shell session logs, and so on
472 When structure definitions, shell session logs, and so on are included
473 in running text, indent them by 4 spaces (i.e., a block enclosed by
474 .in +4n and .in), format them using the .EX and EE macros, and surround
475 them with suitable paragraph markers (either .PP or .IP). For example:
476
477 .PP
478 .in +4n
479 .EX
480 int
481 main(int argc, char *argv[])
482 {
483 return 0;
484 }
485 .EE
486 .in
487 .PP
488
489 Preferred terms
490 The following table lists some preferred terms to use in man pages,
491 mainly to ensure consistency across pages.
492
493 Term Avoid using Notes
494 ──────────────────────────────────────────────────────────────────
495
496 bit mask bitmask
497 built-in builtin
498 Epoch epoch For the UNIX Epoch
499 (00:00:00, 1 Jan
500 1970 UTC)
501 filename file name
502 filesystem file system
503 hostname host name
504 inode i-node
505 lowercase lower case, lower-case
506 nonzero non-zero
507 pathname path name
508 pseudoterminal pseudo-terminal
509 privileged port reserved port, system
510 port
511 real-time realtime, real time
512 run time runtime
513 saved set-group-ID saved group ID, saved
514 set-GID
515 saved set-user-ID saved user ID, saved
516 set-UID
517 set-group-ID set-GID, setgid
518 set-user-ID set-UID, setuid
519 superuser super user, super-user
520 superblock super block, super-
521 block
522 timestamp time stamp
523 timezone time zone
524 uppercase upper case, upper-case
525 usable useable
526 user space userspace
527 username user name
528 x86-64 x86_64 Except if referring
529 to result of "un‐
530 ame -m" or similar
531 zeros zeroes
532
533 See also the discussion Hyphenation of attributive compounds below.
534
535 Terms to avoid
536 The following table lists some terms to avoid using in man pages, along
537 with some suggested alternatives, mainly to ensure consistency across
538 pages.
539
540 Avoid Use instead Notes
541 ────────────────────────────────────────────────────────────
542
543 32bit 32-bit same for 8-bit,
544 16-bit, etc.
545 current process calling process A common mistake
546 made by kernel pro‐
547 grammers when writ‐
548 ing man pages
549 manpage man page, manual
550 page
551 minus infinity negative infinity
552 non-root unprivileged user
553 non-superuser unprivileged user
554 nonprivileged unprivileged
555 OS operating system
556 plus infinity positive infinity
557 pty pseudoterminal
558 tty terminal
559 Unices UNIX systems
560 Unixes UNIX systems
561
562 Trademarks
563 Use the correct spelling and case for trademarks. The following is a
564 list of the correct spellings of various relevant trademarks that are
565 sometimes misspelled:
566
567 DG/UX
568 HP-UX
569 UNIX
570 UnixWare
571
572 NULL, NUL, null pointer, and null character
573 A null pointer is a pointer that points to nothing, and is normally in‐
574 dicated by the constant NULL. On the other hand, NUL is the null byte,
575 a byte with the value 0, represented in C via the character constant
576 '\0'.
577
578 The preferred term for the pointer is "null pointer" or simply "NULL";
579 avoid writing "NULL pointer".
580
581 The preferred term for the byte is "null byte". Avoid writing "NUL",
582 since it is too easily confused with "NULL". Avoid also the terms
583 "zero byte" and "null character". The byte that terminates a C string
584 should be described as "the terminating null byte"; strings may be de‐
585 scribed as "null-terminated", but avoid the use of "NUL-terminated".
586
587 Hyperlinks
588 For hyperlinks, use the .UR/.UE macro pair (see groff_man(7)). This
589 produces proper hyperlinks that can be used in a web browser, when ren‐
590 dering a page with, say:
591
592 BROWSER=firefox man -H pagename
593
594 Use of e.g., i.e., etc., a.k.a., and similar
595 In general, the use of abbreviations such as "e.g.", "i.e.", "etc.",
596 "cf.", and "a.k.a." should be avoided, in favor of suitable full word‐
597 ings ("for example", "that is", "and so on", "compare to", "also known
598 as").
599
600 The only place where such abbreviations may be acceptable is in short
601 parenthetical asides (e.g., like this one).
602
603 Always include periods in such abbreviations, as shown here. In addi‐
604 tion, "e.g." and "i.e." should always be followed by a comma.
605
606 Em-dashes
607 The way to write an em-dash—the glyph that appears at either end of
608 this subphrase—in *roff is with the macro "\(em". (On an ASCII termi‐
609 nal, an em-dash typically renders as two hyphens, but in other typo‐
610 graphical contexts it renders as a long dash.) Em-dashes should be
611 written without surrounding spaces.
612
613 Hyphenation of attributive compounds
614 Compound terms should be hyphenated when used attributively (i.e., to
615 qualify a following noun). Some examples:
616
617 32-bit value
618 command-line argument
619 floating-point number
620 run-time check
621 user-space function
622 wide-character string
623
624 Hyphenation with multi, non, pre, re, sub, and so on
625 The general tendency in modern English is not to hyphenate after pre‐
626 fixes such as "multi", "non", "pre", "re", "sub", and so on. Manual
627 pages should generally follow this rule when these prefixes are used in
628 natural English constructions with simple suffixes. The following list
629 gives some examples of the preferred forms:
630
631 interprocess
632 multithreaded
633 multiprocess
634 nonblocking
635 nondefault
636 nonempty
637 noninteractive
638 nonnegative
639 nonportable
640 nonzero
641 preallocated
642 precreate
643 prerecorded
644 reestablished
645 reinitialize
646 rearm
647 reread
648 subcomponent
649 subdirectory
650 subsystem
651
652 Hyphens should be retained when the prefixes are used in nonstandard
653 English words, with trademarks, proper nouns, acronyms, or compound
654 terms. Some examples:
655
656 non-ASCII
657 non-English
658 non-NULL
659 non-real-time
660
661 Finally, note that "re-create" and "recreate" are two different verbs,
662 and the former is probably what you want.
663
664 Generating optimal glyphs
665 Where a real minus character is required (e.g., for numbers such as -1,
666 for man page cross references such as utf-8(7), or when writing options
667 that have a leading dash, such as in ls -l), use the following form in
668 the man page source:
669
670 \-
671
672 This guideline applies also to code examples.
673
674 To produce unslanted single quotes that render well in ASCII, UTF-8,
675 and PDF, use "\(aq" ("apostrophe quote"); for example
676
677 \(aqC\(aq
678
679 where C is the quoted character. This guideline applies also to char‐
680 acter constants used in code examples.
681
682 Where a proper caret (^) that renders well in both a terminal and PDF
683 is required, use "\(ha". This is especially necessary in code samples,
684 to get a nicely rendered caret when rendering to PDF.
685
686 Using a naked "~" character results in a poor rendering in PDF. In‐
687 stead use "\(ti". This is especially necessary in code samples, to get
688 a nicely rendered tilde when rendering to PDF.
689
690 Example programs and shell sessions
691 Manual pages may include example programs demonstrating how to use a
692 system call or library function. However, note the following:
693
694 * Example programs should be written in C.
695
696 * An example program is necessary and useful only if it demonstrates
697 something beyond what can easily be provided in a textual descrip‐
698 tion of the interface. An example program that does nothing other
699 than call an interface usually serves little purpose.
700
701 * Example programs should ideally be short (e.g., a good example can
702 often be provided in less than 100 lines of code), though in some
703 cases longer programs may be necessary to properly illustrate the
704 use of an API.
705
706 * Expressive code and useful comments are appreciated.
707
708 * Example programs should do error checking after system calls and li‐
709 brary function calls.
710
711 * Example programs should be complete, and compile without warnings
712 when compiled with cc -Wall.
713
714 * Where possible and appropriate, example programs should allow exper‐
715 imentation, by varying their behavior based on inputs (ideally from
716 command-line arguments, or alternatively, via input read by the pro‐
717 gram).
718
719 * Example programs should be laid out according to Kernighan and
720 Ritchie style, with 4-space indents. (Avoid the use of TAB charac‐
721 ters in source code!) The following command can be used to format
722 your source code to something close to the preferred style:
723
724 indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c
725
726 * For consistency, all example programs should terminate using either
727 of:
728
729 exit(EXIT_SUCCESS);
730 exit(EXIT_FAILURE);
731
732 Avoid using the following forms to terminate a program:
733
734 exit(0);
735 exit(1);
736 return n;
737
738 * If there is extensive explanatory text before the program source
739 code, mark off the source code with a subsection heading Program
740 source, as in:
741
742 .SS Program source
743
744 Always do this if the explanatory text includes a shell session log.
745
746 If you include a shell session log demonstrating the use of a program
747 or other system feature:
748
749 * Place the session log above the source code listing
750
751 * Indent the session log by four spaces.
752
753 * Boldface the user input text, to distinguish it from output produced
754 by the system.
755
756 For some examples of what example programs should look like, see
757 wait(2) and pipe(2).
758
760 For canonical examples of how man pages in the man-pages package should
761 look, see pipe(2) and fcntl(2).
762
764 man(1), man2html(1), attributes(7), groff(7), groff_man(7), man(7),
765 mdoc(7)
766
768 This page is part of release 5.10 of the Linux man-pages project. A
769 description of the project, information about reporting bugs, and the
770 latest version of this page, can be found at
771 https://www.kernel.org/doc/man-pages/.
772
773
774
775Linux 2020-08-13 MAN-PAGES(7)