[groff] 10/10: eqn(1): Further revise.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit ce573f1317a3e70246cdbb06f431dd741525999c
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri May 26 10:25:05 2023 -0500

    eqn(1): Further revise.
    
    Content:
    * Discuss tab and leader handling more accurately, and shift discussion
      to follow the presentation of braces for grouping since it's
      impossible to explain them otherwise.
    * Replace "big" with "fat" as an example of a primitive; "big" is broken
      and doesn't act like a primitive (Savannah #64255).
    * Revise presentation of spacing and face types.  This is kind of hard
      to do because as far as I can tell the underlying abstraction is a bit
      sloppy.  You can apply the "letter" type to things that aren't
      letters; some letters (uppercase Greek) don't have the "letter" type
      by default; having the "digit" type is not distinguishable from being
      plain "ordinary" with neither "letter" nor "digit" subtype; the
      purpose of the face types is to, natch, assign a face, but "ordinary"
      doesn't need to do that since it already bears the default face used
      by the formatter (or possibly the "grfont" face--I haven't determined
      that yet).  But if that is the case then I don't see why "ordinary"
      doesn't have as its subtypes "oblique" and "heavy" instead, thus
      creating a means of automatically boldfacing a class of ordinary
      characters.  Finally, there is terminological overlap between the
      "ordinary" spacing type of eqn(1) and "ordinary characters" in groff
      (but this is largely due to my innovation in the latter, to
      distinguish them from special characters).  The reform whistle is
      blowing...
    * Drop the times sign as an example of an ordinary character.  It is,
      but it will more likely be encountered in eqn input as "times" where
      it is a predefine macro defining a binary operator using the \[mu]
      special character, and its spacing will thus _not_ be "ordinary".
    * Recast description of "chartype" primitive for clarity (modifier was
      misplaced) and to use active voice.
    * Revise table of type assignments to be valid GNU eqn input.
    * Add a caveat about displayed vs. inline equations, to disabuse those
      accustomed to TeX of an assumption.
    * Add "Examples" section.
    
    Style:
    * Tighten wording.
    * Fix semicolon splice.
    
    Markup:
    * Protect keywords "ordinary" and "letter" from hyphenation.
---
 src/preproc/eqn/eqn.1.man | 208 ++++++++++++++++++++++++++++++++--------------
 1 file changed, 145 insertions(+), 63 deletions(-)

diff --git a/src/preproc/eqn/eqn.1.man b/src/preproc/eqn/eqn.1.man
index 211e1325d..db2e447d5 100644
--- a/src/preproc/eqn/eqn.1.man
+++ b/src/preproc/eqn/eqn.1.man
@@ -272,12 +272,6 @@ Spaces and newlines are interchangeable;
 they separate input tokens but do not break lines or produce space in
 the output.
 .
-Tab and leader characters separate tokens as well as advancing the
-drawing position to the next tab stop
-(but are seldom used in
-.I eqn
-input).
-.
 .
 .P
 A handful of tokens manage the grouping and spacing of other tokens.
@@ -285,7 +279,7 @@ A handful of tokens manage the grouping and spacing of 
other tokens.
 .
 .TP
 .B "{ }"
-Left and right braces perform grouping.
+Braces perform grouping.
 .
 Whereas
 .RB \[lq] "e sup a b" \[rq]
@@ -320,6 +314,22 @@ Use them to tune the appearance of the output.
 .
 .
 .P
+Tab and leader characters separate tokens as well as advancing the
+drawing position to the next tab stop,
+but are seldom used in
+.I eqn
+input.
+.
+When they occur,
+they must appear at the outermost lexical scope.
+.
+This roughly means that they can't appear within braces that are
+necessary to disambiguate the input;
+.I @g@eqn
+will diagnose an error in this event.
+.
+.
+.P
 Other tokens are primitives,
 macros,
 an argument to either of the foregoing,
@@ -332,7 +342,7 @@ are fundamental keywords of the
 .I eqn
 language.
 .
