[groff] 04/04: eqn(1): Revise still more.

[G. Branden Robinson]

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
 .
 .