Added some new manuals (mdoc.3 mandoc_char.7).
[mandoc.git] / man.7
1 .\" $Id: man.7,v 1.6 2009/03/27 14:56:15 kristaps Exp $
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: March 27 2009 $
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
32 manuals. In this reference document, we describe the syntax and
33 structure of the
34 .Nm
35 language.
36 .Pp
37 .Em \&Do not ever
38 use
39 .Nm
40 to write your manuals. Use the
41 .Xr mdoc 7
42 language, instead.
43 .\" PARAGRAPH
44 .Pp
45 An
46 .Nm
47 document follows simple rules: lines beginning with the control
48 character
49 .Sq \&.
50 are parsed for macros. Other lines are interpreted within the scope of
51 prior macros:
52 .Bd -literal -offset indent
53 \&.SH Macro lines change control state.
54 Other lines are interpreted within the current state.
55 .Ed
56 .\" SECTION
57 .Sh INPUT ENCODING
58 .Nm
59 documents may contain only graphable 7-bit ASCII characters and the
60 space character
61 .Sq \ .
62 All manuals must have
63 .Ux
64 .Sq \en
65 line termination.
66 .Pp
67 Blank lines are acceptable; where found, the output will assert a
68 vertical space.
69 .Pp
70 The
71 .Sq \ec
72 escape is common in historical
73 .Nm
74 documents; if encountered at the end of a word, it ensures that the
75 subsequent word isn't off-set by whitespace.
76 .\" SUB-SECTION
77 .Ss Special Characters
78 Special character sequences begin with the escape character
79 .Sq \e
80 followed by either an open-parenthesis
81 .Sq \&(
82 for two-character sequences; an open-bracket
83 .Sq \&[
84 for n-character sequences (terminated at a close-bracket
85 .Sq \&] ) ;
86 or a single one-character sequence.
87 .Pp
88 Characters may alternatively be escaped by a slash-asterisk,
89 .Sq \e* ,
90 with the same combinations as described above. This form is deprecated.
91 .\" SECTION
92 .Sh STRUCTURE
93 Macros are one to three three characters in length and begin with a
94 control character ,
95 .Sq \&. ,
96 at the beginning of the line. An arbitrary amount of whitespace may
97 sit between the control character and the macro name. Thus,
98 .Sq \&.PP
99 and
100 .Sq \&.\ \ \ \&PP
101 are equivalent.
102 .Pp
103 All
104 .Nm
105 macros follow the same structural rules:
106 .Bd -literal -offset indent
107 \&.YO \(lBbody...\(rB
108 .Ed
109 .Pp
110 The
111 .Dq body
112 consists of zero or more arguments to the macro.
113 .Pp
114 .Nm
115 has a primitive notion of multi-line scope for the following macros:
116 .Sq \&.TM ,
117 .Sq \&.SM ,
118 .Sq \&.SB ,
119 .Sq \&.BI ,
120 .Sq \&.IB ,
121 .Sq \&.BR ,
122 .Sq \&.RB ,
123 .Sq \&.R ,
124 .Sq \&.B ,
125 .Sq \&.I ,
126 .Sq \&.IR
127 and
128 .Sq \&.RI .
129 When these macros are invoked without arguments, the subsequent line is
130 considered a continuation of the macro. Thus:
131 .Bd -literal -offset indent
132 \&.RI
133 foo
134 .Ed
135 .Pp
136 is equivalent to
137 .Sq \&.RI foo .
138 If two consecutive lines exhibit the latter behaviour,
139 an error is raised. Thus, the following is not acceptable:
140 .Bd -literal -offset indent
141 \&.RI
142 \&.I
143 Hello, world.
144 .Ed
145 .Pp
146 The
147 .Sq \&.TP
148 macro is similar, but does not need an empty argument line to trigger
149 the behaviour.
150 .\" PARAGRAPH
151 .Sh MACROS
152 This section contains a complete list of all
153 .Nm
154 macros and corresponding number of arguments.
155 .Pp
156 .Bl -column "MacroX" "Arguments" -compact -offset indent
157 .It Em Macro Ta Em Arguments
158 .It \&.TH Ta >1, <6
159 .It \&.SH Ta >0
160 .It \&.SS Ta >0
161 .It \&.TP Ta n
162 .It \&.LP Ta 0
163 .It \&.PP Ta 0
164 .It \&.P Ta 0
165 .It \&.IP Ta <3
166 .It \&.HP Ta <2
167 .It \&.SM Ta n
168 .It \&.SB Ta n
169 .It \&.BI Ta n
170 .It \&.IB Ta n
171 .It \&.BR Ta n
172 .It \&.RB Ta n
173 .It \&.R Ta n
174 .It \&.B Ta n
175 .It \&.I Ta n
176 .It \&.IR Ta n
177 .It \&.RI Ta n
178 .El
179 .\" SECTION
180 .Sh SEE ALSO
181 .Xr mandoc 1 ,
182 .Xr mandoc_char 7
183 .\" SECTION
184 .Sh AUTHORS
185 The
186 .Nm
187 utility was written by
188 .An Kristaps Dzonsons Aq kristaps@openbsd.org .
189 .\" SECTION
190 .Sh CAVEATS
191 Do not use this language. Use
192 .Xr mdoc 7 ,
193 instead.