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