man.7

   1 .\"     $Id: man.7,v 1.22 2009/08/13 11:45:29 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 -offset indent
 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 .\" TODO.
 285 .It \&I
 286 Text is rendered in italics.
 287 .It \&IB
 288 Text is rendered alternately in italics and bold face.  Whitespace
 289 between arguments is omitted in output.
 290 .It \&IP
 291 .\" TODO.
 292 .It \&IR
 293 Text is rendered alternately in italics and roman (the default font).
 294 Whitespace between arguments is omitted in output.
 295 .It \&LP, \&P, \&PP
 296 Begin an undecorated paragraph.  The scope of a paragraph is closed by a
 297 subsequent paragraph, sub-section, section, or end of file.
 298 .It \&R
 299 Text is rendered in roman (the default font).
 300 .It \&RB
 301 Text is rendered alternately in roman (the default font) and bold face.
 302 Whitespace between arguments is omitted in output.
 303 .It \&RI
 304 Text is rendered alternately in roman (the default font) and italics.
 305 Whitespace between arguments is omitted in output.
 306 .It \&SB
 307 Text is rendered in small size (one point smaller than the default font)
 308 bold face.
 309 .It \&SH
 310 Begin a section.  The scope of a section is only closed by another
 311 section or the end of file.
 312 .It \&SM
 313 Text is rendered in small size (one point smaller than the default
 314 font).
 315 .It \&SS
 316 Begin a sub-section.  The scope of a sub-section is closed by a
 317 subsequent sub-section, section, or end of file.
 318 .It \&TH
 319 Sets the title of the manual page with the following syntax:
 320 .Bd -literal -offset indent
 321 \&.TH title section date source volume
 322 .Ed
 323 .Pp
 324 At least the
 325 .Va title
 326 and
 327 .Va section
 328 arguments must be provided.  The
 329 .Va date
 330 argument should be formatted as
 331 .Qq %b [%d] %Y
 332 format, described in
 333 .Xr strptime 3 .
 334 The
 335 .Va source
 336 string specifies the organisation providing the utility.  The
 337 .Va volume
 338 replaces the default rendered volume as dictated by the manual section.
 339 .It \&TP
 340 .\" TODO.
 341 .It \&br
 342 Breaks the current line.  Consecutive invocations have no further effect.
 343 .\" TODO.
 344 .It \&fi
 345 End literal mode begun by
 346 .Sq \&nf .
 347 .It \&i
 348 Italicise arguments.  If no arguments are specified, all subsequent text
 349 is italicised.
 350 .It \&na
 351 No alignment to the right margin.
 352 .It \&nf
 353 Begin literal mode: all subsequent free-form lines have their end of
 354 line boundaries preserved.  May be ended by
 355 .Sq \&fi .
 356 .It \&r
 357 Fonts and styles (bold face, italics) reset to roman (default font).
 358 .It \&sp
 359 Insert n spaces, where n is the macro's positive numeric argument.  If
 360 0, this is equivalent to the
 361 .Sq br
 362 macro.
 363 .El
 364 .\" SECTION
 365 .Sh COMPATIBILITY
 366 See
 367 .Xr mdoc 7
 368 for groff compatibility notes.
 369 .\" SECTION
 370 .Sh SEE ALSO
 371 .Xr mandoc 1 ,
 372 .Xr mandoc_char 7
 373 .\" SECTION
 374 .Sh AUTHORS
 375 The
 376 .Nm
 377 utility was written by
 378 .An Kristaps Dzonsons Aq kristaps@kth.se .
 379 .\" SECTION
 380 .Sh CAVEATS
 381 Do not use this language.  Use
 382 .Xr mdoc 7 ,
 383 instead.