| blob | 40b8bee6d705c989e7971be1dbfd17eaf06d5fe9 |
1 .\" Id: eqn.7,v 1.29 2013/07/13 19:41:16 schwarze Exp
2 .\"
3 .\" Copyright (c) 2011 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 July 13, 2013
18 .Dt EQN 7
19 .Os
20 .Sh NAME
21 .Nm eqn
22 .Nd eqn language reference for mandoc
23 .Sh DESCRIPTION
24 The
25 .Nm eqn
26 language is an equation-formatting language.
27 It is used within
28 .Xr mdoc 7
29 and
30 .Xr man 7
31 .Ux
32 manual pages.
33 It describes the
34 .Em structure
35 of an equation, not its mathematical meaning.
36 This manual describes the
37 .Nm
38 language accepted by the
39 .Xr mandoc 1
40 utility, which corresponds to the Second Edition eqn specification (see
41 .Sx SEE ALSO
42 for references).
43 .Pp
44 Equations within
45 .Xr mdoc 7
46 or
47 .Xr man 7
48 documents are enclosed by the standalone
49 .Sq \&.EQ
50 and
51 .Sq \&.EN
52 tags.
53 Equations are multi-line blocks consisting of formulas and control
54 statements.
55 .Sh EQUATION STRUCTURE
56 Each equation is bracketed by
57 .Sq \&.EQ
58 and
59 .Sq \&.EN
60 strings.
61 .Em Note :
62 these are not the same as
63 .Xr roff 7
64 macros, and may only be invoked as
65 .Sq \&.EQ .
66 .Pp
67 The equation grammar is as follows, where quoted strings are
68 case-sensitive literals in the input:
69 .Bd -literal -offset indent
70 eqn : box | eqn box
71 box : text
72 | \*q{\*q eqn \*q}\*q
73 | \*qdefine\*q text text
74 | \*qndefine\*q text text
75 | \*qtdefine\*q text text
76 | \*qgfont\*q text
77 | \*qgsize\*q text
78 | \*qset\*q text text
79 | \*qundef\*q text
80 | box pos box
81 | box mark
82 | \*qmatrix\*q \*q{\*q [col \*q{\*q list \*q}\*q ]*
83 | pile \*q{\*q list \*q}\*q
84 | font box
85 | \*qsize\*q text box
86 | \*qleft\*q text eqn [\*qright\*q text]
87 col : \*qlcol\*q | \*qrcol\*q | \*qccol\*q | \*qcol\*q
88 text : [^space\e\*q]+ | \e\*q.*\e\*q
89 pile : \*qlpile\*q | \*qcpile\*q | \*qrpile\*q | \*qpile\*q
90 pos : \*qover\*q | \*qsup\*q | \*qsub\*q | \*qto\*q | \*qfrom\*q
91 mark : \*qdot\*q | \*qdotdot\*q | \*qhat\*q | \*qtilde\*q | \*qvec\*q
92 | \*qdyad\*q | \*qbar\*q | \*qunder\*q
93 font : \*qroman\*q | \*qitalic\*q | \*qbold\*q | \*qfat\*q
94 list : eqn
95 | list \*qabove\*q eqn
96 space : [\e^~ \et]
97 .Ed
98 .Pp
99 White-space consists of the space, tab, circumflex, and tilde
100 characters.
101 If within a quoted string, these space characters are retained.
102 Quoted strings are also not scanned for replacement definitions.
103 .Pp
104 The following text terms are translated into a rendered glyph, if
105 available: alpha, beta, chi, delta, epsilon, eta, gamma, iota, kappa,
106 lambda, mu, nu, omega, omicron, phi, pi, psi, rho, sigma, tau, theta,
107 upsilon, xi, zeta, DELTA, GAMMA, LAMBDA, OMEGA, PHI, PI, PSI, SIGMA,
108 THETA, UPSILON, XI, inter (intersection), union (union), prod (product),
109 int (integral), sum (summation), grad (gradient), del (vector
110 differential), times (multiply), cdot (centre-dot), nothing (zero-width
111 space), approx (approximately equals), prime (prime), half (one-half),
112 partial (partial differential), inf (infinity), >> (much greater), <<
113 (much less), \-> (left arrow), <\- (right arrow), += (plus-minus), !=
114 (not equal), == (equivalence), <= (less-than-equal), and >=
115 (more-than-equal).
116 .Pp
117 The following control statements are available:
118 .Bl -tag -width Ds
119 .It Cm define
120 Replace all occurrences of a key with a value.
121 Its syntax is as follows:
122 .Pp
123 .D1 define Ar key cvalc
124 .Pp
125 The first character of the value string,
126 .Ar c ,
127 is used as the delimiter for the value
128 .Ar val .
129 This allows for arbitrary enclosure of terms (not just quotes), such as
130 .Pp
131 .D1 define Ar foo 'bar baz'
132 .D1 define Ar foo cbar bazc
133 .Pp
134 It is an error to have an empty
135 .Ar key
136 or
137 .Ar val .
138 Note that a quoted
139 .Ar key
140 causes errors in some
141 .Nm
142 implementations and should not be considered portable.
143 It is not expanded for replacements.
144 Definitions may refer to other definitions; these are evaluated
145 recursively when text replacement occurs and not when the definition is
146 created.
147 .Pp
148 Definitions can create arbitrary strings, for example, the following is
149 a legal construction.
150 .Bd -literal -offset indent
151 define foo 'define'
152 foo bar 'baz'
153 .Ed
154 .Pp
155 Self-referencing definitions will raise an error.
156 The
157 .Cm ndefine
158 statement is a synonym for
159 .Cm define ,
160 while
161 .Cm tdefine
162 is discarded.
163 .It Cm gfont
164 Set the default font of subsequent output.
165 Its syntax is as follows:
166 .Pp
167 .D1 gfont Ar font
168 .Pp
169 In mandoc, this value is discarded.
170 .It Cm gsize
171 Set the default size of subsequent output.
172 Its syntax is as follows:
173 .Pp
174 .D1 gsize Ar size
175 .Pp
176 The
177 .Ar size
178 value should be an integer.
179 .It Cm set
180 Set an equation mode.
181 In mandoc, both arguments are thrown away.
182 Its syntax is as follows:
183 .Pp
184 .D1 set Ar key val
185 .Pp
186 The
187 .Ar key
188 and
189 .Ar val
190 are not expanded for replacements.
191 This statement is a GNU extension.
192 .It Cm undef
193 Unset a previously-defined key.
194 Its syntax is as follows:
195 .Pp
196 .D1 define Ar key
197 .Pp
198 Once invoked, the definition for
199 .Ar key
200 is discarded.
201 The
202 .Ar key
203 is not expanded for replacements.
204 This statement is a GNU extension.
205 .El
206 .Sh COMPATIBILITY
207 This section documents the compatibility of mandoc
208 .Nm
209 and the troff
210 .Nm
211 implementation (including GNU troff).
212 .Pp
213 .Bl -dash -compact
214 .It
215 The text string
216 .Sq \e\*q
217 is interpreted as a literal quote in troff.
218 In mandoc, this is interpreted as a comment.
219 .It
220 In troff, The circumflex and tilde white-space symbols map to
221 fixed-width spaces.
222 In mandoc, these characters are synonyms for the space character.
223 .It
224 The troff implementation of
225 .Nm
226 allows for equation alignment with the
227 .Cm mark
228 and
229 .Cm lineup
230 tokens.
231 mandoc discards these tokens.
232 The
233 .Cm back Ar n ,
234 .Cm fwd Ar n ,
235 .Cm up Ar n ,
236 and
237 .Cm down Ar n
238 commands are also ignored.
239 .El
240 .Sh SEE ALSO
241 .Xr mandoc 1 ,
242 .Xr man 7 ,
243 .Xr mandoc_char 7 ,
244 .Xr mdoc 7 ,
245 .Xr roff 7
246 .Rs
247 .%A Brian W. Kernighan
248 .%A Lorinda L. Cherry
249 .%T System for Typesetting Mathematics
250 .%J Communications of the ACM
251 .%V 18
252 .%P 151\(en157
253 .%D March, 1975
254 .Re
255 .Rs
256 .%A Brian W. Kernighan
257 .%A Lorinda L. Cherry
258 .%T Typesetting Mathematics, User's Guide
259 .%D 1976
260 .Re
261 .Rs
262 .%A Brian W. Kernighan
263 .%A Lorinda L. Cherry
264 .%T Typesetting Mathematics, User's Guide (Second Edition)
265 .%D 1978
266 .Re
267 .Sh HISTORY
268 The eqn utility, a preprocessor for troff, was originally written by
269 Brian W. Kernighan and Lorinda L. Cherry in 1975.
270 The GNU reimplementation of eqn, part of the GNU troff package, was
271 released in 1989 by James Clark.
272 The eqn component of
273 .Xr mandoc 1
274 was added in 2011.
275 .Sh AUTHORS
276 This
277 .Nm
278 reference was written by
279 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .