Annotation of mandoc/man.7, Revision 1.20
1.20 ! kristaps 1: .\" $Id: man.7,v 1.19 2009/07/14 15:56:44 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
73: Anything following a
1.20 ! kristaps 74: .Sq \e"
! 75: delimiter is considered a comment (unless the
1.13 kristaps 76: .Sq \e
77: itself has been escaped) and is ignored to the end of line.
78: Furthermore, a macro line with only a control character
79: .Sq \. ,
80: optionally followed by whitespace, is ignored.
81: .\" SUB-SECTION
1.1 kristaps 82: .Ss Special Characters
83: Special character 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 \&] ) ;
91: or a single one-character sequence.
92: .Pp
93: Characters may alternatively be escaped by a slash-asterisk,
1.2 kristaps 94: .Sq \e* ,
1.18 kristaps 95: with the same combinations as described above.
96: .Pp
97: Terms may also be text-decorated using the
98: .Sq \ef
99: escape followed by a text-decoration letter: B (bold), I, (italic), or P
100: and R (Roman, or reset).
1.17 kristaps 101: .\" SUB-SECTION
102: .Ss Whitespace
103: Unless specifically escaped, consecutive blocks of whitespace are pruned
104: from input. These are later re-added, if applicable, by a front-end
105: utility such as
106: .Xr mandoc 1 .
1.1 kristaps 107: .\" SECTION
1.16 kristaps 108: .Sh STRUCTURE
109: Each
110: .Nm
111: document must contain contains at least the
112: .Sq \&.TH
113: macro describing the document's section and title. It may occur
114: anywhere in the document, although conventionally, it appears as the
115: first macro.
116: .Pp
1.20 ! kristaps 117: Beyond the
1.16 kristaps 118: .Sq \&.TH ,
119: at least one macro or text node must appear in the document.
120: .\" SECTION
1.15 kristaps 121: .Sh SYNTAX
1.2 kristaps 122: Macros are one to three three characters in length and begin with a
1.4 kristaps 123: control character ,
124: .Sq \&. ,
1.2 kristaps 125: at the beginning of the line. An arbitrary amount of whitespace may
126: sit between the control character and the macro name. Thus,
1.4 kristaps 127: .Sq \&.PP
1.2 kristaps 128: and
129: .Sq \&.\ \ \ \&PP
130: are equivalent.
131: .Pp
1.20 ! kristaps 132: All
1.4 kristaps 133: .Nm
134: macros follow the same structural rules:
135: .Bd -literal -offset indent
1.20 ! kristaps 136: \&.YO \(lBbody...\(rB
1.1 kristaps 137: .Ed
138: .Pp
139: The
140: .Dq body
141: consists of zero or more arguments to the macro.
1.4 kristaps 142: .Pp
143: .Nm
1.20 ! kristaps 144: has a primitive notion of multi-line scope for the following macros:
1.4 kristaps 145: .Sq \&.TM ,
146: .Sq \&.SM ,
147: .Sq \&.SB ,
148: .Sq \&.BI ,
149: .Sq \&.IB ,
150: .Sq \&.BR ,
151: .Sq \&.RB ,
152: .Sq \&.R ,
153: .Sq \&.B ,
154: .Sq \&.I ,
1.20 ! kristaps 155: .Sq \&.IR
1.4 kristaps 156: and
157: .Sq \&.RI .
158: When these macros are invoked without arguments, the subsequent line is
159: considered a continuation of the macro. Thus:
1.20 ! kristaps 160: .Bd -literal -offset indent
! 161: \&.RI
1.4 kristaps 162: foo
163: .Ed
164: .Pp
1.20 ! kristaps 165: is equivalent to
1.8 kristaps 166: .Sq \&.RI foo .
1.5 kristaps 167: If two consecutive lines exhibit the latter behaviour,
168: an error is raised. Thus, the following is not acceptable:
1.20 ! kristaps 169: .Bd -literal -offset indent
! 170: \&.RI
! 171: \&.I
1.4 kristaps 172: Hello, world.
173: .Ed
174: .Pp
175: The
176: .Sq \&.TP
1.5 kristaps 177: macro is similar, but does not need an empty argument line to trigger
178: the behaviour.
1.15 kristaps 179: .\" SECTION
1.1 kristaps 180: .Sh MACROS
1.20 ! kristaps 181: This section contains a complete list of all
1.1 kristaps 182: .Nm
1.5 kristaps 183: macros and corresponding number of arguments.
1.1 kristaps 184: .Pp
1.4 kristaps 185: .Bl -column "MacroX" "Arguments" -compact -offset indent
1.1 kristaps 186: .It Em Macro Ta Em Arguments
1.4 kristaps 187: .It \&.TH Ta >1, <6
188: .It \&.SH Ta >0
189: .It \&.SS Ta >0
1.1 kristaps 190: .It \&.TP Ta n
1.4 kristaps 191: .It \&.LP Ta 0
192: .It \&.PP Ta 0
193: .It \&.P Ta 0
194: .It \&.IP Ta <3
195: .It \&.HP Ta <2
1.1 kristaps 196: .It \&.SM Ta n
197: .It \&.SB Ta n
198: .It \&.BI Ta n
199: .It \&.IB Ta n
200: .It \&.BR Ta n
201: .It \&.RB Ta n
202: .It \&.R Ta n
203: .It \&.B Ta n
204: .It \&.I Ta n
205: .It \&.IR Ta n
1.3 kristaps 206: .It \&.RI Ta n
1.1 kristaps 207: .El
1.7 kristaps 208: .Pp
209: Although not historically part of the
210: .Nm
211: system, the following macros are also supported:
212: .Pp
213: .Bl -column "MacroX" "Arguments" -compact -offset indent
214: .It Em Macro Ta Em Arguments
215: .It \&.br Ta 0
1.8 kristaps 216: .It \&.i Ta n
1.7 kristaps 217: .El
1.8 kristaps 218: .Pp
219: These follow the same calling conventions as the above
220: .Nm
221: macros.
1.1 kristaps 222: .\" SECTION
1.18 kristaps 223: .Sh COMPATIBILITY
224: See
225: .Xr mdoc 7
226: for groff compatibility notes.
227: .\" SECTION
1.1 kristaps 228: .Sh SEE ALSO
1.6 kristaps 229: .Xr mandoc 1 ,
230: .Xr mandoc_char 7
1.1 kristaps 231: .\" SECTION
232: .Sh AUTHORS
233: The
234: .Nm
1.20 ! kristaps 235: utility was written by
1.12 kristaps 236: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.1 kristaps 237: .\" SECTION
238: .Sh CAVEATS
239: Do not use this language. Use
240: .Xr mdoc 7 ,
241: instead.
CVSweb