1EQN(1)                      General Commands Manual                     EQN(1)
2
3
4

NAME

6       eqn - format equations for troff or MathML
7

SYNOPSIS

9       eqn [-rvCNR] [-d xy] [-T name] [-M dir] [-f F] [-s n] [-p n] [-m n]
10           [file ...]
11

DESCRIPTION

13       This manual page describes the GNU version of eqn, which is part of the
14       groff  document  formatting system.  eqn compiles descriptions of equa‐
15       tions embedded within troff input files into commands that  are  under‐
16       stood  by troff.  Normally, it should be invoked using the -e option of
17       groff.  The syntax is quite compatible with Unix eqn.   The  output  of
18       GNU  eqn cannot be processed with Unix troff; it must be processed with
19       GNU troff.  If no files are given on the command line, the standard in‐
20       put is read.  A filename of - causes the standard input to be read.
21
22       eqn  searches  for  the file eqnrc in the directories given with the -M
23       option first, then in /etc/groff/site-tmac,  /etc/groff/site-tmac,  and
24       finally  in  the standard macro directory /usr/share/groff/1.22.4/tmac.
25       If it exists, eqn processes it before the other input  files.   The  -R
26       option prevents this.
27
28       GNU eqn does not provide the functionality of neqn: it does not support
29       low-resolution, typewriter-like devices  (although  it  may  work  ade‐
30       quately for very simple input).
31

OPTIONS

33       Whitespace is permitted between a command-line option and its argument.
34
35       -dxy   Specify  delimiters  x and y for the left and right end, respec‐
36              tively, of in-line  equations.   Any  delim  statements  in  the
37              source file overrides this.
38
39       -C     Recognize  .EQ  and  .EN even when followed by a character other
40              than space or newline.  Also, the statement ‘delim  on’  is  not
41              handled specially.
42
43       -N     Don't  allow newlines within delimiters.  This option allows eqn
44              to recover better from missing closing delimiters.
45
46       -v     Print the version number.
47
48       -r     Only one size reduction.
49
50       -mn    The minimum point-size is n.  eqn does not reduce  the  size  of
51              subscripts or superscripts to a smaller size than n.
52
53       -Tname The  output  is  for  device name.  Normally, the only effect of
54              this is to define a macro name with a value  of  1;  eqnrc  uses
55              this  to  provide definitions appropriate for the output device.
56              However, if the specified device  is  “MathML”,  the  output  is
57              MathML  markup  rather  than  troff  commands,  and eqnrc is not
58              loaded at all.  The default output device is ps.
59
60       -Mdir  Search dir for eqnrc before the default directories.
61
62       -R     Don't load eqnrc.
63
64       -fF    This is equivalent to a gfont F command.
65
66       -sn    This is equivalent to a gsize n command.  This option is  depre‐
67              cated.   eqn  normally  sets  equations  at whatever the current
68              point size is when the equation is encountered.
69
70       -pn    This says that subscripts and superscripts should  be  n  points
71              smaller  than  the surrounding text.  This option is deprecated.
72              Normally eqn sets subscripts and superscripts at 70% of the size
73              of the surrounding text.
74

USAGE

