Annotation of mandoc/man.7, Revision 1.25
1.25 ! kristaps 1: .\" $Id: man.7,v 1.24 2009/08/13 12:31:50 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.23 kristaps 265: .Bl -tag -width Ds
1.22 kristaps 266: .It \&B
267: Text is rendered in bold face.
268: .It \&BI
269: Text is rendered alternately in bold face and italic. Thus,
270: .Sq \&.BI this word and that
271: causes
272: .Sq this
273: and
274: .Sq and
275: to render in bold face, while
276: .Sq word
277: and
278: .Sq that
279: render in italics. Whitespace between arguments is omitted in output.
280: .It \&BR
281: Text is rendered alternately in bold face and roman (the default font).
282: Whitespace between arguments is omitted in output.
283: .It \&HP
1.23 kristaps 284: Begin a paragraph whose initial output line is left-justified, but
285: subsequent output lines are indented.
1.22 kristaps 286: .It \&I
287: Text is rendered in italics.
288: .It \&IB
289: Text is rendered alternately in italics and bold face. Whitespace
290: between arguments is omitted in output.
291: .It \&IP
1.25 ! kristaps 292: Begin a paragraph with the following syntax:
! 293: .Bd -literal -offset indent
! 294: \&.IP [head [width]]
! 295: .Ed
! 296: .Pp
! 297: This follows the behaviour of the
! 298: .Sq \&TP
! 299: macro except that
! 300: .Va width ,
! 301: which is only considered as such if properly-formed (e.g., 24n, 4,
! 302: etc.), is used as the indentation offset instead of the default
! 303: indentation value.
1.22 kristaps 304: .It \&IR
305: Text is rendered alternately in italics and roman (the default font).
306: Whitespace between arguments is omitted in output.
307: .It \&LP, \&P, \&PP
308: Begin an undecorated paragraph. The scope of a paragraph is closed by a
309: subsequent paragraph, sub-section, section, or end of file.
310: .It \&R
311: Text is rendered in roman (the default font).
312: .It \&RB
313: Text is rendered alternately in roman (the default font) and bold face.
314: Whitespace between arguments is omitted in output.
315: .It \&RI
316: Text is rendered alternately in roman (the default font) and italics.
317: Whitespace between arguments is omitted in output.
318: .It \&SB
319: Text is rendered in small size (one point smaller than the default font)
320: bold face.
321: .It \&SH
322: Begin a section. The scope of a section is only closed by another
323: section or the end of file.
324: .It \&SM
325: Text is rendered in small size (one point smaller than the default
326: font).
327: .It \&SS
328: Begin a sub-section. The scope of a sub-section is closed by a
329: subsequent sub-section, section, or end of file.
330: .It \&TH
331: Sets the title of the manual page with the following syntax:
332: .Bd -literal -offset indent
333: \&.TH title section date source volume
334: .Ed
1.8 kristaps 335: .Pp
1.22 kristaps 336: At least the
337: .Va title
338: and
339: .Va section
340: arguments must be provided. The
341: .Va date
342: argument should be formatted as
343: .Qq %b [%d] %Y
344: format, described in
345: .Xr strptime 3 .
346: The
347: .Va source
348: string specifies the organisation providing the utility. The
349: .Va volume
350: replaces the default rendered volume as dictated by the manual section.
351: .It \&TP
1.25 ! kristaps 352: Begin a paragraph where the head, if exceeding the indentation width, is
1.24 kristaps 353: followed by a newline; if not, the body follows on the same line after a
1.25 ! kristaps 354: buffer to the indentation width. Subsequent output lines are indented.
1.22 kristaps 355: .It \&br
356: Breaks the current line. Consecutive invocations have no further effect.
357: .It \&fi
358: End literal mode begun by
359: .Sq \&nf .
360: .It \&i
361: Italicise arguments. If no arguments are specified, all subsequent text
362: is italicised.
363: .It \&na
364: No alignment to the right margin.
365: .It \&nf
366: Begin literal mode: all subsequent free-form lines have their end of
367: line boundaries preserved. May be ended by
368: .Sq \&fi .
369: .It \&r
370: Fonts and styles (bold face, italics) reset to roman (default font).
371: .It \&sp
372: Insert n spaces, where n is the macro's positive numeric argument. If
373: 0, this is equivalent to the
374: .Sq br
375: macro.
376: .El
1.1 kristaps 377: .\" SECTION
1.18 kristaps 378: .Sh COMPATIBILITY
1.23 kristaps 379: This section documents compatibility with other roff implementations, at
380: this time limited to
381: .Xr groff 1 .
382: .Bl -hyphen
383: .It
384: In quoted literals, groff allowed pair-wise double-quotes to produce a
385: standalone double-quote in formatted output. This idiosyncratic
386: behaviour is no longer applicable.
387: .It
388: The
389: .Sq \&sp
390: macro does not accept negative numbers.
391: .It
392: Blocks of whitespace are stripped from both macro and free-form text
393: lines (except when in literal mode), while groff would retain whitespace
394: in free-form text lines.
395: .El
1.18 kristaps 396: .\" SECTION
1.1 kristaps 397: .Sh SEE ALSO
1.6 kristaps 398: .Xr mandoc 1 ,
399: .Xr mandoc_char 7
1.1 kristaps 400: .\" SECTION
401: .Sh AUTHORS
402: The
403: .Nm
1.23 kristaps 404: reference was written by
1.12 kristaps 405: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.1 kristaps 406: .\" SECTION
407: .Sh CAVEATS
408: Do not use this language. Use
409: .Xr mdoc 7 ,
410: instead.
CVSweb