Annotation of mandoc/man.7, Revision 1.18
1.18 ! kristaps 1: .\" $Id: man.7,v 1.17 2009/06/25 11:35:28 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
28: language was historically used to format
29: .Ux
1.8 kristaps 30: manuals. This reference document describes the syntax and structure of
31: this language.
1.1 kristaps 32: .Pp
1.8 kristaps 33: .Em \&Do not
1.1 kristaps 34: use
35: .Nm
36: to write your manuals. Use the
37: .Xr mdoc 7
38: language, instead.
39: .\" PARAGRAPH
40: .Pp
41: An
42: .Nm
43: document follows simple rules: lines beginning with the control
44: character
1.2 kristaps 45: .Sq \&.
1.1 kristaps 46: are parsed for macros. Other lines are interpreted within the scope of
47: prior macros:
1.4 kristaps 48: .Bd -literal -offset indent
1.1 kristaps 49: \&.SH Macro lines change control state.
50: Other lines are interpreted within the current state.
51: .Ed
52: .\" SECTION
53: .Sh INPUT ENCODING
54: .Nm
1.14 kristaps 55: documents may contain only graphable 7-bit ASCII characters, the
1.1 kristaps 56: space character
1.14 kristaps 57: .Sq \ ,
58: and tabs
59: .Sq \et .
1.1 kristaps 60: All manuals must have
1.5 kristaps 61: .Ux
1.1 kristaps 62: .Sq \en
63: line termination.
64: .Pp
1.5 kristaps 65: Blank lines are acceptable; where found, the output will assert a
1.1 kristaps 66: vertical space.
1.4 kristaps 67: .Pp
68: The
69: .Sq \ec
70: escape is common in historical
71: .Nm
72: documents; if encountered at the end of a word, it ensures that the
73: subsequent word isn't off-set by whitespace.
1.1 kristaps 74: .\" SUB-SECTION
1.13 kristaps 75: .Ss Comments
76: Anything following a
77: .Sq \e"
78: delimiter is considered a comment (unless the
79: .Sq \e
80: itself has been escaped) and is ignored to the end of line.
81: Furthermore, a macro line with only a control character
82: .Sq \. ,
83: optionally followed by whitespace, is ignored.
84: .\" SUB-SECTION
1.1 kristaps 85: .Ss Special Characters
86: Special character sequences begin with the escape character
1.2 kristaps 87: .Sq \e
1.1 kristaps 88: followed by either an open-parenthesis
89: .Sq \&(
90: for two-character sequences; an open-bracket
91: .Sq \&[
92: for n-character sequences (terminated at a close-bracket
93: .Sq \&] ) ;
94: or a single one-character sequence.
95: .Pp
96: Characters may alternatively be escaped by a slash-asterisk,
1.2 kristaps 97: .Sq \e* ,
1.18 ! kristaps 98: with the same combinations as described above.
! 99: .Pp
! 100: Terms may also be text-decorated using the
! 101: .Sq \ef
! 102: escape followed by a text-decoration letter: B (bold), I, (italic), or P
! 103: and R (Roman, or reset).
1.17 kristaps 104: .\" SUB-SECTION
105: .Ss Whitespace
106: Unless specifically escaped, consecutive blocks of whitespace are pruned
107: from input. These are later re-added, if applicable, by a front-end
108: utility such as
109: .Xr mandoc 1 .
1.1 kristaps 110: .\" SECTION
1.16 kristaps 111: .Sh STRUCTURE
112: Each
113: .Nm
114: document must contain contains at least the
115: .Sq \&.TH
116: macro describing the document's section and title. It may occur
117: anywhere in the document, although conventionally, it appears as the
118: first macro.
119: .Pp
120: Beyond the
121: .Sq \&.TH ,
122: at least one macro or text node must appear in the document.
123: .\" SECTION
1.15 kristaps 124: .Sh SYNTAX
1.2 kristaps 125: Macros are one to three three characters in length and begin with a
1.4 kristaps 126: control character ,
127: .Sq \&. ,
1.2 kristaps 128: at the beginning of the line. An arbitrary amount of whitespace may
129: sit between the control character and the macro name. Thus,
1.4 kristaps 130: .Sq \&.PP
1.2 kristaps 131: and
132: .Sq \&.\ \ \ \&PP
133: are equivalent.
134: .Pp
1.4 kristaps 135: All
136: .Nm
137: macros follow the same structural rules:
138: .Bd -literal -offset indent
139: \&.YO \(lBbody...\(rB
1.1 kristaps 140: .Ed
141: .Pp
142: The
143: .Dq body
144: consists of zero or more arguments to the macro.
1.4 kristaps 145: .Pp
146: .Nm
147: has a primitive notion of multi-line scope for the following macros:
148: .Sq \&.TM ,
149: .Sq \&.SM ,
150: .Sq \&.SB ,
151: .Sq \&.BI ,
152: .Sq \&.IB ,
153: .Sq \&.BR ,
154: .Sq \&.RB ,
155: .Sq \&.R ,
156: .Sq \&.B ,
157: .Sq \&.I ,
158: .Sq \&.IR
159: and
160: .Sq \&.RI .
161: When these macros are invoked without arguments, the subsequent line is
162: considered a continuation of the macro. Thus:
163: .Bd -literal -offset indent
164: \&.RI
165: foo
166: .Ed
167: .Pp
1.5 kristaps 168: is equivalent to
1.8 kristaps 169: .Sq \&.RI foo .
1.5 kristaps 170: If two consecutive lines exhibit the latter behaviour,
171: an error is raised. Thus, the following is not acceptable:
1.4 kristaps 172: .Bd -literal -offset indent
173: \&.RI
174: \&.I
175: Hello, world.
176: .Ed
177: .Pp
178: The
179: .Sq \&.TP
1.5 kristaps 180: macro is similar, but does not need an empty argument line to trigger
181: the behaviour.
1.15 kristaps 182: .\" SECTION
1.1 kristaps 183: .Sh MACROS
184: This section contains a complete list of all
185: .Nm
1.5 kristaps 186: macros and corresponding number of arguments.
1.1 kristaps 187: .Pp
1.4 kristaps 188: .Bl -column "MacroX" "Arguments" -compact -offset indent
1.1 kristaps 189: .It Em Macro Ta Em Arguments
1.4 kristaps 190: .It \&.TH Ta >1, <6
191: .It \&.SH Ta >0
192: .It \&.SS Ta >0
1.1 kristaps 193: .It \&.TP Ta n
1.4 kristaps 194: .It \&.LP Ta 0
195: .It \&.PP Ta 0
196: .It \&.P Ta 0
197: .It \&.IP Ta <3
198: .It \&.HP Ta <2
1.1 kristaps 199: .It \&.SM Ta n
200: .It \&.SB Ta n
201: .It \&.BI Ta n
202: .It \&.IB Ta n
203: .It \&.BR Ta n
204: .It \&.RB Ta n
205: .It \&.R Ta n
206: .It \&.B Ta n
207: .It \&.I Ta n
208: .It \&.IR Ta n
1.3 kristaps 209: .It \&.RI Ta n
1.1 kristaps 210: .El
1.7 kristaps 211: .Pp
212: Although not historically part of the
213: .Nm
214: system, the following macros are also supported:
215: .Pp
216: .Bl -column "MacroX" "Arguments" -compact -offset indent
217: .It Em Macro Ta Em Arguments
218: .It \&.br Ta 0
1.8 kristaps 219: .It \&.i Ta n
1.7 kristaps 220: .El
1.8 kristaps 221: .Pp
222: These follow the same calling conventions as the above
223: .Nm
224: macros.
1.1 kristaps 225: .\" SECTION
1.18 ! kristaps 226: .Sh COMPATIBILITY
! 227: See
! 228: .Xr mdoc 7
! 229: for groff compatibility notes.
! 230: .\" SECTION
1.1 kristaps 231: .Sh SEE ALSO
1.6 kristaps 232: .Xr mandoc 1 ,
233: .Xr mandoc_char 7
1.1 kristaps 234: .\" SECTION
235: .Sh AUTHORS
236: The
237: .Nm
238: utility was written by
1.12 kristaps 239: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.1 kristaps 240: .\" SECTION
241: .Sh CAVEATS
242: Do not use this language. Use
243: .Xr mdoc 7 ,
244: instead.
CVSweb