| blob | e194ecf48c4ca686b28573b5ffe496907f4c86fb |
1 .ig \"-*- nroff -*-
2 Copyright (C) 1989-2000 Free Software Foundation, Inc.
4 Permission is granted to make and distribute verbatim copies of
5 this manual provided the copyright notice and this permission notice
6 are preserved on all copies.
8 Permission is granted to copy and distribute modified versions of this
9 manual under the conditions for verbatim copying, provided that the
10 entire resulting derived work is distributed under the terms of a
11 permission notice identical to this one.
13 Permission is granted to copy and distribute translations of this
14 manual into another language, under the above conditions for modified
15 versions, except that this permission notice may be included in
16 translations approved by the Free Software Foundation instead of in
17 the original English.
18 ..
19 .ie \n(.V<\n(.v .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
20 .el .ds tx TeX
21 .\" Like TP, but if specified indent is more than half
22 .\" the current line-length - indent, use the default indent.
23 .de Tp
24 .ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
25 .el .TP "\\$1"
26 ..
27 .\" The BSD man macros can't handle " in arguments to font change macros,
28 .\" so use \(ts instead of ".
29 .tr \(ts"
30 .TH @G@EQN @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
31 .SH NAME
32 @g@eqn \- format equations for troff
33 .SH SYNOPSIS
34 .nr a \n(.j
35 .ad l
36 .nr i \n(.i
37 .in +\w'\fB@g@eqn 'u
38 .ti \niu
39 .B @g@eqn
40 .de OP
41 .ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]"
42 .el .RB "[\ " "\\$1" "\ ]"
43 ..
44 .OP \-rvCNR
45 .OP \-d cc
46 .OP \-T name
47 .OP \-M dir
48 .OP \-f F
49 .OP \-s n
50 .OP \-p n
51 .OP \-m n
52 .RI "[\ " files\|.\|.\|. "\ ]"
53 .br
54 .ad \na
55 .PP
56 It is possible to have whitespace between a command line option and its
57 parameter.
58 .SH DESCRIPTION
59 This manual page describes the GNU version of
60 .BR eqn ,
61 which is part of the groff document formatting system.
62 .B eqn
63 compiles descriptions of equations embedded within
64 .B troff
65 input files into commands that are understood by
66 .BR troff .
67 Normally, it should be invoked using the
68 .B \-e
69 option of
70 .BR groff .
71 The syntax is quite compatible with Unix eqn.
72 The output of GNU eqn cannot be processed with Unix troff;
73 it must be processed with GNU troff.
74 If no files are given on the command line, the standard input
75 will be read.
76 A filename of
77 .B \-
78 will cause the standard input to be read.
79 .LP
80 .B eqn
81 searches for the file
82 .B eqnrc
83 using the path
84 .BR @MACROPATH@ .
85 If it exists, eqn will process it before the other input files.
86 The
87 .B \-R
88 option prevents this.
89 .LP
90 GNU eqn does not provide the functionality of neqn:
91 it does not support low-resolution, typewriter-like devices
92 (although it may work adequately for very simple input).
93 .SH OPTIONS
94 .TP
95 .B \-C
96 Recognize
97 .B .EQ
98 and
99 .B .EN
100 even when followed by a character other than space or newline.
101 .TP
102 .B \-N
103 Don't allow newlines within delimiters.
104 This option allows
105 .B eqn
106 to recover better from missing closing delimiters.
107 .TP
108 .B \-v
109 Print the version number.
110 .TP
111 .B \-r
112 Only one size reduction.
113 .TP
114 .BI \-m n
115 The minimum point-size is
116 .IR n .
117 eqn will not reduce the size of subscripts or superscripts to
118 a smaller size than
119 .IR n .
120 .TP
121 .BI \-T name
122 The output is for device
123 .IR name .
124 The only effect of this is to define a macro
125 .I name
126 with a value of
127 .BR 1 .
128 Typically
129 .B eqnrc
130 will use this to provide definitions appropriate for the output device.
131 The default output device is
132 .BR @DEVICE@ .
133 .TP
134 .BI \-M dir
135 Search
136 .I dir
137 for
138 .B eqnrc
139 before the default directories.
140 .TP
141 .B \-R
142 Don't load
143 .BR eqnrc .
144 .TP
145 .BI \-f F
146 This is equivalent to a
147 .BI gfont\ F
148 command.
149 .TP
150 .BI \-s n
151 This is equivalent to a
152 .BI gsize\ n
153 command.
154 This option is deprecated.
155 eqn will normally set equations at whatever the current point size
156 is when the equation is encountered.
157 .TP
158 .BI \-p n
159 This says that subscripts and superscripts should be
160 .I n
161 points smaller than the surrounding text.
162 This option is deprecated.
163 Normally eqn makes sets subscripts and superscripts at 70%
164 of the size of the surrounding text.
165 .SH USAGE
166 Only the differences between GNU eqn and Unix eqn are described here.
167 .LP
168 Most of the new features of GNU eqn
169 are based on \*(tx.
170 There are some references to the differences between \*(tx and GNU eqn below;
171 these may safely be ignored if you do not know \*(tx.
172 .SS Automatic spacing
173 .LP
174 .B eqn
175 gives each component of an equation a type, and adjusts the spacing
176 between components using that type.
177 Possible types are:
178 .TP \w'punctuation'u+2n
179 ordinary
180 an ordinary character such as 1 or
181 .IR x ;
182 .TP
183 operator
184 a large operator such as
185 .ds Su \s+5\(*S\s0
186 .if \n(.g .if !c\(*S .ds Su the summation operator
187 \*(Su;
188 .TP
189 binary
190 a binary operator such as +;
191 .TP
192 relation
193 a relation such as =;
194 .TP
195 opening
196 a opening bracket such as (;
197 .TP
198 closing
199 a closing bracket such as );
200 .TP
201 punctuation
202 a punctuation character such as ,;
203 .TP
204 inner
205 a subformula contained within brackets;
206 .TP
207 suppress
208 spacing that suppresses automatic spacing adjustment.
209 .LP
210 Components of an equation get a type in one of two ways.
211 .TP
212 .BI type\ t\ e
213 This yields an equation component that contains
214 .I e
215 but that has type
216 .IR t ,
217 where
218 .I t
219 is one of the types mentioned above.
220 For example,
221 .B times
222 is defined as
223 .RS
224 .IP
225 .B
226 type "binary" \e(mu
227 .RE
228 .IP
229 The name of the type doesn't have to be quoted, but quoting protects
230 from macro expansion.
231 .TP
232 .BI chartype\ t\ text
233 Unquoted groups of characters are split up into individual characters,
234 and the type of each character is looked up;
235 this changes the type that is stored for each character;
236 it says that the characters in
237 .I text
238 from now on have type
239 .IR t .
240 For example,
241 .RS
242 .IP
243 .B
244 chartype "punctuation" .,;:
245 .RE
246 .IP
247 would make the characters
248 .B .,;:
249 have type punctuation
250 whenever they subsequently appeared in an equation.
251 The type
252 .I t
253 can also be
254 .B letter
255 or
256 .BR digit ;
257 in these cases
258 .B chartype
259 changes the font type of the characters.
260 See the Fonts subsection.
261 .SS New primitives
262 .TP
263 .IB e1\ smallover\ e2
264 This is similar to
265 .BR over ;
266 .B smallover
267 reduces the size of
268 .I e1
269 and
270 .IR e2 ;
271 it also puts less vertical space between
272 .I e1
273 or
274 .I e2
275 and the fraction bar.
276 The
277 .B over
278 primitive corresponds to the \*(tx
279 .B \eover
280 primitive in display styles;
281 .B smallover
282 corresponds to
283 .B \eover
284 in non-display styles.
285 .TP
286 .BI vcenter\ e
287 This vertically centers
288 .I e
289 about the math axis.
290 The math axis is the vertical position about which characters
291 such as + and - are centered; also it is the vertical position
292 used for the bar of fractions.
293 For example,
294 .B sum
295 is defined as
296 .RS
297 .IP
298 .B
299 { type "operator" vcenter size +5 \e(*S }
300 .RE
301 .TP
302 .IB e1\ accent\ e2
303 This sets
304 .I e2
305 as an accent over
306 .IR e1 .
307 .I e2
308 is assumed to be at the correct height for a lowercase letter;
309 .I e2
310 will be moved down according if
311 .I e1
312 is taller or shorter than a lowercase letter.
313 For example,
314 .B hat
315 is defined as
316 .RS
317 .IP
318 .B
319 accent { "^" }
320 .RE
321 .IP
322 .BR dotdot ,
323 .BR dot ,
324 .BR tilde ,
325 .B vec
326 and
327 .B dyad
328 are also defined using the
329 .B accent
330 primitive.
331 .TP
332 .IB e1\ uaccent\ e2
333 This sets
334 .I e2
335 as an accent under
336 .IR e1 .
337 .I e2
338 is assumed to be at the correct height for a character without a descender;
339 .I e2
340 will be moved down if
341 .I e1
342 has a descender.
343 .B utilde
344 is pre-defined using
345 .B uaccent
346 as a tilde accent below the baseline.
347 .TP
348 .BI split\ \(ts text \(ts
349 This has the same effect as simply
350 .RS
351 .IP
352 .I text
353 .RE
354 .IP
355 but
356 .I text
357 is not subject to macro expansion because it is quoted;
358 .I text
359 will be split up and the spacing between individual characters
360 will be adjusted.
361 .TP
362 .BI nosplit\ text
363 This has the same effect as
364 .RS
365 .IP
366 .BI \(ts text \(ts
367 .RE
368 .IP
369 but because
370 .I text
371 is not quoted it will be subject to macro expansion;
372 .I text
373 will not be split up
374 and the spacing between individual characters will not be adjusted.
375 .TP
376 .IB e\ opprime
377 This is a variant of
378 .B prime
379 that acts as an operator on
380 .IR e .
381 It produces a different result from
382 .B prime
383 in a case such as
384 .BR A\ opprime\ sub\ 1 :
385 with
386 .B opprime
387 the
388 .B 1
389 will be tucked under the prime as a subscript to the
390 .B A
391 (as is conventional in mathematical typesetting),
392 whereas with
393 .B prime
394 the
395 .B 1
396 will be a subscript to the prime character.
397 The precedence of
398 .B opprime
399 is the same as that of
400 .B bar
401 and
402 .BR under ,
403 which is higher than that of everything except
404 .B accent
405 and
406 .BR uaccent .
407 In unquoted text a
408 .B '
409 that is not the first character will be treated like
410 .BR opprime .
411 .TP
412 .BI special\ text\ e
413 This constructs a new object from
414 .I e
415 using a
416 .BR @g@troff (@MAN1EXT@)
417 macro named
418 .IR text .
419 When the macro is called,
420 the string
421 .B 0s
422 will contain the output for
423 .IR e ,
424 and the number registers
425 .BR 0w ,
426 .BR 0h ,
427 .BR 0d ,
428 .BR 0skern
429 and
430 .BR 0skew
431 will contain the width, height, depth, subscript kern, and skew of
432 .IR e .
433 (The
434 .I "subscript kern"
435 of an object says how much a subscript on that object should be tucked in;
436 the
437 .I skew
438 of an object says how far to the right of the center of the object an
439 accent over the object should be placed.)
440 The macro must modify
441 .B 0s
442 so that it will output the desired result with its origin at the current
443 point, and increase the current horizontal position by the width
444 of the object.
445 The number registers must also be modified so that they correspond to the
446 result.
447 .RS
448 .LP
449 For example, suppose you wanted a construct that `cancels' an expression
450 by drawing a diagonal line through it.
451 .IP
452 .nf
453 .ft B
454 .ne 6+\n(.Vu
455 \&.EQ
456 define cancel 'special Ca'
457 \&.EN
458 \&.de Ca
459 \&.ds 0s \eZ'\e\e*(0s'\ev'\e\en(0du'\eD'l \e\en(0wu -\e\en(0hu-\e\en(0du'\ev'\e\en(0hu'
460 \&..
461 .ft
462 .fi
463 .LP
464 Then you could cancel an expression
465 .I e
466 with
467 .BI cancel\ {\ e\ }
468 .LP
469 Here's a more complicated construct that draws a box round an expression:
470 .IP
471 .nf
472 .ft B
473 .ne 11+\n(.Vu
474 \&.EQ
475 define box 'special Bx'
476 \&.EN
477 \&.de Bx
478 \&.ds 0s \eZ'\eh'1n'\e\e*(0s'\e
479 \eZ'\ev'\e\en(0du+1n'\eD'l \e\en(0wu+2n 0'\eD'l 0 -\e\en(0hu-\e\en(0du-2n'\e
480 \eD'l -\e\en(0wu-2n 0'\eD'l 0 \e\en(0hu+\e\en(0du+2n''\eh'\e\en(0wu+2n'
481 \&.nr 0w +2n
482 \&.nr 0d +1n
483 \&.nr 0h +1n
484 \&..
485 .ft
486 .fi
487 .RE
488 .SS Customization
489 The appearance of equations is controlled by
490 a large number of parameters. These can be set using
491 the
492 .B set
493 command.
494 .TP
495 .BI set\ p\ n
496 This sets parameter
497 .I p
498 to value
499 .I n ;
500 .I n
501 is an integer.
502 For example,
503 .RS
504 .IP
505 .B
506 set x_height 45
507 .RE
508 .IP
509 says that
510 .B eqn
511 should assume an x height of 0.45 ems.
512 .RS
513 .LP
514 Possible parameters are as follows.
515 Values are in units of hundredths of an em unless otherwise stated.
516 These descriptions are intended to be expository rather than
517 definitive.
518 .TP \w'\fBdefault_rule_thickness'u+2n
519 .B minimum_size
520 .B eqn
521 will not set anything at a smaller point-size than this.
522 The value is in points.
523 .TP
524 .B fat_offset
525 The
526 .B fat
527 primitive emboldens an equation
528 by overprinting two copies of the equation
529 horizontally offset by this amount.
530 .TP
531 .B over_hang
532 A fraction bar will be longer by twice this amount than
533 the maximum of the widths of the numerator and denominator;
534 in other words, it will overhang the numerator and
535 denominator by at least this amount.
536 .TP
537 .B accent_width
538 When
539 .B bar
540 or
541 .B under
542 is applied to a single character,
543 the line will be this long.
544 Normally,
545 .B bar
546 or
547 .B under
548 produces a line whose length is the width of the object to which it applies;
549 in the case of a single character,
550 this tends to produce a line that looks too long.
551 .TP
552 .B delimiter_factor
553 Extensible delimiters produced with the
554 .B left
555 and
556 .B right
557 primitives will have a combined height and depth of at least this many
558 thousandths of twice the maximum amount by which the sub-equation that
559 the delimiters enclose extends away from the axis.
560 .TP
561 .B delimiter_shortfall
562 Extensible delimiters produced with the
563 .B left
564 and
565 .B right
566 primitives will have a combined height and depth
567 not less than the difference of
568 twice the maximum amount by which the sub-equation that
569 the delimiters enclose extends away from the axis
570 and this amount.
571 .TP
572 .B null_delimiter_space
573 This much horizontal space is inserted
574 on each side of a fraction.
575 .TP
576 .B script_space
577 The width of subscripts and superscripts is increased by this amount.
578 .TP
579 .B thin_space
580 This amount of space is automatically inserted after punctuation
581 characters.
582 .TP
583 .B medium_space
584 This amount of space is automatically inserted on either side
585 of binary operators.
586 .TP
587 .B thick_space
588 This amount of space is automatically inserted on either side of
589 relations.
590 .TP
591 .B x_height
592 The height of lowercase letters without ascenders such as x.
593 .TP
594 .B axis_height
595 The height above the baseline of the center of characters
596 such as \(pl and \(mi.
597 It is important that this value is correct for the font
598 you are using.
599 .TP
600 .B default_rule_thickness
601 This should set to the thickness of the
602 .B \e(ru
603 character, or the thickness of horizontal lines produced with the
604 .B \eD
605 escape sequence.
606 .TP
607 .B num1
608 The
609 .B over
610 command will shift up the numerator by at least this amount.
611 .TP
612 .B num2
613 The
614 .B smallover
615 command will shift up the numerator by at least this amount.
616 .TP
617 .B denom1
618 The
619 .B over
620 command will shift down the denominator by at least this amount.
621 .TP
622 .B denom2
623 The
624 .B smallover
625 command will shift down the denominator by at least this amount.
626 .TP
627 .B sup1
628 Normally superscripts will be shifted up by at least this amount.
629 .TP
630 .B sup2
631 Superscripts within superscripts or upper limits
632 or numerators of
633 .B smallover
634 fractions
635 will be shifted up by at least this amount.
636 This is usually less than sup1.
637 .TP
638 .B sup3
639 Superscripts within denominators or square roots
640 or subscripts or lower limits will be shifted up by at least
641 this amount.
642 This is usually less than sup2.
643 .TP
644 .B sub1
645 Subscripts will normally be shifted down by at least this amount.
646 .TP
647 .B sub2
648 When there is both a subscript and a superscript, the subscript
649 will be shifted down by at least this amount.
650 .TP
651 .B sup_drop
652 The baseline of a superscript will be no more
653 than this much amount below the top of the object on
654 which the superscript is set.
655 .TP
656 .B sub_drop
657 The baseline of a subscript will be at least this much below
658 the bottom of the object on which the subscript is set.
659 .TP
660 .B big_op_spacing1
661 The baseline of an upper limit will be at least this
662 much above the top of the object on which the limit is set.
663 .TP
664 .B big_op_spacing2
665 The baseline of a lower limit will be at least this
666 much below the bottom of the object on which the limit is set.
667 .TP
668 .B big_op_spacing3
669 The bottom of an upper limit will be at least this much above the
670 top of the object on which the limit is set.
671 .TP
672 .B big_op_spacing4
673 The top of a lower limit will be at least this much below
674 the bottom of the object on which the limit is set.
675 .TP
676 .B big_op_spacing5
677 This much vertical space will be added above and below limits.
678 .TP
679 .B baseline_sep
680 The baselines of the rows in a pile or matrix will normally be
681 this far apart.
682 In most cases this should be equal to the sum of
683 .B num1
684 and
685 .BR denom1 .
686 .TP
687 .B shift_down
688 The midpoint between the top baseline and the bottom baseline
689 in a matrix or pile will be shifted down by this much from the axis.
690 In most cases this should be equal to
691 .BR axis_height .
692 .TP
693 .B column_sep
694 This much space will be added between columns in a matrix.
695 .TP
696 .B matrix_side_sep
697 This much space will be added at each side of a matrix.
698 .TP
699 .B draw_lines
700 If this is non-zero, lines will be drawn using the
701 .B \eD
702 escape sequence, rather than with the
703 .B \el
704 escape sequence and the
705 .B \e(ru
706 character.
707 .TP
708 .B body_height
709 The amount by which the height of the equation exceeds this
710 will be added as extra space before the line containing the equation
711 (using
712 .BR \ex .)
713 The default value is 85.
714 .TP
715 .B body_depth
716 The amount by which the depth of the equation exceeds this
717 will be added as extra space after the line containing the equation
718 (using
719 .BR \ex .)
720 The default value is 35.
721 .TP
722 .B nroff
723 If this is non-zero,
724 then
725 .B ndefine
726 will behave like
727 .B define
728 and
729 .B tdefine
730 will be ignored,
731 otherwise
732 .B tdefine
733 will behave like
734 .B define
735 and
736 .B ndefine
737 will be ignored.
738 The default value is 0
739 (This is typically changed to 1 by the
740 .B eqnrc
741 file for the
742 .BR ascii ,
743 .BR latin1 ,
744 .BR utf8 ,
745 and
746 .B cp1047
747 devices.)
748 .LP
749 A more precise description of the role of many of these
750 parameters can be found in Appendix H of
751 .IR The\ \*(txbook .
752 .RE
753 .SS Macros
754 Macros can take arguments.
755 In a macro body,
756 .BI $ n
757 where
758 .I n
759 is between 1 and 9,
760 will be replaced by the
761 .IR n-th
762 argument if the macro is called with arguments;
763 if there are fewer than
764 .I n
765 arguments, it will be replaced by nothing.
766 A word containing a left parenthesis where the part of the word
767 before the left parenthesis has been defined using the
768 .B define
769 command
770 will be recognized as a macro call with arguments;
771 characters following the left parenthesis
772 up to a matching right parenthesis will be treated as comma-separated
773 arguments;
774 commas inside nested parentheses do not terminate an argument.
775 .TP
776 .BI sdefine\ name\ X\ anything\ X
777 This is like the
778 .B define
779 command, but
780 .I name
781 will not be recognized if called with arguments.
782 .TP
783 .BI include\ \(ts file \(ts
784 Include the contents of
785 .IR file .
786 Lines of
787 .I file
788 beginning with
789 .B .EQ
790 or
791 .B .EN
792 will be ignored.
793 .TP
794 .BI ifdef\ name\ X\ anything\ X
795 If
796 .I name
797 has been defined by
798 .B define
799 (or has been automatically defined because
800 .I name
801 is the output device)
802 process
803 .IR anything ;
804 otherwise ignore
805 .IR anything .
806 .I X
807 can be any character not appearing in
808 .IR anything .
809 .SS Fonts
810 .B eqn
811 normally uses at least two fonts to set an equation:
812 an italic font for letters,
813 and a roman font for everything else.
814 The existing
815 .B gfont
816 command
817 changes the font that is used as the italic font.
818 By default this is
819 .BR I .
820 The font that is used as the roman font can be changed
821 using the new
822 .B grfont
823 command.
824 .TP
825 .BI grfont\ f
826 Set the roman font to
827 .IR f .
828 .LP
829 The
830 .B italic
831 primitive uses the current italic font set by
832 .BR gfont ;
833 the
834 .B roman
835 primitive uses the current roman font set by
836 .BR grfont .
837 There is also a new
838 .B gbfont
839 command, which changes the font used by the
840 .B bold
841 primitive.
842 If you only use the
843 .BR roman ,
844 .B italic
845 and
846 .B bold
847 primitives to changes fonts within an equation,
848 you can change all the fonts used by your equations
849 just by using
850 .BR gfont ,
851 .B grfont
852 and
853 .B gbfont
854 commands.
855 .LP
856 You can control which characters are treated as letters
857 (and therefore set in italics) by using the
858 .B chartype
859 command described above.
860 A type of
861 .B letter
862 will cause a character to be set in italic type.
863 A type of
864 .B digit
865 will cause a character to be set in roman type.
866 .SH FILES
867 .Tp \w'\fB@MACRODIR@/eqnrc'u+2n
868 .B @MACRODIR@/eqnrc
869 Initialization file.
870 .SH BUGS
871 Inline equations will be set at the point size that is current at the
872 beginning of the input line.
873 .SH "SEE ALSO"
874 .BR groff (@MAN1EXT@),
875 .BR @g@troff (@MAN1EXT@),
876 .BR groff_font (@MAN5EXT@),
877 .I The\ \*(txbook