1MAN-PAGES(7)               Linux Programmer's Manual              MAN-PAGES(7)
2
3
4

NAME

6       man-pages - conventions for writing Linux man pages
7

SYNOPSIS

9       man [section] title
10

DESCRIPTION

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

FORMATTING AND WORDING CONVENTIONS

350       The  following  subsections  note some details for preferred formatting
351       and wording conventions in various sections of the pages  in  the  man-
352       pages project.
353
354   SYNOPSIS
355       Wrap the function prototype(s) in a .nf/.fi pair to prevent filling.
356
357       In general, where more than one function prototype is shown in the SYN‐
358       OPSIS, the prototypes should not be separated by blank lines.  However,
359       blank lines (achieved using .PP) may be added in the following cases:
360
361       *  to  separate  long  lists of function prototypes into related groups
362          (see for example list(3));
363
364       *  in other cases that may improve readability.
365
366       In the SYNOPSIS, a long function prototype may  need  to  be  continued
367       over  to the next line.  The continuation line is indented according to
368       the following rules:
369
370       1. If there is a single such prototype that needs to be continued, then
371          align  the  continuation line so that when the page is rendered on a
372          fixed-width font device (e.g., on an xterm)  the  continuation  line
373          starts  just below the start of the argument list in the line above.
374          (Exception: the indentation may be adjusted if necessary to  prevent
375          a  very  long continuation line or a further continuation line where
376          the function prototype is very long.)  As an example:
377
378              int tcsetattr(int fd, int optional_actions,
379                            const struct termios *termios_p);
380
381       2. But, where multiple functions in the SYNOPSIS  require  continuation
382          lines, and the function names have different lengths, then align all
383          continuation lines to start in the same  column.   This  provides  a
384          nicer  rendering in PDF output (because the SYNOPSIS uses a variable
385          width font where spaces render narrower than most  characters).   As
386          an example:
387
388              int getopt(int argc, char * const argv[],
389                         const char *optstring);
390              int getopt_long(int argc, char * const argv[],
391                         const char *optstring,
392                         const struct option *longopts, int *longindex);
393
394   RETURN VALUE
395       The  preferred wording to describe how errno is set is "errno is set to
396       indicate the error" or similar.  This wording is  consistent  with  the
397       wording used in both POSIX.1 and FreeBSD.
398
399   ATTRIBUTES
400       Note the following:
401
402       *  Wrap  the  table in this section in a .ad l/.ad pair to disable text
403          filling and a .nh/.hy pair to disable hyphenation.
404
405       *  Ensure that the table occupies the full page width through  the  use
406          of an lbx description for one of the columns (usually the first col‐
407          umn, though in some cases the last column if it contains  a  lot  of
408          text).
409
410       *  Make free use of T{/T} macro pairs to allow table cells to be broken
411          over multiple lines (also bearing in mind that pages  may  sometimes
412          be rendered to a width of less than 80 columns).
413
414       For examples of all of the above, see the source code of various pages.
415

STYLE GUIDE

