man.7

   1 .\" $Id: man.7,v 1.1 2009/03/23 16:02:56 kristaps Exp $
   2 .\"
   3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
   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
   7 .\" above copyright notice and this permission notice appear in all
   8 .\" copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
  11 .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
  12 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
  13 .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
  14 .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
  15 .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  16 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  17 .\" PERFORMANCE OF THIS SOFTWARE.
  18 .\"
  19 .Dd $Mdocdate: March 23 2009 $
  20 .Dt man 7
  21 .Os
  22 .\" SECTION
  23 .Sh NAME
  24 .Nm man
  25 .Nd man language reference
  26 .\" SECTION
  27 .Sh DESCRIPTION
  28 The
  29 .Nm man
  30 language was historically used to format
  31 .Ux
  32 manuals.  In this reference document, we describe the syntax and
  33 structure of the
  34 .Nm
  35 language.
  36 .Pp
  37 .Em \&Do not
  38 use
  39 .Nm
  40 to write your manuals.  Use the
  41 .Xr mdoc 7
  42 language, instead.
  43 .\" PARAGRAPH
  44 .Pp
  45 An
  46 .Nm
  47 document follows simple rules:  lines beginning with the control
  48 character
  49 .Sq \.
  50 are parsed for macros.  Other lines are interpreted within the scope of
  51 prior macros:
  52 .Bd -literal -offset XXX
  53 \&.SH Macro lines change control state.
  54 Other lines are interpreted within the current state.
  55 .Ed
  56 .\" PARAGRAPH
  57 .Pp
  58 Macros are character sequences whose structural rules are described
  59 later in this document.
  60 .\" SECTION
  61 .Sh INPUT ENCODING
  62 .Nm
  63 documents may contain only graphable 7-bit ASCII characters and the
  64 space character
  65 .Sq \  .
  66 All manuals must have
  67 .Sq \en
  68 line termination.
  69 .Pp
  70 Blank lines are acceptable; where found, the output will also assert a
  71 vertical space.
  72 .\" SUB-SECTION
  73 .Ss Special Characters
  74 Special character sequences begin with the escape character
  75 .Sq \\
  76 followed by either an open-parenthesis
  77 .Sq \&(
  78 for two-character sequences; an open-bracket
  79 .Sq \&[
  80 for n-character sequences (terminated at a close-bracket
  81 .Sq \&] ) ;
  82 or a single one-character sequence.
  83 .Pp
  84 Characters may alternatively be escaped by a slash-asterisk,
  85 .Sq \\* ,
  86 with the same combinations as described above.  This form is deprecated.
  87 .Pp
  88 The following is a table of all available escapes.
  89 .Pp
  90 Grammatic:
  91 .Bl -tag -width 12n -offset "XXXX" -compact
  92 .It \\(em
  93 .Pq em-dash
  94 .It \\(en
  95 .Pq en-dash
  96 .It \e-
  97 .Pq hyphen
  98 .It \\\\
  99 .Pq back-slash
 100 .It \e'
 101 .Pq apostrophe
 102 .It \e`
 103 .Pq back-tick
 104 .It \\
 105 .Pq space
 106 .It \\.
 107 .Pq period
 108 .It \\(r!
 109 .Pq upside-down exclamation
 110 .It \\(r?
 111 .Pq upside-down question
 112 .El
 113 .\" PARAGRAPH
 114 .Pp
 115 Enclosures:
 116 .Bl -tag -width 12n -offset "XXXX" -compact
 117 .It \\(lh
 118 .Pq left hand
 119 .It \\(rh
 120 .Pq right hand
 121 .It \\(Fo
 122 .Pq left guillemet
 123 .It \\(Fc
 124 .Pq right guillemet
 125 .It \\(fo
 126 .Pq left guilsing
 127 .It \\(fc
 128 .Pq right guilsing
 129 .It \\(rC
 130 .Pq right brace
 131 .It \\(lC
 132 .Pq left brace
 133 .It \\(ra
 134 .Pq right angle
 135 .It \\(la
 136 .Pq left angle
 137 .It \\(rB
 138 .Pq right bracket
 139 .It \\(lB
 140 .Pq left bracket
 141 .It \\q
 142 .Pq double-quote
 143 .It \\(lq
 144 .Pq left double-quote
 145 .It \\(Lq
 146 .Pq left double-quote, deprecated
 147 .It \\(rq
 148 .Pq right double-quote
 149 .It \\(Rq
 150 .Pq right double-quote, deprecated
 151 .It \\(oq
 152 .Pq left single-quote
 153 .It \\(aq
 154 .Pq right single-quote
 155 .It \\(Bq
 156 .Pq right low double-quote
 157 .It \\(bq
 158 .Pq right low single-quote
 159 .El
 160 .\" PARAGRAPH
 161 .Pp
 162 Indicatives:
 163 .Bl -tag -width 12n -offset "XXXX" -compact
 164 .It \\(<-
 165 .Pq left arrow
 166 .It \\(->
 167 .Pq right arrow
 168 .It \\(ua
 169 .Pq up arrow
 170 .It \\(da
 171 .Pq down arrow
 172 .It \\(<>
 173 .Pq left-right arrow
 174 .It \\(lA
 175 .Pq left double-arrow
 176 .It \\(rA
 177 .Pq right double-arrow
 178 .It \\(uA
 179 .Pq up double-arrow
 180 .It \\(dA
 181 .Pq down double-arrow
 182 .It \\(hA
 183 .Pq left-right double-arrow
 184 .El
 185 .\" PARAGRAPH
 186 .Pp
 187 Mathematical:
 188 .Bl -tag -width 12n -offset "XXXX" -compact
 189 .It \\(es
 190 .Pq empty set
 191 .It \\(ca
 192 .Pq intersection
 193 .It \\(cu
 194 .Pq union
 195 .It \\(gr
 196 .Pq gradient
 197 .It \\(pd
 198 .Pq partial differential
 199 .It \\(ap
 200 .Pq similarity
 201 .It \\(=)
 202 .Pq proper superset
 203 .It \\((=
 204 .Pq proper subset
 205 .It \\(eq
 206 .Pq equals
 207 .It \\(di
 208 .Pq division
 209 .It \\(mu
 210 .Pq multiplication
 211 .It \\(pl
 212 .Pq addition
 213 .It \\(nm
 214 .Pq not element
 215 .It \\(mo
 216 .Pq element
 217 .It \\(Im
 218 .Pq imaginary
 219 .It \\(Re
 220 .Pq real
 221 .It \\(Ah
 222 .Pq aleph
 223 .It \\(te
 224 .Pq existential quantifier
 225 .It \\(fa
 226 .Pq universal quantifier
 227 .It \\(AN
 228 .Pq logical AND
 229 .It \\(OR
 230 .Pq logical OR
 231 .It \\(no
 232 .Pq logical NOT
 233 .It \\(st
 234 .Pq such that
 235 .It \\(tf
 236 .Pq therefore
 237 .It \\(~~
 238 .Pq approximate
 239 .It \\(~=
 240 .Pq approximately equals
 241 .It \\(=~
 242 .Pq congruent
 243 .It \\(Gt
 244 .Pq greater-than, deprecated
 245 .It \\(Lt
 246 .Pq less-than, deprecated
 247 .It \\(<=
 248 .Pq less-than-equal
 249 .It \\(Le
 250 .Pq less-than-equal, deprecated
 251 .It \\(>=
 252 .Pq greater-than-equal
 253 .It \\(Ge
 254 .Pq greater-than-equal
 255 .It \\(==
 256 .Pq equal
 257 .It \\(!=
 258 .Pq not equal
 259 .It \\(Ne
 260 .Pq not equal, deprecated
 261 .It \\(if
 262 .Pq infinity
 263 .It \\(If
 264 .Pq infinity, deprecated
 265 .It \\(na
 266 .Pq NaN , an extension
 267 .It \\(Na
 268 .Pq NaN, deprecated
 269 .It \\(+-
 270 .Pq plus-minus
 271 .It \\(Pm
 272 .Pq plus-minus, deprecated
 273 .It \\(**
 274 .Pq asterisk
 275 .El
 276 .\" PARAGRAPH
 277 .Pp
 278 Ligatures:
 279 .Bl -tag -width 12n -offset "XXXX" -compact
 280 .It \\(ss
 281 .Pq German eszett
 282 .It \\(AE
 283 .Pq upper-case AE
 284 .It \\(ae
 285 .Pq lower-case AE
 286 .It \\(OE
 287 .Pq upper-case OE
 288 .It \\(oe
 289 .Pq lower-case OE
 290 .It \\(ff
 291 .Pq ff ligature
 292 .It \\(fi
 293 .Pq fi ligature
 294 .It \\(fl
 295 .Pq fl ligature
 296 .It \\(Fi
 297 .Pq ffi ligature
 298 .It \\(Fl
 299 .Pq ffl ligature
 300 .El
 301 .\" PARAGRAPH
 302 .Pp
 303 Diacritics and letters:
 304 .Bl -tag -width 12n -offset "XXXX" -compact
 305 .It \\(ga
 306 .Pq grave accent
 307 .It \\(aa
 308 .Pq accute accent
 309 .It \\(a"
 310 .Pq umlaut accent
 311 .It \\(ad
 312 .Pq dieresis accent
 313 .It \\(a~
 314 .Pq tilde accent
 315 .It \\(a^
 316 .Pq circumflex accent
 317 .It \\(ac
 318 .Pq cedilla accent
 319 .It \\(ad
 320 .Pq dieresis accent
 321 .It \\(ah
 322 .Pq caron accent
 323 .It \\(ao
 324 .Pq ring accent
 325 .It \\(ho
 326 .Pq hook accent
 327 .It \\(ab
 328 .Pq breve accent
 329 .It \\(a-
 330 .Pq macron accent
 331 .It \\(-D
 332 .Pq upper-case eth
 333 .It \\(Sd
 334 .Pq lower-case eth
 335 .It \\(TP
 336 .Pq upper-case thorn
 337 .It \\(Tp
 338 .Pq lower-case thorn
 339 .It \\('A
 340 .Pq upper-case acute A
 341 .It \\('E
 342 .Pq upper-case acute E
 343 .It \\('I
 344 .Pq upper-case acute I
 345 .It \\('O
 346 .Pq upper-case acute O
 347 .It \\('U
 348 .Pq upper-case acute U
 349 .It \\('a
 350 .Pq lower-case acute a
 351 .It \\('e
 352 .Pq lower-case acute e
 353 .It \\('i
 354 .Pq lower-case acute i
 355 .It \\('o
 356 .Pq lower-case acute o
 357 .It \\('u
 358 .Pq lower-case acute u
 359 .It \\(`A
 360 .Pq upper-case grave A
 361 .It \\(`E
 362 .Pq upper-case grave E
 363 .It \\(`I
 364 .Pq upper-case grave I
 365 .It \\(`O
 366 .Pq upper-case grave O
 367 .It \\(`U
 368 .Pq upper-case grave U
 369 .It \\(`a
 370 .Pq lower-case grave a
 371 .It \\(`e
 372 .Pq lower-case grave e
 373 .It \\(`i
 374 .Pq lower-case grave i
 375 .It \\(`o
 376 .Pq lower-case grave o
 377 .It \\(`u
 378 .Pq lower-case grave u
 379 .It \\(~A
 380 .Pq upper-case tilde A
 381 .It \\(~N
 382 .Pq upper-case tilde N
 383 .It \\(~O
 384 .Pq upper-case tilde O
 385 .It \\(~a
 386 .Pq lower-case tilde a
 387 .It \\(~n
 388 .Pq lower-case tilde n
 389 .It \\(~o
 390 .Pq lower-case tilde o
 391 .It \\(:A
 392 .Pq upper-case dieresis A
 393 .It \\(:E
 394 .Pq upper-case dieresis E
 395 .It \\(:I
 396 .Pq upper-case dieresis I
 397 .It \\(:O
 398 .Pq upper-case dieresis O
 399 .It \\(:U
 400 .Pq upper-case dieresis U
 401 .It \\(:a
 402 .Pq lower-case dieresis a
 403 .It \\(:e
 404 .Pq lower-case dieresis e
 405 .It \\(:i
 406 .Pq lower-case dieresis i
 407 .It \\(:o
 408 .Pq lower-case dieresis o
 409 .It \\(:u
 410 .Pq lower-case dieresis u
 411 .It \\(:y
 412 .Pq lower-case dieresis y
 413 .It \\(^A
 414 .Pq upper-case circumflex A
 415 .It \\(^E
 416 .Pq upper-case circumflex E
 417 .It \\(^I
 418 .Pq upper-case circumflex I
 419 .It \\(^O
 420 .Pq upper-case circumflex O
 421 .It \\(^U
 422 .Pq upper-case circumflex U
 423 .It \\(^a
 424 .Pq lower-case circumflex a
 425 .It \\(^e
 426 .Pq lower-case circumflex e
 427 .It \\(^i
 428 .Pq lower-case circumflex i
 429 .It \\(^o
 430 .Pq lower-case circumflex o
 431 .It \\(^u
 432 .Pq lower-case circumflex u
 433 .It \\(,C
 434 .Pq upper-case cedilla C
 435 .It \\(,c
 436 .Pq lower-case cedilla c
 437 .It \\(/L
 438 .Pq upper-case stroke L
 439 .It \\(/l
 440 .Pq lower-case stroke l
 441 .It \\(/O
 442 .Pq upper-case stroke O
 443 .It \\(/o
 444 .Pq lower-case stroke o
 445 .It \\(oA
 446 .Pq upper-case ring A
 447 .It \\(oa
 448 .Pq lower-case ring a
 449 .El
 450 .\" PARAGRAPH
 451 .Pp
 452 Monetary:
 453 .Bl -tag -width 12n -offset "XXXX" -compact
 454 .It \\(Cs
 455 .Pq Scandinavian
 456 .It \\(Do
 457 .Pq dollar
 458 .It \\(Po
 459 .Pq pound
 460 .It \\(Ye
 461 .Pq yen
 462 .It \\(Fn
 463 .Pq florin
 464 .It \\(ct
 465 .Pq cent
 466 .El
 467 .\" PARAGRAPH
 468 .Pp
 469 Special symbols:
 470 .Bl -tag -width 12n -offset "XXXX" -compact
 471 .It \\(de
 472 .Pq degree
 473 .It \\(ps
 474 .Pq paragraph
 475 .It \\(sc
 476 .Pq section
 477 .It \\(dg
 478 .Pq dagger
 479 .It \\(dd
 480 .Pq double dagger
 481 .It \\(ci
 482 .Pq circle
 483 .It \\(ba
 484 .Pq bar
 485 .It \\(bb
 486 .Pq broken bar
 487 .It \\(Ba
 488 .Pq bar, deprecated
 489 .It \\(co
 490 .Pq copyright
 491 .It \\(rg
 492 .Pq registered
 493 .It \\(tm
 494 .Pq trademarked
 495 .It \\&
 496 .Pq non-breaking space
 497 .It \\e
 498 .Pq escape
 499 .It \\(Am
 500 .Pq ampersand, deprecated
 501 .El
 502 .\" SECTION
 503 .Sh STRUCTURE
 504 Macros are case in-sensitive and one to three three characters in
 505 length.  All follow the same structural rules:
 506 .Bd -literal -offset XXXX
 507 \&.Yo \(lBbody...\(rB
 508 .Ed
 509 .Pp
 510 The
 511 .Dq body
 512 consists of zero or more arguments to the macro.
 513 .\" PARAGRAPH
 514 .Sh MACROS
 515 This section contains a complete list of all
 516 .Nm
 517 macros, arranged alphabetically, with the number of arguments.
 518 .Pp
 519 .Bl -column "MacroX" "Arguments" -compact -offset XXXX
 520 .It Em Macro Ta Em Arguments
 521 .It \&.TH    Ta    >0
 522 .It \&.SH    Ta    n
 523 .It \&.SS    Ta    n
 524 .It \&.TP    Ta    n
 525 .It \&.LP    Ta    n
 526 .It \&.PP    Ta    n
 527 .It \&.P     Ta    n
 528 .It \&.IP    Ta    n
 529 .It \&.HP    Ta    n
 530 .It \&.SM    Ta    n
 531 .It \&.SB    Ta    n
 532 .It \&.BI    Ta    n
 533 .It \&.IB    Ta    n
 534 .It \&.BR    Ta    n
 535 .It \&.RB    Ta    n
 536 .It \&.R     Ta    n
 537 .It \&.B     Ta    n
 538 .It \&.I     Ta    n
 539 .It \&.IR    Ta    n
 540 .El
 541 .\" SECTION
 542 .Sh SEE ALSO
 543 .Xr mandoc 1
 544 .\" SECTION
 545 .Sh AUTHORS
 546 The
 547 .Nm
 548 utility was written by
 549 .An Kristaps Dzonsons Aq kristaps@openbsd.org .
 550 .\" SECTION
 551 .Sh CAVEATS
 552 Do not use this language.  Use
 553 .Xr mdoc 7 ,
 554 instead.