76       Only the differences between GNU eqn and Unix eqn are described here.
77
78       GNU  eqn  emits  Presentation  MathML  output  when  invoked  with  the
79       -T MathML option.
80
81       GNU eqn sets the input token "..."   as  three  periods  or  low  dots,
82       rather  than the three centered dots of classic eqn.  To get three cen‐
83       tered dots, write cdots or cdot cdot cdot.
84
85       Most of the new features of the GNU eqn input  language  are  based  on
86       TeX.   There are some references to the differences between TeX and GNU
87       eqn below; these may safely be ignored if you do not know TeX.
88
89   Controlling delimiters
90       If not in compatibility mode, eqn recognizes
91
92              delim on
93
94       to restore the delimiters which have been previously  disabled  with  a
95       call  to  ‘delim  off’.  If delimiters haven't been specified, the call
96       has no effect.
97
98   Automatic spacing
99       eqn gives each component of an equation a type, and adjusts the spacing
100       between  components  using  that type.  Possible types are described in
101       the table below.
102
103       ordinary      an ordinary character such as ‘1’ or ‘x
104       operator      a large operator such as ‘Σ’
105       binary        a binary operator such as ‘+’
106       relation      a relation such as ‘=’
107       opening       a opening bracket such as ‘(’
108       closing       a closing bracket such as ‘)’
109       punctuation   a punctuation character such as ‘,’
110       inner         a subformula contained within brackets
111       suppress      a type that suppresses automatic spacing adjustment
112
113       Components of an equation get a type in one of two ways.
114
115       type t e
116              This yields an equation component that contains e but  that  has
117              type  t, where t is one of the types mentioned above.  For exam‐
118              ple, times is defined as
119
120                     type "binary" \(mu
121
122              The name of the type doesn't have to be quoted, but quoting pro‐
123              tects from macro expansion.
124
125       chartype t text
126              Unquoted groups of characters are split up into individual char‐
127              acters, and the type  of  each  character  is  looked  up;  this
128              changes the type that is stored for each character; it says that
129              the characters in text from now on have type t.  For example,
130
131                     chartype "punctuation" .,;:
132
133              would make the characters ‘.,;:’ have type punctuation  whenever
134              they  subsequently appeared in an equation.  The type t can also
135              be letter or digit; in these cases  chartype  changes  the  font
136              type of the characters.  See subsection “Fonts” below.
137
138   New primitives
139       big e  Enlarges  the expression it modifies; intended to have semantics
140              like CSS ‘large’.  In troff output, the point size is  increased
141              by 5; in MathML output, the expression uses
142
143                     <mstyle mathsize='big'>
144
145       e1 smallover e2
146              This  is  similar  to over; smallover reduces the size of e1 and
147              e2; it also puts less vertical space between e1 or  e2  and  the
148              fraction  bar.   The over primitive corresponds to the TeX \over
149              primitive in display styles; smallover corresponds to  \over  in
150              non-display styles.
151
152       vcenter e
153              This vertically centers e about the math axis.  The math axis is
154              the vertical position about which characters such as ‘+’ and ‘−’
155              are  centered; also it is the vertical position used for the bar
156              of fractions.  For example, sum is defined as
157
158                     { type "operator" vcenter size +5 \(*S }
159
160              (Note that vcenter is silently ignored when generating MathML.)
161
162       e1 accent e2
163              This sets e2 as an accent over e1.  e2 is assumed to be  at  the
164              correct  height for a lowercase letter; e2 is moved down accord‐
165              ing to whether e1 is taller or shorter than a lowercase  letter.
166              For example, hat is defined as
167
168                     accent { "^" }
169
170              dotdot, dot, tilde, vec, and dyad are also defined using the ac‐
171              cent primitive.
172
173       e1 uaccent e2
174              This sets e2 as an accent under e1.  e2 is assumed to be at  the
175              correct  height for a character without a descender; e2 is moved
176              down if e1 has a descender.  utilde is pre-defined using uaccent
177              as a tilde accent below the baseline.
178
179       split "text"
180              This has the same effect as simply
181
182                     text
183
184              but text is not subject to macro expansion because it is quoted;
185              text is split up and the spacing between  individual  characters
186              is adjusted.
187
188       nosplit text
189              This has the same effect as
190
191                     "text"
192
193              but because text is not quoted it is subject to macro expansion;
194              text is not split up and the spacing between individual  charac‐
195              ters is not adjusted.
196
197       e opprime
198              This  is  a  variant of prime that acts as an operator on e.  It
199              produces a different result from prime in a case such  as  A op‐
200              prime sub 1:  with  opprime the 1 is tucked under the prime as a
201              subscript to the A (as is conventional in mathematical  typeset‐
202              ting),  whereas  with  prime  the  1 is a subscript to the prime
203              character.  The precedence of opprime is the same as that of bar
204              and under, which is higher than that of everything except accent
205              and uaccent.  In unquoted text a ' that is not the first charac‐
206              ter is treated like opprime.
207
208       special text e
209              This constructs a new object from e using a troff(1) macro named
210              text.  When the macro is called, the string 0s contains the out‐
211              put  for  e,  and  the  number registers 0w, 0h, 0d, 0skern, and
212              0skew contain the width, height, depth, subscript kern, and skew
213              of  e.   (The  subscript  kern of an object says how much a sub‐
214              script on that object should be tucked in; the skew of an object
215              says  how far to the right of the center of the object an accent
216              over the object should be placed.)  The macro must modify 0s  so
217              that  it  outputs the desired result with its origin at the cur‐
218              rent point, and increase the current horizontal position by  the
219              width of the object.  The number registers must also be modified
220              so that they correspond to the result.
221
222              For example, suppose you wanted a construct  that  ‘cancels’  an
223              expression by drawing a diagonal line through it.
224
225                     .EQ
226                     define cancel 'special Ca'
227                     .EN
228                     .de Ca
229                     .  ds 0s \
230                     \Z'\\*(0s'\
231                     \v'\\n(0du'\
232                     \D'l \\n(0wu -\\n(0hu-\\n(0du'\
233                     \v'\\n(0hu'
234                     ..
235
236              Then you could cancel an expression e with cancel { e }
237
238              Here's  a  more  complicated construct that draws a box round an
239              expression:
240
241                     .EQ
242                     define box 'special Bx'
243                     .EN
244                     .de Bx
245                     .  ds 0s \
246                     \Z'\h'1n'\\*(0s'\
247                     \Z'\
248                     \v'\\n(0du+1n'\
249                     \D'l \\n(0wu+2n 0'\
250                     \D'l 0 -\\n(0hu-\\n(0du-2n'\
251                     \D'l -\\n(0wu-2n 0'\
252                     \D'l 0 \\n(0hu+\\n(0du+2n'\
253                     '\
254                     \h'\\n(0wu+2n'
255                     .  nr 0w +2n
256                     .  nr 0d +1n
257                     .  nr 0h +1n
258                     ..
259
260       space n
261              A positive value of the integer n (in hundredths of an em)  sets
262              the  vertical spacing before the equation, a negative value sets
263              the spacing after the equation, replacing  the  default  values.
264              This  primitive  provides an interface to groff's \x escape (but
265              with opposite sign).
266
267              This keyword has no effect if the equation is part of a pic pic‐
268              ture.
269
270   Extended primitives
271       col n { ... }
272       ccol n { ... }
273       lcol n { ... }
274       rcol n { ... }
275       pile n { ... }
276       cpile n { ... }
277       lpile n { ... }
278       rpile n { ... }
279              The  integer value n (in hundredths of an em) increases the ver‐
280              tical spacing between rows, using groff's \x escape  (the  value
281              has no effect in MathML mode).  Negative values are possible but
282              have no effect.  If there is more than a single value given in a
283              matrix, the biggest one is used.
284
285   Customization
286       When  eqn  is  generating  troff markup, the appearance of equations is
287       controlled by a large number of parameters.  They have no  effect  when
288       generating MathML mode, which pushes typesetting and fine motions down‐
289       stream to a MathML rendering engine.  These parameters can be set using
290       the set command.
291
292       set p n
293              This sets parameter p to value n; n is an integer.  For example,
294
295                     set x_height 45
296
297              says that eqn should assume an x height of 0.45 ems.
298
299              Possible parameters are as follows.  Values are in units of hun‐
300              dredths of an em unless otherwise  stated.   These  descriptions
301              are intended to be expository rather than definitive.
302
303              minimum_size
304                     eqn  doesn't  set  anything  at a smaller point-size than
305                     this.  The value is in points.
306
307              fat_offset
308                     The fat primitive emboldens an equation  by  overprinting
309                     two  copies  of  the equation horizontally offset by this
310                     amount.  This parameter is not used in MathML  mode;  in‐
311                     stead, fat text uses
312
313                            <mstyle mathvariant='double-struck'>
314
315              over_hang
316                     A  fraction  bar  is longer by twice this amount than the
317                     maximum of the widths of the numerator  and  denominator;
318                     in  other words, it overhangs the numerator and denomina‐
319                     tor by at least this amount.
320
321              accent_width
322                     When bar or under is applied to a single  character,  the
323                     line  is  this  long.   Normally, bar or under produces a
324                     line whose length is the width of the object to which  it
325                     applies; in the case of a single character, this tends to
326                     produce a line that looks too long.
327
328              delimiter_factor
329                     Extensible delimiters produced with the  left  and  right
330                     primitives  have  a combined height and depth of at least
331                     this many thousandths of  twice  the  maximum  amount  by
332                     which  the  sub-equation  that the delimiters enclose ex‐
333                     tends away from the axis.
334
335              delimiter_shortfall
336                     Extensible delimiters produced with the  left  and  right
337                     primitives have a combined height and depth not less than
338                     the difference of twice the maximum amount by  which  the
339                     sub-equation  that  the  delimiters  enclose extends away
340                     from the axis and this amount.
341
342              null_delimiter_space
343                     This much horizontal space is inserted on each side of  a
344                     fraction.
345
346              script_space
347                     The  width of subscripts and superscripts is increased by
348                     this amount.
349
350              thin_space
351                     This amount of  space  is  automatically  inserted  after
352                     punctuation characters.
353
354              medium_space
355                     This  amount of space is automatically inserted on either
356                     side of binary operators.
357
358              thick_space
359                     This amount of space is automatically inserted on  either
360                     side of relations.
361
362              x_height
363                     The height of lowercase letters without ascenders such as
364                     ‘x’.
365
366              axis_height
367                     The height above the baseline of the center of characters
368                     such  as ‘+’ and ‘−’.  It is important that this value is
369                     correct for the font you are using.
370
371              default_rule_thickness
372                     This should set to the thickness of the  \(ru  character,
373                     or the thickness of horizontal lines produced with the \D
374                     escape sequence.
375
376              num1   The over command shifts up the numerator by at least this
377                     amount.
378
379              num2   The smallover command shifts up the numerator by at least
380                     this amount.
381
382              denom1 The over command shifts down the denominator by at  least
383                     this amount.
384
385              denom2 The  smallover  command shifts down the denominator by at
386                     least this amount.
387
388              sup1   Normally superscripts are shifted up  by  at  least  this
389                     amount.
390
391              sup2   Superscripts  within  superscripts or upper limits or nu‐
392                     merators of smallover fractions  are  shifted  up  by  at
393                     least this amount.  This is usually less than sup1.
394
395              sup3   Superscripts  within denominators or square roots or sub‐
396                     scripts or lower limits are shifted up by at  least  this
397                     amount.  This is usually less than sup2.
398
399              sub1   Subscripts  are  normally  shifted  down by at least this
400                     amount.
401
402              sub2   When there is both a subscript  and  a  superscript,  the
403                     subscript is shifted down by at least this amount.
404
405              sup_drop
406                     The  baseline  of a superscript is no more than this much
407                     amount below the top of the object on  which  the  super‐
408                     script is set.
409
410              sub_drop
411                     The  baseline  of a subscript is at least this much below
412                     the bottom of the object on which the subscript is set.
413
414              big_op_spacing1
415                     The baseline of an upper limit  is  at  least  this  much
416                     above the top of the object on which the limit is set.
417
418              big_op_spacing2
419                     The baseline of a lower limit is at least this much below
420                     the bottom of the object on which the limit is set.
421
422              big_op_spacing3
423                     The bottom of an upper limit is at least this much  above
424                     the top of the object on which the limit is set.
425
426              big_op_spacing4
427                     The  top of a lower limit is at least this much below the
428                     bottom of the object on which the limit is set.
429
430              big_op_spacing5
431                     This much vertical space is added above and below limits.
432
433              baseline_sep
434                     The baselines of the rows in a pile or  matrix  are  nor‐
435                     mally this far apart.  In most cases this should be equal
436                     to the sum of num1 and denom1.
437
438              shift_down
439                     The midpoint between the  top  baseline  and  the  bottom
440                     baseline in a matrix or pile is shifted down by this much
441                     from the axis.  In most cases this  should  be  equal  to
442                     axis_height.
443
444              column_sep
445                     This much space is added between columns in a matrix.
446
447              matrix_side_sep
448                     This much space is added at each side of a matrix.
449
450              draw_lines
451                     If  this is non-zero, lines are drawn using the \D escape
452                     sequence, rather than with the \l escape sequence and the
453                     \(ru character.
454
455              body_height
456                     The  amount  by  which the height of the equation exceeds
457                     this is added as extra space before the  line  containing
458                     the equation (using \x).  The default value is 85.
459
460              body_depth
461                     The  amount  by  which  the depth of the equation exceeds
462                     this is added as extra space after  the  line  containing
463                     the equation (using \x).  The default value is 35.
464
465              nroff  If this is non-zero, then ndefine behaves like define and
466                     tdefine is ignored, otherwise tdefine behaves like define
467                     and  ndefine is ignored.  The default value is 0 (This is
468                     typically changed to 1 by the eqnrc file for  the  ascii,
469                     latin1, utf8, and cp1047 devices.)
470
471              A  more precise description of the role of many of these parame‐
472              ters can be found in Appendix H of The TeXbook.
473
474   Macros
475       Macros can take arguments.  In a macro body, $n where n  is  between  1
476       and  9, is replaced by the nth argument if the macro is called with ar‐
477       guments; if there are fewer than n arguments, it is replaced  by  noth‐
478       ing.   A  word containing a left parenthesis where the part of the word
479       before the left parenthesis has been defined using the  define  command
480       is  recognized as a macro call with arguments; characters following the
481       left parenthesis up to a matching  right  parenthesis  are  treated  as
482       comma-separated arguments; commas inside nested parentheses do not ter‐
483       minate an argument.
484
485       sdefine name X anything X
486              This is like the define command, but name is not  recognized  if
487              called with arguments.
488
489       include "file"
490       copy "file"
491              Include  the  contents  of file (include and copy are synonyms).
492              Lines of file beginning with .EQ or .EN are ignored.
493
494       ifdef name X anything X
495              If name has been defined by define (or  has  been  automatically
496              defined  because  name  is  the output device) process anything;
497              otherwise ignore anything.  X can be any character not appearing
498              in anything.
499
500       undef name
501              Remove definition of name, making it undefined.
502
503       Besides  the  macros  mentioned  above,  the  following definitions are
504       available: Alpha, Beta, ..., Omega (this is the same  as  ALPHA,  BETA,
505       ..., OMEGA), ldots (three dots on the base line), and dollar.
506
507   Fonts
508       eqn normally uses at least two fonts to set an equation: an italic font
509       for letters, and a roman font for everything else.  The existing  gfont
510       command  changes  the font that is used as the italic font.  By default
511       this is I.  The font that is used as the roman font can be changed  us‐
512       ing the new grfont command.
513
514       grfont f
515              Set the roman font to f.
516
517       The italic primitive uses the current italic font set by gfont; the ro‐
518       man primitive uses the current roman font set by grfont.  There is also
519       a  new  gbfont  command, which changes the font used by the bold primi‐
520       tive.  If you only use the roman, italic and bold primitives to changes
521       fonts  within  an  equation,  you can change all the fonts used by your
522       equations just by using gfont, grfont and gbfont commands.
523
524       You can control which characters are treated as letters (and  therefore
525       set  in italics) by using the chartype command described above.  A type
526       of letter causes a character to be set in italic type.  A type of digit
527       causes a character to be set in roman type.
528

FILES

530       /usr/share/groff/1.22.4/tmac/eqnrc
531              Initialization file.
532

MATHML MODE LIMITATIONS

534       MathML  is  designed  on  the  assumption that it cannot know the exact
535       physical characteristics of the media and devices on which it  will  be
536       rendered.  It does not support fine control of motions and sizes to the
537       same degree troff does.  Thus:
538
539       *      eqn parameters have no effect on the generated MathML.
540
541       *      The special, up, down, fwd, and back operations cannot be imple‐
542              mented, and yield a MathML ‘<merror>’ message instead.
543
544       *      The  vcenter  keyword  is  silently ignored, as centering on the
545              math axis is the MathML default.
546
547       *      Characters that eqn over troff sets extra large  –  notably  the
548              integral  sign  –  may  appear  too small and need to have their
549              ‘<mstyle>’ wrappers adjusted by hand.
550
551       As in its troff mode, eqn in MathML mode leaves the .EQ and .EN  delim‐
552       iters  in  place  for displayed equations, but emits no explicit delim‐
553       iters around inline equations.  They can,  however,  be  recognized  as
554       strings  that  begin  with  ‘<math>’  and end with ‘</math>’ and do not
555       cross line boundaries.
556
557       See section “Bugs” below for translation limits specific to eqn.
558

BUGS

560       Inline equations are set at the point size that is current at  the  be‐
561       ginning of the input line.
562
563       In  MathML mode, the mark and lineup features don't work.  These could,
564       in theory, be implemented with ‘<maligngroup>’ elements.
565
566       In MathML mode, each digit of a numeric literal gets a  separate  ‘<mn>
567       </mn>’  pair,  and decimal points are tagged with ‘<mo></mo>’.  This is
568       allowed by the specification, but inefficient.
569

SEE ALSO

571       groff(1), troff(1), pic(1), groff_font(5), The TeXbook
572
573
574
575groff 1.22.4                    20 January 2022                         EQN(1)
Impressum