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