1man-pages(7) Miscellaneous Information Manual man-pages(7)
2
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 Sections of the manual pages
22 The manual Sections are traditionally defined as follows:
23 1 User commands (Programs)
25 Commands that can be executed by the user from within a shell.
26 2 System calls
28 Functions which wrap operations performed by the kernel.
29 3 Library calls
31 All library functions excluding the system call wrappers (Most
32 of the libc functions).
33 4 Special files (devices)
35 Files found in /dev which allow to access to devices through the
36 kernel.
37 5 File formats and configuration files
39 Describes various human-readable file formats and configuration
40 files.
41 6 Games
43 Games and funny little programs available on the system.
44 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 8 System management commands
51 Commands like mount(8), many of which only root can execute.
52 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 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 Title line
65 The first command in a man page should be a TH command:
66 .TH title section date source manual-section
68 The arguments of the command are as follows:
70 title The title of the man page, written in all caps (e.g., MAN-
72 PAGES).
73 section
75 The section number in which the man page should be placed (e.g.,
76 7).
77 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 source The name and version of the project that provides the manual
85 page (not necessarily the package that provides the functional‐
86 ity).
87 manual-section
89 Normally, this should be empty, since the default value will be
90 good.
91 Sections within a manual page
93 The list below shows conventional or suggested sections. Most manual
94 pages should include at least the highlighted sections. Arrange a new
95 manual page so that sections are placed in the order shown in the list.
96 NAME
98 LIBRARY [Normally only in Sections 2, 3]
99 SYNOPSIS
100 CONFIGURATION [Normally only in Section 4]
101 DESCRIPTION
102 OPTIONS [Normally only in Sections 1, 8]
103 EXIT STATUS [Normally only in Sections 1, 8]
104 RETURN VALUE [Normally only in Sections 2, 3]
105 ERRORS [Typically only in Sections 2, 3]
106 ENVIRONMENT
107 FILES
108 ATTRIBUTES [Normally only in Sections 2, 3]
109 VERSIONS [Normally only in Sections 2, 3]
110 STANDARDS
111 HISTORY
112 NOTES
113 CAVEATS
114 BUGS
115 EXAMPLES
116 AUTHORS [Discouraged]
117 REPORTING BUGS [Not used in man-pages]
118 COPYRIGHT [Not used in man-pages]
119 SEE ALSO
120 Where a traditional heading would apply, please use it; this kind of
122 consistency can make the information easier to understand. If you
123 must, you can create your own headings if they make things easier to
124 understand (this can be especially useful for pages in Sections 4 and
125 5). However, before doing this, consider whether you could use the
126 traditional headings, with some subsections (.SS) within those sec‐
127 tions.
128 The following list elaborates on the contents of each of the above sec‐
130 tions.
131 NAME The name of this manual page.
133 See man(7) for important details of the line(s) that should fol‐
135 low the .SH NAME command. All words in this line (including the
136 word immediately following the "\-") should be in lowercase, ex‐
137 cept where English or technical terminological convention dic‐
138 tates otherwise.
139 LIBRARY
141 The library providing a symbol.
142 It shows the common name of the library, and in parentheses, the
144 name of the library file and, if needed, the linker flag needed
145 to link a program against it: (libfoo[, -lfoo]).
146 SYNOPSIS
148 A brief summary of the command or function's interface.
149 For commands, this shows the syntax of the command and its argu‐
151 ments (including options); boldface is used for as-is text and
152 italics are used to indicate replaceable arguments. Brackets
153 ([]) surround optional arguments, vertical bars (|) separate
154 choices, and ellipses (...) can be repeated. For functions, it
155 shows any required data declarations or #include directives,
156 followed by the function declaration.
157 Where a feature test macro must be defined in order to obtain
159 the declaration of a function (or a variable) from a header
160 file, then the SYNOPSIS should indicate this, as described in
161 feature_test_macros(7).
162 CONFIGURATION
164 Configuration details for a device.
165 This section normally appears only in Section 4 pages.
167 DESCRIPTION
169 An explanation of what the program, function, or format does.
170 Discuss how it interacts with files and standard input, and what
172 it produces on standard output or standard error. Omit inter‐
173 nals and implementation details unless they're critical for un‐
174 derstanding the interface. Describe the usual case; for infor‐
175 mation on command-line options of a program use the OPTIONS sec‐
176 tion.
177 When describing new behavior or new flags for a system call or
179 library function, be careful to note the kernel or C library
180 version that introduced the change. The preferred method of
181 noting this information for flags is as part of a .TP list, in
182 the following form (here, for a new system call flag):
183 XYZ_FLAG (since Linux 3.7)
185 Description of flag...
186 Including version information is especially useful to users who
188 are constrained to using older kernel or C library versions
189 (which is typical in embedded systems, for example).
190 OPTIONS
192 A description of the command-line options accepted by a program
193 and how they change its behavior.
194 This section should appear only for Section 1 and 8 manual
196 pages.
197 EXIT STATUS
199 A list of the possible exit status values of a program and the
200 conditions that cause these values to be returned.
201 This section should appear only for Section 1 and 8 manual
203 pages.
204 RETURN VALUE
206 For Section 2 and 3 pages, this section gives a list of the val‐
207 ues the library routine will return to the caller and the condi‐
208 tions that cause these values to be returned.
209 ERRORS For Section 2 and 3 manual pages, this is a list of the values
211 that may be placed in errno in the event of an error, along with
212 information about the cause of the errors.
213 Where several different conditions produce the same error, the
215 preferred approach is to create separate list entries (with du‐
216 plicate error names) for each of the conditions. This makes the
217 separate conditions clear, may make the list easier to read, and
218 allows metainformation (e.g., kernel version number where the
219 condition first became applicable) to be more easily marked for
220 each condition.
221 The error list should be in alphabetical order.
223 ENVIRONMENT
225 A list of all environment variables that affect the program or
226 function and how they affect it.
227 FILES A list of the files the program or function uses, such as con‐
229 figuration files, startup files, and files the program directly
230 operates on.
231 Give the full pathname of these files, and use the installation
233 process to modify the directory part to match user preferences.
234 For many programs, the default installation location is in
235 /usr/local, so your base manual page should use /usr/local as
236 the base.
237 ATTRIBUTES
239 A summary of various attributes of the function(s) documented on
240 this page. See attributes(7) for further details.
241 VERSIONS
243 A summary of systems where the API performs differently, or
244 where there's a similar API.
245 STANDARDS
247 A description of any standards or conventions that relate to the
248 function or command described by the manual page.
249 The preferred terms to use for the various standards are listed
251 as headings in standards(7).
252 This section should note the current standards to which the API
254 conforms to.
255 If the API is not governed by any standards but commonly exists
257 on other systems, note them. If the call is Linux-specific or
258 GNU-specific, note this. If it's available in the BSDs, note
259 that.
260 If this section consists of just a list of standards (which it
262 commonly does), terminate the list with a period ('.').
263 HISTORY
265 A brief summary of the Linux kernel or glibc versions where a
266 system call or library function appeared, or changed signifi‐
267 cantly in its operation.
268 As a general rule, every new interface should include a HISTORY
270 section in its manual page. Unfortunately, many existing manual
271 pages don't include this information (since there was no policy
272 to do so when they were written). Patches to remedy this are
273 welcome, but, from the perspective of programmers writing new
274 code, this information probably matters only in the case of ker‐
275 nel interfaces that have been added in Linux 2.4 or later (i.e.,
276 changes since Linux 2.2), and library functions that have been
277 added to glibc since glibc 2.1 (i.e., changes since glibc 2.0).
278 The syscalls(2) manual page also provides information about ker‐
280 nel versions in which various system calls first appeared.
281 Old versions of standards should be mentioned here, rather than in
283 STANDARDS, for example, SUS, SUSv2, and XPG, or the SVr4 and 4.xBSD im‐
284 plementation standards.
285 NOTES Miscellaneous notes.
287 For Section 2 and 3 man pages you may find it useful to include
289 subsections (SS) named Linux Notes and glibc Notes.
290 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 CAVEATS
297 Warnings about typical user misuse of an API, that don't consti‐
298 tute an API bug or design defect.
299 BUGS A list of limitations, known defects or inconveniences, and
301 other questionable activities.
302 EXAMPLES
304 One or more examples demonstrating how this function, file, or
305 command is used.
306 For details on writing example programs, see Example programs
308 below.
309 AUTHORS
311 A list of authors of the documentation or program.
312 Use of an AUTHORS section is strongly discouraged. Generally,
314 it is better not to clutter every page with a list of (over time
315 potentially numerous) authors; if you write or significantly
316 amend a page, add a copyright notice as a comment in the source
317 file. If you are the author of a device driver and want to in‐
318 clude an address for reporting bugs, place this under the BUGS
319 section.
320 REPORTING BUGS
322 The man-pages project doesn't use a REPORTING BUGS section in
323 manual pages. Information on reporting bugs is instead supplied
324 in the script-generated COLOPHON section. However, various
325 projects do use a REPORTING BUGS section. It is recommended to
326 place it near the foot of the page.
327 COPYRIGHT
329 The man-pages project doesn't use a COPYRIGHT section in manual
330 pages. Copyright information is instead maintained in the page
331 source. In pages where this section is present, it is recom‐
332 mended to place it near the foot of the page, just above SEE
333 ALSO.
334 SEE ALSO
336 A comma-separated list of related man pages, possibly followed
337 by other related pages or documents.
338 The list should be ordered by section number and then alphabeti‐
340 cally by name. Do not terminate this list with a period.
341 Where the SEE ALSO list contains many long manual page names, to
343 improve the visual result of the output, it may be useful to em‐
344 ploy the .ad l (don't right justify) and .nh (don't hyphenate)
345 directives. Hyphenation of individual page names can be pre‐
346 vented by preceding words with the string "\%".
347 Given the distributed, autonomous nature of FOSS projects and
349 their documentation, it is sometimes necessary—and in many cases
350 desirable—that the SEE ALSO section includes references to man‐
351 ual pages provided by other projects.
352
354 The following subsections note some details for preferred formatting
355 and wording conventions in various sections of the pages in the man-
356 pages project.
357 SYNOPSIS
359 Wrap the function prototype(s) in a .nf/.fi pair to prevent filling.
360 In general, where more than one function prototype is shown in the SYN‐
362 OPSIS, the prototypes should not be separated by blank lines. However,
363 blank lines (achieved using .PP) may be added in the following cases:
364 • to separate long lists of function prototypes into related groups
366 (see for example list(3));
367 • in other cases that may improve readability.
369 In the SYNOPSIS, a long function prototype may need to be continued
371 over to the next line. The continuation line is indented according to
372 the following rules:
373 (1) If there is a single such prototype that needs to be continued,
375 then align the continuation line so that when the page is rendered
376 on a fixed-width font device (e.g., on an xterm) the continuation
377 line starts just below the start of the argument list in the line
378 above. (Exception: the indentation may be adjusted if necessary
379 to prevent a very long continuation line or a further continuation
380 line where the function prototype is very long.) As an example:
381 int tcsetattr(int fd, int optional_actions,
383 const struct termios *termios_p);
384 (2) But, where multiple functions in the SYNOPSIS require continuation
386 lines, and the function names have different lengths, then align
387 all continuation lines to start in the same column. This provides
388 a nicer rendering in PDF output (because the SYNOPSIS uses a vari‐
389 able width font where spaces render narrower than most charac‐
390 ters). As an example:
391 int getopt(int argc, char * const argv[],
393 const char *optstring);
394 int getopt_long(int argc, char * const argv[],
395 const char *optstring,
396 const struct option *longopts, int *longindex);
397 RETURN VALUE
399 The preferred wording to describe how errno is set is "errno is set to
400 indicate the error" or similar. This wording is consistent with the
401 wording used in both POSIX.1 and FreeBSD.
402 ATTRIBUTES
404 Note the following:
405 • Wrap the table in this section in a .ad l/.ad pair to disable text
407 filling and a .nh/.hy pair to disable hyphenation.
408 • Ensure that the table occupies the full page width through the use
410 of an lbx description for one of the columns (usually the first col‐
411 umn, though in some cases the last column if it contains a lot of
412 text).
413 • Make free use of T{/T} macro pairs to allow table cells to be broken
415 over multiple lines (also bearing in mind that pages may sometimes
416 be rendered to a width of less than 80 columns).
417 For examples of all of the above, see the source code of various pages.
419
421 The following subsections describe the preferred style for the man-
422 pages project. For details not covered below, the Chicago Manual of
423 Style is usually a good source; try also grepping for preexisting usage
424 in the project source tree.
425 Use of gender-neutral language
427 As far as possible, use gender-neutral language in the text of man
428 pages. Use of "they" ("them", "themself", "their") as a gender-neutral
429 singular pronoun is acceptable.
430 Formatting conventions for manual pages describing commands
432 For manual pages that describe a command (typically in Sections 1 and
433 8), the arguments are always specified using italics, even in the SYN‐
434 OPSIS section.
435 The name of the command, and its options, should always be formatted in
437 bold.
438 Formatting conventions for manual pages describing functions
440 For manual pages that describe functions (typically in Sections 2 and
441 3), the arguments are always specified using italics, even in the SYN‐
442 OPSIS section, where the rest of the function is specified in bold:
443 int myfunction(int argc, char **argv);
445 Variable names should, like argument names, be specified in italics.
447 Any reference to the subject of the current manual page should be writ‐
449 ten with the name in bold followed by a pair of parentheses in Roman
450 (normal) font. For example, in the fcntl(2) man page, references to
451 the subject of the page would be written as: fcntl(). The preferred
452 way to write this in the source file is:
453 .BR fcntl ()
455 (Using this format, rather than the use of "\fB...\fP()" makes it eas‐
457 ier to write tools that parse man page source files.)
458 Use semantic newlines
460 In the source of a manual page, new sentences should be started on new
461 lines, long sentences should be split into lines at clause breaks (com‐
462 mas, semicolons, colons, and so on), and long clauses should be split
463 at phrase boundaries. This convention, sometimes known as "semantic
464 newlines", makes it easier to see the effect of patches, which often
465 operate at the level of individual sentences, clauses, or phrases.
466 Lists
468 There are different kinds of lists:
469 Tagged paragraphs
471 These are used for a list of tags and their descriptions. When
472 the tags are constants (either macros or numbers) they are in
473 bold. Use the .TP macro.
474 An example is this "Tagged paragraphs" subsection is itself.
476 Ordered lists
478 Elements are preceded by a number in parentheses (1), (2).
479 These represent a set of steps that have an order.
480 When there are substeps, they will be numbered like (4.2).
482 Positional lists
484 Elements are preceded by a number (index) in square brackets
485 [4], [5]. These represent fields in a set. The first index
486 will be:
487 0 When it represents fields of a C data structure, to be
489 consistent with arrays.
490 1 When it represents fields of a file, to be consistent
491 with tools like cut(1).
492 Alternatives list
494 Elements are preceded by a letter in parentheses (a), (b).
495 These represent a set of (normally) exclusive alternatives.
496 Bullet lists
498 Elements are preceded by bullet symbols (\[bu]). Anything that
499 doesn't fit elsewhere is usually covered by this type of list.
500 Numbered notes
502 Not really a list, but the syntax is identical to "positional
503 lists".
504 There should always be exactly 2 spaces between the list symbol and the
506 elements. This doesn't apply to "tagged paragraphs", which use the de‐
507 fault indentation rules.
508 Formatting conventions (general)
510 Paragraphs should be separated by suitable markers (usually either .PP
511 or .IP). Do not separate paragraphs using blank lines, as this results
512 in poor rendering in some output formats (such as PostScript and PDF).
513 Filenames (whether pathnames, or references to header files) are always
515 in italics (e.g., <stdio.h>), except in the SYNOPSIS section, where in‐
516 cluded files are in bold (e.g., #include <stdio.h>). When referring to
517 a standard header file include, specify the header file surrounded by
518 angle brackets, in the usual C way (e.g., <stdio.h>).
519 Special macros, which are usually in uppercase, are in bold (e.g., MAX‐
521 INT). Exception: don't boldface NULL.
522 When enumerating a list of error codes, the codes are in bold (this
524 list usually uses the .TP macro).
525 Complete commands should, if long, be written as an indented line on
527 their own, with a blank line before and after the command, for example
528 man 7 man-pages
530 If the command is short, then it can be included inline in the text, in
532 italic format, for example, man 7 man-pages. In this case, it may be
533 worth using nonbreaking spaces (\[ti]) at suitable places in the com‐
534 mand. Command options should be written in italics (e.g., -l).
535 Expressions, if not written on a separate indented line, should be
537 specified in italics. Again, the use of nonbreaking spaces may be ap‐
538 propriate if the expression is inlined with normal text.
539 When showing example shell sessions, user input should be formatted in
541 bold, for example
542 $ date
544 Thu Jul 7 13:01:27 CEST 2016
545 Any reference to another man page should be written with the name in
547 bold, always followed by the section number, formatted in Roman (nor‐
548 mal) font, without any separating spaces (e.g., intro(2)). The pre‐
549 ferred way to write this in the source file is:
550 .BR intro (2)
552 (Including the section number in cross references lets tools like
554 man2html(1) create properly hyperlinked pages.)
555 Control characters should be written in bold face, with no quotes; for
557 example, ^X.
558 Spelling
560 Starting with release 2.59, man-pages follows American spelling conven‐
561 tions (previously, there was a random mix of British and American
562 spellings); please write all new pages and patches according to these
563 conventions.
564 Aside from the well-known spelling differences, there are a few other
566 subtleties to watch for:
567 • American English tends to use the forms "backward", "upward", "to‐
569 ward", and so on rather than the British forms "backwards", "up‐
570 wards", "towards", and so on.
571 • Opinions are divided on "acknowledgement" vs "acknowledgment". The
573 latter is predominant, but not universal usage in American English.
574 POSIX and the BSD license use the former spelling. In the Linux
575 man-pages project, we use "acknowledgement".
576 BSD version numbers
578 The classical scheme for writing BSD version numbers is x.yBSD, where
579 x.y is the version number (e.g., 4.2BSD). Avoid forms such as BSD 4.3.
580 Capitalization
582 In subsection ("SS") headings, capitalize the first word in the head‐
583 ing, but otherwise use lowercase, except where English usage (e.g.,
584 proper nouns) or programming language requirements (e.g., identifier
585 names) dictate otherwise. For example:
586 .SS Unicode under Linux
588 Indentation of structure definitions, shell session logs, and so on
590 When structure definitions, shell session logs, and so on are included
591 in running text, indent them by 4 spaces (i.e., a block enclosed by
592 .in +4n and .in), format them using the .EX and .EE macros, and sur‐
593 round them with suitable paragraph markers (either .PP or .IP). For
594 example:
595 .PP
597 .in +4n
598 .EX
599 int
600 main(int argc, char *argv[])
601 {
602 return 0;
603 }
604 .EE
605 .in
606 .PP
607 Preferred terms
609 The following table lists some preferred terms to use in man pages,
610 mainly to ensure consistency across pages.
611 Term Avoid using Notes
613 ────────────────────────────────────────────────────────────────
614 bit mask bitmask
615 built-in builtin
616 Epoch epoch For the UNIX
617 Epoch (00:00:00,
618 1 Jan 1970 UTC)
619 filename file name
620 filesystem file system
621 hostname host name
622 inode i-node
623 lowercase lower case, lower-case
624 nonzero non-zero
625 pathname path name
626 pseudoterminal pseudo-terminal
627 privileged port reserved port, system
628 port
629 real-time realtime, real time
630 run time runtime
631 saved set-group-ID saved group ID, saved
632 set-GID
633 saved set-user-ID saved user ID, saved
634 set-UID
635 set-group-ID set-GID, setgid
636 set-user-ID set-UID, setuid
637 superuser super user, super-user
638 superblock super block, super-
639 block
640 symbolic link symlink
641 timestamp time stamp
642 timezone time zone
643 uppercase upper case, upper-case
644 usable useable
645 user space userspace
646 username user name
647 x86-64 x86_64 Except if refer‐
648 ring to result
649 of "uname -m" or
650 similar
651 zeros zeroes
652 See also the discussion Hyphenation of attributive compounds below.
654 Terms to avoid
656 The following table lists some terms to avoid using in man pages, along
657 with some suggested alternatives, mainly to ensure consistency across
658 pages.
659 Avoid Use instead Notes
661 ──────────────────────────────────────────────────────────
662 32bit 32-bit same for 8-bit,
664 16-bit, etc.
665 current process calling process A common mistake
666 made by kernel pro‐
667 grammers when writ‐
668 ing man pages
669 manpage man page, manual
670 page
671 minus infinity negative infinity
672 non-root unprivileged user
673 non-superuser unprivileged user
675 nonprivileged unprivileged
676 OS operating system
677 plus infinity positive infinity
678 pty pseudoterminal
679 tty terminal
680 Unices UNIX systems
681 Unixes UNIX systems
682 Trademarks
684 Use the correct spelling and case for trademarks. The following is a
685 list of the correct spellings of various relevant trademarks that are
686 sometimes misspelled:
687 DG/UX
689 HP-UX
690 UNIX
691 UnixWare
692 NULL, NUL, null pointer, and null byte
694 A null pointer is a pointer that points to nothing, and is normally in‐
695 dicated by the constant NULL. On the other hand, NUL is the null byte,
696 a byte with the value 0, represented in C via the character constant
697 '\0'.
698 The preferred term for the pointer is "null pointer" or simply "NULL";
700 avoid writing "NULL pointer".
701 The preferred term for the byte is "null byte". Avoid writing "NUL",
703 since it is too easily confused with "NULL". Avoid also the terms
704 "zero byte" and "null character". The byte that terminates a C string
705 should be described as "the terminating null byte"; strings may be de‐
706 scribed as "null-terminated", but avoid the use of "NUL-terminated".
707 Hyperlinks
709 For hyperlinks, use the .UR/.UE macro pair (see groff_man(7)). This
710 produces proper hyperlinks that can be used in a web browser, when ren‐
711 dering a page with, say:
712 BROWSER=firefox man -H pagename
714 Use of e.g., i.e., etc., a.k.a., and similar
716 In general, the use of abbreviations such as "e.g.", "i.e.", "etc.",
717 "cf.", and "a.k.a." should be avoided, in favor of suitable full word‐
718 ings ("for example", "that is", "and so on", "compare to", "also known
719 as").
720 The only place where such abbreviations may be acceptable is in short
722 parenthetical asides (e.g., like this one).
723 Always include periods in such abbreviations, as shown here. In addi‐
725 tion, "e.g." and "i.e." should always be followed by a comma.
726 Em-dashes
728 The way to write an em-dash—the glyph that appears at either end of
729 this subphrase—in *roff is with the macro "\[em]". (On an ASCII termi‐
730 nal, an em-dash typically renders as two hyphens, but in other typo‐
731 graphical contexts it renders as a long dash.) Em-dashes should be
732 written without surrounding spaces.
733 Hyphenation of attributive compounds
735 Compound terms should be hyphenated when used attributively (i.e., to
736 qualify a following noun). Some examples:
737 32-bit value
739 command-line argument
740 floating-point number
741 run-time check
743 user-space function
744 wide-character string
745 Hyphenation with multi, non, pre, re, sub, and so on
747 The general tendency in modern English is not to hyphenate after pre‐
748 fixes such as "multi", "non", "pre", "re", "sub", and so on. Manual
749 pages should generally follow this rule when these prefixes are used in
750 natural English constructions with simple suffixes. The following list
751 gives some examples of the preferred forms:
752 interprocess
754 multithreaded
755 multiprocess
756 nonblocking
757 nondefault
758 nonempty
759 noninteractive
760 nonnegative
761 nonportable
762 nonzero
763 preallocated
764 precreate
765 prerecorded
766 reestablished
767 reinitialize
768 rearm
769 reread
770 subcomponent
771 subdirectory
772 subsystem
773 Hyphens should be retained when the prefixes are used in nonstandard
775 English words, with trademarks, proper nouns, acronyms, or compound
776 terms. Some examples:
777 non-ASCII
779 non-English
780 non-NULL
781 non-real-time
782 Finally, note that "re-create" and "recreate" are two different verbs,
784 and the former is probably what you want.
785 Generating optimal glyphs
787 Where a real minus character is required (e.g., for numbers such as -1,
788 for man page cross references such as utf-8(7), or when writing options
789 that have a leading dash, such as in ls -l), use the following form in
790 the man page source:
791 \-
793 This guideline applies also to code examples.
795 The use of real minus signs serves the following purposes:
797 • To provide better renderings on various targets other than ASCII
799 terminals, notably in PDF and on Unicode/UTF-8-capable terminals.
800 • To generate glyphs that when copied from rendered pages will produce
802 real minus signs when pasted into a terminal.
803 To produce unslanted single quotes that render well in ASCII, UTF-8,
805 and PDF, use "\[aq]" ("apostrophe quote"); for example
806 \[aq]C\[aq]
808 where C is the quoted character. This guideline applies also to char‐
810 acter constants used in code examples.
811 Where a proper caret (^) that renders well in both a terminal and PDF
813 is required, use "\[ha]". This is especially necessary in code sam‐
814 ples, to get a nicely rendered caret when rendering to PDF.
815 Using a naked "~" character results in a poor rendering in PDF. In‐
817 stead use "\[ti]". This is especially necessary in code samples, to
818 get a nicely rendered tilde when rendering to PDF.
819 Example programs and shell sessions
821 Manual pages may include example programs demonstrating how to use a
822 system call or library function. However, note the following:
823 • Example programs should be written in C.
825 • An example program is necessary and useful only if it demonstrates
827 something beyond what can easily be provided in a textual descrip‐
828 tion of the interface. An example program that does nothing other
829 than call an interface usually serves little purpose.
830 • Example programs should ideally be short (e.g., a good example can
832 often be provided in less than 100 lines of code), though in some
833 cases longer programs may be necessary to properly illustrate the
834 use of an API.
835 • Expressive code is appreciated.
837 • Comments should included where helpful. Complete sentences in free-
839 standing comments should be terminated by a period. Periods should
840 generally be omitted in "tag" comments (i.e., comments that are
841 placed on the same line of code); such comments are in any case typ‐
842 ically brief phrases rather than complete sentences.
843 • Example programs should do error checking after system calls and li‐
845 brary function calls.
846 • Example programs should be complete, and compile without warnings
848 when compiled with cc -Wall.
849 • Where possible and appropriate, example programs should allow exper‐
851 imentation, by varying their behavior based on inputs (ideally from
852 command-line arguments, or alternatively, via input read by the pro‐
853 gram).
854 • Example programs should be laid out according to Kernighan and
856 Ritchie style, with 4-space indents. (Avoid the use of TAB charac‐
857 ters in source code!) The following command can be used to format
858 your source code to something close to the preferred style:
859 indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c
861 • For consistency, all example programs should terminate using either
863 of:
864 exit(EXIT_SUCCESS);
866 exit(EXIT_FAILURE);
867 Avoid using the following forms to terminate a program:
869 exit(0);
871 exit(1);
872 return n;
873 • If there is extensive explanatory text before the program source
875 code, mark off the source code with a subsection heading Program
876 source, as in:
877 .SS Program source
879 Always do this if the explanatory text includes a shell session log.
881 If you include a shell session log demonstrating the use of a program
883 or other system feature:
884 • Place the session log above the source code listing.
886 • Indent the session log by four spaces.
888 • Boldface the user input text, to distinguish it from output produced
890 by the system.
891 For some examples of what example programs should look like, see
893 wait(2) and pipe(2).
894
896 For canonical examples of how man pages in the man-pages package should
897 look, see pipe(2) and fcntl(2).
898
900 man(1), man2html(1), attributes(7), groff(7), groff_man(7), man(7),
901 mdoc(7)
902Linux man-pages 6.04 2023-03-30 man-pages(7)