Print this page
9718 update mandoc to 1.14.4
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man5/eqn.5
+++ new/usr/src/man/man5/eqn.5
1 -.\" $Id: eqn.7,v 1.36 2017/07/20 11:07:27 schwarze Exp $
1 +.\" $Id: eqn.7,v 1.37 2017/09/04 10:35:27 schwarze Exp $
2 2 .\"
3 3 .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4 4 .\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
5 5 .\"
6 6 .\" Permission to use, copy, modify, and distribute this software for any
7 7 .\" purpose with or without fee is hereby granted, provided that the above
8 8 .\" copyright notice and this permission notice appear in all copies.
9 9 .\"
10 10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 17 .\"
18 -.Dd $Mdocdate: July 20 2017 $
18 +.Dd $Mdocdate: September 4 2017 $
19 19 .Dt EQN 5
20 20 .Os
21 21 .Sh NAME
22 22 .Nm eqn
23 23 .Nd eqn language reference for mandoc
24 24 .Sh DESCRIPTION
25 25 The
26 26 .Nm eqn
27 27 language is an equation-formatting language.
28 28 It is used within
29 29 .Xr mdoc 5
30 30 and
31 31 .Xr man 5
32 32 .Ux
33 33 manual pages.
34 34 It describes the
35 35 .Em structure
36 36 of an equation, not its mathematical meaning.
37 37 This manual describes the
38 38 .Nm
39 39 language accepted by the
40 40 .Xr mandoc 1
41 41 utility, which corresponds to the Second Edition
42 42 .Nm
43 43 specification (see
44 44 .Sx SEE ALSO
45 45 for references).
46 46 .Pp
47 47 Equations within
48 48 .Xr mdoc 5
49 49 or
50 50 .Xr man 5
51 51 documents are enclosed by the standalone
52 52 .Sq \&.EQ
53 53 and
54 54 .Sq \&.EN
55 55 tags.
56 56 Equations are multi-line blocks consisting of formulas and control
57 57 statements.
58 58 .Sh EQUATION STRUCTURE
59 59 Each equation is bracketed by
60 60 .Sq \&.EQ
61 61 and
62 62 .Sq \&.EN
63 63 strings.
64 64 .Em Note :
65 65 these are not the same as
66 66 .Xr mandoc_roff 5
67 67 macros, and may only be invoked as
68 68 .Sq \&.EQ .
69 69 .Pp
70 70 The equation grammar is as follows, where quoted strings are
71 71 case-sensitive literals in the input:
72 72 .Bd -literal -offset indent
73 73 eqn : box | eqn box
74 74 box : text
75 75 | \(dq{\(dq eqn \(dq}\(dq
|
↓ open down ↓ |
47 lines elided |
↑ open up ↑ |
76 76 | \(dqdefine\(dq text text
77 77 | \(dqndefine\(dq text text
78 78 | \(dqtdefine\(dq text text
79 79 | \(dqgfont\(dq text
80 80 | \(dqgsize\(dq text
81 81 | \(dqset\(dq text text
82 82 | \(dqundef\(dq text
83 83 | \(dqsqrt\(dq box
84 84 | box pos box
85 85 | box mark
86 - | \(dqmatrix\(dq \(dq{\(dq [col \(dq{\(dq list \(dq}\(dq ]*
86 + | \(dqmatrix\(dq \(dq{\(dq [col \(dq{\(dq list \(dq}\(dq]* \(dq}\(dq
87 87 | pile \(dq{\(dq list \(dq}\(dq
88 88 | font box
89 89 | \(dqsize\(dq text box
90 90 | \(dqleft\(dq text eqn [\(dqright\(dq text]
91 91 col : \(dqlcol\(dq | \(dqrcol\(dq | \(dqccol\(dq | \(dqcol\(dq
92 92 text : [^space\e\(dq]+ | \e\(dq.*\e\(dq
93 93 pile : \(dqlpile\(dq | \(dqcpile\(dq | \(dqrpile\(dq | \(dqpile\(dq
94 94 pos : \(dqover\(dq | \(dqsup\(dq | \(dqsub\(dq | \(dqto\(dq | \(dqfrom\(dq
95 95 mark : \(dqdot\(dq | \(dqdotdot\(dq | \(dqhat\(dq | \(dqtilde\(dq | \(dqvec\(dq
96 96 | \(dqdyad\(dq | \(dqbar\(dq | \(dqunder\(dq
97 97 font : \(dqroman\(dq | \(dqitalic\(dq | \(dqbold\(dq | \(dqfat\(dq
98 98 list : eqn
99 99 | list \(dqabove\(dq eqn
100 100 space : [\e^~ \et]
101 101 .Ed
102 102 .Pp
103 103 White-space consists of the space, tab, circumflex, and tilde
104 104 characters.
105 105 It is required to delimit tokens consisting of alphabetic characters
106 106 and it is ignored at other places.
107 107 Braces and quotes also delimit tokens.
108 108 If within a quoted string, these space characters are retained.
109 109 Quoted strings are also not scanned for keywords, glyph names,
110 110 and expansion of definitions.
111 111 To print a literal quote character, it can be prepended with a
112 112 backslash or expressed with the \e(dq escape sequence.
113 113 .Pp
114 114 Subequations can be enclosed in braces to pass them as arguments
115 115 to operation keywords, overriding standard operation precedence.
116 116 Braces can be nested.
117 117 To set a brace verbatim, it needs to be enclosed in quotes.
118 118 .Pp
119 119 The following text terms are translated into a rendered glyph, if
120 120 available: alpha, beta, chi, delta, epsilon, eta, gamma, iota, kappa,
121 121 lambda, mu, nu, omega, omicron, phi, pi, psi, rho, sigma, tau, theta,
122 122 upsilon, xi, zeta, DELTA, GAMMA, LAMBDA, OMEGA, PHI, PI, PSI, SIGMA,
123 123 THETA, UPSILON, XI, inter (intersection), union (union), prod (product),
124 124 int (integral), sum (summation), grad (gradient), del (vector
125 125 differential), times (multiply), cdot (center-dot), nothing (zero-width
126 126 space), approx (approximately equals), prime (prime), half (one-half),
127 127 partial (partial differential), inf (infinity), >> (much greater), <<
128 128 (much less), <\- (left arrow), \-> (right arrow), +\- (plus-minus), !=
129 129 (not equal), == (equivalence), <= (less-than-equal), and >=
130 130 (more-than-equal).
131 131 The character escape sequences documented in
132 132 .Xr mandoc_char 5
133 133 can be used, too.
134 134 .Pp
135 135 The following control statements are available:
136 136 .Bl -tag -width Ds
137 137 .It Cm define
138 138 Replace all occurrences of a key with a value.
139 139 Its syntax is as follows:
140 140 .Pp
141 141 .D1 Cm define Ar key cvalc
142 142 .Pp
143 143 The first character of the value string,
144 144 .Ar c ,
145 145 is used as the delimiter for the value
146 146 .Ar val .
147 147 This allows for arbitrary enclosure of terms (not just quotes), such as
148 148 .Pp
149 149 .D1 Cm define Ar foo \(aqbar baz\(aq
150 150 .D1 Cm define Ar foo cbar bazc
151 151 .Pp
152 152 It is an error to have an empty
153 153 .Ar key
154 154 or
155 155 .Ar val .
156 156 Note that a quoted
157 157 .Ar key
158 158 causes errors in some
159 159 .Nm
160 160 implementations and should not be considered portable.
161 161 It is not expanded for replacements.
162 162 Definitions may refer to other definitions; these are evaluated
163 163 recursively when text replacement occurs and not when the definition is
164 164 created.
165 165 .Pp
166 166 Definitions can create arbitrary strings, for example, the following is
167 167 a legal construction.
168 168 .Bd -literal -offset indent
169 169 define foo \(aqdefine\(aq
170 170 foo bar \(aqbaz\(aq
171 171 .Ed
172 172 .Pp
173 173 Self-referencing definitions will raise an error.
174 174 The
175 175 .Cm ndefine
176 176 statement is a synonym for
177 177 .Cm define ,
178 178 while
179 179 .Cm tdefine
180 180 is discarded.
181 181 .It Cm gfont
182 182 Set the default font of subsequent output.
183 183 Its syntax is as follows:
184 184 .Pp
185 185 .D1 Cm gfont Ar font
186 186 .Pp
187 187 In mandoc, this value is discarded.
188 188 .It Cm gsize
189 189 Set the default size of subsequent output.
190 190 Its syntax is as follows:
191 191 .Pp
192 192 .D1 Cm gsize Oo +|\- Oc Ns Ar size
193 193 .Pp
194 194 The
195 195 .Ar size
196 196 value should be an integer.
197 197 If prepended by a sign,
198 198 the font size is changed relative to the current size.
199 199 .It Cm set
200 200 Set an equation mode.
201 201 In mandoc, both arguments are thrown away.
202 202 Its syntax is as follows:
203 203 .Pp
204 204 .D1 Cm set Ar key val
205 205 .Pp
206 206 The
207 207 .Ar key
208 208 and
209 209 .Ar val
210 210 are not expanded for replacements.
211 211 This statement is a GNU extension.
212 212 .It Cm undef
213 213 Unset a previously-defined key.
214 214 Its syntax is as follows:
215 215 .Pp
216 216 .D1 Cm define Ar key
217 217 .Pp
218 218 Once invoked, the definition for
219 219 .Ar key
220 220 is discarded.
221 221 The
222 222 .Ar key
223 223 is not expanded for replacements.
224 224 This statement is a GNU extension.
225 225 .El
226 226 .Pp
227 227 Operation keywords have the following semantics:
228 228 .Bl -tag -width Ds
229 229 .It Cm above
230 230 See
231 231 .Cm pile .
232 232 .It Cm bar
233 233 Draw a line over the preceding box.
234 234 .It Cm bold
235 235 Set the following box using bold font.
236 236 .It Cm ccol
237 237 Like
238 238 .Cm cpile ,
239 239 but for use in
240 240 .Cm matrix .
241 241 .It Cm cpile
242 242 Like
243 243 .Cm pile ,
244 244 but with slightly increased vertical spacing.
245 245 .It Cm dot
246 246 Set a single dot over the preceding box.
247 247 .It Cm dotdot
248 248 Set two dots (dieresis) over the preceding box.
249 249 .It Cm dyad
250 250 Set a dyad symbol (left-right arrow) over the preceding box.
251 251 .It Cm fat
252 252 A synonym for
253 253 .Cm bold .
254 254 .It Cm font
255 255 Set the second argument using the font specified by the first argument;
256 256 currently not recognized by the
257 257 .Xr mandoc 1
258 258 .Nm
259 259 parser.
260 260 .It Cm from
261 261 Set the following box below the preceding box,
262 262 using a slightly smaller font.
263 263 Used for sums, integrals, limits, and the like.
264 264 .It Cm hat
265 265 Set a hat (circumflex) over the preceding box.
266 266 .It Cm italic
267 267 Set the following box using italic font.
268 268 .It Cm lcol
269 269 Like
270 270 .Cm lpile ,
271 271 but for use in
272 272 .Cm matrix .
273 273 .It Cm left
274 274 Set the first argument as a big left delimiter before the second argument.
275 275 As an optional third argument,
276 276 .Cm right
277 277 can follow.
278 278 In that case, the fourth argument is set as a big right delimiter after
279 279 the second argument.
280 280 .It Cm lpile
281 281 Like
282 282 .Cm cpile ,
283 283 but subequations are left-justified.
284 284 .It Cm matrix
285 285 Followed by a list of columns enclosed in braces.
286 286 All columns need to have the same number of subequations.
287 287 The columns are set as a matrix.
288 288 The difference compared to multiple subsequent
289 289 .Cm pile
290 290 operators is that in a
291 291 .Cm matrix ,
292 292 corresponding subequations in all columns line up horizontally,
293 293 while each
294 294 .Cm pile
295 295 does vertical spacing independently.
296 296 .It Cm over
297 297 Set a fraction.
298 298 The preceding box is the numerator, the following box is the denominator.
299 299 .It Cm pile
300 300 Followed by a list of subequations enclosed in braces,
301 301 the subequations being separated by
302 302 .Cm above
303 303 keywords.
304 304 Sets the subequations one above the other, each of them centered.
305 305 Typically used to represent vectors in coordinate representation.
306 306 .It Cm rcol
307 307 Like
308 308 .Cm rpile ,
309 309 but for use in
310 310 .Cm matrix .
311 311 .It Cm right
312 312 See
313 313 .Cm left ;
314 314 .Cm right
315 315 cannot be used without
316 316 .Cm left .
317 317 To set a big right delimiter without a big left delimiter, the following
318 318 construction can be used:
319 319 .Pp
320 320 .D1 Cm left No \(dq\(dq Ar box Cm right Ar delimiter
321 321 .It Cm roman
322 322 Set the following box using the default font.
323 323 .It Cm rpile
324 324 Like
325 325 .Cm cpile ,
326 326 but subequations are right-justified.
327 327 .It Cm size
328 328 Set the second argument with the font size specified by the first
329 329 argument; currently ignored by
330 330 .Xr mandoc 1 .
331 331 By prepending a plus or minus sign to the first argument,
332 332 the font size can be selected relative to the current size.
333 333 .It Cm sqrt
334 334 Set the square root of the following box.
335 335 .It Cm sub
336 336 Set the following box as a subscript to the preceding box.
337 337 .It Cm sup
338 338 Set the following box as a superscript to the preceding box.
339 339 As a special case, if a
340 340 .Cm sup
341 341 clause immediately follows a
342 342 .Cm sub
343 343 clause as in
344 344 .Pp
345 345 .D1 Ar mainbox Cm sub Ar subbox Cm sup Ar supbox
346 346 .Pp
347 347 both are set with respect to the same
348 348 .Ar mainbox ,
349 349 that is,
350 350 .Ar supbox
351 351 is set above
352 352 .Ar subbox .
353 353 .It Cm tilde
354 354 Set a tilde over the preceding box.
355 355 .It Cm to
356 356 Set the following box above the preceding box,
357 357 using a slightly smaller font.
358 358 Used for sums and integrals and the like.
359 359 As a special case, if a
360 360 .Cm to
361 361 clause immediately follows a
362 362 .Cm from
363 363 clause as in
364 364 .Pp
365 365 .D1 Ar mainbox Cm from Ar frombox Cm to Ar tobox
366 366 .Pp
367 367 both are set below and above the same
368 368 .Ar mainbox .
369 369 .It Cm under
370 370 Underline the preceding box.
371 371 .It Cm vec
372 372 Set a vector symbol (right arrow) over the preceding box.
373 373 .El
374 374 .Pp
375 375 The binary operations
376 376 .Cm from ,
377 377 .Cm to ,
378 378 .Cm sub ,
379 379 and
380 380 .Cm sup
381 381 group to the right, that is,
382 382 .Pp
383 383 .D1 Ar mainbox Cm sup Ar supbox Cm sub Ar subbox
384 384 .Pp
385 385 is the same as
386 386 .Pp
387 387 .D1 Ar mainbox Cm sup Brq Ar supbox Cm sub Ar subbox
388 388 .Pp
389 389 and different from
390 390 .Pp
391 391 .D1 Bro Ar mainbox Cm sup Ar supbox Brc Cm sub Ar subbox .
392 392 .Pp
393 393 By contrast,
394 394 .Cm over
395 395 groups to the left.
396 396 .Pp
397 397 In the following list, earlier operations bind more tightly than
398 398 later operations:
399 399 .Pp
400 400 .Bl -enum -compact
401 401 .It
402 402 .Cm dyad ,
403 403 .Cm vec ,
404 404 .Cm under ,
405 405 .Cm bar ,
406 406 .Cm tilde ,
407 407 .Cm hat ,
408 408 .Cm dot ,
409 409 .Cm dotdot
410 410 .It
411 411 .Cm fat ,
412 412 .Cm roman ,
413 413 .Cm italic ,
414 414 .Cm bold ,
415 415 .Cm size
416 416 .It
417 417 .Cm sub ,
418 418 .Cm sup
419 419 .It
420 420 .Cm sqrt
421 421 .It
422 422 .Cm over
423 423 .It
424 424 .Cm from ,
425 425 .Cm to
426 426 .El
427 427 .Sh COMPATIBILITY
428 428 This section documents the compatibility of mandoc
429 429 .Nm
430 430 and the troff
431 431 .Nm
432 432 implementation (including GNU troff).
433 433 .Pp
434 434 .Bl -dash -compact
435 435 .It
436 436 The text string
437 437 .Sq \e\(dq
438 438 is interpreted as a literal quote in troff.
439 439 In mandoc, this is interpreted as a comment.
440 440 .It
441 441 In troff, The circumflex and tilde white-space symbols map to
442 442 fixed-width spaces.
443 443 In mandoc, these characters are synonyms for the space character.
444 444 .It
445 445 The troff implementation of
446 446 .Nm
447 447 allows for equation alignment with the
448 448 .Cm mark
449 449 and
450 450 .Cm lineup
451 451 tokens.
452 452 mandoc discards these tokens.
453 453 The
454 454 .Cm back Ar n ,
455 455 .Cm fwd Ar n ,
456 456 .Cm up Ar n ,
457 457 and
458 458 .Cm down Ar n
459 459 commands are also ignored.
460 460 .El
461 461 .Sh SEE ALSO
462 462 .Xr mandoc 1 ,
463 463 .Xr man 5 ,
464 464 .Xr mandoc_char 5 ,
465 465 .Xr mandoc_roff 5 ,
466 466 .Xr mdoc 5
467 467 .Rs
468 468 .%A Brian W. Kernighan
469 469 .%A Lorinda L. Cherry
470 470 .%T System for Typesetting Mathematics
471 471 .%J Communications of the ACM
472 472 .%V 18
473 473 .%P 151\(en157
474 474 .%D March, 1975
475 475 .Re
476 476 .Rs
477 477 .%A Brian W. Kernighan
478 478 .%A Lorinda L. Cherry
479 479 .%T Typesetting Mathematics, User's Guide
480 480 .%D 1976
481 481 .Re
482 482 .Rs
483 483 .%A Brian W. Kernighan
484 484 .%A Lorinda L. Cherry
485 485 .%T Typesetting Mathematics, User's Guide (Second Edition)
486 486 .%D 1978
487 487 .Re
488 488 .Sh HISTORY
489 489 The eqn utility, a preprocessor for troff, was originally written by
490 490 Brian W. Kernighan and Lorinda L. Cherry in 1975.
491 491 The GNU reimplementation of eqn, part of the GNU troff package, was
492 492 released in 1989 by James Clark.
493 493 The eqn component of
494 494 .Xr mandoc 1
495 495 was added in 2011.
496 496 .Sh AUTHORS
497 497 This
498 498 .Nm
499 499 reference was written by
500 500 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
|
↓ open down ↓ |
404 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX