* src/preproc/eqn/eqn.man: Revised.
[s-roff.git] / src / preproc / eqn / eqn.man
blob4f0696bdd883de464e18d725034fd27cbce6a3f9
1 .ig
2 Copyright (C) 1989-2000, 2001, 2004 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.
21 .ie \n(.V<\n(.v \
22 .  ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
23 .el \
24 .  ds tx TeX
27 .\" Like TP, but if specified indent is more than half
28 .\" the current line-length - indent, use the default indent.
29 .de Tp
30 .  ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
31 .  el .TP "\\$1"
35 .\" The BSD man macros can't handle " in arguments to font change macros,
36 .\" so use \(ts instead of ".
37 .tr \(ts"
40 .TH @G@EQN @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
43 .SH NAME
44 @g@eqn \- format equations for troff
47 .SH SYNOPSIS
48 .nr a \n(.j
49 .ad l
50 .nr i \n(.i
51 .in +\w'\fB@g@eqn 'u
52 .ti \niu
53 .B @g@eqn
54 .de OP
55 .  ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]"
56 .  el .RB "[\ " "\\$1" "\ ]"
58 .OP \-rvCNR
59 .OP \-d xy
60 .OP \-T name
61 .OP \-M dir
62 .OP \-f F
63 .OP \-s n
64 .OP \-p n
65 .OP \-m n
66 .RI "[\ " files\|.\|.\|. "\ ]"
67 .br
68 .ad \na
70 .LP
71 It is possible to have whitespace between a command line option and its
72 parameter.
75 .SH DESCRIPTION
76 This manual page describes the GNU version of
77 .BR eqn ,
78 which is part of the groff document formatting system.
79 .B eqn
80 compiles descriptions of equations embedded within
81 .B troff
82 input files into commands that are understood by
83 .BR troff .
84 Normally, it should be invoked using the
85 .B \-e
86 option of
87 .BR groff .
88 The syntax is quite compatible with Unix eqn.
89 The output of GNU
90 .B eqn
91 cannot be processed with Unix troff;
92 it must be processed with GNU troff.
93 If no files are given on the command line, the standard input
94 will be read.
95 A filename of
96 .B \-
97 will cause the standard input to be read.
99 .LP
100 .B eqn
101 searches for the file
102 .B eqnrc
103 in the directories given with the
104 .B \-M
105 option first, then in
106 .BR @SYSTEMMACRODIR@ ,
107 .BR @LOCALMACRODIR@ ,
108 and finally in the standard macro directory
109 .BR @MACRODIR@ .
110 If it exists,
111 .B eqn
112 will process it before the other input files.
114 .B \-R
115 option prevents this.
119 .B eqn
120 does not provide the functionality of neqn:
121 it does not support low-resolution, typewriter-like devices
122 (although it may work adequately for very simple input).
125 .SH OPTIONS
127 .BI \-d xy
128 Specify delimiters
129 .I x
130 and\~\c
131 .I y
132 for the left and right end, respectively, of in-line equations.
134 .B delim
135 statements in the source file overrides this.
138 .B \-C
139 Recognize
140 .B .EQ
142 .B .EN
143 even when followed by a character other than space or newline.
145 .B \-N
146 Don't allow newlines within delimiters.
147 This option allows
148 .B eqn
149 to recover better from missing closing delimiters.
152 .B \-v
153 Print the version number.
156 .B \-r
157 Only one size reduction.
160 .BI \-m n
161 The minimum point-size is\~\c
162 .IR n .
163 .B eqn
164 will not reduce the size of subscripts or superscripts to
165 a smaller size than\~\c
166 .IR n .
169 .BI \-T name
170 The output is for device
171 .IR name .
172 The only effect of this is to define a macro
173 .I name
174 with a value of\~\c
175 .BR 1 .
176 Typically
177 .B eqnrc
178 will use this to provide definitions appropriate for the output device.
179 The default output device is
180 .BR @DEVICE@ .
183 .BI \-M dir
184 Search
185 .I dir
187 .B eqnrc
188 before the default directories.
191 .B \-R
192 Don't load
193 .BR eqnrc .
196 .BI \-f F
197 This is equivalent to a
198 .BI gfont\  F
199 command.
202 .BI \-s n
203 This is equivalent to a
204 .BI gsize\  n
205 command.
206 This option is deprecated.
207 .B eqn
208 will normally set equations at whatever the current point size
209 is when the equation is encountered.
212 .BI \-p n
213 This says that subscripts and superscripts should be
214 .I n\~\c
215 points smaller than the surrounding text.
216 This option is deprecated. 
217 Normally
218 .B eqn
219 makes sets subscripts and superscripts at 70% 
220 of the size of the surrounding text.
223 .SH USAGE
224 Only the differences between GNU
225 .B eqn
226 and Unix eqn are described here.
229 Most of the new features of GNU
230 .B eqn
231 are based on \*(tx.
232 There are some references to the differences between \*(tx and GNU
233 .B eqn
234 below;
235 these may safely be ignored if you do not know \*(tx.
237 .SS Automatic spacing
238 .B eqn
239 gives each component of an equation a type, and adjusts the spacing
240 between components using that type.
241 Possible types are:
244 .TP \w'punctuation'u+2n
245 ordinary
246 an ordinary character such as `1' or `\c
247 .IR x ';
250 operator
251 a large operator such as
252 .ds Su `\s+5\(*S\s0'
253 .if \n(.g .if !c\(*S .ds Su the summation operator
254 \*(Su;
257 binary
258 a binary operator such as `\(pl';
261 relation
262 a relation such as `=';
265 opening
266 a opening bracket such as `(';
269 closing
270 a closing bracket such as `)';
273 punctuation
274 a punctuation character such as `,';
277 inner
278 a subformula contained within brackets;
280 suppress
281 spacing that suppresses automatic spacing adjustment.
285 Components of an equation get a type in one of two ways.
288 .BI type\  t\ e
289 This yields an equation component that contains\~\c
290 .I e
291 but that has type\~\c
292 .IR t ,
293 where
294 .I t
295 is one of the types mentioned above.
296 For example,
297 .B times
298 is defined as
303 type "binary" \e(mu
307 The name of the type doesn't have to be quoted, but quoting protects
308 from macro expansion.
311 .BI chartype\  t\ text
312 Unquoted groups of characters are split up into individual characters,
313 and the type of each character is looked up;
314 this changes the type that is stored for each character;
315 it says that the characters in
316 .I text
317 from now on have type\~\c
318 .IR t .
319 For example,
324 chartype "punctuation" .,;:
328 would make the characters `.,;:' have type punctuation
329 whenever they subsequently appeared in an equation.
330 The type\~\c
331 .I t
332 can also be
333 .B letter
335 .BR digit ;
336 in these cases
337 .B chartype
338 changes the font type of the characters.
339 See the
340 .B Fonts
341 subsection.
343 .SS New primitives
345 .IB e1\  smallover\  e2
346 This is similar to
347 .BR over ;
348 .B smallover
349 reduces the size of
350 .I e1
352 .IR e2 ;
353 it also puts less vertical space between
354 .I e1
356 .I e2
357 and the fraction bar.
359 .B over
360 primitive corresponds to the \*(tx
361 .B \eover
362 primitive in display styles;
363 .B smallover
364 corresponds to
365 .B \eover
366 in non-display styles.
369 .BI vcenter\  e
370 This vertically centers
371 .I e
372 about the math axis.
373 The math axis is the vertical position about which characters
374 such as `\(pl' and `\(mi' are centered; also it is the vertical position
375 used for the bar of fractions.
376 For example,
377 .B sum
378 is defined as
383 { type "operator" vcenter size +5 \e(*S }
387 .IB e1\  accent\  e2
388 This sets
389 .I e2
390 as an accent over
391 .IR e1 .
392 .I e2
393 is assumed to be at the correct height for a lowercase letter;
394 .I e2
395 will be moved down according if
396 .I e1
397 is taller or shorter than a lowercase letter.
398 For example,
399 .B hat
400 is defined as
405 accent { "^" }
409 .BR dotdot ,
410 .BR dot ,
411 .BR tilde ,
412 .BR vec ,
414 .B dyad
415 are also defined using the
416 .B accent
417 primitive.
420 .IB e1\  uaccent\  e2
421 This sets
422 .I e2
423 as an accent under
424 .IR e1 .
425 .I e2
426 is assumed to be at the correct height for a character without a descender;
427 .I e2
428 will be moved down if
429 .I e1
430 has a descender.
431 .B utilde
432 is pre-defined using
433 .B uaccent
434 as a tilde accent below the baseline.
437 .BI split\ \(ts text \(ts
438 This has the same effect as simply
442 .I text
447 .I text
448 is not subject to macro expansion because it is quoted;
449 .I text
450 will be split up and the spacing between individual characters
451 will be adjusted.
454 .BI nosplit\  text
455 This has the same effect as
459 .BI \(ts text \(ts
463 but because
464 .I text
465 is not quoted it will be subject to macro expansion;
466 .I text
467 will not be split up
468 and the spacing between individual characters will not be adjusted.
471 .IB e\  opprime
472 This is a variant of
473 .B prime
474 that acts as an operator on\~\c
475 .IR e .
476 It produces a different result from
477 .B prime
478 in a case such as
479 .BR A\ opprime\ sub\ 1 :
480 with
481 .B opprime
482 the\~\c
483 .B 1
484 will be tucked under the prime as a subscript to the\~\c
485 .B A
486 (as is conventional in mathematical typesetting),
487 whereas with
488 .B prime
489 the\~\c
490 .B 1
491 will be a subscript to the prime character.
492 The precedence of
493 .B opprime
494 is the same as that of
495 .B bar
497 .BR under ,
498 which is higher than that of everything except
499 .B accent
501 .BR uaccent .
502 In unquoted text a\~\c
503 .B '
504 that is not the first character will be treated like
505 .BR opprime .
508 .BI special\  text\ e
509 This constructs a new object from\~\c
510 .I e
511 using a
512 .BR @g@troff (@MAN1EXT@)
513 macro named
514 .IR text .
515 When the macro is called,
516 the string
517 .B 0s
518 will contain the output for\~\c
519 .IR e ,
520 and the number registers
521 .BR 0w ,
522 .BR 0h ,
523 .BR 0d ,
524 .BR 0skern ,
526 .BR 0skew
527 will contain the width, height, depth, subscript kern, and skew of\~\c
528 .IR e .
529 (The
530 .I "subscript kern"
531 of an object says how much a subscript on that object should be tucked in;
533 .I skew
534 of an object says how far to the right of the center of the object an
535 accent over the object should be placed.)
536 The macro must modify
537 .B 0s
538 so that it will output the desired result with its origin at the current
539 point, and increase the current horizontal position by the width
540 of the object.
541 The number registers must also be modified so that they correspond to the
542 result.
545 For example, suppose you wanted a construct that `cancels' an expression
546 by drawing a diagonal line through it.
550 .ft B
551 .if t .ne 6+\n(.Vu
553 \&.EQ
555 define cancel 'special Ca'
557 \&.EN
559 \&.de Ca
561 \&.\ \ ds 0s \e
563 \eZ'\e\e*(0s'\e
565 \ev'\e\en(0du'\e
567 \eD'l \e\en(0wu -\e\en(0hu-\e\en(0du'\e
569 \ev'\e\en(0hu'
571 \&..
576 Then you could cancel an expression\~\c
577 .I e
578 with
579 .BI \%cancel\ {\  e\  }
582 Here's a more complicated construct that draws a box round an expression:
586 .ft B
587 .if t .ne 11+\n(.Vu
588 \&.EQ
590 define box 'special Bx'
592 \&.EN
594 \&.de Bx
596 \&.\ \ ds 0s \e
598 \eZ'\eh'1n'\e\e*(0s'\e
600 \eZ'\e
602 \ev'\e\en(0du+1n'\e
604 \eD'l \e\en(0wu+2n 0'\e
606 \eD'l 0 -\e\en(0hu-\e\en(0du-2n'\e
608 \eD'l -\e\en(0wu-2n 0'\e
610 \eD'l 0 \e\en(0hu+\e\en(0du+2n'\e
612 \&'\e
614 \eh'\e\en(0wu+2n'
616 \&.\ \ nr 0w +2n
618 \&.\ \ nr 0d +1n
620 \&.\ \ nr 0h +1n
622 \&..
626 .SS Customization
627 The appearance of equations is controlled by a large number of parameters.
628 These can be set using
630 .B set
631 command.
634 .BI set\  p\ n
635 This sets parameter\~\c
636 .I p
637 to value\~\c
638 .IR n ;
639 .I n\~\c
640 is an integer.
641 For example,
646 set x_height 45
650 says that
651 .B eqn
652 should assume an x\~height of 0.45\~ems.
656 Possible parameters are as follows.
657 Values are in units of hundredths of an em unless otherwise stated.
658 These descriptions are intended to be expository rather than
659 definitive.
661 .ie t \
662 .  TP \w'\fBdefault_rule_thickness'u+2n
663 .el \
664 .  TP
665 .B minimum_size
666 .B eqn
667 will not set anything at a smaller point-size than this.
668 The value is in points.
671 .B fat_offset
673 .B fat
674 primitive emboldens an equation
675 by overprinting two copies of the equation
676 horizontally offset by this amount.
679 .B over_hang
680 A fraction bar will be longer by twice this amount than
681 the maximum of the widths of the numerator and denominator;
682 in other words, it will overhang the numerator and
683 denominator by at least this amount.
686 .B accent_width
687 When
688 .B bar
690 .B under
691 is applied to a single character,
692 the line will be this long.
693 Normally,
694 .B bar
696 .B under
697 produces a line whose length is the width of the object to which it applies;
698 in the case of a single character,
699 this tends to produce a line that looks too long.
702 .B delimiter_factor
703 Extensible delimiters produced with the
704 .B left
706 .B right
707 primitives will have a combined height and depth of at least this many
708 thousandths of twice the maximum amount by which the sub-equation that
709 the delimiters enclose extends away from the axis.
712 .B delimiter_shortfall
713 Extensible delimiters produced with the
714 .B left
716 .B right
717 primitives will have a combined height and depth
718 not less than the difference of
719 twice the maximum amount by which the sub-equation that
720 the delimiters enclose extends away from the axis
721 and this amount.
724 .B null_delimiter_space
725 This much horizontal space is inserted
726 on each side of a fraction.
729 .B script_space
730 The width of subscripts and superscripts is increased by this amount.
733 .B thin_space
734 This amount of space is automatically inserted after punctuation
735 characters.
738 .B medium_space
739 This amount of space is automatically inserted on either side
740 of binary operators.
743 .B thick_space
744 This amount of space is automatically inserted on either side of
745 relations.
748 .B x_height
749 The height of lowercase letters without ascenders such as `x'.
752 .B axis_height
753 The height above the baseline of the center of characters
754 such as `\(pl' and `\(mi'.
755 It is important that this value is correct for the font
756 you are using.
759 .B default_rule_thickness
760 This should set to the thickness of the
761 .B \e(ru
762 character, or the thickness of horizontal lines produced with the
763 .B \eD
764 escape sequence.
767 .B num1
769 .B over
770 command will shift up the numerator by at least this amount.
773 .B num2
775 .B smallover
776 command will shift up the numerator by at least this amount.
779 .B denom1
781 .B over
782 command will shift down the denominator by at least this amount.
785 .B denom2
787 .B smallover
788 command will shift down the denominator by at least this amount.
791 .B sup1
792 Normally superscripts will be shifted up by at least this amount.
795 .B sup2
796 Superscripts within superscripts or upper limits
797 or numerators of
798 .B smallover
799 fractions
800 will be shifted up by at least this amount.
801 This is usually less than sup1.
804 .B sup3
805 Superscripts within denominators or square roots
806 or subscripts or lower limits will be shifted up by at least
807 this amount.
808 This is usually less than sup2.
811 .B sub1
812 Subscripts will normally be shifted down by at least this amount.
815 .B sub2
816 When there is both a subscript and a superscript, the subscript
817 will be shifted down by at least this amount.
820 .B sup_drop
821 The baseline of a superscript will be no more
822 than this much amount below the top of the object on
823 which the superscript is set.
826 .B sub_drop
827 The baseline of a subscript will be at least this much below
828 the bottom of the object on which the subscript is set.
831 .B big_op_spacing1
832 The baseline of an upper limit will be at least this
833 much above the top of the object on which the limit is set.
836 .B big_op_spacing2
837 The baseline of a lower limit will be at least this
838 much below the bottom of the object on which the limit is set.
841 .B big_op_spacing3
842 The bottom of an upper limit will be at least this much above the
843 top of the object on which the limit is set.
846 .B big_op_spacing4
847 The top of a lower limit will be at least this much below
848 the bottom of the object on which the limit is set.
851 .B big_op_spacing5
852 This much vertical space will be added above and below limits.
855 .B baseline_sep
856 The baselines of the rows in a pile or matrix will normally be
857 this far apart.
858 In most cases this should be equal to the sum of
859 .B num1
861 .BR denom1 .
864 .B shift_down
865 The midpoint between the top baseline and the bottom baseline
866 in a matrix or pile will be shifted down by this much from the axis.
867 In most cases this should be equal to
868 .BR axis_height .
871 .B column_sep
872 This much space will be added between columns in a matrix.
875 .B matrix_side_sep
876 This much space will be added at each side of a matrix.
879 .B draw_lines
880 If this is non-zero, lines will be drawn using the
881 .B \eD
882 escape sequence, rather than with the
883 .B \el
884 escape sequence and the
885 .B \e(ru
886 character.
889 .B body_height
890 The amount by which the height of the equation exceeds this
891 will be added as extra space before the line containing the equation
892 (using
893 .BR \ex ).
894 The default value is 85.
897 .B body_depth
898 The amount by which the depth of the equation exceeds this
899 will be added as extra space after the line containing the equation
900 (using
901 .BR \ex ).
902 The default value is 35.
905 .B nroff
906 If this is non-zero,
907 then
908 .B ndefine
909 will behave like
910 .B define
912 .B tdefine
913 will be ignored,
914 otherwise
915 .B tdefine
916 will behave like
917 .B define
919 .B ndefine
920 will be ignored.
921 The default value is\~0
922 (This is typically changed to\~1 by the
923 .B eqnrc
924 file for the
925 .BR ascii ,
926 .BR latin1 ,
927 .BR utf8 ,
929 .B cp1047
930 devices.)
933 A more precise description of the role of many of these
934 parameters can be found in Appendix\~H of
935 .IR "The \*(txbook" .
938 .SS Macros
939 Macros can take arguments.
940 In a macro body,
941 .BI $ n
942 where
943 .I n
944 is between 1 and\~9,
945 will be replaced by the
946 .IR n-th
947 argument if the macro is called with arguments;
948 if there are fewer than
949 .I n\~\c
950 arguments, it will be replaced by nothing.
951 A word containing a left parenthesis where the part of the word
952 before the left parenthesis has been defined using the
953 .B define
954 command
955 will be recognized as a macro call with arguments;
956 characters following the left parenthesis
957 up to a matching right parenthesis will be treated as comma-separated
958 arguments;
959 commas inside nested parentheses do not terminate an argument.
962 .BI sdefine\  name\ X\ anything\ X
963 This is like the
964 .B define
965 command, but
966 .I name
967 will not be recognized if called with arguments.
970 .BI include\ \(ts file \(ts
971 Include the contents of
972 .IR file .
973 Lines of
974 .I file
975 beginning with
976 .B .EQ
978 .B .EN
979 will be ignored.
982 .BI ifdef\  name\ X\ anything\ X
984 .I name
985 has been defined by
986 .B define
987 (or has been automatically defined because
988 .I name
989 is the output device)
990 process
991 .IR anything ;
992 otherwise ignore
993 .IR anything .
994 .I X
995 can be any character not appearing in
996 .IR anything .
998 .SS Fonts
999 .B eqn
1000 normally uses at least two fonts to set an equation:
1001 an italic font for letters,
1002 and a roman font for everything else.
1003 The existing
1004 .B gfont
1005 command
1006 changes the font that is used as the italic font.
1007 By default this is\~\c
1008 .BR I .
1009 The font that is used as the roman font can be changed
1010 using the new
1011 .B grfont
1012 command.
1015 .BI grfont\  f
1016 Set the roman font to\~\c
1017 .IR f .
1021 .B italic
1022 primitive uses the current italic font set by
1023 .BR gfont ;
1025 .B roman
1026 primitive uses the current roman font set by
1027 .BR grfont .
1028 There is also a new
1029 .B gbfont
1030 command, which changes the font used by the
1031 .B bold
1032 primitive.
1033 If you only use the
1034 .BR roman ,
1035 .B italic
1037 .B bold
1038 primitives to changes fonts within an equation,
1039 you can change all the fonts used by your equations
1040 just by using
1041 .BR gfont ,
1042 .B grfont
1044 .B gbfont
1045 commands.
1048 You can control which characters are treated as letters
1049 (and therefore set in italics) by using the
1050 .B chartype
1051 command described above.
1052 A type of
1053 .B letter
1054 will cause a character to be set in italic type.
1055 A type of
1056 .B digit
1057 will cause a character to be set in roman type.
1060 .SH FILES
1061 .Tp \w'\fB@MACRODIR@/eqnrc'u+2n
1062 .B @MACRODIR@/eqnrc
1063 Initialization file.
1066 .SH BUGS
1067 Inline equations will be set at the point size that is current at the
1068 beginning of the input line.
1071 .SH "SEE ALSO"
1072 .BR groff (@MAN1EXT@),
1073 .BR @g@troff (@MAN1EXT@),
1074 .BR groff_font (@MAN5EXT@),
1075 .I The\ \*(txbook
1077 .\" Local Variables:
1078 .\" mode: nroff
1079 .\" End: