share/man/man7/man.7

   1 .\" Copyright (c) 1998.
   2 .\"     The FreeBSD Project.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" $FreeBSD$
  33 .\"
  34 .Dd November 30, 1998
  35 .Os
  36 .Dt MAN 7
  37 .Sh NAME
  38 .Nm man
  39 .Nd quick reference guide for the
  40 .Nm \-man
  41 macro package
  42 .Sh SYNOPSIS
  43 .Nm groff
  44 .Fl m Ns Ar an
  45 .Ar
  46 .Sh DESCRIPTION
  47 The
  48 .Nm \-man
  49 package is a set of macros used to format
  50 .Ux
  51 manual pages.  On
  52 .Bx
  53 systems, the use of
  54 .Nm
  55 is deprecated and the more expressive
  56 .Nm mdoc
  57 package is recommended in its place.
  58 .Sh USAGE
  59 .Ss Conventions
  60 .Nm
  61 macros are named using one or two upper case alphabetic characters.
  62 Following regular
  63 .Xr troff 1
  64 convention, each macro request starts with a
  65 .Li "."
  66 as the first character of a line.  Arguments to macro requests
  67 expecting printable text may consist of zero to six words.  Some macros will
  68 process the next input line if no arguments are supplied.  For
  69 example, a
  70 .Li ".I"
  71 request on a line by itself will cause the next input line to be set
  72 in italics.
  73 Whitespace characters may be embedded in an argument by enclosing
  74 it in quotes.  Type font and size are reset to their defaults before
  75 each paragraph and after processing font size and face changing macros.
  76 .Ss Indentation
  77 The prevailing indent distance is remembered between successive
  78 indented paragraphs and is reset to the default on reaching a
  79 non-indented paragraph.  Default units for indents are
  80 .Dq ens .
  81 .Ss Preprocessing
  82 The
  83 .Xr man 1
  84 program is conventionally used to format and display manual pages.  If
  85 the first line of the manual page source starts with the literal string
  86 .Li \&\'\e"
  87 .\" " bring emacs's font-lock mode back in sync ...
  88 then the remaining letters on the line indicate preprocessors that
  89 need to be run prior to formatting with
  90 .Xr troff 1 .
  91 Supported preprocessing directives are:
  92 .Bl -column "Letter" "Preprocessor" -offset indent
  93 .It Em Letter Ta Em Preprocessor
  94 .It e Ta Xr eqn 1
  95 .It g Ta Xr grap 1
  96 .It p Ta Xr pic 1
  97 .It r Ta Xr refer 1
  98 .It t Ta Xr tbl 1
  99 .It v Ta Xr vgrind 1
 100 .El
 101 .Ss Available Strings
 102 The
 103 .Nm
 104 package has the following predefined strings:
 105 .Bl -column "String" "XXXXXXXXXXXXXXXXXXXXXXXXXXXX" -offset indent
 106 .It Em String Ta Em Description
 107 .It "\e*R" Ta "registration symbol"
 108 .It "\e*S" Ta "change to default font size"
 109 .It "\e*(Tm" Ta "trademark symbol"
 110 .It "\e*(lq" Ta "left quote"
 111 .It "\e*(rq" Ta "right quote"
 112 .El
 113 .Pp
 114 .Ss Available Macros
 115 The available macros are presented in alphabetical order.
 116 .Bl -tag -width "XXX XX"
 117 .It ".B" Op Ar words
 118 typeset
 119 .Ar words
 120 using a bold face.  Does not cause a line break.  If no
 121 arguments are given the next text line is processed.
 122 .It ".BI" Op Ar words
 123 join
 124 .Ar words
 125 alternating bold and italic faces.  Does not cause a line break.  If
 126 no arguments are given the next text line is processed.
 127 .It ".BR" Op Ar words
 128 join
 129 .Ar words
 130 alternating bold and roman faces.  Does not cause a line break.  If no
 131 arguments are given the next text line is processed.
 132 .It ".DT"
 133 restore the default tab spacing of 0.5 inches.  Does not cause a line
 134 break.
 135 .It ".HP" Op Ar indent
 136 Begin a paragraph with a hanging indent and sets the prevailing indent
 137 to
 138 .Ar indent .
 139 This request forces a line break.  If
 140 .Ar indent
 141 is not specified, the value of the prevailing indent is used.
 142 .It ".I" Op Ar words
 143 typeset
 144 .Ar words
 145 using an italic face.  Does not cause a line break.  If no
 146 arguments are given the next text line is processed.
 147 .It ".IB" Op Ar words
 148 join
 149 .Ar words
 150 alternating italic and bold faces.  Does not cause a line break.  If no
 151 arguments are given the next text line is processed.
 152 .It ".IP" Op Ar tag Op Ar indent
 153 Begin an indented paragraph with tag
 154 .Ar tag
 155 and prevailing indent set to
 156 .Ar indent .
 157 If
 158 .Ar tag
 159 is not specified it is taken to be the null string
 160 .Qq "" .
 161 If
 162 .Ar indent
 163 is not specified it is taken to be the prevailing indent.
 164 .It ".IR" Op Ar words
 165 join
 166 .Ar words
 167 alternating italic and roman faces.
 168 Does not cause a line break.  If no
 169 arguments are given the next text line is processed.
 170 .It ".LP"
 171 begin a left-aligned paragraph.  The prevailing indent is set to the
 172 default.  This request forces a line break.
 173 .It "\&.P"
 174 aliased to \&.LP.
 175 .It ".PD" Op Ar distance
 176 set the vertical distance between paragraphs to
 177 .Ar distance .
 178 If argument
 179 .Ar distance
 180 is not specified a value of 0.4v is used.
 181 .It ".PP"
 182 aliased to \&.LP.
 183 .It ".RE"
 184 end of a relative indent (see \&.RS below).  This request forces a
 185 line break and restores the prevailing indent to its previous value.
 186 .It ".RB" Op Ar words
 187 join
 188 .Ar words
 189 alternating roman and bold faces.  Does not cause a line break.  If no
 190 arguments are given the next text line is processed.
 191 .It ".RI" Op Ar words
 192 join
 193 .Ar words
 194 alternating roman and italic faces.  Does not cause a line break.  If no
 195 arguments are given the next text line is processed.
 196 .It ".RS" Op Ar indent
 197 start a relative indent, increasing the indentation by
 198 .Ar indent .
 199 If argument
 200 .Ar indent
 201 is not specified, the value of the prevailing indent is used.
 202 .It ".SB" Op Ar words
 203 typeset
 204 .Ar words
 205 using a bold face after reducing the font size by 1 point.
 206 Does not cause a line break.  If no arguments are given the next text
 207 line is processed.
 208 .It ".SH" Op Ar words
 209 specifies a section heading.  This request forces a line break.
 210 It resets the prevailing indent and margins to their defaults.
 211 .It ".SM" Op Ar words
 212 typeset
 213 .Ar words
 214 after reducing the font size by 1 point.  Does not cause a line break.
 215 If no arguments are given the next text line is processed.
 216 .It ".SS" Op Ar words
 217 specifies a section subheading.  This request forces a line
 218 break.  If no arguments are given the next text line is processed.
 219 It resets the prevailing indent and margins to their defaults.
 220 .It ".TH" Ar name Ar section Ar date Xo
 221 .Op Ar footer Op Ar center
 222 .Xc
 223 Begin reference page
 224 .Ar name
 225 belonging to section
 226 .Ar section .
 227 The third argument
 228 .Ar date ,
 229 is the date of the most recent change.  If present,
 230 .Ar footer
 231 specifies the left page footer text and
 232 .Ar center
 233 specifies the center header text.  This request must the very first
 234 request in the manual page.
 235 .It ".TP" Op Ar indent
 236 begin an indented paragraph with the tag specified in the next text
 237 line.  If argument
 238 .Ar indent
 239 is given, it specifies the new value of the prevailing indent.
 240 This request forces a line break.
 241 .El
 242 .Sh PAGE STRUCTURE
 243 Most manual pages follow the general structure outlined below:
 244 .Bl -tag -width ".SH NAME"
 245 .It ".TH" Ar title Op Ar section-number
 246 The very first macro request in a manual page has to be the \&.TH
 247 request which establishes the name and title of the manual page.  The
 248 \&.TH request also establishes the number of the manual page section.
 249 .It ".SH NAME"
 250 The name, or list of names, by which the command is called, followed
 251 by a dash and a one-line summary of the action performed.  This
 252 section should not contain any
 253 .Nm troff
 254 commands or escapes, or any macro requests.  This section is used to
 255 generate the database used by the
 256 .Xr whatis 1
 257 command.
 258 .It ".SH SYNOPSIS"
 259 A brief summary of the usage of the command or function being
 260 described.
 261 .Bl -tag -width "Commands"
 262 .It Commands
 263 The syntax of the command and its arguments as would be typed on the
 264 command line.  Words that have to be typed exactly as printed are to
 265 be presented in bold face.  Arguments are indicated by the use of an
 266 italic face.  Arguments and command names so indicated should not be
 267 capitalized, even when starting a sentence.
 268 .Pp
 269 Syntactic symbols used should appear in roman face:
 270 .Bl -tag -width "XXX"
 271 .It "[]"
 272 square brackets are used to indicate optional arguments.
 273 .It "|"
 274 vertical bars are used to indicate a one of many exclusive choice.
 275 Only one item from a list separated by vertical bars is to be selected.
 276 .It "..."
 277 an ellipsis following an argument is used to indicate that the
 278 arguments can be repeated.  When an ellipsis follows a bracketed set,
 279 the expression within the brackets can be repeated.
 280 .El
 281 .It Functions
 282 Required data declarations or
 283 .Li "#include"
 284 directives are to be shown first, followed by the function declaration.
 285 .El
 286 .It ".SH DESCRIPTION"
 287 An overview of the command or functions external behavior, including
 288 its interactions with files or data, how standard input, standard
 289 output and standard error are handled.  Internals and implementation
 290 details are not normally specified.  The question answered by this
 291 section is "what does it do?" or "what is it for?".
 292 .Pp
 293 Literal text, filenames and references to items that appear elsewhere
 294 in the reference manuals should be presented using a constant width
 295 face.
 296 Arguments should be presented using an italic face.
 297 .It ".SH OPTIONS"
 298 The list of options together with a description of how each affects
 299 the commands operation.
 300 .It ".SH USAGE"
 301 This section is optional and contains a detailed description of the
 302 subcommands and input grammar understood by the command.
 303 .It ".SH RETURN VALUES"
 304 The list of return values a library routine could return to the caller,
 305 with the conditions that cause these values to be returned.
 306 .It ".SH EXIT STATUS"
 307 The list of values returned as the exit status of the command, with
 308 the conditions that cause these values to be returned.
 309 .It ".SH FILES"
 310 The list of files associated with the command or function.
 311 .It ".SH SEE ALSO"
 312 A comma separated list of related manual pages followed by references
 313 to other published documentation.
 314 .It ".SH DIAGNOSTICS"
 315 A list of diagnostic messages with corresponding explanations.
 316 .It ".SH BUGS"
 317 Known defects and limitations, if any.
 318 .El
 319 .Sh FILES
 320 .Bl -tag -width "/usr/share/tmac/tmac.groff_an"
 321 .It "/usr/share/tmac/tmac.an"
 322 Initial file defining the
 323 .Nm
 324 package.
 325 .It "/usr/share/tmac/tmac.groff_an"
 326 .Nm groff
 327 source for macro definitions.
 328 .It "/usr/share/tmac/man.local"
 329 local modifications to the
 330 .Nm
 331 package.
 332 .El
 333 .Sh SEE ALSO
 334 .Xr apropos 1 ,
 335 .Xr groff 1 ,
 336 .Xr man 1 ,
 337 .Xr nroff 1 ,
 338 .Xr troff 1 ,
 339 .Xr whatis 1 ,
 340 .Xr mdoc 7 ,
 341 .Xr mdoc.samples 7
 342 .Sh HISTORY
 343 This manual page was written by
 344 .An Joseph Koshy Aq jkoshy@FreeBSD.org .