man.7

   1 .\"     $Id: man.7,v 1.25 2009/08/13 12:54:52 kristaps Exp $
   2 .\"
   3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .Dd $Mdocdate: August 13 2009 $
  18 .Dt MAN 7
  19 .Os
  20 .\" SECTION
  21 .Sh NAME
  22 .Nm man
  23 .Nd man language reference
  24 .\" SECTION
  25 .Sh DESCRIPTION
  26 The
  27 .Nm man
  28 language was historically used to format
  29 .Ux
  30 manuals.  This reference document describes its syntax, structure, and
  31 usage.
  32 .Pp
  33 .Bf -emphasis
  34 Do not use
  35 .Nm
  36 to write your manuals.
  37 .Ef
  38 Use the
  39 .Xr mdoc 7
  40 language, instead.
  41 .\" PARAGRAPH
  42 .Pp
  43 An
  44 .Nm
  45 document follows simple rules:  lines beginning with the control
  46 character
  47 .Sq \&.
  48 are parsed for macros.  Other lines are interpreted within the scope of
  49 prior macros:
  50 .Bd -literal -offset indent
  51 \&.SH Macro lines change control state.
  52 Other lines are interpreted within the current state.
  53 .Ed
  54 .\" SECTION
  55 .Sh INPUT ENCODING
  56 .Nm
  57 documents may contain only graphable 7-bit ASCII characters, the
  58 space character, and the tabs character.  All manuals must have
  59 .Ux
  60 line termination.
  61 .Pp
  62 Blank lines are acceptable; where found, the output will assert a
  63 vertical space.
  64 .Pp
  65 The
  66 .Sq \ec
  67 escape is common in historical
  68 .Nm
  69 documents; if encountered at the end of a word, it ensures that the
  70 subsequent word isn't off-set by whitespace.
  71 .\" SUB-SECTION
  72 .Ss Comments
  73 Text following a
  74 .Sq \e\*" ,
  75 whether in a macro or free-form text line, is ignored to the end of
  76 line.  A macro line with only a control character and comment escape,
  77 .Sq \&.\e" ,
  78 is also ignored.  Macro lines with only a control charater and
  79 optionally whitespace are stripped from input.
  80 .\" SUB-SECTION
  81 .Ss Special Characters
  82 Special characters may occur in both macro and free-form lines.
  83 Sequences begin with the escape character
  84 .Sq \e
  85 followed by either an open-parenthesis
  86 .Sq \&(
  87 for two-character sequences; an open-bracket
  88 .Sq \&[
  89 for n-character sequences (terminated at a close-bracket
  90 .Sq \&] ) ;
  91 or a single one-character sequence.  See
  92 .Xr mandoc_char 7
  93 for a complete list.  Examples include
  94 .Sq \e(em
  95 .Pq em-dash
  96 and
  97 .Sq \ee
  98 .Pq back-slash .
  99 .\" SUB-SECTION----------------------
 100 .Ss Text Decoration
 101 Terms may be text-decorated using the
 102 .Sq \ef
 103 escape followed by an indicator: B (bold), I, (italic), or P and R
 104 (Roman, or reset).
 105 .\" SUB-SECTION----------------------
 106 .Ss Whitespace
 107 Unless specifically escaped, consecutive blocks of whitespace are pruned
 108 from input.  These are later re-added, if applicable, by a front-end
 109 utility such as
 110 .Xr mandoc 1 .
 111 .\" SECTION
 112 .Sh MANUAL STRUCTURE
 113 Each
 114 .Nm
 115 document must contain contains at least the
 116 .Sq \&TH
 117 macro describing the document's section and title.  It may occur
 118 anywhere in the document, although conventionally, it appears as the
 119 first macro.
 120 .Pp
 121 Beyond
 122 .Sq \&TH ,
 123 at least one macro or text node must appear in the document.  Documents
 124 are generally structured as follows:
 125 .Bd -literal -offset indent
 126 \&.TH FOO 1 "13 Aug 2009"
 127 \&.
 128 \&.SH NAME
 129 foo \e- a description goes here
 130 \&.
 131 \&.SH SYNOPSIS
 132 \efBfoo\efR [\efB\e-options\efR] arguments...
 133 \&.
 134 \&.SH DESCRIPTION
 135 The \efBfoo\efR utility does...
 136 \&.
 137 \&.\e\*q .SH RETURN VALUES
 138 \&.\e\*q .SH ENVIRONMENT
 139 \&.\e\*q .SH FILES
 140 \&.\e\*q .SH EXAMPLES
 141 \&.\e\*q .SH DIAGNOSTICS
 142 \&.\e\*q .SH ERRORS
 143 \&.\e\*q .SH SEE ALSO
 144 \&.\e\*q \efBbar\efR(1)
 145 \&.\e\*q .SH STANDARDS
 146 \&.\e\*q .SH HISTORY
 147 \&.\e\*q .SH AUTHORS
 148 \&.\e\*q .SH CAVEATS
 149 \&.\e\*q .SH BUGS
 150 .Ed
 151 .\" SECTION
 152 .Sh MACRO SYNTAX
 153 Macros are one to three three characters in length and begin with a
 154 control character ,
 155 .Sq \&. ,
 156 at the beginning of the line.  An arbitrary amount of whitespace may
 157 sit between the control character and the macro name.  Thus,
 158 .Sq \&.PP
 159 and
 160 .Sq \&.\ \ \ \&PP
 161 are equivalent.
 162 .Pp
 163 The
 164 .Nm
 165 macros are classified by scope: line scope or block scope.  Line-scoped
 166 macros are only scoped to the current line (and, in some situations,
 167 the subsequent line).  Block macros are scoped to the current line and
 168 subsequent lines until closed by another block macro.
 169 .\" SUBSECTION
 170 .Ss Line Macros
 171 Line-macros are scoped to the current line, with the body consisting of
 172 zero or more arguments.  If a macro is next-line scoped and the line
 173 arguments are empty, the next line is used instead.  Thus:
 174 .Bd -literal -offset indent
 175 \&.RI
 176 foo
 177 .Ed
 178 .\" PARAGRAPH
 179 .Pp
 180 is equivalent to
 181 .Sq \&.RI foo .
 182 .\" PARAGRAPH
 183 Consecutive next-line invocations are disallowed.
 184 .Bd -literal -offset indent
 185 \&.YO \(lBbody...\(rB
 186 \(lBbody...\(rB
 187 .Ed
 188 .\" PARAGRAPH
 189 .Pp
 190 .Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX"
 191 .It Em Macro Ta Em Arguments Ta Em Scope
 192 .It  \&B     Ta    n         Ta    next-line
 193 .It  \&BI    Ta    n         Ta    current
 194 .It  \&BR    Ta    n         Ta    current
 195 .It  \&I     Ta    n         Ta    next-line
 196 .It  \&IB    Ta    n         Ta    current
 197 .It  \&IR    Ta    n         Ta    current
 198 .It  \&R     Ta    n         Ta    next-line
 199 .It  \&RB    Ta    n         Ta    current
 200 .It  \&RI    Ta    n         Ta    current
 201 .It  \&SB    Ta    n         Ta    next-line
 202 .It  \&SM    Ta    n         Ta    next-line
 203 .It  \&TH    Ta    >1, <6    Ta    current
 204 .It  \&br    Ta    0         Ta    current
 205 .It  \&fi    Ta    0         Ta    current
 206 .It  \&i     Ta    n         Ta    current
 207 .It  \&na    Ta    0         Ta    current
 208 .It  \&nf    Ta    0         Ta    current
 209 .It  \&r     Ta    0         Ta    current
 210 .It  \&sp    Ta    1         Ta    current
 211 .El
 212 .\" PARAGRAPH
 213 .Pp
 214 The lower-case
 215 .Sq \&br ,
 216 .Sq \&fi ,
 217 .Sq \&i ,
 218 .Sq \&na ,
 219 .Sq \&nf ,
 220 .Sq \&r ,
 221 and
 222 .Sq \&sp
 223 macros aren't historically part of
 224 .Nm
 225 and should not be used.  They're included for compatibility.
 226 .\" SUBSECTION
 227 .Ss Block Macros
 228 Block macros are comprised of a head and body.  The head is scoped to
 229 the current line and, in one circumstance, the next line; the body is
 230 scoped to subsequent lines and is closed out by a subsequent block macro
 231 invocation.
 232 .Bd -literal -offset indent
 233 \&.YO \(lBhead...\(rB
 234 \(lBhead...\(rB
 235 \(lBbody...\(rB
 236 .Ed
 237 .\" PARAGRAPH
 238 .Pp
 239 If a block macro is next-line scoped, it may only be followed by in-line
 240 macros (excluding
 241 .Sq na ,
 242 .Sq sp ,
 243 .Sq nf ,
 244 .Sq fi ,
 245 and
 246 .Sq TH ) .
 247 .\" PARAGRAPH
 248 .Pp
 249 .Bl -column "MacroX" "Arguments" "ScopeXXXX" -compact -offset indent
 250 .It Em Macro Ta Em Arguments Ta Em Scope
 251 .It \&HP     Ta    <2        Ta    current
 252 .It \&IP     Ta    <3        Ta    current
 253 .It \&LP     Ta    0         Ta    current
 254 .It \&P      Ta    0         Ta    current
 255 .It \&PP     Ta    0         Ta    current
 256 .It \&SH     Ta    >0        Ta    current
 257 .It \&SS     Ta    >0        Ta    current
 258 .It \&TP     Ta    n         Ta    next-line
 259 .El
 260 .\" SECTION
 261 .Sh REFERENCE
 262 This section is a canonical reference to all macros, arranged
 263 alphabetically.  For the scoping of individual macros, see
 264 .Sx MACRO SYNTAX .
 265 .Bl -tag -width Ds
 266 .It \&B
 267 Text is rendered in bold face.
 268 .It \&BI
 269 Text is rendered alternately in bold face and italic.  Thus,
 270 .Sq \&.BI this word and that
 271 causes
 272 .Sq this
 273 and
 274 .Sq and
 275 to render in bold face, while
 276 .Sq word
 277 and
 278 .Sq that
 279 render in italics.  Whitespace between arguments is omitted in output.
 280 .It \&BR
 281 Text is rendered alternately in bold face and roman (the default font).
 282 Whitespace between arguments is omitted in output.
 283 .It \&HP
 284 Begin a paragraph whose initial output line is left-justified, but
 285 subsequent output lines are indented.
 286 .It \&I
 287 Text is rendered in italics.
 288 .It \&IB
 289 Text is rendered alternately in italics and bold face.  Whitespace
 290 between arguments is omitted in output.
 291 .It \&IP
 292 Begin a paragraph with the following syntax:
 293 .Bd -literal -offset indent
 294 \&.IP [head [width]]
 295 .Ed
 296 .Pp
 297 This follows the behaviour of the
 298 .Sq \&TP
 299 macro except that
 300 .Va width ,
 301 which is only considered as such if properly-formed (e.g., 24n, 4,
 302 etc.), is used as the indentation offset instead of the default
 303 indentation value.
 304 .It \&IR
 305 Text is rendered alternately in italics and roman (the default font).
 306 Whitespace between arguments is omitted in output.
 307 .It \&LP, \&P, \&PP
 308 Begin an undecorated paragraph.  The scope of a paragraph is closed by a
 309 subsequent paragraph, sub-section, section, or end of file.
 310 .It \&R
 311 Text is rendered in roman (the default font).
 312 .It \&RB
 313 Text is rendered alternately in roman (the default font) and bold face.
 314 Whitespace between arguments is omitted in output.
 315 .It \&RI
 316 Text is rendered alternately in roman (the default font) and italics.
 317 Whitespace between arguments is omitted in output.
 318 .It \&SB
 319 Text is rendered in small size (one point smaller than the default font)
 320 bold face.
 321 .It \&SH
 322 Begin a section.  The scope of a section is only closed by another
 323 section or the end of file.
 324 .It \&SM
 325 Text is rendered in small size (one point smaller than the default
 326 font).
 327 .It \&SS
 328 Begin a sub-section.  The scope of a sub-section is closed by a
 329 subsequent sub-section, section, or end of file.
 330 .It \&TH
 331 Sets the title of the manual page with the following syntax:
 332 .Bd -literal -offset indent
 333 \&.TH title section date source volume
 334 .Ed
 335 .Pp
 336 At least the
 337 .Va title
 338 and
 339 .Va section
 340 arguments must be provided.  The
 341 .Va date
 342 argument should be formatted as
 343 .Qq %b [%d] %Y
 344 format, described in
 345 .Xr strptime 3 .
 346 The
 347 .Va source
 348 string specifies the organisation providing the utility.  The
 349 .Va volume
 350 replaces the default rendered volume as dictated by the manual section.
 351 .It \&TP
 352 Begin a paragraph where the head, if exceeding the indentation width, is
 353 followed by a newline; if not, the body follows on the same line after a
 354 buffer to the indentation width.  Subsequent output lines are indented.
 355 .It \&br
 356 Breaks the current line.  Consecutive invocations have no further effect.
 357 .It \&fi
 358 End literal mode begun by
 359 .Sq \&nf .
 360 .It \&i
 361 Italicise arguments.  If no arguments are specified, all subsequent text
 362 is italicised.
 363 .It \&na
 364 No alignment to the right margin.
 365 .It \&nf
 366 Begin literal mode: all subsequent free-form lines have their end of
 367 line boundaries preserved.  May be ended by
 368 .Sq \&fi .
 369 .It \&r
 370 Fonts and styles (bold face, italics) reset to roman (default font).
 371 .It \&sp
 372 Insert n spaces, where n is the macro's positive numeric argument.  If
 373 0, this is equivalent to the
 374 .Sq br
 375 macro.
 376 .El
 377 .\" SECTION
 378 .Sh COMPATIBILITY
 379 This section documents compatibility with other roff implementations, at
 380 this time limited to
 381 .Xr groff 1 .
 382 .Bl -hyphen
 383 .It
 384 In quoted literals, groff allowed pair-wise double-quotes to produce a
 385 standalone double-quote in formatted output.  This idiosyncratic
 386 behaviour is no longer applicable.
 387 .It
 388 The
 389 .Sq \&sp
 390 macro does not accept negative numbers.
 391 .It
 392 Blocks of whitespace are stripped from both macro and free-form text
 393 lines (except when in literal mode), while groff would retain whitespace
 394 in free-form text lines.
 395 .El
 396 .\" SECTION
 397 .Sh SEE ALSO
 398 .Xr mandoc 1 ,
 399 .Xr mandoc_char 7
 400 .\" SECTION
 401 .Sh AUTHORS
 402 The
 403 .Nm
 404 reference was written by
 405 .An Kristaps Dzonsons Aq kristaps@kth.se .
 406 .\" SECTION
 407 .Sh CAVEATS
 408 Do not use this language.  Use
 409 .Xr mdoc 7 ,
 410 instead.