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