1EQN(7)               BSD Miscellaneous Information Manual               EQN(7)
2

NAME

4     eqn — eqn language reference for mandoc
5

DESCRIPTION

7     The eqn language is an equation-formatting language.  It is used within
8     mdoc(7) and man(7) UNIX manual pages.  It describes the structure of an
9     equation, not its mathematical meaning.  This manual describes the eqn
10     language accepted by the mandoc(1) utility, which corresponds to the Sec‐
11     ond Edition eqn specification (see SEE ALSO for references).
12
13     Equations within mdoc(7) or man(7) documents are enclosed by the stand‐
14     alone ‘.EQ’ and ‘.EN’ tags.  Equations are multi-line blocks consisting
15     of formulas and control statements.
16

EQUATION STRUCTURE

18     Each equation is bracketed by ‘.EQ’ and ‘.EN’ strings.  Note: these are
19     not the same as roff(7) macros, and may only be invoked as ‘.EQ’.
20
21     The equation grammar is as follows, where quoted strings are case-sensi‐
22     tive literals in the input:
23
24           eqn     : box | eqn box
25           box     : text
26                   | "{" eqn "}"
27                   | "define" text text
28                   | "ndefine" text text
29                   | "tdefine" text text
30                   | "gfont" text
31                   | "gsize" text
32                   | "set" text text
33                   | "undef" text
34                   | "sqrt" box
35                   | box pos box
36                   | box mark
37                   | "matrix" "{" [col "{" list "}"]* "}"
38                   | pile "{" list "}"
39                   | font box
40                   | "size" text box
41                   | "left" text eqn ["right" text]
42           col     : "lcol" | "rcol" | "ccol" | "col"
43           text    : [^space\"]+ | \".*\"
44           pile    : "lpile" | "cpile" | "rpile" | "pile"
45           pos     : "over" | "sup" | "sub" | "to" | "from"
46           mark    : "dot" | "dotdot" | "hat" | "tilde" | "vec"
47                   | "dyad" | "bar" | "under"
48           font    : "roman" | "italic" | "bold" | "fat"
49           list    : eqn
50                   | list "above" eqn
51           space   : [\^~ \t]
52
53     White-space consists of the space, tab, circumflex, and tilde characters.
54     It is required to delimit tokens consisting of alphabetic characters and
55     it is ignored at other places.  Braces and quotes also delimit tokens.
56     If within a quoted string, these space characters are retained.  Quoted
57     strings are also not scanned for keywords, glyph names, and expansion of
58     definitions.  To print a literal quote character, it can be prepended
59     with a backslash or expressed with the \(dq escape sequence.
60
61     Subequations can be enclosed in braces to pass them as arguments to oper‐
62     ation keywords, overriding standard operation precedence.  Braces can be
63     nested.  To set a brace verbatim, it needs to be enclosed in quotes.
64
65     The following text terms are translated into a rendered glyph, if avail‐
66     able: alpha, beta, chi, delta, epsilon, eta, gamma, iota, kappa, lambda,
67     mu, nu, omega, omicron, phi, pi, psi, rho, sigma, tau, theta, upsilon,
68     xi, zeta, DELTA, GAMMA, LAMBDA, OMEGA, PHI, PI, PSI, SIGMA, THETA,
69     UPSILON, XI, inter (intersection), union (union), prod (product), int
70     (integral), sum (summation), grad (gradient), del (vector differential),
71     times (multiply), cdot (center-dot), nothing (zero-width space), approx
72     (approximately equals), prime (prime), half (one-half), partial (partial
73     differential), inf (infinity), >> (much greater), << (much less), <-
74     (left arrow), -> (right arrow), +- (plus-minus), != (not equal), ==
75     (equivalence), <= (less-than-equal), and >= (more-than-equal).  The char‐
76     acter escape sequences documented in mandoc_char(7) can be used, too.
77
78     The following control statements are available:
79
80     define  Replace all occurrences of a key with a value.  Its syntax is as
81             follows:
82
83                   define key cvalc
84
85             The first character of the value string, c, is used as the delim‐
86             iter for the value val.  This allows for arbitrary enclosure of
87             terms (not just quotes), such as
88
89                   define foo 'bar baz'
90                   define foo cbar bazc
91
92             It is an error to have an empty key or val.  Note that a quoted
93             key causes errors in some eqn implementations and should not be
94             considered portable.  It is not expanded for replacements.  Defi‐
95             nitions may refer to other definitions; these are evaluated
96             recursively when text replacement occurs and not when the defini‐
97             tion is created.
98
99             Definitions can create arbitrary strings, for example, the fol‐
100             lowing is a legal construction.
101
102                   define foo 'define'
103                   foo bar 'baz'
104
105             Self-referencing definitions will raise an error.  The ndefine
106             statement is a synonym for define, while tdefine is discarded.
107
108     gfont   Set the default font of subsequent output.  Its syntax is as fol‐
109             lows:
110
111                   gfont font
112
113             In mandoc, this value is discarded.
114
115     gsize   Set the default size of subsequent output.  Its syntax is as fol‐
116             lows:
117
118                   gsize [+|-]size
119
120             The size value should be an integer.  If prepended by a sign, the
121             font size is changed relative to the current size.
122
123     set     Set an equation mode.  In mandoc, both arguments are thrown away.
124             Its syntax is as follows:
125
126                   set key val
127
128             The key and val are not expanded for replacements.  This state‐
129             ment is a GNU extension.
130
131     undef   Unset a previously-defined key.  Its syntax is as follows:
132
133                   define key
134
135             Once invoked, the definition for key is discarded.  The key is
136             not expanded for replacements.  This statement is a GNU exten‐
137             sion.
138
139     Operation keywords have the following semantics:
140
141     above   See pile.
142
143     bar     Draw a line over the preceding box.
144
145     bold    Set the following box using bold font.
146
147     ccol    Like cpile, but for use in matrix.
148
149     cpile   Like pile, but with slightly increased vertical spacing.
150
151     dot     Set a single dot over the preceding box.
152
153     dotdot  Set two dots (dieresis) over the preceding box.
154
155     dyad    Set a dyad symbol (left-right arrow) over the preceding box.
156
157     fat     A synonym for bold.
158
159     font    Set the second argument using the font specified by the first
160             argument; currently not recognized by the mandoc(1) eqn parser.
161
162     from    Set the following box below the preceding box, using a slightly
163             smaller font.  Used for sums, integrals, limits, and the like.
164
165     hat     Set a hat (circumflex) over the preceding box.
166
167     italic  Set the following box using italic font.
168
169     lcol    Like lpile, but for use in matrix.
170
171     left    Set the first argument as a big left delimiter before the second
172             argument.  As an optional third argument, right can follow.  In
173             that case, the fourth argument is set as a big right delimiter
174             after the second argument.
175
176     lpile   Like cpile, but subequations are left-justified.
177
178     matrix  Followed by a list of columns enclosed in braces.  All columns
179             need to have the same number of subequations.  The columns are
180             set as a matrix.  The difference compared to multiple subsequent
181             pile operators is that in a matrix, corresponding subequations in
182             all columns line up horizontally, while each pile does vertical
183             spacing independently.
184
185     over    Set a fraction.  The preceding box is the numerator, the follow‐
186             ing box is the denominator.
187
188     pile    Followed by a list of subequations enclosed in braces, the sube‐
189             quations being separated by above keywords.  Sets the subequa‐
190             tions one above the other, each of them centered.  Typically used
191             to represent vectors in coordinate representation.
192
193     rcol    Like rpile, but for use in matrix.
194
195     right   See left; right cannot be used without left.  To set a big right
196             delimiter without a big left delimiter, the following construc‐
197             tion can be used:
198
199                   left "" box right delimiter
200
201     roman   Set the following box using the default font.
202
203     rpile   Like cpile, but subequations are right-justified.
204
205     size    Set the second argument with the font size specified by the first
206             argument; currently ignored by mandoc(1).  By prepending a plus
207             or minus sign to the first argument, the font size can be
208             selected relative to the current size.
209
210     sqrt    Set the square root of the following box.
211
212     sub     Set the following box as a subscript to the preceding box.
213
214     sup     Set the following box as a superscript to the preceding box.  As
215             a special case, if a sup clause immediately follows a sub clause
216             as in
217
218                   mainbox sub subbox sup supbox
219
220             both are set with respect to the same mainbox, that is, supbox is
221             set above subbox.
222
223     tilde   Set a tilde over the preceding box.
224
225     to      Set the following box above the preceding box, using a slightly
226             smaller font.  Used for sums and integrals and the like.  As a
227             special case, if a to clause immediately follows a from clause as
228             in
229
230                   mainbox from frombox to tobox
231
232             both are set below and above the same mainbox.
233
234     under   Underline the preceding box.
235
236     vec     Set a vector symbol (right arrow) over the preceding box.
237
238     The binary operations from, to, sub, and sup group to the right, that is,
239
240           mainbox sup supbox sub subbox
241
242     is the same as
243
244           mainbox sup {supbox sub subbox}
245
246     and different from
247
248           {mainbox sup supbox} sub subbox.
249
250     By contrast, over groups to the left.
251
252     In the following list, earlier operations bind more tightly than later
253     operations:
254
255     1.   dyad, vec, under, bar, tilde, hat, dot, dotdot
256     2.   fat, roman, italic, bold, size
257     3.   sub, sup
258     4.   sqrt
259     5.   over
260     6.   from, to
261

COMPATIBILITY

263     This section documents the compatibility of mandoc eqn and the troff eqn
264     implementation (including GNU troff).
265
266     -   The text string ‘\"’ is interpreted as a literal quote in troff.  In
267         mandoc, this is interpreted as a comment.
268     -   In troff, The circumflex and tilde white-space symbols map to fixed-
269         width spaces.  In mandoc, these characters are synonyms for the space
270         character.
271     -   The troff implementation of eqn allows for equation alignment with
272         the mark and lineup tokens.  mandoc discards these tokens.  The back
273         n, fwd n, up n, and down n commands are also ignored.
274

SEE ALSO

276     mandoc(1), man(7), mandoc_char(7), mdoc(7), roff(7)
277
278     Brian W. Kernighan and Lorinda L. Cherry, "System for Typesetting
279     Mathematics", Communications of the ACM, 18, 151–157, March, 1975.
280
281     Brian W. Kernighan and Lorinda L. Cherry, Typesetting Mathematics, User's
282     Guide, 1976.
283
284     Brian W. Kernighan and Lorinda L. Cherry, Typesetting Mathematics, User's
285     Guide (Second Edition), 1978.
286

HISTORY

288     The eqn utility, a preprocessor for troff, was originally written by
289     Brian W. Kernighan and Lorinda L. Cherry in 1975.  The GNU reimplementa‐
290     tion of eqn, part of the GNU troff package, was released in 1989 by James
291     Clark.  The eqn component of mandoc(1) was added in 2011.
292

AUTHORS

294     This eqn reference was written by Kristaps Dzonsons <kristaps@bsd.lv>.
295
296BSD                              June 20, 2019                             BSD
Impressum