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