]> git.cameronkatri.com Git - mandoc.git/blob - roff.7
Increase performance by stashing the list type in struct mdoc_node.
[mandoc.git] / roff.7
1 .\" $Id: roff.7,v 1.5 2010/05/17 02:38:13 kristaps Exp $
2 .\"
3 .\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
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 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.
16 .\"
17 .Dd $Mdocdate: May 17 2010 $
18 .Dt ROFF 7
19 .Os
20 .Sh NAME
21 .Nm roff
22 .Nd roff language reference
23 .Sh DESCRIPTION
24 The
25 .Nm roff
26 language is a general-purpose text-formatting language. The purpose of
27 this document is to consistently describe those language constructs
28 accepted by the
29 .Xr mandoc 1
30 utility. It is a work in progress.
31 .Pp
32 An
33 .Nm
34 document follows simple rules: lines beginning with the control
35 characters
36 .Sq \.
37 or
38 .Sq \(aq
39 are parsed for macros. Other lines are interpreted within the scope of
40 prior macros:
41 .Bd -literal -offset indent
42 \&.xx Macro lines change control state.
43 Other lines are interpreted within the current state.
44 .Ed
45 .Sh LANGUAGE SYNTAX
46 .Nm
47 documents may contain only graphable 7-bit ASCII characters, the space
48 character, and, in certain circumstances, the tab character. All
49 manuals must have
50 .Ux
51 line terminators.
52 .Sh MACRO SYNTAX
53 Macros are arbitrary in length and begin with a control character ,
54 .Sq \.
55 or
56 .Sq \(aq ,
57 at the beginning of the line.
58 An arbitrary amount of whitespace may sit between the control character
59 and the macro name.
60 Thus, the following are equivalent:
61 .Bd -literal -offset indent
62 \&.if
63 \&.\ \ \ \&if
64 .Ed
65 .Sh REFERENCE
66 This section is a canonical reference of all macros, arranged
67 alphabetically.
68 .Ss \&am
69 The syntax of this macro is the same as that of
70 .Sx \&ig ,
71 except that a leading argument must be specified.
72 It is ignored, as are its children.
73 .Ss \&ami
74 The syntax of this macro is the same as that of
75 .Sx \&ig ,
76 except that a leading argument must be specified.
77 It is ignored, as are its children.
78 .Ss \&am1
79 The syntax of this macro is the same as that of
80 .Sx \&ig ,
81 except that a leading argument must be specified.
82 It is ignored, as are its children.
83 .Ss \&de
84 The syntax of this macro is the same as that of
85 .Sx \&ig ,
86 except that a leading argument must be specified.
87 It is ignored, as are its children.
88 .Ss \&dei
89 The syntax of this macro is the same as that of
90 .Sx \&ig ,
91 except that a leading argument must be specified.
92 It is ignored, as are its children.
93 .Ss \&de1
94 The syntax of this macro is the same as that of
95 .Sx \&ig ,
96 except that a leading argument must be specified.
97 It is ignored, as are its children.
98 .Ss \&el
99 The
100 .Qq else
101 half of an if/else conditional.
102 Pops a result off the stack of conditional evaluations pushed by
103 .Sx \&ie
104 and uses it as its conditional.
105 If no stack entries are present (e.g., due to no prior
106 .Sx \&ie
107 calls)
108 then false is assumed.
109 The syntax of this macro is similar to
110 .Sx \&if
111 except that the conditional is missing.
112 .Ss \&ie
113 The
114 .Qq if
115 half of an if/else conditional.
116 The result of the conditional is pushed into a stack used by subsequent
117 invocations of
118 .Sx \&el ,
119 which may be separated by any intervening input (or not exist at all).
120 Its syntax is equivalent to
121 .Sx \&if .
122 .Ss \&if
123 Begins a conditional that always evaluates to false.
124 If a conditional is false, its children are not processed, but are
125 syntactically interpreted to preserve the integrity of the input
126 document.
127 Thus,
128 .Pp
129 .D1 \&.if t \e .ig
130 .Pp
131 will discard the
132 .Sq \&.ig ,
133 which may lead to interesting results, but
134 .Pp
135 .D1 \&.if t \e .if t \e{\e
136 .Pp
137 will continue to syntactically interpret to the block close of the final
138 conditional.
139 Sub-conditionals, in this case, obviously inherit the truth value of
140 the parent.
141 This macro has the following syntax:
142 .Pp
143 .Bd -literal -offset indent -compact
144 \&.if COND \e{\e
145 BODY...
146 \&.\e}
147 .Ed
148 .Bd -literal -offset indent -compact
149 \&.if COND \e{ BODY
150 BODY... \e}
151 .Ed
152 .Bd -literal -offset indent -compact
153 \&.if COND \e{ BODY
154 BODY...
155 \&.\e}
156 .Ed
157 .Bd -literal -offset indent -compact
158 \&.if COND \e
159 BODY
160 .Ed
161 .Pp
162 COND is a conditional (for the time being, this always evaluates to
163 false).
164 .Pp
165 If the BODY section is begun by an escaped brace
166 .Sq \e{ ,
167 scope continues until a closing-brace macro
168 .Sq \.\e} .
169 If the BODY is not enclosed in braces, scope continues until the next
170 macro or word.
171 If the COND is followed by a BODY on the same line, whether after a
172 brace or not, then macros
173 .Em must
174 begin with a control character.
175 It is generally more intuitive, in this case, to write
176 .Bd -literal -offset indent
177 \&.if COND \e{\e
178 \&.foo
179 bar
180 \&.\e}
181 .Ed
182 .Pp
183 than having the macro follow as
184 .Pp
185 .D1 \&.if COND \e{ .foo
186 .Pp
187 The scope of a conditional is always parsed, but only executed if the
188 conditional evaluates to true.
189 .Pp
190 Note that text subsequent a
191 .Sq \&.\e}
192 macro is discarded.
193 Furthermore, if an explicit closing sequence
194 .Sq \e}
195 is specified in a free-form line, the entire line is accepted within the
196 scope of the prior macro, not only the text preceding the close.
197 .Ss \&ig
198 Ignore input.
199 Accepts the following syntax:
200 .Pp
201 .Bd -literal -offset indent -compact
202 \&.ig
203 BODY...
204 \&..
205 .Ed
206 .Bd -literal -offset indent -compact
207 \&.ig END
208 BODY...
209 \&.END
210 .Ed
211 .Pp
212 In the first case, input is ignored until a
213 .Sq \&..
214 macro is encountered on its own line.
215 In the second case, input is ignored until a
216 .Sq \&.END
217 is encountered.
218 Text subsequent the
219 .Sq \&.END
220 or
221 .Sq \&..
222 is discarded.
223 .Pp
224 Do not use the escape
225 .Sq \e
226 anywhere in the definition of END.
227 It causes very strange behaviour.
228 Furthermore, if you redefine a
229 .Nm
230 macro, such as
231 .Pp
232 .D1 \&.ig if
233 .Pp
234 the subsequent invocation of
235 .Sx \&if
236 will first signify the end of comment, then be invoked as a macro.
237 This behaviour really shouldn't be counted upon.
238 .Sh COMPATIBILITY
239 This section documents compatibility between mandoc and other other
240 troff implementations, at this time limited to GNU troff
241 .Pq Qq groff .
242 The term
243 .Qq historic groff
244 refers to groff versions before the
245 .Pa doc.tmac
246 file re-write
247 .Pq somewhere between 1.15 and 1.19 .
248 .Pp
249 .Bl -dash -compact
250 .It
251 Historic groff did not accept white-space buffering the custom END tag
252 for the
253 .Sx \&ig
254 macro.
255 .It
256 The
257 .Sx \&if
258 and family would print funny white-spaces with historic groff when
259 depending on next-line syntax.
260 .El
261 .Sh AUTHORS
262 The
263 .Nm
264 reference was written by
265 .An Kristaps Dzonsons Aq kristaps@bsd.lv .