417       The  following  subsections  describe  the preferred style for the man-
418       pages project.  For details not covered below, the  Chicago  Manual  of
419       Style is usually a good source; try also grepping for preexisting usage
420       in the project source tree.
421
422   Use of gender-neutral language
423       As far as possible, use gender-neutral language  in  the  text  of  man
424       pages.  Use of "they" ("them", "themself", "their") as a gender-neutral
425       singular pronoun is acceptable.
426
427   Formatting conventions for manual pages describing commands
428       For manual pages that describe a command (typically in Sections  1  and
429       8),  the arguments are always specified using italics, even in the SYN‐
430       OPSIS section.
431
432       The name of the command, and its options, should always be formatted in
433       bold.
434
435   Formatting conventions for manual pages describing functions
436       For  manual  pages that describe functions (typically in Sections 2 and
437       3), the arguments are always specified using italics, even in the  SYN‐
438       OPSIS section, where the rest of the function is specified in bold:
439
440           int myfunction(int argc, char **argv);
441
442       Variable names should, like argument names, be specified in italics.
443
444       Any reference to the subject of the current manual page should be writ‐
445       ten with the name in bold followed by a pair of  parentheses  in  Roman
446       (normal)  font.   For  example, in the fcntl(2) man page, references to
447       the subject of the page would be written as:  fcntl().   The  preferred
448       way to write this in the source file is:
449
450           .BR fcntl ()
451
452       (Using  this format, rather than the use of "\fB...\fP()" makes it eas‐
453       ier to write tools that parse man page source files.)
454
455   Use semantic newlines
456       In the source of a manual page, new sentences should be started on  new
457       lines,  and  long sentences should be split into lines at clause breaks
458       (commas, semicolons, colons, and so on).   This  convention,  sometimes
459       known  as  "semantic  newlines",  makes  it easier to see the effect of
460       patches, which often operate at the level of  individual  sentences  or
461       sentence clauses.
462
463   Formatting conventions (general)
464       Paragraphs  should be separated by suitable markers (usually either .PP
465       or .IP).  Do not separate paragraphs using blank lines, as this results
466       in poor rendering in some output formats (such as PostScript and PDF).
467
468       Filenames (whether pathnames, or references to header files) are always
469       in italics (e.g., <stdio.h>), except in the SYNOPSIS section, where in‐
470       cluded files are in bold (e.g., #include <stdio.h>).  When referring to
471       a standard header file include, specify the header file  surrounded  by
472       angle brackets, in the usual C way (e.g., <stdio.h>).
473
474       Special macros, which are usually in uppercase, are in bold (e.g., MAX‐
475       INT).  Exception: don't boldface NULL.
476
477       When enumerating a list of error codes, the codes  are  in  bold  (this
478       list usually uses the .TP macro).
479
480       Complete  commands  should,  if long, be written as an indented line on
481       their own, with a blank line before and after the command, for example
482
483           man 7 man-pages
484
485       If the command is short, then it can be included inline in the text, in
486       italic  format,  for example, man 7 man-pages.  In this case, it may be
487       worth using nonbreaking spaces ("\ ") at suitable places  in  the  com‐
488       mand.  Command options should be written in italics (e.g., -l).
489
490       Expressions,  if  not  written  on  a separate indented line, should be
491       specified in italics.  Again, the use of nonbreaking spaces may be  ap‐
492       propriate if the expression is inlined with normal text.
493
494       When  showing example shell sessions, user input should be formatted in
495       bold, for example
496
497           $ date
498           Thu Jul  7 13:01:27 CEST 2016
499
500       Any reference to another man page should be written with  the  name  in
501       bold,  always  followed by the section number, formatted in Roman (nor‐
502       mal) font, without any separating spaces (e.g.,  intro(2)).   The  pre‐
503       ferred way to write this in the source file is:
504
505           .BR intro (2)
506
507       (Including  the  section  number  in  cross  references lets tools like
508       man2html(1) create properly hyperlinked pages.)
509
510       Control characters should be written in bold face, with no quotes;  for
511       example, ^X.
512
513   Spelling
514       Starting with release 2.59, man-pages follows American spelling conven‐
515       tions (previously, there was a  random  mix  of  British  and  American
516       spellings);  please  write all new pages and patches according to these
517       conventions.
518
519       Aside from the well-known spelling differences, there are a  few  other
520       subtleties to watch for:
521
522       *  American  English  tends to use the forms "backward", "upward", "to‐
523          ward", and so on rather than the  British  forms  "backwards",  "up‐
524          wards", "towards", and so on.
525
526       *  Opinions  are divided on "acknowledgement" vs "acknowledgment".  The
527          latter is predominant, but not universal usage in American  English.
528          POSIX  and  the  BSD  license use the former spelling.  In the Linux
529          man-pages project, we use "acknowledgement".
530
531   BSD version numbers
532       The classical scheme for writing BSD version numbers is  x.yBSD,  where
533       x.y is the version number (e.g., 4.2BSD).  Avoid forms such as BSD 4.3.
534
535   Capitalization
536       In  subsection  ("SS") headings, capitalize the first word in the head‐
537       ing, but otherwise use lowercase, except  where  English  usage  (e.g.,
538       proper  nouns)  or  programming language requirements (e.g., identifier
539       names) dictate otherwise.  For example:
540
541           .SS Unicode under Linux
542
543   Indentation of structure definitions, shell session logs, and so on
544       When structure definitions, shell session logs, and so on are  included
545       in  running  text,  indent  them by 4 spaces (i.e., a block enclosed by
546       .in +4n and .in), format them using the .EX and EE macros, and surround
547       them with suitable paragraph markers (either .PP or .IP).  For example:
548
549               .PP
550               .in +4n
551               .EX
552               int
553               main(int argc, char *argv[])
554               {
555                   return 0;
556               }
557               .EE
558               .in
559               .PP
560
561   Preferred terms
562       The  following  table  lists  some preferred terms to use in man pages,
563       mainly to ensure consistency across pages.
564
565       Term                 Avoid using              Notes
566       ────────────────────────────────────────────────────────────────
567       bit mask             bitmask
568       built-in             builtin
569       Epoch                epoch                    For the UNIX
570                                                     Epoch (00:00:00,
571                                                     1 Jan 1970 UTC)
572       filename             file name
573       filesystem           file system
574       hostname             host name
575       inode                i-node
576       lowercase            lower case, lower-case
577       nonzero              non-zero
578       pathname             path name
579       pseudoterminal       pseudo-terminal
580       privileged port      reserved port, system
581                            port
582       real-time            realtime, real time
583       run time             runtime
584       saved set-group-ID   saved group ID, saved
585                            set-GID
586       saved set-user-ID    saved user ID, saved
587                            set-UID
588       set-group-ID         set-GID, setgid
589       set-user-ID          set-UID, setuid
590       superuser            super user, super-user
591       superblock           super block, super-
592                            block
593       timestamp            time stamp
594
595       timezone             time zone
596       uppercase            upper case, upper-case
597       usable               useable
598       user space           userspace
599       username             user name
600       x86-64               x86_64                   Except if refer‐
601                                                     ring to result
602                                                     of "uname -m" or
603                                                     similar
604       zeros                zeroes
605
606       See also the discussion Hyphenation of attributive compounds below.
607
608   Terms to avoid
609       The following table lists some terms to avoid using in man pages, along
610       with some suggested alternatives, mainly to ensure consistency across
611       pages.
612
613       Avoid             Use instead         Notes
614       ──────────────────────────────────────────────────────────
615
616       32bit             32-bit              same for 8-bit,
617                                             16-bit, etc.
618       current process   calling process     A common mistake
619                                             made by kernel pro‐
620                                             grammers when writ‐
621                                             ing man pages
622       manpage           man page, manual
623                         page
624       minus infinity    negative infinity
625       non-root          unprivileged user
626       non-superuser     unprivileged user
627       nonprivileged     unprivileged
628       OS                operating system
629       plus infinity     positive infinity
630       pty               pseudoterminal
631       tty               terminal
632       Unices            UNIX systems
633       Unixes            UNIX systems
634
635   Trademarks
636       Use the correct spelling and case for trademarks.  The following  is  a
637       list  of  the correct spellings of various relevant trademarks that are
638       sometimes misspelled:
639
640            DG/UX
641            HP-UX
642            UNIX
643            UnixWare
644
645   NULL, NUL, null pointer, and null byte
646       A null pointer is a pointer that points to nothing, and is normally in‐
647       dicated by the constant NULL.  On the other hand, NUL is the null byte,
648       a byte with the value 0, represented in C via  the  character  constant
649       '\0'.
650
651       The  preferred term for the pointer is "null pointer" or simply "NULL";
652       avoid writing "NULL pointer".
653
654       The preferred term for the byte is "null byte".  Avoid  writing  "NUL",
655       since  it  is  too  easily  confused with "NULL".  Avoid also the terms
656       "zero byte" and "null character".  The byte that terminates a C  string
657       should  be described as "the terminating null byte"; strings may be de‐
658       scribed as "null-terminated", but avoid the use of "NUL-terminated".
659
660   Hyperlinks
661       For hyperlinks, use the .UR/.UE macro pair  (see  groff_man(7)).   This
662       produces proper hyperlinks that can be used in a web browser, when ren‐
663       dering a page with, say:
664
665            BROWSER=firefox man -H pagename
666
667   Use of e.g., i.e., etc., a.k.a., and similar
668       In general, the use of abbreviations such as  "e.g.",  "i.e.",  "etc.",
669       "cf.",  and "a.k.a." should be avoided, in favor of suitable full word‐
670       ings ("for example", "that is", "and so on", "compare to", "also  known
671       as").
672
673       The  only  place where such abbreviations may be acceptable is in short
674       parenthetical asides (e.g., like this one).
675
676       Always include periods in such abbreviations, as shown here.  In  addi‐
677       tion, "e.g." and "i.e." should always be followed by a comma.
678
679   Em-dashes
680       The  way  to  write  an em-dash—the glyph that appears at either end of
681       this subphrase—in *roff is with the macro "\(em".  (On an ASCII  termi‐
682       nal,  an  em-dash  typically renders as two hyphens, but in other typo‐
683       graphical contexts it renders as a long  dash.)   Em-dashes  should  be
684       written without surrounding spaces.
685
686   Hyphenation of attributive compounds
687       Compound  terms  should be hyphenated when used attributively (i.e., to
688       qualify a following noun). Some examples:
689
690           32-bit value
691           command-line argument
692           floating-point number
693           run-time check
694           user-space function
695           wide-character string
696
697   Hyphenation with multi, non, pre, re, sub, and so on
698       The general tendency in modern English is not to hyphenate  after  pre‐
699       fixes  such  as  "multi", "non", "pre", "re", "sub", and so on.  Manual
700       pages should generally follow this rule when these prefixes are used in
701       natural English constructions with simple suffixes.  The following list
702       gives some examples of the preferred forms:
703
704           interprocess
705           multithreaded
706           multiprocess
707           nonblocking
708           nondefault
709           nonempty
710           noninteractive
711           nonnegative
712           nonportable
713           nonzero
714           preallocated
715           precreate
716           prerecorded
717           reestablished
718           reinitialize
719           rearm
720           reread
721           subcomponent
722           subdirectory
723           subsystem
724
725       Hyphens should be retained when the prefixes are  used  in  nonstandard
726       English  words,  with  trademarks,  proper nouns, acronyms, or compound
727       terms.  Some examples:
728
729           non-ASCII
730           non-English
731           non-NULL
732           non-real-time
733
734       Finally, note that "re-create" and "recreate" are two different  verbs,
735       and the former is probably what you want.
736
737   Generating optimal glyphs
738       Where a real minus character is required (e.g., for numbers such as -1,
739       for man page cross references such as utf-8(7), or when writing options
740       that  have a leading dash, such as in ls -l), use the following form in
741       the man page source:
742
743           \-
744
745       This guideline applies also to code examples.
746
747       The use of real minus signs serves the following purposes:
748
749       *  To provide better renderings on various  targets  other  than  ASCII
750          terminals, notably in PDF and on Unicode/UTF-8-capable terminals.
751
752       *  To generate glyphs that when copied from rendered pages will produce
753          real minus signs when pasted into a terminal.
754
755       To produce unslanted single quotes that render well  in  ASCII,  UTF-8,
756       and PDF, use "\(aq" ("apostrophe quote"); for example
757
758           \(aqC\(aq
759
760       where  C is the quoted character.  This guideline applies also to char‐
761       acter constants used in code examples.
762
763       Where a proper caret (^) that renders well in both a terminal  and  PDF
764       is required, use "\(ha".  This is especially necessary in code samples,
765       to get a nicely rendered caret when rendering to PDF.
766
767       Using a naked "~" character results in a poor rendering  in  PDF.   In‐
768       stead use "\(ti".  This is especially necessary in code samples, to get
769       a nicely rendered tilde when rendering to PDF.
770
771   Example programs and shell sessions
772       Manual pages may include example programs demonstrating how  to  use  a
773       system call or library function.  However, note the following:
774
775       *  Example programs should be written in C.
776
777       *  An  example  program is necessary and useful only if it demonstrates
778          something beyond what can easily be provided in a  textual  descrip‐
779          tion  of  the interface.  An example program that does nothing other
780          than call an interface usually serves little purpose.
781
782       *  Example programs should ideally be short (e.g., a good  example  can
783          often  be  provided  in less than 100 lines of code), though in some
784          cases longer programs may be necessary to  properly  illustrate  the
785          use of an API.
786
787       *  Expressive code is appreciated.
788
789       *  Comments should included where helpful.  Complete sentences in free-
790          standing comments should be terminated by a period.  Periods  should
791          generally  be  omitted  in  "tag"  comments (i.e., comments that are
792          placed on the same line of code); such comments are in any case typ‐
793          ically brief phrases rather than complete sentences.
794
795       *  Example programs should do error checking after system calls and li‐
796          brary function calls.
797
798       *  Example programs should be complete, and  compile  without  warnings
799          when compiled with cc -Wall.
800
801       *  Where possible and appropriate, example programs should allow exper‐
802          imentation, by varying their behavior based on inputs (ideally  from
803          command-line arguments, or alternatively, via input read by the pro‐
804          gram).
805
806       *  Example programs should be  laid  out  according  to  Kernighan  and
807          Ritchie  style, with 4-space indents.  (Avoid the use of TAB charac‐
808          ters in source code!)  The following command can be used  to  format
809          your source code to something close to the preferred style:
810
811              indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c
812
813       *  For  consistency, all example programs should terminate using either
814          of:
815
816               exit(EXIT_SUCCESS);
817               exit(EXIT_FAILURE);
818
819          Avoid using the following forms to terminate a program:
820
821              exit(0);
822              exit(1);
823              return n;
824
825       *  If there is extensive explanatory text  before  the  program  source
826          code,  mark  off  the  source code with a subsection heading Program
827          source, as in:
828
829              .SS Program source
830
831          Always do this if the explanatory text includes a shell session log.
832
833       If you include a shell session log demonstrating the use of  a  program
834       or other system feature:
835
836       *  Place the session log above the source code listing
837
838       *  Indent the session log by four spaces.
839
840       *  Boldface the user input text, to distinguish it from output produced
841          by the system.
842
843       For some examples of  what  example  programs  should  look  like,  see
844       wait(2) and pipe(2).
845

EXAMPLES

847       For canonical examples of how man pages in the man-pages package should
848       look, see pipe(2) and fcntl(2).
849

SEE ALSO

851       man(1), man2html(1),  attributes(7),  groff(7),  groff_man(7),  man(7),
852       mdoc(7)
853

COLOPHON

855       This  page  is  part of release 5.13 of the Linux man-pages project.  A
856       description of the project, information about reporting bugs,  and  the
857       latest     version     of     this    page,    can    be    found    at
858       https://www.kernel.org/doc/man-pages/.
859
860
861
862Linux                             2021-03-22                      MAN-PAGES(7)
Impressum