Annotation of mandoc/man.7, Revision 1.29
1.29 ! kristaps 1: .\" $Id: man.7,v 1.28 2009/08/18 14:27:16 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.28 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.28 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.28 kristaps 166: . Sq \&.PP
1.2 kristaps 167: and
1.28 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.22 kristaps 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.
1.28 kristaps 177: .
178: .
179: . Ss Line Macros
1.22 kristaps 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:
1.28 kristaps 183: . Bd -literal -offset indent
1.20 kristaps 184: \&.RI
1.4 kristaps 185: foo
1.28 kristaps 186: . Ed
187: . Pp
1.20 kristaps 188: is equivalent to
1.28 kristaps 189: . Sq \&.RI foo .
1.22 kristaps 190: .\" PARAGRAPH
191: Consecutive next-line invocations are disallowed.
1.28 kristaps 192: . Bd -literal -offset indent
1.22 kristaps 193: \&.YO \(lBbody...\(rB
194: \(lBbody...\(rB
1.28 kristaps 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
1.22 kristaps 220: The lower-case
1.28 kristaps 221: . Sq \&br ,
222: . Sq \&fi ,
223: . Sq \&i ,
224: . Sq \&na ,
225: . Sq \&nf ,
226: . Sq \&r ,
1.22 kristaps 227: and
1.28 kristaps 228: . Sq \&sp
1.22 kristaps 229: macros aren't historically part of
1.28 kristaps 230: . Nm
1.22 kristaps 231: and should not be used. They're included for compatibility.
1.28 kristaps 232: .
233: .
234: . Ss Block Macros
1.22 kristaps 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.
1.28 kristaps 239: . Bd -literal -offset indent
1.22 kristaps 240: \&.YO \(lBhead...\(rB
241: \(lBhead...\(rB
242: \(lBbody...\(rB
1.28 kristaps 243: . Ed
244: . Pp
1.22 kristaps 245: If a block macro is next-line scoped, it may only be followed by in-line
246: macros (excluding
1.28 kristaps 247: . Sq br ,
248: . Sq na ,
249: . Sq sp ,
250: . Sq nf ,
251: . Sq fi ,
1.22 kristaps 252: and
1.28 kristaps 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: .
1.22 kristaps 268: .Sh REFERENCE
269: This section is a canonical reference to all macros, arranged
270: alphabetically. For the scoping of individual macros, see
1.28 kristaps 271: . Sx MACRO SYNTAX .
272: .
273: .
274: . Ss Terms
1.26 kristaps 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
1.28 kristaps 278: . Qq n ,
1.26 kristaps 279: corresponding to the width of the formatted letter n, or
1.28 kristaps 280: . Qq m ,
1.26 kristaps 281: corresponding to the width of the formatted letter m. The latter is the
1.27 kristaps 282: default, if unspecified. Thus,
1.28 kristaps 283: . Bd -literal -offset indent
1.27 kristaps 284: \&.HP 12n
1.28 kristaps 285: . Ed
286: . Pp
1.27 kristaps 287: indicates an offset of 12
1.28 kristaps 288: . Qq n
289: . Ns -sized
1.27 kristaps 290: letters.
1.28 kristaps 291: .
292: .
293: . Ss Macro Reference
294: . Bl -tag -width Ds
295: . It \&B
1.22 kristaps 296: Text is rendered in bold face.
1.28 kristaps 297: . It \&BI
1.22 kristaps 298: Text is rendered alternately in bold face and italic. Thus,
1.28 kristaps 299: . Sq \&.BI this word and that
1.22 kristaps 300: causes
1.28 kristaps 301: . Sq this
1.22 kristaps 302: and
1.28 kristaps 303: . Sq and
1.22 kristaps 304: to render in bold face, while
1.28 kristaps 305: . Sq word
1.22 kristaps 306: and
1.28 kristaps 307: . Sq that
1.22 kristaps 308: render in italics. Whitespace between arguments is omitted in output.
1.28 kristaps 309: . It \&BR
1.22 kristaps 310: Text is rendered alternately in bold face and roman (the default font).
311: Whitespace between arguments is omitted in output.
1.28 kristaps 312: . It \&HP
1.23 kristaps 313: Begin a paragraph whose initial output line is left-justified, but
1.27 kristaps 314: subsequent output lines are indented, with the following syntax:
1.28 kristaps 315: . Bd -literal -offset indent
1.27 kristaps 316: \&.HP [width]
1.28 kristaps 317: . Ed
318: . Pp
1.27 kristaps 319: If
1.28 kristaps 320: . Va width
1.27 kristaps 321: is specified, it's saved for later paragraph left-margins; if
322: unspecified, the saved or default width is used.
1.28 kristaps 323: . It \&I
1.22 kristaps 324: Text is rendered in italics.
1.28 kristaps 325: . It \&IB
1.22 kristaps 326: Text is rendered alternately in italics and bold face. Whitespace
327: between arguments is omitted in output.
1.28 kristaps 328: . It \&IP
1.25 kristaps 329: Begin a paragraph with the following syntax:
1.28 kristaps 330: . Bd -literal -offset indent
1.25 kristaps 331: \&.IP [head [width]]
1.28 kristaps 332: . Ed
333: . Pp
1.25 kristaps 334: This follows the behaviour of the
1.28 kristaps 335: . Sq \&TP
1.26 kristaps 336: except for the macro syntax (all arguments on the line, instead of
1.27 kristaps 337: having next-line scope). If
1.28 kristaps 338: . Va width
1.27 kristaps 339: is specified, it's saved for later paragraph left-margins; if
340: unspecified, the saved or default width is used.
1.28 kristaps 341: . It \&IR
1.22 kristaps 342: Text is rendered alternately in italics and roman (the default font).
343: Whitespace between arguments is omitted in output.
1.28 kristaps 344: . It \&LP, \&P, \&PP
1.22 kristaps 345: Begin an undecorated paragraph. The scope of a paragraph is closed by a
1.27 kristaps 346: subsequent paragraph, sub-section, section, or end of file. The saved
347: paragraph left-margin width is re-set to the default.
1.28 kristaps 348: . It \&R
1.22 kristaps 349: Text is rendered in roman (the default font).
1.28 kristaps 350: . It \&RB
1.22 kristaps 351: Text is rendered alternately in roman (the default font) and bold face.
352: Whitespace between arguments is omitted in output.
1.28 kristaps 353: . It \&RI
1.22 kristaps 354: Text is rendered alternately in roman (the default font) and italics.
355: Whitespace between arguments is omitted in output.
1.28 kristaps 356: . It \&SB
1.22 kristaps 357: Text is rendered in small size (one point smaller than the default font)
358: bold face.
1.28 kristaps 359: . It \&SH
1.22 kristaps 360: Begin a section. The scope of a section is only closed by another
1.27 kristaps 361: section or the end of file. The paragraph left-margin width is re-set
362: to the default.
1.28 kristaps 363: . It \&SM
1.22 kristaps 364: Text is rendered in small size (one point smaller than the default
365: font).
1.28 kristaps 366: . It \&SS
1.22 kristaps 367: Begin a sub-section. The scope of a sub-section is closed by a
1.27 kristaps 368: subsequent sub-section, section, or end of file. The paragraph
369: left-margin width is re-set to the default.
1.28 kristaps 370: . It \&TH
1.22 kristaps 371: Sets the title of the manual page with the following syntax:
1.28 kristaps 372: . Bd -literal -offset indent
1.22 kristaps 373: \&.TH title section date source volume
1.28 kristaps 374: . Ed
375: . Pp
1.22 kristaps 376: At least the
1.28 kristaps 377: . Va title
1.22 kristaps 378: and
1.28 kristaps 379: . Va section
1.22 kristaps 380: arguments must be provided. The
1.28 kristaps 381: . Va date
1.22 kristaps 382: argument should be formatted as
1.28 kristaps 383: . Qq %b [%d] %Y
1.22 kristaps 384: format, described in
1.28 kristaps 385: . Xr strptime 3 .
1.22 kristaps 386: The
1.28 kristaps 387: . Va source
1.22 kristaps 388: string specifies the organisation providing the utility. The
1.28 kristaps 389: . Va volume
1.22 kristaps 390: replaces the default rendered volume as dictated by the manual section.
1.28 kristaps 391: . It \&TP
1.25 kristaps 392: Begin a paragraph where the head, if exceeding the indentation width, is
1.24 kristaps 393: followed by a newline; if not, the body follows on the same line after a
1.25 kristaps 394: buffer to the indentation width. Subsequent output lines are indented.
1.28 kristaps 395: . Pp
1.26 kristaps 396: The indentation width may be set as follows:
1.28 kristaps 397: . Bd -literal -offset indent
1.26 kristaps 398: \&.TP [width]
1.28 kristaps 399: . Ed
400: . Pp
1.26 kristaps 401: Where
1.28 kristaps 402: . Va width
1.27 kristaps 403: must be a properly-formed numeric width. If
1.28 kristaps 404: . Va width
1.27 kristaps 405: is specified, it's saved for later paragraph left-margins; if
406: unspecified, the saved or default width is used.
1.28 kristaps 407: . It \&br
1.22 kristaps 408: Breaks the current line. Consecutive invocations have no further effect.
1.28 kristaps 409: . It \&fi
1.22 kristaps 410: End literal mode begun by
1.28 kristaps 411: . Sq \&nf .
412: . It \&i
1.22 kristaps 413: Italicise arguments. If no arguments are specified, all subsequent text
414: is italicised.
1.28 kristaps 415: . It \&na
1.22 kristaps 416: No alignment to the right margin.
1.28 kristaps 417: . It \&nf
1.22 kristaps 418: Begin literal mode: all subsequent free-form lines have their end of
419: line boundaries preserved. May be ended by
1.28 kristaps 420: . Sq \&fi .
421: . It \&r
1.22 kristaps 422: Fonts and styles (bold face, italics) reset to roman (default font).
1.28 kristaps 423: . It \&sp
1.22 kristaps 424: Insert n spaces, where n is the macro's positive numeric argument. If
425: 0, this is equivalent to the
1.28 kristaps 426: . Sq br
1.22 kristaps 427: macro.
1.28 kristaps 428: . El
429: .
430: .
1.18 kristaps 431: .Sh COMPATIBILITY
1.23 kristaps 432: This section documents compatibility with other roff implementations, at
433: this time limited to
1.28 kristaps 434: . Xr groff 1 .
435: . Bl -hyphen
436: . It
1.23 kristaps 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.
1.28 kristaps 440: . It
1.23 kristaps 441: The
1.28 kristaps 442: . Sq \&sp
1.23 kristaps 443: macro does not accept negative numbers.
1.28 kristaps 444: . It
1.23 kristaps 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.
1.28 kristaps 448: . El
449: .
450: .
1.1 kristaps 451: .Sh SEE ALSO
1.28 kristaps 452: . Xr mandoc 1 ,
453: . Xr mandoc_char 7
454: .
455: .
1.1 kristaps 456: .Sh AUTHORS
457: The
1.28 kristaps 458: . Nm
1.23 kristaps 459: reference was written by
1.28 kristaps 460: . An Kristaps Dzonsons Aq kristaps@kth.se .
461: .
462: .
1.1 kristaps 463: .Sh CAVEATS
464: Do not use this language. Use
1.28 kristaps 465: . Xr mdoc 7 ,
1.1 kristaps 466: instead.
1.28 kristaps 467: .
CVSweb