Annotation of mandoc/man.7, Revision 1.8
1.8 ! kristaps 1: .\" $Id: man.7,v 1.7 2009/03/27 15:22:56 kristaps Exp $
1.1 kristaps 2: .\"
3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
6: .\" purpose with or without fee is hereby granted, provided that the
7: .\" above copyright notice and this permission notice appear in all
8: .\" copies.
9: .\"
10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
11: .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
12: .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
13: .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
14: .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
15: .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
16: .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
17: .\" PERFORMANCE OF THIS SOFTWARE.
18: .\"
19: .Dd $Mdocdate$
20: .Dt man 7
21: .Os
22: .\" SECTION
23: .Sh NAME
24: .Nm man
25: .Nd man language reference
26: .\" SECTION
27: .Sh DESCRIPTION
28: The
29: .Nm man
30: language was historically used to format
31: .Ux
1.8 ! kristaps 32: manuals. This reference document describes the syntax and structure of
! 33: this language.
1.1 kristaps 34: .Pp
1.8 ! kristaps 35: .Em \&Do not
1.1 kristaps 36: use
37: .Nm
38: to write your manuals. Use the
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
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
57: documents may contain only graphable 7-bit ASCII characters and the
58: space character
59: .Sq \ .
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
75: .Ss Special Characters
76: Special character sequences begin with the escape character
1.2 kristaps 77: .Sq \e
1.1 kristaps 78: followed by either an open-parenthesis
79: .Sq \&(
80: for two-character sequences; an open-bracket
81: .Sq \&[
82: for n-character sequences (terminated at a close-bracket
83: .Sq \&] ) ;
84: or a single one-character sequence.
85: .Pp
86: Characters may alternatively be escaped by a slash-asterisk,
1.2 kristaps 87: .Sq \e* ,
1.1 kristaps 88: with the same combinations as described above. This form is deprecated.
89: .\" SECTION
90: .Sh STRUCTURE
1.2 kristaps 91: Macros are one to three three characters in length and begin with a
1.4 kristaps 92: control character ,
93: .Sq \&. ,
1.2 kristaps 94: at the beginning of the line. An arbitrary amount of whitespace may
95: sit between the control character and the macro name. Thus,
1.4 kristaps 96: .Sq \&.PP
1.2 kristaps 97: and
98: .Sq \&.\ \ \ \&PP
99: are equivalent.
100: .Pp
1.4 kristaps 101: All
102: .Nm
103: macros follow the same structural rules:
104: .Bd -literal -offset indent
105: \&.YO \(lBbody...\(rB
1.1 kristaps 106: .Ed
107: .Pp
108: The
109: .Dq body
110: consists of zero or more arguments to the macro.
1.4 kristaps 111: .Pp
112: .Nm
113: has a primitive notion of multi-line scope for the following macros:
114: .Sq \&.TM ,
115: .Sq \&.SM ,
116: .Sq \&.SB ,
117: .Sq \&.BI ,
118: .Sq \&.IB ,
119: .Sq \&.BR ,
120: .Sq \&.RB ,
121: .Sq \&.R ,
122: .Sq \&.B ,
123: .Sq \&.I ,
124: .Sq \&.IR
125: and
126: .Sq \&.RI .
127: When these macros are invoked without arguments, the subsequent line is
128: considered a continuation of the macro. Thus:
129: .Bd -literal -offset indent
130: \&.RI
131: foo
132: .Ed
133: .Pp
1.5 kristaps 134: is equivalent to
1.8 ! kristaps 135: .Sq \&.RI foo .
1.5 kristaps 136: If two consecutive lines exhibit the latter behaviour,
137: an error is raised. Thus, the following is not acceptable:
1.4 kristaps 138: .Bd -literal -offset indent
139: \&.RI
140: \&.I
141: Hello, world.
142: .Ed
143: .Pp
144: The
145: .Sq \&.TP
1.5 kristaps 146: macro is similar, but does not need an empty argument line to trigger
147: the behaviour.
1.1 kristaps 148: .\" PARAGRAPH
149: .Sh MACROS
150: This section contains a complete list of all
151: .Nm
1.5 kristaps 152: macros and corresponding number of arguments.
1.1 kristaps 153: .Pp
1.4 kristaps 154: .Bl -column "MacroX" "Arguments" -compact -offset indent
1.1 kristaps 155: .It Em Macro Ta Em Arguments
1.4 kristaps 156: .It \&.TH Ta >1, <6
157: .It \&.SH Ta >0
158: .It \&.SS Ta >0
1.1 kristaps 159: .It \&.TP Ta n
1.4 kristaps 160: .It \&.LP Ta 0
161: .It \&.PP Ta 0
162: .It \&.P Ta 0
163: .It \&.IP Ta <3
164: .It \&.HP Ta <2
1.1 kristaps 165: .It \&.SM Ta n
166: .It \&.SB Ta n
167: .It \&.BI Ta n
168: .It \&.IB Ta n
169: .It \&.BR Ta n
170: .It \&.RB Ta n
171: .It \&.R Ta n
172: .It \&.B Ta n
173: .It \&.I Ta n
174: .It \&.IR Ta n
1.3 kristaps 175: .It \&.RI Ta n
1.1 kristaps 176: .El
1.7 kristaps 177: .Pp
178: Although not historically part of the
179: .Nm
180: system, the following macros are also supported:
181: .Pp
182: .Bl -column "MacroX" "Arguments" -compact -offset indent
183: .It Em Macro Ta Em Arguments
184: .It \&.br Ta 0
1.8 ! kristaps 185: .It \&.i Ta n
1.7 kristaps 186: .El
1.8 ! kristaps 187: .Pp
! 188: These follow the same calling conventions as the above
! 189: .Nm
! 190: macros.
1.1 kristaps 191: .\" SECTION
192: .Sh SEE ALSO
1.6 kristaps 193: .Xr mandoc 1 ,
194: .Xr mandoc_char 7
1.1 kristaps 195: .\" SECTION
196: .Sh AUTHORS
197: The
198: .Nm
199: utility was written by
200: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
201: .\" SECTION
202: .Sh CAVEATS
203: Do not use this language. Use
204: .Xr mdoc 7 ,
205: instead.
CVSweb