From 58b849af4bcdabb6b2383d4de7de9eac01ef059a Mon Sep 17 00:00:00 2001 From: Werner LEMBERG Date: Sat, 4 Dec 2004 11:55:12 +0000 Subject: [PATCH] * src/preproc/eqn/eqn.man: Revised. --- ChangeLog | 4 + src/preproc/eqn/eqn.man | 359 ++++++++++++++++++++++++++++++++++++------------ 2 files changed, 275 insertions(+), 88 deletions(-) diff --git a/ChangeLog b/ChangeLog index 997d675f..65fde6db 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2004-12-04 Werner LEMBERG + + * src/preproc/eqn/eqn.man: Revised. + 2004-11-25 Werner LEMBERG * src/utils/xtotroff/xtotroff.c: Reformat to be similar to other diff --git a/src/preproc/eqn/eqn.man b/src/preproc/eqn/eqn.man index 6d0733c4..4f0696bd 100644 --- a/src/preproc/eqn/eqn.man +++ b/src/preproc/eqn/eqn.man @@ -1,5 +1,5 @@ .ig -Copyright (C) 1989-2000, 2001 Free Software Foundation, Inc. +Copyright (C) 1989-2000, 2001, 2004 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -16,20 +16,34 @@ versions, except that this permission notice may be included in translations approved by the Free Software Foundation instead of in the original English. .. -.ie \n(.V<\n(.v .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X -.el .ds tx TeX +. +. +.ie \n(.V<\n(.v \ +. ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X +.el \ +. ds tx TeX +. +. .\" Like TP, but if specified indent is more than half .\" the current line-length - indent, use the default indent. .de Tp -.ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP -.el .TP "\\$1" +. ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP +. el .TP "\\$1" .. +. +. .\" The BSD man macros can't handle " in arguments to font change macros, .\" so use \(ts instead of ". .tr \(ts" +. +. .TH @G@EQN @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@" +. +. .SH NAME @g@eqn \- format equations for troff +. +. .SH SYNOPSIS .nr a \n(.j .ad l @@ -38,8 +52,8 @@ the original English. .ti \niu .B @g@eqn .de OP -.ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]" -.el .RB "[\ " "\\$1" "\ ]" +. ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]" +. el .RB "[\ " "\\$1" "\ ]" .. .OP \-rvCNR .OP \-d xy @@ -52,9 +66,12 @@ the original English. .RI "[\ " files\|.\|.\|. "\ ]" .br .ad \na -.PP +. +.LP It is possible to have whitespace between a command line option and its parameter. +. +. .SH DESCRIPTION This manual page describes the GNU version of .BR eqn , @@ -69,13 +86,16 @@ Normally, it should be invoked using the option of .BR groff . The syntax is quite compatible with Unix eqn. -The output of GNU eqn cannot be processed with Unix troff; +The output of GNU +.B eqn +cannot be processed with Unix troff; it must be processed with GNU troff. If no files are given on the command line, the standard input will be read. A filename of .B \- will cause the standard input to be read. +. .LP .B eqn searches for the file @@ -87,25 +107,33 @@ option first, then in .BR @LOCALMACRODIR@ , and finally in the standard macro directory .BR @MACRODIR@ . -If it exists, eqn will process it before the other input files. +If it exists, +.B eqn +will process it before the other input files. The .B \-R option prevents this. +. .LP -GNU eqn does not provide the functionality of neqn: +GNU +.B eqn +does not provide the functionality of neqn: it does not support low-resolution, typewriter-like devices (although it may work adequately for very simple input). +. +. .SH OPTIONS .TP .BI \-d xy Specify delimiters .I x -and +and\~\c .I y for the left and right end, respectively, of in-line equations. Any .B delim statements in the source file overrides this. +. .TP .B \-C Recognize @@ -119,32 +147,38 @@ Don't allow newlines within delimiters. This option allows .B eqn to recover better from missing closing delimiters. +. .TP .B \-v Print the version number. +. .TP .B \-r Only one size reduction. +. .TP .BI \-m n -The minimum point-size is +The minimum point-size is\~\c .IR n . -eqn will not reduce the size of subscripts or superscripts to -a smaller size than +.B eqn +will not reduce the size of subscripts or superscripts to +a smaller size than\~\c .IR n . +. .TP .BI \-T name The output is for device .IR name . The only effect of this is to define a macro .I name -with a value of +with a value of\~\c .BR 1 . Typically .B eqnrc will use this to provide definitions appropriate for the output device. The default output device is .BR @DEVICE@ . +. .TP .BI \-M dir Search @@ -152,82 +186,109 @@ Search for .B eqnrc before the default directories. +. .TP .B \-R Don't load .BR eqnrc . +. .TP .BI \-f F This is equivalent to a .BI gfont\ F command. +. .TP .BI \-s n This is equivalent to a .BI gsize\ n command. This option is deprecated. -eqn will normally set equations at whatever the current point size +.B eqn +will normally set equations at whatever the current point size is when the equation is encountered. +. .TP .BI \-p n This says that subscripts and superscripts should be -.I n +.I n\~\c points smaller than the surrounding text. This option is deprecated. -Normally eqn makes sets subscripts and superscripts at 70% +Normally +.B eqn +makes sets subscripts and superscripts at 70% of the size of the surrounding text. +. +. .SH USAGE -Only the differences between GNU eqn and Unix eqn are described here. +Only the differences between GNU +.B eqn +and Unix eqn are described here. +. .LP -Most of the new features of GNU eqn +Most of the new features of GNU +.B eqn are based on \*(tx. -There are some references to the differences between \*(tx and GNU eqn below; +There are some references to the differences between \*(tx and GNU +.B eqn +below; these may safely be ignored if you do not know \*(tx. +. .SS Automatic spacing -.LP .B eqn gives each component of an equation a type, and adjusts the spacing between components using that type. Possible types are: +. +.RS .TP \w'punctuation'u+2n ordinary -an ordinary character such as 1 or -.IR x ; +an ordinary character such as `1' or `\c +.IR x '; +. .TP operator a large operator such as -.ds Su \s+5\(*S\s0 +.ds Su `\s+5\(*S\s0' .if \n(.g .if !c\(*S .ds Su the summation operator \*(Su; +. .TP binary -a binary operator such as +; +a binary operator such as `\(pl'; +. .TP relation -a relation such as =; +a relation such as `='; +. .TP opening -a opening bracket such as (; +a opening bracket such as `('; +. .TP closing -a closing bracket such as ); +a closing bracket such as `)'; +. .TP punctuation -a punctuation character such as ,; +a punctuation character such as `,'; +. .TP inner a subformula contained within brackets; .TP suppress spacing that suppresses automatic spacing adjustment. +.RE +. .LP Components of an equation get a type in one of two ways. +. .TP .BI type\ t\ e -This yields an equation component that contains +This yields an equation component that contains\~\c .I e -but that has type +but that has type\~\c .IR t , where .I t @@ -235,14 +296,17 @@ is one of the types mentioned above. For example, .B times is defined as +. .RS .IP .B type "binary" \e(mu .RE +. .IP The name of the type doesn't have to be quoted, but quoting protects from macro expansion. +. .TP .BI chartype\ t\ text Unquoted groups of characters are split up into individual characters, @@ -250,20 +314,20 @@ and the type of each character is looked up; this changes the type that is stored for each character; it says that the characters in .I text -from now on have type +from now on have type\~\c .IR t . For example, +. .RS .IP .B chartype "punctuation" .,;: .RE +. .IP -would make the characters -.B .,;: -have type punctuation +would make the characters `.,;:' have type punctuation whenever they subsequently appeared in an equation. -The type +The type\~\c .I t can also be .B letter @@ -272,7 +336,10 @@ or in these cases .B chartype changes the font type of the characters. -See the Fonts subsection. +See the +.B Fonts +subsection. +. .SS New primitives .TP .IB e1\ smallover\ e2 @@ -297,22 +364,25 @@ primitive in display styles; corresponds to .B \eover in non-display styles. +. .TP .BI vcenter\ e This vertically centers .I e about the math axis. The math axis is the vertical position about which characters -such as + and - are centered; also it is the vertical position +such as `\(pl' and `\(mi' are centered; also it is the vertical position used for the bar of fractions. For example, .B sum is defined as +. .RS .IP .B { type "operator" vcenter size +5 \e(*S } .RE +. .TP .IB e1\ accent\ e2 This sets @@ -328,21 +398,24 @@ is taller or shorter than a lowercase letter. For example, .B hat is defined as +. .RS .IP .B accent { "^" } .RE +. .IP .BR dotdot , .BR dot , .BR tilde , -.B vec +.BR vec , and .B dyad are also defined using the .B accent primitive. +. .TP .IB e1\ uaccent\ e2 This sets @@ -359,13 +432,16 @@ has a descender. is pre-defined using .B uaccent as a tilde accent below the baseline. +. .TP .BI split\ \(ts text \(ts This has the same effect as simply +. .RS .IP .I text .RE +. .IP but .I text @@ -373,13 +449,16 @@ is not subject to macro expansion because it is quoted; .I text will be split up and the spacing between individual characters will be adjusted. +. .TP .BI nosplit\ text This has the same effect as +. .RS .IP .BI \(ts text \(ts .RE +. .IP but because .I text @@ -387,11 +466,12 @@ is not quoted it will be subject to macro expansion; .I text will not be split up and the spacing between individual characters will not be adjusted. +. .TP .IB e\ opprime This is a variant of .B prime -that acts as an operator on +that acts as an operator on\~\c .IR e . It produces a different result from .B prime @@ -399,14 +479,14 @@ in a case such as .BR A\ opprime\ sub\ 1 : with .B opprime -the +the\~\c .B 1 -will be tucked under the prime as a subscript to the +will be tucked under the prime as a subscript to the\~\c .B A (as is conventional in mathematical typesetting), whereas with .B prime -the +the\~\c .B 1 will be a subscript to the prime character. The precedence of @@ -419,31 +499,32 @@ which is higher than that of everything except .B accent and .BR uaccent . -In unquoted text a +In unquoted text a\~\c .B ' that is not the first character will be treated like .BR opprime . +. .TP .BI special\ text\ e -This constructs a new object from +This constructs a new object from\~\c .I e using a -.BR @g@troff (@MAN1EXT@) +.BR @g@troff (@MAN1EXT@) macro named .IR text . When the macro is called, the string .B 0s -will contain the output for +will contain the output for\~\c .IR e , and the number registers .BR 0w , .BR 0h , .BR 0d , -.BR 0skern +.BR 0skern , and .BR 0skew -will contain the width, height, depth, subscript kern, and skew of +will contain the width, height, depth, subscript kern, and skew of\~\c .IR e . (The .I "subscript kern" @@ -459,82 +540,133 @@ point, and increase the current horizontal position by the width of the object. The number registers must also be modified so that they correspond to the result. -.RS -.LP +. +.IP For example, suppose you wanted a construct that `cancels' an expression by drawing a diagonal line through it. +. +.RS .IP -.nf .ft B .if t .ne 6+\n(.Vu +.br \&.EQ +.br define cancel 'special Ca' +.br \&.EN +.br \&.de Ca -\&.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' +.br +\&.\ \ ds 0s \e +.br +\eZ'\e\e*(0s'\e +.br +\ev'\e\en(0du'\e +.br +\eD'l \e\en(0wu -\e\en(0hu-\e\en(0du'\e +.br +\ev'\e\en(0hu' +.br \&.. .ft -.fi -.LP -Then you could cancel an expression +.RE +. +.IP +Then you could cancel an expression\~\c .I e with -.BI cancel\ {\ e\ } -.LP +.BI \%cancel\ {\ e\ } +. +.IP Here's a more complicated construct that draws a box round an expression: +. +.RS .IP -.nf .ft B .if t .ne 11+\n(.Vu \&.EQ +.br define box 'special Bx' +.br \&.EN +.br \&.de Bx -\&.ds 0s \eZ'\eh'1n'\e\e*(0s'\e -\eZ'\ev'\e\en(0du+1n'\eD'l \e\en(0wu+2n 0'\eD'l 0 -\e\en(0hu-\e\en(0du-2n'\e -\eD'l -\e\en(0wu-2n 0'\eD'l 0 \e\en(0hu+\e\en(0du+2n''\eh'\e\en(0wu+2n' -\&.nr 0w +2n -\&.nr 0d +1n -\&.nr 0h +1n +.br +\&.\ \ ds 0s \e +.br +\eZ'\eh'1n'\e\e*(0s'\e +.br +\eZ'\e +.br +\ev'\e\en(0du+1n'\e +.br +\eD'l \e\en(0wu+2n 0'\e +.br +\eD'l 0 -\e\en(0hu-\e\en(0du-2n'\e +.br +\eD'l -\e\en(0wu-2n 0'\e +.br +\eD'l 0 \e\en(0hu+\e\en(0du+2n'\e +.br +\&'\e +.br +\eh'\e\en(0wu+2n' +.br +\&.\ \ nr 0w +2n +.br +\&.\ \ nr 0d +1n +.br +\&.\ \ nr 0h +1n +.br \&.. .ft -.fi .RE +. .SS Customization -The appearance of equations is controlled by -a large number of parameters. These can be set using +The appearance of equations is controlled by a large number of parameters. +These can be set using the .B set command. +. .TP .BI set\ p\ n -This sets parameter +This sets parameter\~\c .I p -to value -.I n ; -.I n +to value\~\c +.IR n ; +.I n\~\c is an integer. For example, +. .RS .IP .B set x_height 45 .RE +. .IP says that .B eqn -should assume an x height of 0.45 ems. +should assume an x\~height of 0.45\~ems. +. .RS .LP Possible parameters are as follows. Values are in units of hundredths of an em unless otherwise stated. These descriptions are intended to be expository rather than definitive. -.TP \w'\fBdefault_rule_thickness'u+2n +. +.ie t \ +. TP \w'\fBdefault_rule_thickness'u+2n +.el \ +. TP .B minimum_size .B eqn will not set anything at a smaller point-size than this. The value is in points. +. .TP .B fat_offset The @@ -542,12 +674,14 @@ The primitive emboldens an equation by overprinting two copies of the equation horizontally offset by this amount. +. .TP .B over_hang A fraction bar will be longer by twice this amount than the maximum of the widths of the numerator and denominator; in other words, it will overhang the numerator and denominator by at least this amount. +. .TP .B accent_width When @@ -563,6 +697,7 @@ or produces a line whose length is the width of the object to which it applies; in the case of a single character, this tends to produce a line that looks too long. +. .TP .B delimiter_factor Extensible delimiters produced with the @@ -572,6 +707,7 @@ and primitives will have a combined height and depth of at least this many thousandths of twice the maximum amount by which the sub-equation that the delimiters enclose extends away from the axis. +. .TP .B delimiter_shortfall Extensible delimiters produced with the @@ -583,34 +719,42 @@ not less than the difference of twice the maximum amount by which the sub-equation that the delimiters enclose extends away from the axis and this amount. +. .TP .B null_delimiter_space This much horizontal space is inserted on each side of a fraction. +. .TP .B script_space The width of subscripts and superscripts is increased by this amount. +. .TP .B thin_space This amount of space is automatically inserted after punctuation characters. +. .TP .B medium_space This amount of space is automatically inserted on either side of binary operators. +. .TP .B thick_space This amount of space is automatically inserted on either side of relations. +. .TP .B x_height -The height of lowercase letters without ascenders such as x. +The height of lowercase letters without ascenders such as `x'. +. .TP .B axis_height The height above the baseline of the center of characters -such as \(pl and \(mi. +such as `\(pl' and `\(mi'. It is important that this value is correct for the font you are using. +. .TP .B default_rule_thickness This should set to the thickness of the @@ -618,29 +762,35 @@ This should set to the thickness of the character, or the thickness of horizontal lines produced with the .B \eD escape sequence. +. .TP .B num1 The .B over command will shift up the numerator by at least this amount. +. .TP .B num2 The .B smallover command will shift up the numerator by at least this amount. +. .TP .B denom1 The .B over command will shift down the denominator by at least this amount. +. .TP .B denom2 The .B smallover command will shift down the denominator by at least this amount. +. .TP .B sup1 Normally superscripts will be shifted up by at least this amount. +. .TP .B sup2 Superscripts within superscripts or upper limits @@ -649,47 +799,58 @@ or numerators of fractions will be shifted up by at least this amount. This is usually less than sup1. +. .TP .B sup3 Superscripts within denominators or square roots or subscripts or lower limits will be shifted up by at least this amount. This is usually less than sup2. +. .TP .B sub1 Subscripts will normally be shifted down by at least this amount. +. .TP .B sub2 When there is both a subscript and a superscript, the subscript will be shifted down by at least this amount. +. .TP .B sup_drop The baseline of a superscript will be no more than this much amount below the top of the object on which the superscript is set. +. .TP .B sub_drop The baseline of a subscript will be at least this much below the bottom of the object on which the subscript is set. +. .TP .B big_op_spacing1 The baseline of an upper limit will be at least this much above the top of the object on which the limit is set. +. .TP .B big_op_spacing2 The baseline of a lower limit will be at least this much below the bottom of the object on which the limit is set. +. .TP .B big_op_spacing3 The bottom of an upper limit will be at least this much above the top of the object on which the limit is set. +. .TP .B big_op_spacing4 The top of a lower limit will be at least this much below the bottom of the object on which the limit is set. +. .TP .B big_op_spacing5 This much vertical space will be added above and below limits. +. .TP .B baseline_sep The baselines of the rows in a pile or matrix will normally be @@ -698,18 +859,22 @@ In most cases this should be equal to the sum of .B num1 and .BR denom1 . +. .TP .B shift_down The midpoint between the top baseline and the bottom baseline in a matrix or pile will be shifted down by this much from the axis. In most cases this should be equal to .BR axis_height . +. .TP .B column_sep This much space will be added between columns in a matrix. +. .TP .B matrix_side_sep This much space will be added at each side of a matrix. +. .TP .B draw_lines If this is non-zero, lines will be drawn using the @@ -719,20 +884,23 @@ escape sequence, rather than with the escape sequence and the .B \e(ru character. +. .TP .B body_height The amount by which the height of the equation exceeds this will be added as extra space before the line containing the equation (using -.BR \ex .) +.BR \ex ). The default value is 85. +. .TP .B body_depth The amount by which the depth of the equation exceeds this will be added as extra space after the line containing the equation (using -.BR \ex .) +.BR \ex ). The default value is 35. +. .TP .B nroff If this is non-zero, @@ -750,8 +918,8 @@ will behave like and .B ndefine will be ignored. -The default value is 0 -(This is typically changed to 1 by the +The default value is\~0 +(This is typically changed to\~1 by the .B eqnrc file for the .BR ascii , @@ -760,23 +928,25 @@ file for the and .B cp1047 devices.) +. .LP A more precise description of the role of many of these -parameters can be found in Appendix H of -.IR The\ \*(txbook . +parameters can be found in Appendix\~H of +.IR "The \*(txbook" . .RE +. .SS Macros Macros can take arguments. In a macro body, .BI $ n where .I n -is between 1 and 9, +is between 1 and\~9, will be replaced by the .IR n-th argument if the macro is called with arguments; if there are fewer than -.I n +.I n\~\c arguments, it will be replaced by nothing. A word containing a left parenthesis where the part of the word before the left parenthesis has been defined using the @@ -787,6 +957,7 @@ characters following the left parenthesis up to a matching right parenthesis will be treated as comma-separated arguments; commas inside nested parentheses do not terminate an argument. +. .TP .BI sdefine\ name\ X\ anything\ X This is like the @@ -794,6 +965,7 @@ This is like the command, but .I name will not be recognized if called with arguments. +. .TP .BI include\ \(ts file \(ts Include the contents of @@ -805,6 +977,7 @@ beginning with or .B .EN will be ignored. +. .TP .BI ifdef\ name\ X\ anything\ X If @@ -821,6 +994,7 @@ otherwise ignore .I X can be any character not appearing in .IR anything . +. .SS Fonts .B eqn normally uses at least two fonts to set an equation: @@ -830,16 +1004,18 @@ The existing .B gfont command changes the font that is used as the italic font. -By default this is +By default this is\~\c .BR I . The font that is used as the roman font can be changed using the new .B grfont command. +. .TP .BI grfont\ f -Set the roman font to +Set the roman font to\~\c .IR f . +. .LP The .B italic @@ -867,6 +1043,7 @@ just by using and .B gbfont commands. +. .LP You can control which characters are treated as letters (and therefore set in italics) by using the @@ -878,13 +1055,19 @@ will cause a character to be set in italic type. A type of .B digit will cause a character to be set in roman type. +. +. .SH FILES .Tp \w'\fB@MACRODIR@/eqnrc'u+2n .B @MACRODIR@/eqnrc Initialization file. +. +. .SH BUGS Inline equations will be set at the point size that is current at the beginning of the input line. +. +. .SH "SEE ALSO" .BR groff (@MAN1EXT@), .BR @g@troff (@MAN1EXT@), -- 2.11.4.GIT