Annotation of mandoc/man.7, Revision 1.1
1.1 ! kristaps 1: .\" $Id: mdoc.7,v 1.14 2009/03/23 14:22:11 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$
! 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.
CVSweb