Annotation of mandoc/man.7, Revision 1.26
1.26 ! kristaps 1: .\" $Id: man.7,v 1.25 2009/08/13 12:54:52 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
241: .Sq na ,
242: .Sq sp ,
243: .Sq nf ,
244: .Sq fi ,
245: and
246: .Sq TH ) .
247: .\" PARAGRAPH
1.7 kristaps 248: .Pp
1.22 kristaps 249: .Bl -column "MacroX" "Arguments" "ScopeXXXX" -compact -offset indent
250: .It Em Macro Ta Em Arguments Ta Em Scope
251: .It \&HP Ta <2 Ta current
252: .It \&IP Ta <3 Ta current
253: .It \&LP Ta 0 Ta current
254: .It \&P Ta 0 Ta current
255: .It \&PP Ta 0 Ta current
256: .It \&SH Ta >0 Ta current
257: .It \&SS Ta >0 Ta current
258: .It \&TP Ta n Ta next-line
1.7 kristaps 259: .El
1.22 kristaps 260: .\" SECTION
261: .Sh REFERENCE
262: This section is a canonical reference to all macros, arranged
263: alphabetically. For the scoping of individual macros, see
264: .Sx MACRO SYNTAX .
1.26 ! kristaps 265: .\" SUBSECTION
! 266: .Ss Terms
! 267: In this reference, a numerical width may be either a standalone natural
! 268: number (such as 3, 4, 10, etc.) or a natural number followed by a width
! 269: multiplier
! 270: .Qq n ,
! 271: corresponding to the width of the formatted letter n, or
! 272: .Qq m ,
! 273: corresponding to the width of the formatted letter m. The latter is the
! 274: default, if unspecified.
! 275: .\" SUBSECTION
! 276: .Ss Macro Reference
1.23 kristaps 277: .Bl -tag -width Ds
1.22 kristaps 278: .It \&B
279: Text is rendered in bold face.
280: .It \&BI
281: Text is rendered alternately in bold face and italic. Thus,
282: .Sq \&.BI this word and that
283: causes
284: .Sq this
285: and
286: .Sq and
287: to render in bold face, while
288: .Sq word
289: and
290: .Sq that
291: render in italics. Whitespace between arguments is omitted in output.
292: .It \&BR
293: Text is rendered alternately in bold face and roman (the default font).
294: Whitespace between arguments is omitted in output.
295: .It \&HP
1.23 kristaps 296: Begin a paragraph whose initial output line is left-justified, but
297: subsequent output lines are indented.
1.22 kristaps 298: .It \&I
299: Text is rendered in italics.
300: .It \&IB
301: Text is rendered alternately in italics and bold face. Whitespace
302: between arguments is omitted in output.
303: .It \&IP
1.25 kristaps 304: Begin a paragraph with the following syntax:
305: .Bd -literal -offset indent
306: \&.IP [head [width]]
307: .Ed
308: .Pp
309: This follows the behaviour of the
310: .Sq \&TP
1.26 ! kristaps 311: except for the macro syntax (all arguments on the line, instead of
! 312: having next-line scope).
1.22 kristaps 313: .It \&IR
314: Text is rendered alternately in italics and roman (the default font).
315: Whitespace between arguments is omitted in output.
316: .It \&LP, \&P, \&PP
317: Begin an undecorated paragraph. The scope of a paragraph is closed by a
318: subsequent paragraph, sub-section, section, or end of file.
319: .It \&R
320: Text is rendered in roman (the default font).
321: .It \&RB
322: Text is rendered alternately in roman (the default font) and bold face.
323: Whitespace between arguments is omitted in output.
324: .It \&RI
325: Text is rendered alternately in roman (the default font) and italics.
326: Whitespace between arguments is omitted in output.
327: .It \&SB
328: Text is rendered in small size (one point smaller than the default font)
329: bold face.
330: .It \&SH
331: Begin a section. The scope of a section is only closed by another
332: section or the end of file.
333: .It \&SM
334: Text is rendered in small size (one point smaller than the default
335: font).
336: .It \&SS
337: Begin a sub-section. The scope of a sub-section is closed by a
338: subsequent sub-section, section, or end of file.
339: .It \&TH
340: Sets the title of the manual page with the following syntax:
341: .Bd -literal -offset indent
342: \&.TH title section date source volume
343: .Ed
1.8 kristaps 344: .Pp
1.22 kristaps 345: At least the
346: .Va title
347: and
348: .Va section
349: arguments must be provided. The
350: .Va date
351: argument should be formatted as
352: .Qq %b [%d] %Y
353: format, described in
354: .Xr strptime 3 .
355: The
356: .Va source
357: string specifies the organisation providing the utility. The
358: .Va volume
359: replaces the default rendered volume as dictated by the manual section.
360: .It \&TP
1.25 kristaps 361: Begin a paragraph where the head, if exceeding the indentation width, is
1.24 kristaps 362: followed by a newline; if not, the body follows on the same line after a
1.25 kristaps 363: buffer to the indentation width. Subsequent output lines are indented.
1.26 ! kristaps 364: .Pp
! 365: The indentation width may be set as follows:
! 366: .Bd -literal -offset indent
! 367: \&.TP [width]
! 368: .Ed
! 369: .Pp
! 370: Where
! 371: .Va width
! 372: must be a properly-formed numeric width. If unspecified or improperly
! 373: formed, the default indentation width is used.
1.22 kristaps 374: .It \&br
375: Breaks the current line. Consecutive invocations have no further effect.
376: .It \&fi
377: End literal mode begun by
378: .Sq \&nf .
379: .It \&i
380: Italicise arguments. If no arguments are specified, all subsequent text
381: is italicised.
382: .It \&na
383: No alignment to the right margin.
384: .It \&nf
385: Begin literal mode: all subsequent free-form lines have their end of
386: line boundaries preserved. May be ended by
387: .Sq \&fi .
388: .It \&r
389: Fonts and styles (bold face, italics) reset to roman (default font).
390: .It \&sp
391: Insert n spaces, where n is the macro's positive numeric argument. If
392: 0, this is equivalent to the
393: .Sq br
394: macro.
395: .El
1.1 kristaps 396: .\" SECTION
1.18 kristaps 397: .Sh COMPATIBILITY
1.23 kristaps 398: This section documents compatibility with other roff implementations, at
399: this time limited to
400: .Xr groff 1 .
401: .Bl -hyphen
402: .It
403: In quoted literals, groff allowed pair-wise double-quotes to produce a
404: standalone double-quote in formatted output. This idiosyncratic
405: behaviour is no longer applicable.
406: .It
407: The
408: .Sq \&sp
409: macro does not accept negative numbers.
410: .It
411: Blocks of whitespace are stripped from both macro and free-form text
412: lines (except when in literal mode), while groff would retain whitespace
413: in free-form text lines.
414: .El
1.18 kristaps 415: .\" SECTION
1.1 kristaps 416: .Sh SEE ALSO
1.6 kristaps 417: .Xr mandoc 1 ,
418: .Xr mandoc_char 7
1.1 kristaps 419: .\" SECTION
420: .Sh AUTHORS
421: The
422: .Nm
1.23 kristaps 423: reference was written by
1.12 kristaps 424: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.1 kristaps 425: .\" SECTION
426: .Sh CAVEATS
427: Do not use this language. Use
428: .Xr mdoc 7 ,
429: instead.
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to man.7 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc