[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 04/04: eqn(1): Revise still more.
From: |
G. Branden Robinson |
Subject: |
[groff] 04/04: eqn(1): Revise still more. |
Date: |
Sun, 4 Jun 2023 00:16:23 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit 8cdf96d99e7bcab3c0505e7872c1cccc10639dd2
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Jun 3 01:38:54 2023 -0500
eqn(1): Revise still more.
* Get the word "mathematics" into the summary description.
* Fix subject/verb agreement.
* Recast introductory description for tightness and precision.
* Add forward reference to additional token separation rules that come
into play when using GNU eqn's parameterized macros.
* Clarify how "copy" and "include" primitives resolve the locations of
their file name arguments.
* Distinguish matrices from piles.
* Stop using generic references to eqn and troff when discussing GNU
extensions. (AT&T eqn didn't have the "Customization" parameters, and
AT&T troff would not understand GNU eqn output.)
* Recast description of GNU eqn parameterized macro calls, introducing
that term. Document that `tdefine` and `ndefine` can define
parameterized macros too. When specifying a numeric range, indicate
whether it's an open or closed set.
* Document `ldots` as setting an ellipsis, not just "three dots".
* Clarify form of quoting necessary to prevent macro expansion (and
matching of primitives).
* Expand quadratic formula example to illustrate parameterized macro
call. Typeset the output to demonstrate the (near) equivalence, and
challenge the reader to spot the 0.06 em of difference in operator
spacing.
---
src/preproc/eqn/eqn.1.man | 108 ++++++++++++++++++++++++++++++----------------
1 file changed, 70 insertions(+), 38 deletions(-)
diff --git a/src/preproc/eqn/eqn.1.man b/src/preproc/eqn/eqn.1.man
index d62a8fb0b..f28648c84 100644
--- a/src/preproc/eqn/eqn.1.man
+++ b/src/preproc/eqn/eqn.1.man
@@ -1,7 +1,7 @@
'\" et
.TH @g@eqn @MAN1EXT@ "@MDATE@" "groff @VERSION@"
.SH Name
-@g@eqn \- format equations for
+@g@eqn \- format mathematics (equations) for
.I groff
or MathML
.
@@ -104,20 +104,22 @@ document formatting system.
.I @g@eqn
is a
.MR @g@troff @MAN1EXT@
-preprocessor that translates descriptions of equations embedded in
+preprocessor that translates expressions in its own language,
+embedded in
.MR roff @MAN7EXT@
-input files into the language understood by
+input files,
+into mathematical notation typeset by
.MR @g@troff @MAN1EXT@ .
.
-It copies the contents of each
-.I file
+It copies each
+.IR file 's
to the standard output stream,
-except that lines between
+except that input between lines starting with
.B .EQ
and
-.B .EN
-(or within a pair of user-specified delimiters)
-are interpreted as equation descriptions.
+.BR .EN ,
+or within a pair of user-specified delimiters,
+is translated as above.
.
Normally,
.I @g@eqn
@@ -320,12 +322,15 @@ necessary to disambiguate the input;
.I @g@eqn
will diagnose an error in this event.
.
+(See subsection \[lq]Macros\[rq] below for additional token separation
+rules.)
+.
.
.P
Other tokens are primitives,
macros,
an argument to either of the foregoing,
-or a component of an equation.
+or components of an equation.
.
.
.br
@@ -381,7 +386,7 @@ constants,
numeric literals,
and operators.
.
-.I %g%eqn
+.I @g@eqn
remaps some input character sequences to
.I groff
special character escape sequences for economy in equation entry and to
@@ -673,6 +678,10 @@ beginning with
or
.BR .EN .
.
+If a relative path name,
+.I file
+is sought relative to the current working directory.
+.
.
.TP
.BI ifdef\~ "name X anything X"
@@ -1060,7 +1069,7 @@ Negative values are accepted but have no effect.
.
If more than one
.I n
-occurs in a matrix,
+occurs in a matrix or pile,
the largest is used.
.
.
@@ -1069,9 +1078,9 @@ the largest is used.
.\" ====================================================================
.
When
-.I eqn
+.I @g@eqn
generates
-.I troff \" generic
+.I @g@troff
input,
the appearance of equations is controlled by a large number of
parameters.
@@ -1515,29 +1524,35 @@ In GNU
.IR eqn , \" GNU
macros can take arguments.
.
-In a macro body,
+A word defined by any of the
+.BR \%define ,
+.BR \%ndefine ,
+or
+.B \%tdefine
+primitives followed immediately by a left parenthesis is treated as a
+.I "parameterized macro call:"
+subsequent tokens up to a matching right parenthesis are treated as
+comma-separated arguments.
+.
+In this context only,
+commas and parentheses also serve as token separators.
+.
+A macro argument is not terminated by a comma inside parentheses nested
+within it.
+.
+In a macro definition,
.BI $ n\c
,
where
.I n
-is between 1 and\~9,
+is between 1 and\~9 inclusive,
is replaced by the
.IR n th
-argument if the macro is called with arguments;
+argument;
if there are fewer than
.IR n \~arguments,
it is replaced by nothing.
.
-A word containing a left parenthesis where the part of the word before
-the left parenthesis has been defined using the
-.B \%define
-primitive is recognized as a macro call with arguments;
-characters following the left parenthesis up to a matching right
-parenthesis are treated as comma-separated arguments.
-.
-Commas inside nested parentheses
-do not terminate an argument.
-.
.
.\" ====================================================================
.SS "Predefined macros"
@@ -1643,7 +1658,7 @@ and
which sets a dollar sign,
and
.BR ldots ,
-which sets three dots on the baseline.
+which sets an ellipsis on the text baseline.
.
.
.\" ====================================================================
@@ -1929,14 +1944,14 @@ and do not cross line boundaries.
.SH Caveats
.\" ====================================================================
.
-Words must be quoted anywhere they occur in
+Tokens must be double-quoted in
.I eqn \" generic
input if they are not to be recognized as names of macros or primitives,
or if they are to be interpreted by
.IR troff . \" generic
.
-These names,
-particularly short ones like
+In particlar,
+short ones like
.RB \[lq] pi \[rq]
and
.RB \[lq] PI \[rq],
@@ -2110,23 +2125,40 @@ x = { - b ~ \[+-] ~ sqrt { b sup 2 - 4 a c } } over { 2
a }
.
.
.P
-We could alternatively define the plus-minus sign as a binary operator.
+Alternatively,
+we could define the plus-minus sign as a binary operator.
.
-The default parameters put 0.06 em less space on either side of that
-symbol,
-this being the difference between the
+Automatic spacing puts 0.06\~em less space on either side of the
+plus-minus than \[ti] does,
+this being the difference between the widths of the
.B medium_space
-used by binary operators and the width of the full space.
+parameter used by binary operators and that of the full space.
+.
+Independently,
+we can define a macro \[lq]frac\[rq] for setting fractions.
.
.
.RS
.P
.EX
\&.EQ
-chartype "binary" \[rs][+-]
-x = { \- b \[rs][+\-] sqrt { b sup 2 \- 4 a c } } over { 2 a }
+chartype "binary" \[rs][+\-]
+define frac ! { $1 } over { $2 } !
+x = frac(\- b \[rs][+\-] sqrt { b sup 2 \- 4 a c }, 2 a)
\&.EN
.EE
+.if t \{\
+.
+.
+.P
+.RS
+.EQ
+chartype "binary" \[+-]
+define frac ! { $1 } over { $2 } !
+x = frac(- b \[+-] sqrt { b sup 2 - 4 a c }, 2 a)
+.EN
+.RE
+.\}
.RE
.
.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 04/04: eqn(1): Revise still more.,
G. Branden Robinson <=