Documentation/howto-man-page.txt

   1 .\" This is a util-linux manual page example in troff format.
   2 .\"
   3 .\" The .TH macro expects the following arguments:
   4 .\"     title section date footer header
   5 .\" The title is usually the command name.
   6 .\" The section must match the filename extension.
   7 .\" The date is the month and year when the last update happened.
   8 .\" The footer is fixed to "util-linux".
   9 .\" The header is a textual description of the section:
  10 .\"     1 "User Commands"
  11 .\"     2 "System calls"
  12 .\"     3 "Programmer's Manual"
  13 .\"     4 "Special Files"
  14 .\"     5 "File Formats"
  15 .\"     6 "Games"
  16 .\"     7 "Miscellanea"
  17 .\"     8 "System Administration"
  18 .\"
  19 .\" Please read `man 7 groff_man' to see how to use the various macros.
  20 .\"
  21 .TH EXAMPLE "1" "April 2016" "util-linux" "User Commands"
  22 .SH NAME
  23 example \- a util-linux man-page howto
  24 .SH SYNOPSIS
  25 .B example
  26 [options]
  27 .I argument
  28 .SH DESCRIPTION
  29 Each manual page needs some sort of description of the command.
  30 Write such here.
  31 .SH OPTIONS
  32 .TP
  33 \fB\-n\fR, \fB\-\-no\-argument\fR
  34 This option does not use an argument.
  35 .TP
  36 \fB\-\-optional\fR[\fI=argument\fR]
  37 Tell in this description that the
  38 .I argument
  39 is optional, and what happens when it is or is not given.  Notice that the word
  40 .I argument
  41 is not abbreviated as is customary in the usage text.  For example, when the
  42 usage text uses the argument
  43 .IR num ,
  44 the manual page should say
  45 .IR number .
  46 .IP
  47 Notice that after release v2.28 it was decided that introducing new options
  48 taking optional arguments should be limited to long-only options.  This is
  49 done primarily to avoid problematic behaviour of short options.  Imagine for
  50 example normal option
  51 .B \-n
  52 and optional option
  53 .BR \-o .
  54 One will expect
  55 .B command \ \-no
  56 and
  57 .B command \ \-on
  58 to be the same, but in fact the former is two separate options while the
  59 later will use
  60 .B n
  61 as option argument of
  62 .BR -o .
  63 So it is best to avoid short forms of optional options altogether.
  64 .TP
  65 \fB\-r\fR, \fB\-\-required\fR \fIargument\fR
  66 Tell in this description that the
  67 .I argument
  68 is required.
  69 .TP
  70 \fB\-V\fR, \fB\-\-version\fR
  71 Display version information and exit.
  72 .TP
  73 \fB\-h\fR, \fB\-\-help\fR
  74 Display help text and exit.
  75 .SH NOTES
  76 Tell details that users might need to know.  For example, kernel feature or
  77 version requirements.
  78 .PP
  79 The man-page source lines should not exceed 80 characters in length.
  80 .PP
  81 Do not leave empty lines in the groff input.  If you need a break or a new
  82 paragraph, use the appropriate groff macros.  See
  83 .BR groff_man (7)
  84 how to use man page macros.
  85 .PP
  86 The use cases of
  87 .I italic
  88 (which is underlined on a terminal) and
  89 .B bold
  90 are not strictly defined.  The main convention is that
  91 .I symbolic arguments
  92 use italic, and
  93 .B commands
  94 and
  95 .B literal arguments
  96 use bold, and
  97 .I other highlights
  98 use
  99 .B either
 100 one.
 101 .\"
 102 .\" The manual page comments are undervalued way of adding clarifications
 103 .\" quite not belong to the manual, questions, TODO items etc.  Feel free
 104 .\" to use them.
 105 .\"
 106 .PP
 107 When in the source a new sentence begins somewhere midline, it should use a
 108 double space before its initial letter.  This is done because \fBgroff\fR
 109 uses a double space after a sentence when this sentence ends at the end of
 110 an input line and the next sentence begins on the next line.
 111 Unless a double space is used before other sentence starts as well, the
 112 spacing style will be inconsistent.
 113 .SH ENVIRONMENT
 114 Tell which environment variables affect, and how, the execution of the command.
 115 .TP
 116 .B EXAMPLE_PATH
 117 Configuration file path.  Notice that well-known environment variables, such as
 118 .BR HOME ,
 119 do not need explanation.
 120 .SH FILES
 121 Tell which file(s) the command uses.
 122 .TP
 123 .B $EXAMPLE_PATH
 124 .TQ
 125 .B $HOME/.example.conf
 126 .TQ
 127 .B /etc/example.conf
 128 What are these files, in which order are they read, and will the evaluation
 129 end or continue if one of them is found.
 130 In case the explanation is not simple, write a separate "Special Files"
 131 manual page that tells about syntax, meaning of key-value settings, etc.
 132 This "Special Files" manual page then needs to be referred in the
 133 .B SEE ALSO
 134 section.
 135 .TP
 136 .B /var/log/example.log
 137 Another file.
 138 .SH EXAMPLES
 139 Write typical and/or clever use examples here.  The below examples are stupid,
 140 and you should never write them in a real man page.
 141 .TP
 142 .B example -h
 143 Output help screen.
 144 .TP
 145 .B example -V
 146 Output version information.
 147 .SH "EXIT STATUS"
 148 This section can be left out if the command has only two return values,
 149 .B 0
 150 for success and
 151 .B 1
 152 for failure.  Use of
 153 .B sysexits.h
 154 return values must be mentioned, but does not need to be explained.
 155 .PP
 156 .RS
 157 .PD 0
 158 .TP
 159 .B 0
 160 success
 161 .TP
 162 .B 1
 163 failure
 164 .TP
 165 .B 2
 166 tell why this could happen
 167 .TP
 168 .B 3
 169 etc
 170 .PD
 171 .RE
 172 .SH AUTHORS
 173 .MT rjh@\:example.org
 174 Random J. Hacker
 175 .ME
 176 .br
 177 .MT fred@\:example.com
 178 Fred Foobar
 179 .ME
 180 .SH "SEE ALSO"
 181 .BR groff_man (7),
 182 .BR foo (1),
 183 .BR bar (8)
 184 .SH AVAILABILITY
 185 The example command is part of the util-linux package and is available from
 186 .UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
 187 Linux Kernel Archive
 188 .UE .