man.7

   1 .\"     $Id: man.7,v 1.24 2009/08/13 12:31:50 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 .\" TODO.
 287 .It \&I
 288 Text is rendered in italics.
 289 .It \&IB
 290 Text is rendered alternately in italics and bold face.  Whitespace
 291 between arguments is omitted in output.
 292 .It \&IP
 293 .\" TODO.
 294 .It \&IR
 295 Text is rendered alternately in italics and roman (the default font).
 296 Whitespace between arguments is omitted in output.
 297 .It \&LP, \&P, \&PP
 298 Begin an undecorated paragraph.  The scope of a paragraph is closed by a
 299 subsequent paragraph, sub-section, section, or end of file.
 300 .It \&R
 301 Text is rendered in roman (the default font).
 302 .It \&RB
 303 Text is rendered alternately in roman (the default font) and bold face.
 304 Whitespace between arguments is omitted in output.
 305 .It \&RI
 306 Text is rendered alternately in roman (the default font) and italics.
 307 Whitespace between arguments is omitted in output.
 308 .It \&SB
 309 Text is rendered in small size (one point smaller than the default font)
 310 bold face.
 311 .It \&SH
 312 Begin a section.  The scope of a section is only closed by another
 313 section or the end of file.
 314 .It \&SM
 315 Text is rendered in small size (one point smaller than the default
 316 font).
 317 .It \&SS
 318 Begin a sub-section.  The scope of a sub-section is closed by a
 319 subsequent sub-section, section, or end of file.
 320 .It \&TH
 321 Sets the title of the manual page with the following syntax:
 322 .Bd -literal -offset indent
 323 \&.TH title section date source volume
 324 .Ed
 325 .Pp
 326 At least the
 327 .Va title
 328 and
 329 .Va section
 330 arguments must be provided.  The
 331 .Va date
 332 argument should be formatted as
 333 .Qq %b [%d] %Y
 334 format, described in
 335 .Xr strptime 3 .
 336 The
 337 .Va source
 338 string specifies the organisation providing the utility.  The
 339 .Va volume
 340 replaces the default rendered volume as dictated by the manual section.
 341 .It \&TP
 342 Begin a paragraph where the head, if exceeding the indentation point, is
 343 followed by a newline; if not, the body follows on the same line after a
 344 buffer to the indentation point.  Subsequent output lines are indented.
 345 .It \&br
 346 Breaks the current line.  Consecutive invocations have no further effect.
 347 .\" TODO.
 348 .It \&fi
 349 End literal mode begun by
 350 .Sq \&nf .
 351 .It \&i
 352 Italicise arguments.  If no arguments are specified, all subsequent text
 353 is italicised.
 354 .It \&na
 355 No alignment to the right margin.
 356 .It \&nf
 357 Begin literal mode: all subsequent free-form lines have their end of
 358 line boundaries preserved.  May be ended by
 359 .Sq \&fi .
 360 .It \&r
 361 Fonts and styles (bold face, italics) reset to roman (default font).
 362 .It \&sp
 363 Insert n spaces, where n is the macro's positive numeric argument.  If
 364 0, this is equivalent to the
 365 .Sq br
 366 macro.
 367 .El
 368 .\" SECTION
 369 .Sh COMPATIBILITY
 370 This section documents compatibility with other roff implementations, at
 371 this time limited to
 372 .Xr groff 1 .
 373 .Bl -hyphen
 374 .It
 375 In quoted literals, groff allowed pair-wise double-quotes to produce a
 376 standalone double-quote in formatted output.  This idiosyncratic
 377 behaviour is no longer applicable.
 378 .It
 379 The
 380 .Sq \&sp
 381 macro does not accept negative numbers.
 382 .It
 383 Blocks of whitespace are stripped from both macro and free-form text
 384 lines (except when in literal mode), while groff would retain whitespace
 385 in free-form text lines.
 386 .El
 387 .\" SECTION
 388 .Sh SEE ALSO
 389 .Xr mandoc 1 ,
 390 .Xr mandoc_char 7
 391 .\" SECTION
 392 .Sh AUTHORS
 393 The
 394 .Nm
 395 reference was written by
 396 .An Kristaps Dzonsons Aq kristaps@kth.se .
 397 .\" SECTION
 398 .Sh CAVEATS
 399 Do not use this language.  Use
 400 .Xr mdoc 7 ,
 401 instead.