-They can configure an aspect of the preprocessor's state;
+They can configure an aspect of the preprocessor's state,
 as when setting a \[lq]global\[rq] font selection or type size
 .RB ( gfont
 and
@@ -346,7 +356,7 @@ these are termed
 .
 Other primitives perform formatting operations on the tokens after them
 (as with
-.BR big ,
+.BR fat ,
 .BR over ,
 .BR sqrt ,
 or
@@ -406,14 +416,19 @@ Lf(CR) Lf(CR).
 .
 GNU
 .I eqn
-imputes a type to each component of an equation,
-assigning a typeface to
-and adjusting the spacing between them accordingly.
+imputes types to the components of an equation,
+adjusting the spacing between them accordingly.
 .
-Recognized types are as follows.
+Recognized types are as follows;
+most affect spacing only,
+whereas the
+.RB \%\[lq] letter \[rq]
+subtype of
+.RB \%\[lq] ordinary \[rq]
+also assigns a style.
 .
 .
-.RS 2n \" we need quite a bit of space for this table
+.RS 2n \" we need quite a bit of horizontal space for this table
 .P
 .TS
 Lf(CR) Lx
@@ -423,11 +438,11 @@ Lf(CR) Lx.
 ordinary       T{
 character such as \[lq]1\[rq],
 \[lq]a\[rq],
-\[lq]!\&\[rq],
-or \[lq]\[mu]\[rq]
+or
+\[lq]!\&\[rq]
 T}
-letter alphabetic character
-digit  numeral
+letter character to be italicized by default
+digit  \f[I]n/a\f[]
 operator       T{
 large operator such as
 .ds Su \[lq]\s+5\[*S]\s0\[rq]
@@ -460,45 +475,31 @@ to
 .
 .TP
 .BI chartype\~ "t text"
-Each (unquoted) character
-.RI in\~ text
-is assigned
+Assign each character in (unquoted)
+.I text
 .RI type\~ t ,
 persistently.
 .
-If
-.I t
-is
-.RB \[lq] letter \[rq],
-.B \%chartype
-also assigns the italic typeface to each character in
-.IR text .
-.
-See subsection \[lq]Fonts\[rq] below.
-.
 .
 .P
 .I @g@eqn \" GNU
-sets up default spacings as if by the following commands.
+sets up spacings and styles as if by the following commands.
 .
 .P
 .RS
 .TS
 tab(@);
-Lf(CR) Lf(CR).
+Lf(CR)1 Lf(CR).
 chartype \[dq]letter\[dq]@abcdefghiklmnopqrstuvwxyz
 chartype \[dq]letter\[dq]@ABCDEFGHIKLMNOPQRSTUVWXYZ
-.T&
-Lf(CR)t Lf(CR)
-^ Lf(CR)
-^ Lf(CR)
-^ Lf(CR).
-chartype 
\[dq]letter\[dq]@\[rs][*a]\[rs][*b]\[rs][*x]\[rs][*d]\[rs][*e]\[rs][*y]
-\&@\[rs][*g]\[rs][*i]\[rs][*k]\[rs][*l]\[rs][*m]\[rs][*n]
-\&@\[rs][*w]\[rs][*o]\[rs][*f]\[rs][*p]\[rs][*q]\[rs][*r]
-\&@\[rs][*s]\[rs][*t]\[rs][*h]\[rs][*u]\[rs][*c]\[rs][*z]
-.T&
-Lf(CR) Lf(CR).
+chartype \[dq]letter\[dq]@\[rs][*a]\[rs][*b]\[rs][*x]\[rs][*d]\[rs][*e]\
+\[rs][*y]
+chartype \[dq]letter\[dq]@\[rs][*g]\[rs][*i]\[rs][*k]\[rs][*l]\[rs][*m]\
+\[rs][*n]
+chartype \[dq]letter\[dq]@\[rs][*w]\[rs][*o]\[rs][*f]\[rs][*p]\[rs][*q]\
+\[rs][*r]
+chartype \[dq]letter\[dq]@\[rs][*s]\[rs][*t]\[rs][*h]\[rs][*u]\[rs][*c]\
+\[rs][*z]
 chartype \[dq]binary\[dq]@*\[rs][pl]\[rs][mi]
 chartype \[dq]relation\[dq]@<>\[rs][eq]\[rs][<=]\[rs][>=]
 chartype \[dq]opening\[dq]@{([
@@ -516,12 +517,12 @@ assigns all other ordinary and special
 characters,
 including numerals 0\[en]9,
 the
-.RB \[lq] ordinary \[rq]
+.RB \%\[lq] ordinary \[rq]
 type.
 .
 (The
 .RB \[lq] digit \[rq]
-type is not used by default,
+type is not used,
 but is available for customization.)
 .\" XXX: How would you actually customize it, though?  There doesn't
 .\" seem to be a means of replacing the font associated with a type.
@@ -531,7 +532,7 @@ In keeping with common practice in mathematical typesetting,
 lowercase,
 but not uppercase,
 Greek letters are assigned the
-.RB \[lq] letter \[rq]
+.RB \%\[lq] letter \[rq]
 type to style them in italics.
 .
 .
@@ -595,7 +596,8 @@ in subsection \[lq]Fonts\[rq] below.
 .
 .TP
 .BI big\~ e
-Enlarges the expression it modifies;
+Enlarges the expression
+.IR e ;
 intended to have semantics like
 CSS \[lq]large\[rq].
 .
@@ -1048,11 +1050,10 @@ primitive.
 .BI set\~ "p n"
 assigns
 .RI parameter\~ p
-the
-.RI value\~ n ,
-where
+the integer
+.RI value\~ n ;
 .IR n \~is
-an integer.
+interpreted in units of hundredths of an em unless otherwise stated.
 .
 For example,
 .
@@ -1073,10 +1074,8 @@ should assume that the font's x-height is 0.45\~ems.
 .
 .RS
 .P
-Available parameters are as follows.
-.
-Values are in units of hundredths of an em unless otherwise stated,
-with defaults shown in parentheses.
+Available parameters are as follows;
+defaults are shown in parentheses.
 .
 We intend these descriptions to be expository rather than rigorous.
 .
@@ -1698,7 +1697,7 @@ primitive
 sets a character's type,
 which determines the face used to set it.
 .
-The \[lq]letter\[rq] type is set in italics;
+The \%\[lq]letter\[rq] type is set in italics;
 others are set in roman.
 .
 Use the
@@ -1885,17 +1884,15 @@ MathML is designed on the assumption that it cannot 
know the exact
 physical characteristics of the media and devices on which it will
 be rendered.
 .
-It does not support fine control of motions and sizes to the same
+It does not support control of motions and sizes to the same
 degree
 .I @g@troff
 does.
 .
-Thus:
-.
 .
 .IP \[bu] 2n
 .I @g@eqn
-parameters have no effect on the generated MathML.
+customization parameters have no effect on generated MathML.
 .
 .
 .IP \[bu]
@@ -1980,8 +1977,29 @@ instead.
 .
 .
 .P
-Delimited equations are set at the type size that is current at the
-beginning of the input line.
+Delimited equations are set at the type size current at the beginning of
+the input line,
+not that immediately preceding the opening delimiter.
+.
+.
+.P
+Unlike \*[tx],
+.I eqn \" generic
+does not inherently distinguish displayed and inline equation styles;
+see the
+.B smallover
+primitive above.
+.
+However,
+macro packages frequently define
+.B EQ
+and
+.B EN
+macros such that the equation within is displayed.
+.
+These macros may accept arguments permitting the equation to labeled or
+captioned;
+see the package's documentation.
 .
 .
 .\" ====================================================================
@@ -2018,6 +2036,70 @@ but inefficient.
 .
 .
 .\" ====================================================================
+.SH Examples
+.\" ====================================================================
+.
+We first illustrate
+.I @g@eqn
+usage with a trigonometric identity.
+.
+.
+.RS
+.P
+.EX
+\&.EQ
+sin ( alpha + beta ) = sin alpha cos beta + cos alpha sin beta
+\&.EN
+.EE
+.if t \{\
+.
+.
+.P
+.EQ
+sin ( alpha + beta ) = sin alpha cos beta + cos alpha sin beta
+.EN
+.\}
+.RE
+.
+.
+.P
+It can be convenient to set up delimiters if mathematical content will
+appear frequently in running text.
+.
+.
+.RS
+.P
+.EX
+\&.EQ
+delim $$
+\&.EN
+.
+With a large table of logarithms in memory,
+we employed the property $ln ( x y ) = ln x + ln y$ to speed the
+calculation.
+.EE
+.if t \{\
+.
+.
+.P
+.EQ
+delim $$
+.EN
+.
+With a large table of logarithms in memory,
+we employed the property $ln ( x y ) = ln x + ln y$ to speed the
+calculation.
+.
+.\" We _must_ shut delimiters back off when serially processing man
+.\" pages, or subsequent documents cannot safely use those characters.
+.EQ
+delim off
+.EN
+.\}
+.RE
+.
+.
+.\" ====================================================================
 .SH "See also"
 .\" ====================================================================
 .