[groff] 27/33: eqn(1): Fix content and style nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 0513b50e82ccf348dfee8131b60da8865e059d4e
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Oct 13 04:55:52 2022 -0500

    eqn(1): Fix content and style nits.
    
    * Set terms in italics in summary-description (Savannah #63150).
    * Increase terminological discipline: refer to primitives as such,
      leaving the term "command" for the a general class of instructions
      to the preprocessor.
    * Soften claim: this page _mainly_, but not exclusively, discusses
      differences between AT&T (Unix V7) eqn and GNU eqn.
    * Recast to more clearly distinguish GNU eqn and AT&T eqn when the
      former is installed without a command prefix.
    * Recast discussion of automatic spacing for clarity.  Document
      peristence of "chartype" and non-persistence of "type".
    * Protect "chartype" literal from hyphenation.
    * Expand example of "type" usage to contextualize and closely match the
      actual implementation of "times".
    * Use poor man's keeps with some primitive synopses.
    * Recast discussion of "special" primitive for comprehensibility.
      - Say "drawing position", not "current point".  This is *roff, not
        PostScript.
      - Be more precise about whither the drawing position must be returned.
      - Update "cancel" example to illustrate its usage _without_ defining
        an eqn macro to wrap it.
      - Observe that *roff macro arguments won't be converted to
        mathematical glyphs as eqn otherwise does for its input.
      - Explain more about how the box ("Bx") example works.
      - Fix transcription errors in Bx macro example that broke it.
      - Update Bx example to illustrate definition of eqn macro to wrap it,
        and usage of that macro.
    * Recast discussion of "space" primitive.
    * Migrate description of delimiter usage to a more general location.
    * Migrate terminology: escape -> escape sequence.
    * Stop referring to troff input as "markup".
    * Protect Greek letter names and MathML tags from hyphenation.
    * Drop internal cross reference to material about "translation limits"
      that doesn't seem to be present (and never has been according to "git
      log").
    * Migrate terminology: point size -> type size
    * Recast to avoid use of an example to conceal incomplete sentence.
    * Generalize discussion of word quoting.
    * Fix misplaced modifier.
    * Tighten wording.
---
 src/preproc/eqn/eqn.1.man | 327 ++++++++++++++++++++++++----------------------
 1 file changed, 174 insertions(+), 153 deletions(-)

diff --git a/src/preproc/eqn/eqn.1.man b/src/preproc/eqn/eqn.1.man
index 18133610f..f121dceda 100644
--- a/src/preproc/eqn/eqn.1.man
+++ b/src/preproc/eqn/eqn.1.man
@@ -1,7 +1,9 @@
 '\" t
 .TH @g@eqn @MAN1EXT@ "@MDATE@" "groff @VERSION@"
 .SH Name
-@g@eqn \- format equations for groff or MathML
+@g@eqn \- format equations for
+.I groff
+or MathML
 .
 .
 .\" ====================================================================
@@ -156,12 +158,11 @@ If it exists,
 processes it before the other input files.
 .
 .
-.LP
-Only the differences between GNU
+.P
+This man page primarily discusses the differences between GNU
 .I eqn \" GNU
 and AT&T
-.I eqn \" AT&T
-are described in this document.
+.IR eqn .\" AT&T
 .
 Most of the new features of the GNU
 .I eqn \" GNU
@@ -217,10 +218,10 @@ or
 .\" ====================================================================
 .
 .I eqn
-gives each component of an equation a type,
-and adjusts the spacing between components using that type.
+imputes a type to each component of an equation,
+adjusting the spacing between them accordingly.
 .
-Possible types are described in the table below.
+Recognized types are as follows.
 .
 .
 .IP
@@ -247,58 +248,61 @@ suppress  a type without automatic spacing adjustment
 .TE
 .
 .
-.LP
-Components of an equation get a type in one of two ways.
+.P
+Two primitives apply types to equation components.
+.
+Quote type names in
+.I eqn
+commands to prevent macro expansion from being attempted on their names.
 .
 .
 .TP
 .BI type\~ "t e"
-This yields an equation component that
-.RI contains\~ e
-but that has
-.RI type\~ t ,
-where
-.I t
-is one of the types mentioned above.
+Apply
+.RI type\~ t
+to
+.RI expression\~ e .
 .
 For example,
-.B times
-is defined as follows.
+.RB \[lq] times \[rq]
+is defined as if by the following.
 .
 .
 .RS
 .IP
 .EX
-type "binary" \[rs](mu
+define times \[aq] type "binary" \[rs](mu \[aq]
 .EE
 .RE
 .
 .
-.IP
-The type name doesn't have to be quoted,
-but doing so protects it from macro expansion.
-.
-.
+.br
+.ne 7v
 .TP
 .BI chartype\~ "t text"
 Each (unquoted) character
 .RI in\~ text
 is assigned
-.RI type\~ t .
+.RI type\~ t ,
+persistently.
 .
-The
-.RI type\~ t
-can also be
+If
+.I t
+is
 .RB \[lq] letter \[rq]
 or
-.RB \[lq] digit \[rq];
-in these cases
-.B chartype
-changes the font style of the characters.
+.RB \[lq] digit \[rq],
+.B \%chartype
+also assigns a typeface to each character in
+.IR text .
 .
 See subsection \[lq]Fonts\[rq] below.
 .
-For example,
+As an example,
+the default spacing for some punctuation characters is set up as if
+by the following
+.I eqn \" generic
+command.
 .
 .
 .RS
@@ -309,13 +313,6 @@ chartype "punctuation" .,;:
 .RE
 .
 .
-.IP
-assigns the
-.RB \[lq] punctuation \[rq]
-type to each of the characters in \[lq].,;:\[rq] wherever they
-subsequently appear in an equation.
-.
-.
 .\" ====================================================================
 .SS Primitives
 .\" ====================================================================
@@ -369,9 +366,9 @@ CSS \[lq]large\[rq].
 In
 .I @g@troff
 output,
-the point size is increased by\~5;
-in MathML output,
-the expression uses
+the type size is increased by\~5.
+.
+MathML output emits the following.
 .
 .
 .RS
@@ -575,17 +572,19 @@ that is not the first character on the input line is 
treated like
 .
 .TP
 .BI special\~ "text e"
-This constructs a new object
-.RI from\~ e
-using a
-.MR @g@troff @MAN1EXT@
-macro named
-.IR text .
+Construct an object by calling the
+.I troff \" generic
+macro
+.I text
+.RI on\~ e .
 .
-When the macro is called,
-the string
+The
+.I troff \" generic
+string
 .B 0s
-contains the output
+contains the
+.I eqn \" generic
+output
 .RI for\~ e ,
 and the registers
 .BR 0w ,
@@ -594,12 +593,13 @@ and the registers
 .BR 0skern ,
 and
 .B 0skew
-contain the width,
+the width,
 height,
 depth,
 subscript kern,
 and skew
-.RI of\~ e .
+.RI of\~ e ,
+respectively.
 .
 (The
 .I subscript kern
@@ -615,12 +615,12 @@ accent over it should be placed.)
 .
 The macro must modify
 .B 0s
-so that it outputs the desired result with its origin at the current
-point,
-and increase the current horizontal position by the width of the object.
+so that it outputs the desired result and returns the drawing position
+to the text baseline at the beginning of
+.IR e .
 .
-The registers must also be modified so that they correspond to
-the result.
+Update these registers to correspond to the new dimensions of the
+result.
 .
 .
 .IP
@@ -629,81 +629,102 @@ suppose you wanted a construct that \[lq]cancels\[rq] an 
expression by
 drawing a diagonal line through it.
 .
 .
+.br
+.ne 11v
 .RS
 .IP
-.if t .ne 10v+\n(.Vu
 .EX
-\&.EQ
-define cancel \[aq]special Ca\[aq]
-\&.EN
 \&.de Ca
-\&.\&  ds 0s \[rs]
+\&.  ds 0s \[rs]
 \[rs]Z\[aq]\[rs]\[rs]*(0s\[aq]\[rs]
 \[rs]v\[aq]\[rs]\[rs]n(0du\[aq]\[rs]
 \[rs]D\[aq]l \[rs]\[rs]n(0wu \-\[rs]\[rs]n(0hu-\[rs]\[rs]n(0du\[aq]\[rs]
 \[rs]v\[aq]\[rs]\[rs]n(0hu\[aq]
 \&..
+\&.EQ
+special Ca "x \[rs][mi] 3 \[rs][pl] x" \[ti] 3
+\&.EN
 .EE
 .RE
 .
 .
 .IP
-You could then cancel an
-.RI expression\~ e
-with
-.RB \[lq] "cancel {"
-.I e
-.BR } \[rq].
-.
+We use the
+.B \[rs][mi]
+and
+.B \[rs][pl]
+special characters instead of + and \-
+because they are part of the argument to a
+.I @g@troff
+macro,
+so
+.I @g@eqn
+does not transform them to mathematical glyphs for us.
 .
-.IP
 Here's a more complicated construct that draws a box around an
-expression.
+expression;
+the bottom of the box rests on the text baseline.
+.
+We define the
+.I eqn \" generic
+macro
+.B box
+to wrap the call of the
+.I @g@troff
+macro
+.BR Bx .
 .
 .
+.br
+.ne 17v
 .RS
 .IP
-.if t .ne 18v+\n(.Vu
 .EX
-\&.EQ
-define box \[aq]special Bx\[aq]
-\&.EN
 \&.de Bx
 \&.ds 0s \[rs]
-\[rs]Z\[aq]\[rs]h\[aq]1n\[aq]\[rs]\[rs]*(0s\[aq]\[rs]
-\[rs]Z\[aq]\[rs]
+\[rs]Z\[aq]\[rs]\[rs]h\[aq]1n\[aq]\[rs]\[rs]*[0s]\[aq]\[rs]
 \[rs]v\[aq]\[rs]\[rs]n(0du+1n\[aq]\[rs]
 \[rs]D\[aq]l \[rs]\[rs]n(0wu+2n 0\[aq]\[rs]
-\[rs]D\[aq]l 0 \-\[rs]\[rs]n(0hu\-\[rs]\[rs]n(0du-2n\[aq]\[rs]
+\[rs]D\[aq]l 0 \-\[rs]\[rs]n(0hu\-\[rs]\[rs]n(0du\-2n\[aq]\[rs]
 \[rs]D\[aq]l \-\[rs]\[rs]n(0wu\-2n 0\[aq]\[rs]
 \[rs]D\[aq]l 0 \[rs]\[rs]n(0hu+\[rs]\[rs]n(0du+2n\[aq]\[rs]
-\&\[aq]\[rs]
 \[rs]h\[aq]\[rs]\[rs]n(0wu+2n\[aq]
 \&.nr 0w +2n
 \&.nr 0d +1n
 \&.nr 0h +1n
 \&..
+\&.EQ
+define box \[aq] special Bx $1 \[aq]
+box(foo) \[ti] "bar"
+\&.EN
 .EE
 .RE
 .
 .
+.br
+.ne 5v
 .TP
 .BI space\~ n
-A positive value of the
-.RI integer\~ n
-(in hundredths of an em)
-sets the vertical spacing before the equation,
-a negative value sets the spacing after the equation,
-replacing the default values.
+Set extra vertical spacing around the equation,
+replacing the default values,
+where
+.IR n \~is
+an integer in hundredths of an em.
+.
+If positive,
+.IR n \~increases
+vertical spacing before the equation;
+if negative,
+it does so after the equation.
 .
 This primitive provides an interface to
 .IR groff 's
 .B \[rs]x
-escape
-(but with opposite sign).
+escape sequence,
+but with the opposite sign convention.
 .
-This keyword has no effect if the equation is part of a
-.I pic
+It has no effect if the equation is part of a
+.MR @g@pic @MAN1EXT@
 picture.
 .
 .
@@ -716,12 +737,12 @@ recognizes an
 .RB \[lq] on \[rq]
 argument to the
 .B delim
-primitive specially;
-restoring any delimiters that have been previously disabled with
+primitive specially,
+restoring any delimiters previously disabled with
 .RB \[lq] "delim off" \[rq].
 .
 If delimiters haven't been specified,
-neither of these commands have effect.
+neither command has effect.
 .
 .
 .TP
@@ -755,13 +776,15 @@ increases the vertical spacing between rows,
 using
 .IR groff 's
 .B \[rs]x
-escape
+escape sequence
 (the value has no effect in MathML mode).
 .
 Negative values are possible but have no effect.
 .
-If there is more than a single value given in a matrix,
-the biggest one is used.
+If more than one
+.I n
+occurs in a matrix,
+the largest is used.
 .
 .
 .\" ====================================================================
@@ -770,9 +793,9 @@ the biggest one is used.
 .
 When
 .I eqn
-is generating
+generates
 .I troff \" generic
-markup,
+input,
 the appearance of equations is controlled by a large number of
 parameters.
 .
@@ -782,7 +805,7 @@ rendering engine.
 .
 These parameters can be set using the
 .B set
-command.
+primitive.
 .
 .
 .TP
@@ -825,7 +848,7 @@ definitive.
 .TP
 .B minimum_size
 .I @g@eqn
-won't set anything at a smaller point size than this.
+won't set anything at a smaller type size than this.
 .
 The value is in points.
 .
@@ -956,28 +979,28 @@ escape sequence.
 .B num1
 The
 .B over
-command shifts up the numerator by at least this amount.
+primitive shifts up the numerator by at least this amount.
 .
 .
 .TP
 .B num2
 The
 .B smallover
-command shifts up the numerator by at least this amount.
+primitive shifts up the numerator by at least this amount.
 .
 .
 .TP
 .B denom1
 The
 .B over
-command shifts down the denominator by at least this amount.
+primitive shifts down the denominator by at least this amount.
 .
 .
 .TP
 .B denom2
 The
 .B smallover
-command shifts down the denominator by at least this amount.
+primitive shifts down the denominator by at least this amount.
 .
 .
 .TP
@@ -1151,10 +1174,11 @@ and
 output devices.
 .
 .
-.LP
-A more precise description of the role of many of these
-parameters can be found in Appendix\~H of
-.IR "The \*[tx]book" .
+.P
+Appendix\~H
+of
+.I "The \*[tx]book"
+discusses many of these parameters in greater detail.
 .RE
 .
 .
@@ -1162,7 +1186,9 @@ parameters can be found in Appendix\~H of
 .SS Macros
 .\" ====================================================================
 .
-Macros can take arguments.
+In GNU
+.IR eqn , \" GNU
+macros can take arguments.
 .
 In a macro body,
 .BI $ n
@@ -1179,36 +1205,36 @@ 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
-command is recognized as a macro call with arguments;
+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.
 .
+In the following synopses,
+.I X
+can be any character not appearing in the parameter thus bracketed.
+.
 .
 .TP
 .BI sdefine\~ "name X anything X"
 This is like the
 .B define
-command,
+primitive,
 but
 .I name
 is not recognized if called with arguments.
 .
 .
 .TP
-.BI "include \[dq]" file \[dq]
+.BI include\~ file
 .TQ
-.BI "copy \[dq]" file \[dq]
-Include the contents of
-.I file
-.RB ( include
-and
-.B copy
-are synonyms).
+.BI copy\~ file
+Interpolate the contents of
+.IR file .
 .
-Lines of
+Lines in
 .I file
 beginning with
 .B .EQ
@@ -1231,10 +1257,6 @@ process
 otherwise ignore
 .IR anything .
 .
-.I X
-can be any character not appearing in
-.IR anything .
-.
 .
 .TP
 .BI undef\~ name
@@ -1247,9 +1269,10 @@ making it undefined.
 .SS "Predefined macros"
 .\" ====================================================================
 .
-.I @g@eqn
+GNU
+.I eqn \" GNU
 supports the predefined macros offered by AT&T
-.I eqn:
+.IR eqn : \" AT&T
 .BR and ,
 .BR approx ,
 .BR arc ,
@@ -1300,11 +1323,11 @@ and
 .RB \[lq] .\|.\|. \[rq].
 .
 The lowercase classical Greek letters are available as
-.BR alpha ,
+.BR \%alpha ,
 .BR beta ,
 .BR chi ,
 .BR delta ,
-.BR epsilon ,
+.BR \%epsilon ,
 .BR eta ,
 .BR gamma ,
 .BR iota ,
@@ -1313,7 +1336,7 @@ The lowercase classical Greek letters are available as
 .BR mu ,
 .BR nu ,
 .BR omega ,
-.BR omicron ,
+.BR \%omicron ,
 .BR phi ,
 .BR pi ,
 .BR psi ,
@@ -1321,7 +1344,7 @@ The lowercase classical Greek letters are available as
 .BR sigma ,
 .BR tau ,
 .BR theta ,
-.BR upsilon ,
+.BR \%upsilon ,
 .BR xi ,
 and
 .BR zeta .
@@ -1329,9 +1352,9 @@ and
 Obtain their uppercase forms by spelling these names with an initial
 capital letter or in full capitals,
 as in
-.B Alpha
+.B \%Alpha
 or
-.BR ALPHA .
+.BR \%ALPHA .
 .
 .
 .P
@@ -1360,9 +1383,9 @@ an italic font for letters,
 and a roman font for everything else.
 .
 The AT&T
-.I eqn
+.I eqn \" AT&T
 .B gfont
-command changes the font that is used as the italic font.
+primitive changes the font that is used as the italic font.
 .
 By default this
 .RB is\~ I .
@@ -1378,7 +1401,7 @@ Set the roman font
 .RI to\~ f .
 .
 .
-.LP
+.P
 The
 .B italic
 primitive uses the current italic font set by
@@ -1388,25 +1411,27 @@ the
 primitive uses the current roman font set by
 .BR grfont .
 .
-There is also a new
+GNU
+.I eqn \" GNU
+offers a
 .B gbfont
-command,
+primitive,
 which changes the font used by the
 .B bold
 primitive.
 .
-If you only use the
+If you use only the
 .BR roman ,
 .B italic
 and
 .B bold
-primitives to changes fonts within an equation,
-you can change all the fonts used by your equations just by using
+primitives to change fonts within an equation,
+then
 .BR gfont ,
 .B grfont
 and
 .B gbfont
-commands.
+suffice to configure all the typefaces used by your equations.
 .
 .
 .LP
@@ -1414,7 +1439,7 @@ You can control which characters are treated as letters
 (and therefore set in italics)
 by using the
 .B chartype
-command described above.
+primitive described above.
 .
 A type of
 .B letter
@@ -1604,7 +1629,7 @@ The
 and
 .B back
 operations cannot be implemented,
-and yield a MathML \[lq]<merror>\[rq] message instead.
+and yield a MathML \%\[lq]<merror>\[rq] message instead.
 .
 .IP \[bu]
 The
@@ -1639,18 +1664,14 @@ be recognized as strings that begin with 
\[lq]<math>\[rq] and end with
 \[lq]</math>\[rq] and do not cross line boundaries.
 .
 .
-.LP
-See section \[lq]Bugs\[rq] below for translation limits specific to
-.IR @g@eqn .
-.
-.
 .\" ====================================================================
 .SH Bugs
 .\" ====================================================================
 .
-Names of macros and primitives must be quoted anywhere they occur in
+Words must be quoted anywhere they occur in
 .I eqn \" generic
-input if they are to be interpreted by
+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,
@@ -1688,7 +1709,7 @@ instead.
 .
 .
 .P
-Inline equations are set at the point size that is current at the
+Inline equations are set at the type size that is current at the
 beginning of the input line.
 .
 .