Annotation of mandoc/man.7, Revision 1.31
1.31 ! kristaps 1: .\" $Id: man.7,v 1.30 2009/08/20 11:44:47 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
1.31 ! kristaps 206: . It DT Ta 0 Ta current
1.30 kristaps 207: . It I Ta n Ta next-line
208: . It IB Ta n Ta current
209: . It IR Ta n Ta current
210: . It R Ta n Ta next-line
211: . It RB Ta n Ta current
212: . It RI Ta n Ta current
213: . It SB Ta n Ta next-line
214: . It SM Ta n Ta next-line
215: . It TH Ta >1, <6 Ta current
216: . It br Ta 0 Ta current
217: . It fi Ta 0 Ta current
218: . It i Ta n Ta current
219: . It na Ta 0 Ta current
220: . It nf Ta 0 Ta current
221: . It r Ta 0 Ta current
222: . It sp Ta 1 Ta current
1.28 kristaps 223: . El
224: . Pp
1.31 ! kristaps 225: The
! 226: . Sq RS ,
! 227: . Sq RE ,
1.30 kristaps 228: . Sq br ,
229: . Sq fi ,
230: . Sq i ,
231: . Sq na ,
232: . Sq nf ,
233: . Sq r ,
1.22 kristaps 234: and
1.30 kristaps 235: . Sq sp
1.22 kristaps 236: macros aren't historically part of
1.28 kristaps 237: . Nm
1.22 kristaps 238: and should not be used. They're included for compatibility.
1.28 kristaps 239: .
240: .
241: . Ss Block Macros
1.30 kristaps 242: Block macros are comprised of a head and body. Like for in-line macros,
243: the head is scoped to the current line and, in one circumstance, the
244: next line; the body is scoped to subsequent lines and is closed out by a
245: subsequent block macro invocation.
1.28 kristaps 246: . Bd -literal -offset indent
1.22 kristaps 247: \&.YO \(lBhead...\(rB
248: \(lBhead...\(rB
249: \(lBbody...\(rB
1.28 kristaps 250: . Ed
251: . Pp
1.30 kristaps 252: The closure of body scope may be to the section, where a macro is closed
253: by
254: . Sq SH ;
255: sub-section, closed by a section or
256: . Sq SS ;
257: part, closed by a section, sub-section, or
258: . Sq RE ;
259: or paragraph, closed by a section, sub-section, part,
260: . Sq HP ,
261: . Sq IP ,
262: . Sq LP ,
263: . Sq P ,
264: . Sq PP ,
265: or
266: . Sq TP .
267: No closure refers to an explicit block closing macro.
268: . Pp
269: It is considered an error when part or next-line scope is open at the
270: end of file.
271: . Pp
272: . Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" -compact -offset indent
273: . It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope
274: . It HP Ta <2 Ta current Ta paragraph
275: . It IP Ta <3 Ta current Ta paragraph
276: . It LP Ta 0 Ta current Ta paragraph
277: . It P Ta 0 Ta current Ta paragraph
278: . It PP Ta 0 Ta current Ta paragraph
279: . It RE Ta 0 Ta current Ta none
280: . It RS Ta 1 Ta current Ta part
281: . It SH Ta >0 Ta current Ta section
282: . It SS Ta >0 Ta current Ta sub-section
283: . It TP Ta n Ta next-line Ta paragraph
284: . El
285: . Pp
1.22 kristaps 286: If a block macro is next-line scoped, it may only be followed by in-line
287: macros (excluding
1.31 ! kristaps 288: . Sq DT ,
! 289: . Sq TH ,
1.28 kristaps 290: . Sq br ,
291: . Sq na ,
292: . Sq sp ,
293: . Sq nf ,
1.22 kristaps 294: and
1.31 ! kristaps 295: . Sq fi ) .
1.28 kristaps 296: .
297: .
1.22 kristaps 298: .Sh REFERENCE
299: This section is a canonical reference to all macros, arranged
300: alphabetically. For the scoping of individual macros, see
1.28 kristaps 301: . Sx MACRO SYNTAX .
302: .
303: .
1.30 kristaps 304: . Ss Definitions
1.26 kristaps 305: In this reference, a numerical width may be either a standalone natural
306: number (such as 3, 4, 10, etc.) or a natural number followed by a width
307: multiplier
1.28 kristaps 308: . Qq n ,
1.26 kristaps 309: corresponding to the width of the formatted letter n, or
1.28 kristaps 310: . Qq m ,
1.26 kristaps 311: corresponding to the width of the formatted letter m. The latter is the
1.27 kristaps 312: default, if unspecified. Thus,
1.28 kristaps 313: . Bd -literal -offset indent
1.27 kristaps 314: \&.HP 12n
1.28 kristaps 315: . Ed
316: . Pp
1.27 kristaps 317: indicates an offset of 12
1.28 kristaps 318: . Qq n
319: . Ns -sized
1.27 kristaps 320: letters.
1.28 kristaps 321: .
322: .
323: . Ss Macro Reference
324: . Bl -tag -width Ds
1.30 kristaps 325: . It B
1.22 kristaps 326: Text is rendered in bold face.
1.30 kristaps 327: . It BI
1.22 kristaps 328: Text is rendered alternately in bold face and italic. Thus,
1.30 kristaps 329: . Sq .BI this word and that
1.22 kristaps 330: causes
1.28 kristaps 331: . Sq this
1.22 kristaps 332: and
1.28 kristaps 333: . Sq and
1.22 kristaps 334: to render in bold face, while
1.28 kristaps 335: . Sq word
1.22 kristaps 336: and
1.28 kristaps 337: . Sq that
1.22 kristaps 338: render in italics. Whitespace between arguments is omitted in output.
1.30 kristaps 339: . It BR
1.22 kristaps 340: Text is rendered alternately in bold face and roman (the default font).
341: Whitespace between arguments is omitted in output.
1.31 ! kristaps 342: . It DT
! 343: Re-set the tab spacing to 0.5 inches.
1.30 kristaps 344: . It HP
1.23 kristaps 345: Begin a paragraph whose initial output line is left-justified, but
1.27 kristaps 346: subsequent output lines are indented, with the following syntax:
1.28 kristaps 347: . Bd -literal -offset indent
1.27 kristaps 348: \&.HP [width]
1.28 kristaps 349: . Ed
350: . Pp
1.27 kristaps 351: If
1.28 kristaps 352: . Va width
1.27 kristaps 353: is specified, it's saved for later paragraph left-margins; if
354: unspecified, the saved or default width is used.
1.30 kristaps 355: . It I
1.22 kristaps 356: Text is rendered in italics.
1.30 kristaps 357: . It IB
1.22 kristaps 358: Text is rendered alternately in italics and bold face. Whitespace
359: between arguments is omitted in output.
1.30 kristaps 360: . It IP
1.25 kristaps 361: Begin a paragraph with the following syntax:
1.28 kristaps 362: . Bd -literal -offset indent
1.25 kristaps 363: \&.IP [head [width]]
1.28 kristaps 364: . Ed
365: . Pp
1.25 kristaps 366: This follows the behaviour of the
1.30 kristaps 367: . Sq TP
1.26 kristaps 368: except for the macro syntax (all arguments on the line, instead of
1.27 kristaps 369: having next-line scope). If
1.28 kristaps 370: . Va width
1.27 kristaps 371: is specified, it's saved for later paragraph left-margins; if
372: unspecified, the saved or default width is used.
1.30 kristaps 373: . It IR
1.22 kristaps 374: Text is rendered alternately in italics and roman (the default font).
375: Whitespace between arguments is omitted in output.
1.30 kristaps 376: . It LP, P, PP
1.22 kristaps 377: Begin an undecorated paragraph. The scope of a paragraph is closed by a
1.27 kristaps 378: subsequent paragraph, sub-section, section, or end of file. The saved
379: paragraph left-margin width is re-set to the default.
1.30 kristaps 380: . It R
1.22 kristaps 381: Text is rendered in roman (the default font).
1.30 kristaps 382: . It RB
1.22 kristaps 383: Text is rendered alternately in roman (the default font) and bold face.
384: Whitespace between arguments is omitted in output.
1.30 kristaps 385: . It RE
386: Explicitly close out the scope of a prior
387: . Sq RS .
388: . It RI
1.22 kristaps 389: Text is rendered alternately in roman (the default font) and italics.
390: Whitespace between arguments is omitted in output.
1.30 kristaps 391: . It RS
392: Begin a part setting the left margin. The left margin controls the
393: offset, following an initial indentation, to un-indented text such as
394: that of
395: . Sq PP .
396: The width may be specified as following:
397: . Bd -literal -offset indent
398: \&.RS [width]
399: . Ed
400: . Pp
401: If
402: . Va width
403: is not specified, the saved or default width is used.
404: . It SB
1.22 kristaps 405: Text is rendered in small size (one point smaller than the default font)
406: bold face.
1.30 kristaps 407: . It SH
1.22 kristaps 408: Begin a section. The scope of a section is only closed by another
1.27 kristaps 409: section or the end of file. The paragraph left-margin width is re-set
410: to the default.
1.30 kristaps 411: . It SM
1.22 kristaps 412: Text is rendered in small size (one point smaller than the default
413: font).
1.30 kristaps 414: . It SS
1.22 kristaps 415: Begin a sub-section. The scope of a sub-section is closed by a
1.27 kristaps 416: subsequent sub-section, section, or end of file. The paragraph
417: left-margin width is re-set to the default.
1.30 kristaps 418: . It TH
1.22 kristaps 419: Sets the title of the manual page with the following syntax:
1.28 kristaps 420: . Bd -literal -offset indent
1.30 kristaps 421: \&.TH title section [date [source [volume]]]
1.28 kristaps 422: . Ed
423: . Pp
1.22 kristaps 424: At least the
1.28 kristaps 425: . Va title
1.22 kristaps 426: and
1.28 kristaps 427: . Va section
1.22 kristaps 428: arguments must be provided. The
1.28 kristaps 429: . Va date
1.22 kristaps 430: argument should be formatted as
1.28 kristaps 431: . Qq %b [%d] %Y
1.22 kristaps 432: format, described in
1.28 kristaps 433: . Xr strptime 3 .
1.22 kristaps 434: The
1.28 kristaps 435: . Va source
1.22 kristaps 436: string specifies the organisation providing the utility. The
1.28 kristaps 437: . Va volume
1.22 kristaps 438: replaces the default rendered volume as dictated by the manual section.
1.30 kristaps 439: . It TP
1.25 kristaps 440: Begin a paragraph where the head, if exceeding the indentation width, is
1.24 kristaps 441: followed by a newline; if not, the body follows on the same line after a
1.25 kristaps 442: buffer to the indentation width. Subsequent output lines are indented.
1.28 kristaps 443: . Pp
1.26 kristaps 444: The indentation width may be set as follows:
1.28 kristaps 445: . Bd -literal -offset indent
1.26 kristaps 446: \&.TP [width]
1.28 kristaps 447: . Ed
448: . Pp
1.26 kristaps 449: Where
1.28 kristaps 450: . Va width
1.27 kristaps 451: must be a properly-formed numeric width. If
1.28 kristaps 452: . Va width
1.27 kristaps 453: is specified, it's saved for later paragraph left-margins; if
454: unspecified, the saved or default width is used.
1.30 kristaps 455: . It br
1.22 kristaps 456: Breaks the current line. Consecutive invocations have no further effect.
1.30 kristaps 457: . It fi
1.22 kristaps 458: End literal mode begun by
1.30 kristaps 459: . Sq nf .
460: . It i
1.22 kristaps 461: Italicise arguments. If no arguments are specified, all subsequent text
462: is italicised.
1.30 kristaps 463: . It na
1.31 ! kristaps 464: Don't alignment the right margin.
1.30 kristaps 465: . It nf
1.22 kristaps 466: Begin literal mode: all subsequent free-form lines have their end of
467: line boundaries preserved. May be ended by
1.30 kristaps 468: . Sq fi .
469: . It r
1.22 kristaps 470: Fonts and styles (bold face, italics) reset to roman (default font).
1.30 kristaps 471: . It sp
1.22 kristaps 472: Insert n spaces, where n is the macro's positive numeric argument. If
473: 0, this is equivalent to the
1.28 kristaps 474: . Sq br
1.22 kristaps 475: macro.
1.28 kristaps 476: . El
477: .
478: .
1.18 kristaps 479: .Sh COMPATIBILITY
1.23 kristaps 480: This section documents compatibility with other roff implementations, at
481: this time limited to
1.28 kristaps 482: . Xr groff 1 .
483: . Bl -hyphen
484: . It
1.23 kristaps 485: In quoted literals, groff allowed pair-wise double-quotes to produce a
486: standalone double-quote in formatted output. This idiosyncratic
487: behaviour is no longer applicable.
1.28 kristaps 488: . It
1.23 kristaps 489: The
1.30 kristaps 490: . Sq sp
1.23 kristaps 491: macro does not accept negative numbers.
1.28 kristaps 492: . It
1.23 kristaps 493: Blocks of whitespace are stripped from both macro and free-form text
494: lines (except when in literal mode), while groff would retain whitespace
495: in free-form text lines.
1.28 kristaps 496: . El
497: .
498: .
1.1 kristaps 499: .Sh SEE ALSO
1.28 kristaps 500: . Xr mandoc 1 ,
501: . Xr mandoc_char 7
502: .
503: .
1.1 kristaps 504: .Sh AUTHORS
505: The
1.28 kristaps 506: . Nm
1.23 kristaps 507: reference was written by
1.28 kristaps 508: . An Kristaps Dzonsons Aq kristaps@kth.se .
509: .
510: .
1.1 kristaps 511: .Sh CAVEATS
512: Do not use this language. Use
1.28 kristaps 513: . Xr mdoc 7 ,
1.1 kristaps 514: instead.
1.28 kristaps 515: .
CVSweb