Debian Codegraph @

upstream/debian-trixie/man1/eqn.1

raw
1 '\" et
2 .TH \%eqn 1 "3 June 2025" "groff 1.23.0"
3 .SH Name
4 \%eqn \- format mathematics (equations) for
5 .I groff
6 or MathML
7 .
8 .
9 .\" ====================================================================
10 .\" Legal Terms
11 .\" ====================================================================
12 .\"
13 .\" Copyright (C) 1989-2023 Free Software Foundation, Inc.
14 .\"
15 .\" Permission is granted to make and distribute verbatim copies of this
16 .\" manual provided the copyright notice and this permission notice are
17 .\" preserved on all copies.
18 .\"
19 .\" Permission is granted to copy and distribute modified versions of
20 .\" this manual under the conditions for verbatim copying, provided that
21 .\" the entire resulting derived work is distributed under the terms of
22 .\" a permission notice identical to this one.
23 .\"
24 .\" Permission is granted to copy and distribute translations of this
25 .\" manual into another language, under the above conditions for
26 .\" modified versions, except that this permission notice may be
27 .\" included in translations approved by the Free Software Foundation
28 .\" instead of in the original English.
29 .
30 .
31 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
32 .do nr *groff_eqn_1_man_C \n[.cp]
33 .cp 0
34 .
35 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
36 .nr do-fallback 0
37 .if !\n(.f .nr do-fallback 1 \" mandoc
38 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
39 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
40 .if \n[do-fallback] \{\
41 . de MR
42 . ie \\n(.$=1 \
43 . I \%\\$1
44 . el \
45 . IR \%\\$1 (\\$2)\\$3
46 . .
47 .\}
48 .rr do-fallback
49 .
50 .
51 .ie \n(.V<\n(.v \
52 . ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
53 .el \
54 . ds tx TeX
55 .
56 .
57 .\" ====================================================================
58 .SH Synopsis
59 .\" ====================================================================
60 .
61 .SY \%eqn
62 .RB [ \-CNrR ]
63 .RB [ \- d
64 .IR xy ]
65 .RB [ \-f
66 .IR F ]
67 .RB [ \-m
68 .IR n ]
69 .RB [ \-M
70 .IR dir ]
71 .RB [ \-p
72 .IR n ]
73 .RB [ \-s
74 .IR n ]
75 .RB [ \-T
76 .IR dev ]
77 .RI [ file\~ .\|.\|.]
78 .YS
79 .
80 .
81 .SY \%eqn
82 .B \-\-help
83 .YS
84 .
85 .
86 .SY \%eqn
87 .B \-v
88 .
89 .SY \%eqn
90 .B \-\-version
91 .YS
92 .
93 .
94 .\" ====================================================================
95 .SH Description
96 .\" ====================================================================
97 .
98 The GNU implementation of
99 .I eqn \" GNU
100 is part of the
101 .MR groff 7
102 document formatting system.
103 .
104 .I \%eqn
105 is a
106 .MR \%troff 1
107 preprocessor that translates expressions in its own language,
108 embedded in
109 .MR roff 7
110 input files,
111 into mathematical notation typeset by
112 .MR \%troff 1 .
113 .
114 It copies each
115 .IR file 's
116 contents to the standard output stream,
117 translating each
118 .I equation
119 between lines starting with
120 .B .EQ
121 and
122 .BR .EN ,
123 or within a pair of user-specified delimiters.
124 .
125 Normally,
126 .I \%eqn
127 is not executed directly by the user,
128 but invoked by specifying the
129 .B \-e
130 option to
131 .MR groff 1 .
132 .
133 While GNU
134 .IR eqn 's \" GNU
135 input syntax is highly compatible with AT&T
136 .IR eqn , \" AT&T
137 the output
138 .I \%eqn
139 produces cannot be processed by AT&T
140 .IR troff ; \" AT&T
141 GNU
142 .I troff \" GNU
143 (or a
144 .I troff \" generic
145 implementing relevant GNU extensions)
146 must be used.
147 .
148 If no
149 .I file
150 operands are given on the command line,
151 or if
152 .I file
153 is
154 .RB \[lq] \- \[rq],
155 .I \%eqn
156 reads the standard input stream.
157 .
158 .
159 .P
160 Unless the
161 .B \-R
162 option is used,
163 .I \%eqn
164 searches for the file
165 .I eqnrc
166 in the directories given with the
167 .B \-M
168 option first,
169 then in
170 .if !'no'no' .IR /usr/\:\%lib/\:\%groff/\:\%site\-tmac ,
171 .IR /usr/\:\%share/\:\%groff/\:\%site\-tmac ,
172 and finally in the standard macro directory
173 .IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac .
174 .
175 If it exists and is readable,
176 .I \%eqn
177 processes it before any input files.
178 .
179 .
180 .P
181 This man page primarily discusses the differences between GNU
182 .I eqn \" GNU
183 and AT&T
184 .IR eqn .\" AT&T
185 .
186 Most of the new features of the GNU
187 .I eqn \" GNU
188 input language are based on \*[tx].
189 .
190 There are some references to the differences between \*[tx] and GNU
191 .I eqn \" GNU
192 below;
193 these may safely be ignored if you do not know \*[tx].
194 .
195 .
196 .P
197 Three points are worth special note. \" good, bad, and different
198 .
199 .
200 .IP \[bu] 2n
201 GNU
202 .I eqn \" GNU
203 emits Presentation MathML output when invoked with the
204 .RB \[lq] "\-T\~MathML" \[rq]
205 option.
206 .
207 .
208 .IP \[bu]
209 GNU
210 .I eqn \" GNU
211 does not support terminal devices well,
212 though it may suffice for simple inputs.
213 .
214 .
215 .IP \[bu]
216 GNU
217 .I eqn
218 sets the input token
219 .RB \[lq] .\|.\|.\& \[rq]
220 as an ellipsis on the text baseline,
221 not the three centered dots of AT&T
222 .IR eqn . \" AT&T
223 .
224 Set an ellipsis on the math axis with the GNU extension macro
225 .BR cdots .
226 .
227 .
228 .\" ====================================================================
229 .SS "Anatomy of an equation"
230 .\" ====================================================================
231 .
232 .I eqn
233 input consists of tokens.
234 .
235 Consider a form of Newton's second law of motion.
236 .
237 The input
238 .
239 .
240 .P
241 .RS
242 .EX
243 \&.EQ
244 F =
245 m a
246 \&.EN
247 .EE
248 .RE
249 .
250 .
251 .P
252 becomes
253 .EQ
254 F =
255 m a.
256 .EN
257 .
258 Each of
259 .BR F ,
260 .BR = ,
261 .BR m ,
262 and
263 .B a
264 is a token.
265 .
266 .
267 Spaces and newlines are interchangeable;
268 they separate tokens but do not break lines or produce space in
269 the output.
270 .
271 .
272 .P
273 The following input characters not only separate tokens,
274 but manage their grouping and spacing as well.
275 .
276 .
277 .TP
278 .B "{ }"
279 Braces perform grouping.
280 .
281 Whereas
282 .RB \[lq] "e sup a b" \[rq]
283 expresses
284 .ie n .RI \[lq]( e "\~to the\~" a )\~times\~ b \[rq],
285 .el \{\
286 .EQ
287 e sup a b ,
288 .EN
289 .\}
290 .RB \[lq] "e sup { a b }" \[rq]
291 means
292 .ie n .RI \[lq] e "\~to the\~(" a \~times\~ b )\[rq].
293 .el \{\
294 .EQ
295 e sup { a b } .
296 .EN
297 .\}
298 .
299 When immediately preceded by a
300 .RB \[lq] left \[rq]
301 or
302 .RB \[lq] right \[rq]
303 primitive,
304 a brace loses its special meaning.
305 .
306 .
307 .TP
308 .B "\[ha] \[ti]
309 are the
310 .I "half space"
311 and
312 .I "full space,"
313 respectively.
314 .
315 Use them to tune the appearance of the output.
316 .
317 .
318 .P
319 Tab and leader characters separate tokens as well as advancing the
320 drawing position to the next tab stop,
321 but are seldom used in
322 .I eqn
323 input.
324 .
325 When they occur,
326 they must appear at the outermost lexical scope.
327 .
328 This roughly means that they can't appear within braces that are
329 necessary to disambiguate the input;
330 .I \%eqn
331 will diagnose an error in this event.
332 .
333 (See subsection \[lq]Macros\[rq] below for additional token separation
334 rules.)
335 .
336 .
337 .P
338 Other tokens are primitives,
339 macros,
340 an argument to either of the foregoing,
341 or components of an equation.
342 .
343 .
344 .br
345 .ne 4v
346 .P
347 .I Primitives
348 are fundamental keywords of the
349 .I eqn
350 language.
351 .
352 They can configure an aspect of the preprocessor's state,
353 as when setting a \[lq]global\[rq] font selection or type size
354 .RB ( gfont
355 and
356 .BR gsize ),
357 or declaring or deleting macros
358 .RB \%(\[lq] define \[rq]
359 and
360 .BR undef );
361 these are termed
362 .I commands.
363 .
364 Other primitives perform formatting operations on the tokens after them
365 (as with
366 .BR fat ,
367 .BR over ,
368 .BR sqrt ,
369 or
370 .BR up ).
371 .
372 .
373 .P
374 Equation
375 .I components
376 include mathematical variables,
377 constants,
378 numeric literals,
379 and operators.
380 .
381 .I \%eqn
382 remaps some input character sequences to
383 .I groff
384 special character escape sequences for economy in equation entry and to
385 ensure that glyphs from an unstyled font are used;
386 see
387 .MR groff_char 7 .
388 .
389 .
390 .P
391 .RS
392 .TS
393 tab(@);
394 Lf(CR) Lf(CR) Lw(1i) Lf(CR) Lf(CR).
395 +@\[rs][pl]@\&@\[aq]@\[rs][fm]
396 -@\[rs][mi]@\&@<=@\[rs][<=]
397 \&=@\[rs][eq]@\&@>=@\[rs][>=]
398 .TE
399 .RE
400 .
401 .
402 .P
403 .I Macros
404 permit primitives,
405 components,
406 and other macros to be collected and referred to by a single token.
407 .
408 Predefined macros make convenient the preparation of
409 .I eqn
410 input in a form resembling its spoken expression;
411 for example,
412 consider
413 .BR cos ,
414 .BR hat ,
415 .BR inf ,
416 and
417 .BR lim .
418 .
419 .
420 .\" ====================================================================
421 .SS "Spacing and typeface"
422 .\" ====================================================================
423 .
424 GNU
425 .I eqn
426 imputes types to the components of an equation,
427 adjusting the spacing between them accordingly.
428 .
429 Recognized types are as follows;
430 most affect spacing only,
431 whereas the
432 .RB \%\[lq] letter \[rq]
433 subtype of
434 .RB \%\[lq] ordinary \[rq]
435 also assigns a style.
436 .
437 .
438 .RS 2n \" we need quite a bit of horizontal space for this table
439 .P
440 .TS
441 Lf(CR) Lx
442 Af(CR) Lx
443 Af(CR) Lx
444 Lf(CR) Lx.
445 ordinary T{
446 character such as \[lq]1\[rq],
447 \[lq]a\[rq],
448 or
449 \[lq]!\&\[rq]
450 T}
451 letter character to be italicized by default
452 digit \f[I]n/a\f[]
453 operator T{
454 large operator such as
455 .ds Su \[lq]\s+5\[*S]\s0\[rq]
456 .if \n(.g .if !c\[*S] .ds Su the summation operator
457 \*[Su]
458 .rm Su
459 T}
460 binary binary operator such as \[lq]\[pl]\[rq]
461 relation relational operator such as \[lq]=\[rq]
462 opening opening bracket such as \[lq](\[rq]
463 closing closing bracket such as \[lq])\[rq]
464 punctuation punctuation character such as \[lq],\[rq]
465 inner sub-formula contained within brackets
466 suppress component to which automatic spacing is not applied
467 .TE
468 .RE
469 .
470 .
471 .P
472 Two primitives apply types to equation components.
473 .
474 .
475 .TP
476 .BI type\~ "t e"
477 Apply
478 .RI type\~ t
479 to
480 .RI expression\~ e .
481 .
482 .
483 .TP
484 .BI chartype\~ "t text"
485 Assign each character in (unquoted)
486 .I text
487 .RI type\~ t ,
488 persistently.
489 .
490 .
491 .P
492 .I \%eqn \" GNU
493 sets up spacings and styles as if by the following commands.
494 .
495 .P
496 .RS
497 .TS
498 tab(@);
499 Lf(CR)1 Lf(CR).
500 chartype \[dq]letter\[dq]@abcdefghiklmnopqrstuvwxyz
501 chartype \[dq]letter\[dq]@ABCDEFGHIKLMNOPQRSTUVWXYZ
502 chartype \[dq]letter\[dq]@\[rs][*a]\[rs][*b]\[rs][*g]\[rs][*d]\[rs][*e]\
503 \[rs][*z]
504 chartype \[dq]letter\[dq]@\[rs][*y]\[rs][*h]\[rs][*i]\[rs][*k]\[rs][*l]\
505 \[rs][*m]
506 chartype \[dq]letter\[dq]@\[rs][*n]\[rs][*c]\[rs][*o]\[rs][*p]\[rs][*r]\
507 \[rs][*s]
508 chartype \[dq]letter\[dq]@\[rs][*t]\[rs][*u]\[rs][*f]\[rs][*x]\[rs][*q]\
509 \[rs][*w]
510 chartype \[dq]binary\[dq]@*\[rs][pl]\[rs][mi]
511 chartype \[dq]relation\[dq]@<>\[rs][eq]\[rs][<=]\[rs][>=]
512 chartype \[dq]opening\[dq]@{([
513 chartype \[dq]closing\[dq]@})]
514 chartype \[dq]punctuation\[dq]@,;:.
515 chartype \[dq]suppress\[dq]@\[ha]\[ti]
516 .TE
517 .RE
518 .
519 .
520 .P
521 .I \%eqn
522 assigns all other ordinary and special
523 .I roff
524 characters,
525 including numerals 0\[en]9,
526 the
527 .RB \%\[lq] ordinary \[rq]
528 type.
529 .
530 (The
531 .RB \[lq] digit \[rq]
532 type is not used,
533 but is available for customization.)
534 .\" XXX: How would you actually customize it, though? There doesn't
535 .\" seem to be a means of replacing the font associated with a type.
536 .\" Is the "digit" type just cruft?
537 .
538 In keeping with common practice in mathematical typesetting,
539 lowercase,
540 but not uppercase,
541 Greek letters are assigned the
542 .RB \%\[lq] letter \[rq]
543 type to style them in italics.
544 .
545 The macros for producing ellipses,
546 .RB \[lq] .\|.\|. \[rq],
547 .BR cdots ,
548 and
549 .BR ldots ,
550 use the
551 .RB \%\[lq] inner \[rq]
552 type.
553 .
554 .
555 .\" ====================================================================
556 .SS Primitives
557 .\" ====================================================================
558 .
559 .I \%eqn
560 supports without alteration the AT&T
561 .I eqn \" AT&T
562 primitives
563 .BR above ,
564 .BR back ,
565 .BR bar ,
566 .BR bold ,
567 .BR \%define ,
568 .BR down ,
569 .BR fat ,
570 .BR font ,
571 .BR from ,
572 .BR fwd ,
573 .BR gfont ,
574 .BR gsize ,
575 .BR italic ,
576 .BR left ,
577 .BR lineup ,
578 .BR mark ,
579 .BR \%matrix ,
580 .BR \%ndefine ,
581 .BR over ,
582 .BR right ,
583 .BR roman ,
584 .BR size ,
585 .BR sqrt ,
586 .BR sub ,
587 .BR sup ,
588 .BR \%tdefine ,
589 .BR to ,
590 .BR \%under ,
591 and
592 .BR up .
593 .
594 .
595 .\" ====================================================================
596 .SS "New primitives"
597 .\" ====================================================================
598 .
599 The GNU extension primitives
600 .RB \[lq] type \[rq]
601 and
602 .B \%chartype
603 are discussed in subsection \[lq]Spacing and typeface\[rq] above;
604 .RB \[lq] set \[rq]
605 in subsection \[lq]Customization\[rq] below;
606 and
607 .B grfont
608 and
609 .B gbfont
610 in subsection \[lq]Fonts\[rq] below.
611 .
612 In the following synopses,
613 .I X
614 can be any character not appearing in the parameter thus bracketed.
615 .
616 .
617 .TP
618 .IB e1 \~accent\~ e2
619 Set
620 .I e2
621 as an accent over
622 .IR e1 .
623 .
624 .I e2
625 is assumed to be at the appropriate height for a lowercase letter
626 without an ascender;
627 .I \% eqn
628 vertically shifts it depending on
629 .IR e1 's
630 height.
631 .
632 For example,
633 .B hat
634 is defined as follows.
635 .
636 .
637 .RS
638 .IP
639 .EX
640 accent { "\[ha]" }
641 .EE
642 .RE
643 .
644 .
645 .IP
646 .BR dotdot ,
647 .BR dot ,
648 .BR tilde ,
649 .BR vec ,
650 and
651 .B dyad
652 are also defined using the
653 .B \%accent
654 primitive.
655 .
656 .
657 .TP
658 .BI big\~ e
659 Enlarge the expression
660 .IR e ;
661 semantics like those of CSS \[lq]large\[rq] are intended.
662 .
663 In
664 .I \%troff
665 output,
666 the type size is increased by\~5 scaled points.
667 .
668 MathML output emits the following.
669 .
670 .
671 .RS
672 .IP
673 .EX
674 <mstyle \%mathsize=\[aq]big\[aq]>
675 .EE
676 .RE
677 .
678 .
679 .TP
680 .BI copy\~ file
681 .TQ
682 .BI include\~ file
683 Interpolate the contents of
684 .IR file ,
685 omitting lines
686 beginning with
687 .B .EQ
688 or
689 .BR .EN .
690 .
691 If a relative path name,
692 .I file
693 is sought relative to the current working directory.
694 .
695 .
696 .TP
697 .BI ifdef\~ "name X anything X"
698 If
699 .I name
700 is defined as a primitive or macro,
701 interpret
702 .IR anything .
703 .
704 .
705 .TP
706 .BI nosplit\~ text
707 As
708 .RI \[dq] text \[dq],
709 but since
710 .I text
711 is not quoted it is subject to macro expansion;
712 it is not split up and the spacing between characters not adjusted per
713 subsection \[lq]Spacing and typeface\[rq] above.
714 .
715 .
716 .TP
717 .IB e\~ opprime
718 As
719 .BR prime ,
720 but set the prime symbol as an operator
721 .RI on\~ e .
722 .
723 In the input
724 .RB \[lq] "A opprime sub 1" \[rq],
725 the\~\[lq]1\[rq] is tucked under the prime as a subscript to
726 the\~\[lq]A\[rq]
727 (as is conventional in mathematical typesetting),
728 whereas when
729 .B prime
730 is used,
731 the\~\[lq]1\[rq] is a subscript to the prime character.
732 .
733 The precedence of
734 .B \%opprime
735 is the same as that of
736 .B bar
737 and
738 .RB \%\[lq] under \[rq],
739 and higher than that of other primitives except
740 .B \%accent
741 and
742 .BR uaccent .
743 .
744 In unquoted text,
745 a neutral apostrophe
746 .RB ( \[aq] )
747 that is not the first character on the input line is treated like
748 .BR \%opprime .
749 .
750 .
751 .TP
752 .BI sdefine\~ "name X anything X"
753 As
754 .RB \%\[lq] define \[rq],
755 but
756 .I name
757 is not recognized as a macro if called with arguments.
758 .
759 .
760 .TP
761 .IB e1 \~smallover\~ e2
762 As
763 .BR over ,
764 but reduces the type size of
765 .I e1
766 and
767 .IR e2 ,
768 and puts less vertical space between
769 .I e1
770 and
771 .I e2
772 and the fraction bar.
773 .
774 The
775 .B over
776 primitive corresponds to the \*[tx]
777 .B \[rs]over
778 primitive in displayed equation styles;
779 .B smallover
780 corresponds to
781 .B \[rs]over
782 in non-display (\[lq]inline\[rq]) styles.
783 .
784 .
785 .br
786 .ne 5v
787 .TP
788 .BI space\~ n
789 Set extra vertical spacing around the equation,
790 replacing the default values,
791 where
792 .IR n \~is
793 an integer in hundredths of an em.
794 .
795 If positive,
796 .IR n \~increases
797 vertical spacing before the equation;
798 if negative,
799 it does so after the equation.
800 .
801 This primitive provides an interface to
802 .IR groff 's
803 .B \[rs]x
804 escape sequence,
805 but with the opposite sign convention.
806 .
807 It has no effect if the equation is part of a
808 .MR \%pic 1
809 picture.
810 .
811 .
812 .TP
813 .BI special\~ "troff-macro e"
814 Construct an object by calling
815 .I troff-macro
816 .RI on\~ e .
817 .
818 The
819 .I troff \" generic
820 string
821 .B 0s
822 contains the
823 .I eqn \" generic
824 output
825 .RI for\~ e ,
826 and the registers
827 .BR 0w ,
828 .BR 0h ,
829 .BR 0d ,
830 .BR 0skern ,
831 and
832 .B 0skew
833 the width,
834 height,
835 depth,
836 subscript kern,
837 and skew
838 .RI of\~ e ,
839 respectively.
840 .
841 (The
842 .I subscript kern
843 of an object indicates how much a subscript on that object should be
844 \[lq]tucked in\[rq],
845 or placed to the left relative to a non-subscripted glyph of the same
846 size.
847 .
848 The
849 .I skew
850 of an object is how far to the right of the center of the object an
851 accent over it should be placed.)
852 .
853 The macro must modify
854 .B 0s
855 so that it outputs the desired result,
856 returns the drawing position to the text baseline at the beginning of
857 .IR e ,
858 and updates the foregoing registers to correspond to the new dimensions
859 of the result.
860 .
861 .
862 .IP
863 Suppose you want a construct that \[lq]cancels\[rq] an expression by
864 drawing a diagonal line through it.
865 .
866 .
867 .br
868 .ne 11v
869 .RS
870 .IP
871 .EX
872 \&.de Ca
873 \&. ds 0s \[rs]
874 \[rs]Z\[aq]\[rs]\[rs]*(0s\[aq]\[rs]
875 \[rs]v\[aq]\[rs]\[rs]n(0du\[aq]\[rs]
876 \[rs]D\[aq]l \[rs]\[rs]n(0wu \-\[rs]\[rs]n(0hu\-\[rs]\
877 \[rs]n(0du\[aq]\[rs]
878 \[rs]v\[aq]\[rs]\[rs]n(0hu\[aq]
879 \&..
880 \&.EQ
881 special Ca "x \[rs][mi] 3 \[rs][pl] x" \[ti] 3
882 \&.EN
883 .EE
884 .RE
885 .
886 .
887 .IP
888 We use the
889 .B \[rs][mi]
890 and
891 .B \[rs][pl]
892 special characters instead of + and \-
893 because they are part of the argument to a
894 .I \%troff
895 macro,
896 so
897 .I \%eqn
898 does not transform them to mathematical glyphs for us.
899 .
900 Here's a more complicated construct that draws a box around an
901 expression;
902 the bottom of the box rests on the text baseline.
903 .
904 We define the
905 .I eqn \" generic
906 macro
907 .B box
908 to wrap the call of the
909 .I \%troff
910 macro
911 .BR Bx .
912 .
913 .
914 .br
915 .ne 17v
916 .RS
917 .IP
918 .EX
919 \&.de Bx
920 \&.ds 0s \[rs]
921 \[rs]Z\[aq]\[rs]\[rs]h\[aq]1n\[aq]\[rs]\[rs]*[0s]\[aq]\[rs]
922 \[rs]v\[aq]\[rs]\[rs]n(0du+1n\[aq]\[rs]
923 \[rs]D\[aq]l \[rs]\[rs]n(0wu+2n 0\[aq]\[rs]
924 \[rs]D\[aq]l 0 \-\[rs]\[rs]n(0hu\-\[rs]\[rs]n(0du\-2n\[aq]\[rs]
925 \[rs]D\[aq]l \-\[rs]\[rs]n(0wu\-2n 0\[aq]\[rs]
926 \[rs]D\[aq]l 0 \[rs]\[rs]n(0hu+\[rs]\[rs]n(0du+2n\[aq]\[rs]
927 \[rs]h\[aq]\[rs]\[rs]n(0wu+2n\[aq]
928 \&.nr 0w +2n
929 \&.nr 0d +1n
930 \&.nr 0h +1n
931 \&..
932 \&.EQ
933 define box \[aq] special Bx $1 \[aq]
934 box(foo) \[ti] "bar"
935 \&.EN
936 .EE
937 .RE
938 .
939 .
940 .TP
941 .BI "split \[dq]" text \[dq]
942 As
943 .IR text ,
944 but since
945 .I text
946 is quoted,
947 it is not subject to macro expansion;
948 it is split up and the spacing between characters adjusted per
949 subsection \[lq]Spacing and typeface\[rq] above.
950 .
951 .
952 .TP
953 .IB e1 \~uaccent\~ e2
954 Set
955 .I e2
956 as an accent under
957 .IR e1 .
958 .
959 .I e2
960 is assumed to be at the appropriate height for a letter without a
961 descender;
962 .I \% eqn
963 vertically shifts it depending on whether
964 .I e1
965 has a descender.
966 .
967 .B utilde
968 is predefined using
969 .B uaccent
970 as a tilde accent below the baseline.
971 .
972 .
973 .TP
974 .BI undef\~ name
975 Remove definition of macro or primitive
976 .IR name ,
977 making it undefined.
978 .
979 .
980 .TP
981 .BI vcenter\~ e
982 Vertically center
983 .I e
984 about the
985 .IR "math axis" ,
986 a horizontal line upon which fraction bars and characters such as
987 \[lq]\[pl]\[rq] and \[lq]\[mi]\[rq] are aligned.
988 .
989 MathML already behaves this way,
990 so
991 .I \%eqn
992 ignores this primitive when producing that output format.
993 .
994 The built-in
995 .B sum
996 macro is defined as if by the following.
997 .
998 .RS
999 .IP
1000 .EX
1001 define sum ! { type "operator" vcenter size +5 \[rs](*S } !
1002 .EE
1003 .RE
1004 .
1005 .
1006 .br
1007 .ne 8v
1008 .\" ====================================================================
1009 .SS "Extended primitives"
1010 .\" ====================================================================
1011 .
1012 GNU
1013 .I eqn \" GNU
1014 extends the syntax of some AT&T
1015 .I eqn \" AT&T
1016 primitives,
1017 introducing one deliberate incompatibility.
1018 .
1019 .
1020 .TP
1021 .B "delim on"
1022 .I \%eqn
1023 recognizes an
1024 .RB \[lq] on \[rq]
1025 argument to the
1026 .B \%delim
1027 primitive specially,
1028 restoring any delimiters previously disabled with
1029 .RB \%\[lq] "delim off" \[rq].
1030 .
1031 If delimiters haven't been specified,
1032 neither command has effect.
1033 .
1034 Few
1035 .I eqn \" generic
1036 documents are expected to use \[lq]o\[rq] and \[lq]n\[rq] as left and
1037 right delimiters,
1038 respectively.
1039 .
1040 If yours does,
1041 consider swapping them,
1042 or select others.
1043 .
1044 .
1045 .TP
1046 .BI col\~ n\~\c
1047 .BR {\~ .\|.\|.\& \~}
1048 .TQ
1049 .BI ccol\~ n\~\c
1050 .BR {\~ .\|.\|.\& \~}
1051 .TQ
1052 .BI lcol\~ n\~\c
1053 .BR {\~ .\|.\|.\& \~}
1054 .TQ
1055 .BI rcol\~ n\~\c
1056 .BR {\~ .\|.\|.\& \~}
1057 .TQ
1058 .BI pile\~ n\~\c
1059 .BR {\~ .\|.\|.\& \~}
1060 .TQ
1061 .BI cpile\~ n\~\c
1062 .BR {\~ .\|.\|.\& \~}
1063 .TQ
1064 .BI lpile\~ n\~\c
1065 .BR {\~ .\|.\|.\& \~}
1066 .TQ
1067 .BI rpile\~ n\~\c
1068 .BR {\~ .\|.\|.\& \~}
1069 The integer
1070 .RI value\~ n
1071 (in hundredths of an em)
1072 increases the vertical spacing between rows,
1073 using
1074 .IR groff 's
1075 .B \[rs]x
1076 escape sequence
1077 (the value has no effect in MathML mode).
1078 .
1079 Negative values are accepted but have no effect.
1080 .
1081 If more than one
1082 .I n
1083 occurs in a matrix or pile,
1084 the largest is used.
1085 .
1086 .
1087 .\" ====================================================================
1088 .SS Customization
1089 .\" ====================================================================
1090 .
1091 When
1092 .I \%eqn
1093 generates
1094 .I \%troff
1095 input,
1096 the appearance of equations is controlled by a large number of
1097 parameters.
1098 .
1099 They have no effect when generating MathML,
1100 which delegates typesetting to a MathML rendering engine.
1101 .
1102 Configure these parameters with the
1103 .B set
1104 primitive.
1105 .
1106 .
1107 .TP
1108 .BI set\~ "p n"
1109 assigns
1110 .RI parameter\~ p
1111 the integer
1112 .RI value\~ n ;
1113 .IR n \~is
1114 interpreted in units of hundredths of an em unless otherwise stated.
1115 .
1116 For example,
1117 .
1118 .
1119 .RS
1120 .IP
1121 .EX
1122 set x_height 45
1123 .EE
1124 .RE
1125 .
1126 .
1127 .IP
1128 says that
1129 .I \%eqn
1130 should assume that the font's x-height is 0.45\~ems.
1131 .
1132 .
1133 .RS
1134 .P
1135 Available parameters are as follows;
1136 defaults are shown in parentheses.
1137 .
1138 We intend these descriptions to be expository rather than rigorous.
1139 .
1140 .
1141 .TP 17n
1142 .B minimum_size
1143 sets a floor for the type size
1144 (in scaled points)
1145 at which equations are set
1146 .RB ( 5 ).
1147 .
1148 .
1149 .TP
1150 .B fat_offset
1151 The
1152 .B fat
1153 primitive emboldens an equation by overprinting two copies of the
1154 equation horizontally offset by this amount
1155 .RB ( 4 ).
1156 .
1157 In MathML mode,
1158 components to which
1159 .B \%fat_offset
1160 applies instead use the following.
1161 .
1162 .RS
1163 .RS
1164 .EX
1165 <mstyle mathvariant=\[aq]double\-struck\[aq]>
1166 .EE
1167 .RE
1168 .RE
1169 .
1170 .
1171 .TP
1172 .B over_hang
1173 A fraction bar is longer by twice this amount than
1174 the maximum of the widths of the numerator and denominator;
1175 in other words,
1176 it overhangs the numerator and denominator by at least this amount
1177 .RB ( 0 ).
1178 .
1179 .
1180 .TP
1181 .B accent_width
1182 When
1183 .B bar
1184 or
1185 .B \%under
1186 is applied to a single character,
1187 the line is this long
1188 .RB ( 31 ).
1189 .
1190 Normally,
1191 .B bar
1192 or
1193 .B \%under
1194 produces a line whose length is the width of the object to which it
1195 applies;
1196 in the case of a single character,
1197 this tends to produce a line that looks too long.
1198 .
1199 .
1200 .TP
1201 .B delimiter_factor
1202 Extensible delimiters produced with the
1203 .B left
1204 and
1205 .B right
1206 primitives have a combined height and depth of at least this many
1207 thousandths of twice the maximum amount by which the sub-equation that
1208 the delimiters enclose extends away from the axis
1209 .RB ( 900 ).
1210 .
1211 .
1212 .TP
1213 .B delimiter_shortfall
1214 Extensible delimiters produced with the
1215 .B left
1216 and
1217 .B right
1218 primitives have a combined height and depth not less than the
1219 difference of twice the maximum amount by which the sub-equation that
1220 the delimiters enclose extends away from the axis and this amount
1221 .RB ( 50 ).
1222 .
1223 .
1224 .TP
1225 .B null_delimiter_space
1226 This much horizontal space is inserted on each side of a fraction
1227 .RB ( 12 ).
1228 .
1229 .
1230 .TP
1231 .B script_space
1232 The width of subscripts and superscripts is increased by this amount
1233 .RB ( 5 ).
1234 .
1235 .
1236 .TP
1237 .B thin_space
1238 This amount of space is automatically inserted after punctuation
1239 characters.
1240 .
1241 It also configures the width of the space produced by the
1242 .B \[ha]
1243 token
1244 .RB ( 17 ).
1245 .
1246 .
1247 .TP
1248 .B medium_space
1249 This amount of space is automatically inserted on either side of
1250 binary operators
1251 .RB ( 22 ).
1252 .
1253 .
1254 .TP
1255 .B thick_space
1256 This amount of space is automatically inserted on either side of
1257 relations.
1258 .
1259 It also configures the width of the space produced by the
1260 .B \[ti]
1261 token
1262 .RB ( 28 ).
1263 .
1264 .
1265 .TP
1266 .B x_height
1267 The height of lowercase letters without ascenders such as \[lq]x\[rq]
1268 .RB ( 45 ).
1269 .
1270 .
1271 .TP
1272 .B axis_height
1273 The height above the baseline of the center of characters such as
1274 \[lq]\[pl]\[rq] and \[lq]\[mi]\[rq]
1275 .RB ( 26 ).
1276 .
1277 It is important that this value is correct for the font
1278 you are using.
1279 .
1280 .
1281 .TP
1282 .B default_rule_thickness
1283 This should be set to the thickness of the
1284 .B \[rs][ru]
1285 character,
1286 or the thickness of horizontal lines produced with the
1287 .B \[rs]D
1288 escape sequence
1289 .RB ( 4 ).
1290 .
1291 .
1292 .TP
1293 .B num1
1294 The
1295 .B over
1296 primitive shifts up the numerator by at least this amount
1297 .RB ( 70 ).
1298 .
1299 .
1300 .TP
1301 .B num2
1302 The
1303 .B smallover
1304 primitive shifts up the numerator by at least this amount
1305 .RB ( 36 ).
1306 .
1307 .
1308 .TP
1309 .B denom1
1310 The
1311 .B over
1312 primitive shifts down the denominator by at least this amount
1313 .RB ( 70 ).
1314 .
1315 .
1316 .TP
1317 .B denom2
1318 The
1319 .B smallover
1320 primitive shifts down the denominator by at least this amount
1321 .RB ( 36 ).
1322 .
1323 .
1324 .TP
1325 .B sup1
1326 Normally superscripts are shifted up by at least this amount
1327 .RB ( 42 ).
1328 .
1329 .
1330 .TP
1331 .B sup2
1332 Superscripts within superscripts or upper limits
1333 or numerators of
1334 .B smallover
1335 fractions are shifted up by at least this amount
1336 .RB ( 37 ).
1337 .
1338 Conventionally,
1339 this is less than
1340 .BR sup1 .
1341 .
1342 .
1343 .TP
1344 .B sup3
1345 Superscripts within denominators or square roots
1346 or subscripts or lower limits are shifted up by at least
1347 this amount
1348 .RB ( 28 ).
1349 .
1350 Conventionally,
1351 this is less than
1352 .BR sup2 .
1353 .
1354 .
1355 .TP
1356 .B sub1
1357 Subscripts are normally shifted down by at least this amount
1358 .RB ( 20 ).
1359 .
1360 .
1361 .TP
1362 .B sub2
1363 When there is both a subscript and a superscript,
1364 the subscript is shifted down by at least this amount
1365 .RB ( 23 ).
1366 .
1367 .
1368 .TP
1369 .B sup_drop
1370 The baseline of a superscript is no more than this much below the top of
1371 the object on which the superscript is set
1372 .RB ( 38 ).
1373 .
1374 .
1375 .TP
1376 .B sub_drop
1377 The baseline of a subscript is at least this much below the bottom of
1378 the object on which the subscript is set
1379 .RB ( 5 ).
1380 .
1381 .
1382 .TP
1383 .B big_op_spacing1
1384 The baseline of an upper limit is at least this much above the top of
1385 the object on which the limit is set
1386 .RB ( 11 ).
1387 .
1388 .
1389 .TP
1390 .B big_op_spacing2
1391 The baseline of a lower limit is at least this much below the bottom
1392 of the object on which the limit is set
1393 .RB ( 17 ).
1394 .
1395 .
1396 .TP
1397 .B big_op_spacing3
1398 The bottom of an upper limit is at least this much above the top of
1399 the object on which the limit is set
1400 .RB ( 20 ).
1401 .
1402 .
1403 .TP
1404 .B big_op_spacing4
1405 The top of a lower limit is at least this much below the bottom of the
1406 object on which the limit is set
1407 .RB ( 60 ).
1408 .
1409 .
1410 .TP
1411 .B big_op_spacing5
1412 This much vertical space is added above and below limits
1413 .RB ( 10 ).
1414 .
1415 .
1416 .TP
1417 .B baseline_sep
1418 The baselines of the rows in a pile or matrix are normally this far
1419 apart
1420 .RB ( 140 ).
1421 .
1422 Usually equal to the sum of
1423 .B num1
1424 and
1425 .BR denom1 .
1426 .
1427 .
1428 .TP
1429 .B shift_down
1430 The midpoint between the top baseline and the bottom baseline in a
1431 matrix or pile is shifted down by this much from the axis
1432 .RB ( 26 ).
1433 .
1434 Usually equal to
1435 .BR axis_height .
1436 .
1437 .
1438 .TP
1439 .B column_sep
1440 This much space is added between columns in a matrix
1441 .RB ( 100 ).
1442 .
1443 .
1444 .TP
1445 .B matrix_side_sep
1446 This much space is added at each side of a matrix
1447 .RB ( 17 ).
1448 .
1449 .
1450 .br
1451 .ne 4v
1452 .TP
1453 .B draw_lines
1454 If non-zero,
1455 .I \%eqn
1456 draws lines using the
1457 .I troff \" generic
1458 .B \[rs]D
1459 escape sequence,
1460 rather than the
1461 .B \[rs]l
1462 escape sequence and the
1463 .B \[rs][ru]
1464 special character.
1465 .
1466 The
1467 .I eqnrc
1468 file sets the default:
1469 .BR 1 \~on
1470 .BR ps ,
1471 .BR html ,
1472 and the X11 devices,
1473 .RB otherwise\~ 0 .
1474 .
1475 .
1476 .TP
1477 .B body_height
1478 is the presumed height of an equation above the text baseline;
1479 .I \%eqn
1480 adds any excess as extra pre-vertical line spacing with
1481 .IR troff 's\" generic
1482 .B \[rs]x
1483 escape sequence
1484 .RB ( 85 ).
1485 .
1486 .
1487 .TP
1488 .B body_depth
1489 is the presumed depth of an equation below the text baseline;
1490 .I \%eqn
1491 adds any excess as extra post-vertical line spacing with
1492 .IR troff 's\" generic
1493 .B \[rs]x
1494 escape sequence
1495 .RB ( 35 ).
1496 .
1497 .
1498 .TP
1499 .B nroff
1500 If non-zero,
1501 then
1502 .B \%ndefine
1503 behaves like
1504 .B \%define
1505 and
1506 .B \%tdefine
1507 is ignored,
1508 otherwise
1509 .B \%tdefine
1510 behaves like
1511 .B \%define
1512 and
1513 .B \%ndefine
1514 is ignored.
1515 .
1516 The
1517 .I eqnrc
1518 file sets the default:
1519 .BR 1 \~on
1520 .BR ascii ,
1521 .BR latin1 ,
1522 .BR utf8 ,
1523 and
1524 .B cp1047
1525 devices,
1526 .RB otherwise\~ 0 .
1527 .RE
1528 .
1529 .
1530 .\" ====================================================================
1531 .SS Macros
1532 .\" ====================================================================
1533 .
1534 In GNU
1535 .IR eqn , \" GNU
1536 macros can take arguments.
1537 .
1538 A word defined by any of the
1539 .BR \%define ,
1540 .BR \%ndefine ,
1541 or
1542 .B \%tdefine
1543 primitives followed immediately by a left parenthesis is treated as a
1544 .I "parameterized macro call:"
1545 subsequent tokens up to a matching right parenthesis are treated as
1546 comma-separated arguments.
1547 .
1548 In this context only,
1549 commas and parentheses also serve as token separators.
1550 .
1551 A macro argument is not terminated by a comma inside parentheses nested
1552 within it.
1553 .
1554 In a macro definition,
1555 .BI $ n\c
1556 ,
1557 where
1558 .I n
1559 is between 1 and\~9 inclusive,
1560 is replaced by the
1561 .IR n th
1562 argument;
1563 if there are fewer than
1564 .IR n \~arguments,
1565 it is replaced by nothing.
1566 .
1567 .
1568 .\" ====================================================================
1569 .SS "Predefined macros"
1570 .\" ====================================================================
1571 .
1572 GNU
1573 .I eqn \" GNU
1574 supports the predefined macros offered by AT&T
1575 .IR eqn : \" AT&T
1576 .BR and ,
1577 .BR \%approx ,
1578 .BR arc ,
1579 .BR cos ,
1580 .BR cosh ,
1581 .BR del ,
1582 .BR det ,
1583 .BR dot ,
1584 .BR \%dotdot ,
1585 .BR dyad ,
1586 .BR exp ,
1587 .BR for ,
1588 .BR grad ,
1589 .BR half ,
1590 .BR hat ,
1591 .BR if ,
1592 .BR \%inter ,
1593 .BR Im ,
1594 .BR inf ,
1595 .BR int ,
1596 .BR lim ,
1597 .BR ln ,
1598 .BR log ,
1599 .BR max ,
1600 .BR min ,
1601 .BR \%nothing ,
1602 .BR \%partial ,
1603 .BR prime ,
1604 .BR prod ,
1605 .BR Re ,
1606 .BR sin ,
1607 .BR sinh ,
1608 .BR sum ,
1609 .BR tan ,
1610 .BR tanh ,
1611 .BR tilde ,
1612 .BR times ,
1613 .BR union ,
1614 .BR vec ,
1615 .BR == ,
1616 .BR != ,
1617 .BR += ,
1618 .BR \-> ,
1619 .BR <\- ,
1620 .BR << ,
1621 .BR >> ,
1622 and
1623 .RB \[lq] .\|.\|. \[rq].
1624 .
1625 The lowercase classical Greek letters are available as
1626 .BR \%alpha ,
1627 .BR beta ,
1628 .BR chi ,
1629 .BR delta ,
1630 .BR \%epsilon ,
1631 .BR eta ,
1632 .BR gamma ,
1633 .BR iota ,
1634 .BR kappa ,
1635 .BR lambda ,
1636 .BR mu ,
1637 .BR nu ,
1638 .BR omega ,
1639 .BR \%omicron ,
1640 .BR phi ,
1641 .BR pi ,
1642 .BR psi ,
1643 .BR rho ,
1644 .BR sigma ,
1645 .BR tau ,
1646 .BR theta ,
1647 .BR \%upsilon ,
1648 .BR xi ,
1649 and
1650 .BR zeta .
1651 .
1652 Spell them with an initial capital letter
1653 .RB \%( Alpha )
1654 or in full capitals
1655 .RB \%( ALPHA )
1656 to obtain uppercase forms.
1657 .
1658 .
1659 .P
1660 GNU
1661 .I eqn \" GNU
1662 further defines the macros
1663 .BR cdot ,
1664 .BR cdots ,
1665 and
1666 .B utilde
1667 (all discussed above),
1668 .BR \%dollar ,
1669 which sets a dollar sign,
1670 and
1671 .BR ldots ,
1672 which sets an ellipsis on the text baseline.
1673 .
1674 .
1675 .\" ====================================================================
1676 .SS Fonts
1677 .\" ====================================================================
1678 .
1679 .I \%eqn
1680 uses up to three typefaces to set an equation:
1681 italic (oblique),
1682 roman (upright),
1683 and bold.
1684 .
1685 Assign each a
1686 .I groff
1687 typeface with the primitives
1688 .BR gfont ,
1689 .BR \%grfont ,
1690 and
1691 .B \%gbfont.
1692 .
1693 The defaults are the styles
1694 .BR I ,
1695 .BR R ,
1696 and
1697 .B B
1698 (applied to the current font family).
1699 .
1700 The
1701 .B \%chartype
1702 primitive
1703 (see above)
1704 sets a character's type,
1705 which determines the face used to set it.
1706 .
1707 The
1708 .RB \%\[lq] letter \[rq]
1709 type is set in italics;
1710 others are set in roman.
1711 .
1712 Use the
1713 .B bold
1714 primitive to select an (upright) bold style.
1715 .
1716 .
1717 .TP
1718 .BI gbfont\~ f
1719 .RI Select\~ f
1720 as the bold font.
1721 .
1722 This is a GNU extension.
1723 .
1724 .
1725 .TP
1726 .BI gfont\~ f
1727 .RI Select\~ f
1728 as the italic font.
1729 .
1730 .
1731 .TP
1732 .BI grfont\~ f
1733 .RI Select\~ f
1734 as the roman font.
1735 .
1736 This is a GNU extension.
1737 .
1738 .
1739 .br
1740 .ne 4v
1741 .\" ====================================================================
1742 .SH Options
1743 .\" ====================================================================
1744 .
1745 .B \-\-help
1746 displays a usage message,
1747 while
1748 .B \-v
1749 and
1750 .B \-\-version
1751 show version information;
1752 all exit afterward.
1753 .
1754 .
1755 .TP
1756 .B \-C
1757 Recognize
1758 .B .EQ
1759 and
1760 .B .EN
1761 even when followed by a character other than space or newline.
1762 .
1763 .
1764 .TP
1765 .BI \-d\~ xy
1766 Specify delimiters
1767 .I x
1768 for left
1769 .RI and\~ y
1770 for right ends
1771 of equations not bracketed by
1772 .BR .EQ / .EN .
1773 .
1774 .I x
1775 and
1776 .I y
1777 need not be distinct.
1778 .
1779 Any
1780 .RB \%\[lq] delim
1781 .IR xy \[rq]
1782 statements in the source file override this option.
1783 .
1784 .
1785 .TP
1786 .BI \-f\~ F
1787 is equivalent to
1788 .RB \[lq] gfont
1789 .IR F \[rq].
1790 .
1791 .
1792 .TP
1793 .BI \-m\~ n
1794 is equivalent to
1795 .RB \[lq] "set \%minimum_size"
1796 .IR n \[rq].
1797 .
1798 .
1799 .TP
1800 .BI \-M\~ dir
1801 Search
1802 .I dir
1803 for
1804 .I eqnrc
1805 before those listed in section \[lq]Description\[rq] above.
1806 .
1807 .
1808 .TP
1809 .B \-N
1810 Prohibit newlines within delimiters.
1811 .
1812 This option allows
1813 .I \%eqn
1814 to recover better from missing closing delimiters.
1815 .
1816 .
1817 .TP
1818 .BI \-p\~ n
1819 Set sub- and superscripts
1820 .IR n \~points
1821 smaller than the surrounding text.
1822 .
1823 This option is deprecated.
1824 .
1825 .I \%eqn
1826 normally sets sub- and superscripts at 70% of the type size of the
1827 surrounding text.
1828 .
1829 .
1830 .TP
1831 .B \-r
1832 Reduce the type size of subscripts at most once relative to the base
1833 type size for the equation.
1834 .
1835 .
1836 .TP
1837 .B \-R
1838 Don't load
1839 .IR eqnrc .
1840 .
1841 .
1842 .TP
1843 .BI \-s\~ n
1844 is equivalent to
1845 .RB \[lq] gsize
1846 .IR n \[rq].
1847 .
1848 This option is deprecated.
1849 .
1850 .
1851 .TP
1852 .BI \-T\~ dev
1853 Prepare output for the device
1854 .IR dev .
1855 .
1856 In most cases,
1857 the effect of this is to define a macro
1858 .I dev
1859 with a value
1860 .RB of\~ 1 ;
1861 .I eqnrc
1862 uses this to provide definitions appropriate for the device.
1863 .
1864 However,
1865 if the specified driver is \[lq]MathML\[rq],
1866 the output is MathML markup rather than
1867 .I \%troff
1868 input,
1869 and
1870 .I eqnrc
1871 is not loaded at all.
1872 .
1873 The default output device is
1874 .BR \%ps .
1875 .
1876 .
1877 .\" ====================================================================
1878 .SH Files
1879 .\" ====================================================================
1880 .
1881 .TP
1882 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:\%eqnrc
1883 Initialization file.
1884 .
1885 .
1886 .\" ====================================================================
1887 .SH "MathML mode limitations"
1888 .\" ====================================================================
1889 .
1890 MathML is designed on the assumption that it cannot know the exact
1891 physical characteristics of the media and devices on which it will
1892 be rendered.
1893 .
1894 It does not support control of motions and sizes to the same
1895 degree
1896 .I \%troff
1897 does.
1898 .
1899 .
1900 .IP \[bu] 2n
1901 .I \%eqn
1902 customization parameters have no effect on generated MathML.
1903 .
1904 .
1905 .IP \[bu]
1906 The
1907 .BR \%special ,
1908 .BR up ,
1909 .BR down ,
1910 .BR fwd ,
1911 and
1912 .B back
1913 primitives cannot be implemented,
1914 and yield a MathML \%\[lq]<merror>\[rq] message instead.
1915 .
1916 .
1917 .IP \[bu]
1918 The
1919 .B vcenter
1920 primitive is silently ignored,
1921 as centering on the math axis is the MathML default.
1922 .
1923 .
1924 .IP \[bu]
1925 Characters that
1926 .I \%eqn
1927 sets extra large in
1928 .I troff \" mode
1929 mode\[em]notably the integral sign\[em]may appear too small and need to
1930 have their \[lq]<mstyle>\[rq] wrappers adjusted by hand.
1931 .
1932 .
1933 .P
1934 As in its
1935 .I troff \" mode
1936 mode,
1937 .I \%eqn
1938 in MathML mode leaves the
1939 .B .EQ
1940 and
1941 .B .EN
1942 tokens in place,
1943 but emits nothing corresponding to
1944 .B \%delim
1945 delimiters.
1946 .
1947 They can,
1948 however,
1949 be recognized as character sequences that begin with \[lq]<math>\[rq],
1950 end with \[lq]</math>\[rq],
1951 and do not cross line boundaries.
1952 .
1953 .
1954 .\" ====================================================================
1955 .SH Caveats
1956 .\" ====================================================================
1957 .
1958 Tokens must be double-quoted in
1959 .I eqn \" generic
1960 input if they are not to be recognized as names of macros or primitives,
1961 or if they are to be interpreted by
1962 .IR troff . \" generic
1963 .
1964 In particular,
1965 short ones,
1966 like
1967 .RB \[lq] pi \[rq]
1968 and
1969 .RB \[lq] PI \[rq],
1970 can collide with
1971 .I troff \" generic
1972 identifiers.
1973 .
1974 For instance,
1975 the
1976 .I eqn \" generic
1977 command
1978 .RB \%\[lq]\^ "gfont PI" \^\[rq]
1979 does not select
1980 .IR groff 's
1981 Palatino italic font for the global italic face;
1982 you must use
1983 .RB \%\[lq]\^ "gfont \[dq]PI\[dq]" \^\[rq]
1984 instead.
1985 .
1986 .
1987 .P
1988 Delimited equations are set at the type size current at the beginning of
1989 the input line,
1990 not necessarily that immediately preceding the opening delimiter.
1991 .
1992 .
1993 .P
1994 Unlike \*[tx],
1995 .I eqn \" generic
1996 does not inherently distinguish displayed and inline equation styles;
1997 see the
1998 .B smallover
1999 primitive above.
2000 .
2001 However,
2002 macro packages frequently define
2003 .B EQ
2004 and
2005 .B EN
2006 macros such that the equation within is displayed.
2007 .
2008 These macros may accept arguments permitting the equation to be labeled
2009 or captioned;
2010 see the package's documentation.
2011 .
2012 .
2013 .\" ====================================================================
2014 .SH Bugs
2015 .\" ====================================================================
2016 .
2017 .I eqn \" generic
2018 abuses terminology\[em]its
2019 \[lq]equations\[rq]
2020 can be inequalities,
2021 bare expressions,
2022 or unintelligible gibberish.
2023 .
2024 But there's no changing it now.
2025 .
2026 .
2027 .P
2028 In
2029 .I nroff \" mode
2030 mode,
2031 lowercase Greek letters are rendered in roman instead of italic style.
2032 .
2033 .
2034 .P
2035 In MathML mode,
2036 the
2037 .B mark
2038 and
2039 .B lineup
2040 features don't work.
2041 .
2042 These could,
2043 in theory,
2044 be implemented with \%\[lq]<maligngroup>\[rq] elements.
2045 .
2046 .
2047 .P
2048 In MathML mode,
2049 each digit of a numeric literal gets a separate \[lq]<mn>\:</mn>\[rq]
2050 pair,
2051 and decimal points are tagged with \[lq]<mo>\:</mo>\[rq].
2052 .
2053 This is allowed by the specification,
2054 but inefficient.
2055 .
2056 .
2057 .\" ====================================================================
2058 .SH Examples
2059 .\" ====================================================================
2060 .
2061 We first illustrate
2062 .I \%eqn
2063 usage with a trigonometric identity.
2064 .
2065 .
2066 .RS
2067 .P
2068 .EX
2069 \&.EQ
2070 sin ( alpha + beta ) = sin alpha cos beta + cos alpha sin beta
2071 \&.EN
2072 .EE
2073 .if t \{\
2074 .
2075 .
2076 .P
2077 .RS
2078 .EQ
2079 sin ( alpha + beta ) = sin alpha cos beta + cos alpha sin beta
2080 .EN
2081 .RE
2082 .\}
2083 .RE
2084 .
2085 .
2086 .P
2087 It can be convenient to set up delimiters if mathematical content will
2088 appear frequently in running text.
2089 .
2090 .
2091 .RS
2092 .P
2093 .EX
2094 \&.EQ
2095 delim $$
2096 \&.EN
2097 .
2098 Having cached a table of logarithms,
2099 the property $ln ( x y ) = ln x + ln y$ sped calculations.
2100 .EE
2101 .if t \{\
2102 .
2103 .
2104 .P
2105 .RS
2106 .EQ
2107 delim $$
2108 .EN
2109 .
2110 Having cached a table of logarithms,
2111 the property $ln ( x y ) = ln x + ln y$ sped calculations.
2112 .
2113 .\" We _must_ shut delimiters back off when serially processing man
2114 .\" pages, or subsequent documents cannot safely use those characters.
2115 .EQ
2116 delim off
2117 .EN
2118 .RE
2119 .\}
2120 .RE
2121 .
2122 .
2123 .P
2124 The quadratic formula illustrates use of fractions and radicals,
2125 and affords an opportunity to use the full space token
2126 .BR \[ti] .
2127 .
2128 .
2129 .RS
2130 .P
2131 .EX
2132 \&.EQ
2133 x = { \- b \[ti] \[rs][+\-] \[ti] sqrt { b sup 2 \- 4 a c } } \
2134 over { 2 a }
2135 \&.EN
2136 .EE
2137 .if t \{\
2138 .
2139 .
2140 .P
2141 .RS
2142 .EQ
2143 x = { - b ~ \[+-] ~ sqrt { b sup 2 - 4 a c } } over { 2 a }
2144 .EN
2145 .RE
2146 .\}
2147 .RE
2148 .
2149 .
2150 .P
2151 Alternatively,
2152 we could define the plus-minus sign as a binary operator.
2153 .
2154 Automatic spacing puts 0.06\~em less space on either side of the
2155 plus-minus than \[ti] does,
2156 this being the difference between the widths of the
2157 .B medium_space
2158 parameter used by binary operators and that of the full space.
2159 .
2160 Independently,
2161 we can define a macro \[lq]frac\[rq] for setting fractions.
2162 .
2163 .
2164 .RS
2165 .P
2166 .EX
2167 \&.EQ
2168 chartype "binary" \[rs][+\-]
2169 define frac ! { $1 } over { $2 } !
2170 x = frac(\- b \[rs][+\-] sqrt { b sup 2 \- 4 a c }, 2 a)
2171 \&.EN
2172 .EE
2173 .if t \{\
2174 .
2175 .
2176 .P
2177 .RS
2178 .EQ
2179 chartype "binary" \[+-]
2180 define frac ! { $1 } over { $2 } !
2181 x = frac(- b \[+-] sqrt { b sup 2 - 4 a c }, 2 a)
2182 .EN
2183 .RE
2184 .\}
2185 .RE
2186 .
2187 .
2188 .\" ====================================================================
2189 .SH "See also"
2190 .\" ====================================================================
2191 .
2192 \[lq]Typesetting Mathematics\[em]User's Guide\[rq]
2193 (2nd edition),
2194 by Brian W.\& Kernighan
2195 and Lorinda L.\& Cherry,
2196 1978,
2197 AT&T Bell Laboratories Computing Science Technical Report No.\& 17.
2198 .
2199 .
2200 .P
2201 .IR The\~\*[tx]book ,
2202 by Donald E.\& Knuth,
2203 1984,
2204 Addison-Wesley Professional.
2205 .
2206 Appendix\~G
2207 discusses many of the parameters from section \[lq]Customization\[rq]
2208 above in greater detail.
2209 .
2210 .
2211 .P
2212 .MR groff_char 7 ,
2213 particularly subsections \[lq]Logical symbols\[rq],
2214 \[lq]Mathematical symbols\[rq],
2215 and \[lq]Greek glyphs\[rq],
2216 documents a variety of special character escape sequences useful in
2217 mathematical typesetting.
2218 .
2219 .
2220 .P
2221 .MR groff 1 ,
2222 .MR \%troff 1 ,
2223 .MR \%pic 1 ,
2224 .MR groff_font 5
2225 .
2226 .
2227 .\" Clean up.
2228 .rm tx
2229 .
2230 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
2231 .cp \n[*groff_eqn_1_man_C]
2232 .do rr *groff_eqn_1_man_C
2233 .
2234 .
2235 .\" Local Variables:
2236 .\" fill-column: 72
2237 .\" mode: nroff
2238 .\" tab-width: 12
2239 .\" End:
2240 .\" vim: set filetype=groff tabstop=12 textwidth=72: