[groff] 03/05: eqn(1): Expand and clarify.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 08f6c1d79f9aa9c2a14d5dcc1da2f869d05acc69
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu May 18 22:55:42 2023 -0500

    eqn(1): Expand and clarify.
    
    * Add new introductory subsection, "Anatomy of an equation".
    * Document that the GNU eqn "thin_space" and "thick_space" parameters
      also configure the spacing produced by the half space and full space
      tokens, as noted by Doug McIlroy.  Consensus is that this is a bug
      (you might want to be able to tune these widths separately), and we
      expect to address that in a future groff release.
    
    See <https://lists.gnu.org/archive/html/groff/2023-05/msg00065.html> and
    follow-ups.
---
 src/preproc/eqn/eqn.1.man | 160 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 160 insertions(+)

diff --git a/src/preproc/eqn/eqn.1.man b/src/preproc/eqn/eqn.1.man
index 2aeeeb5e8..1e4b39f21 100644
--- a/src/preproc/eqn/eqn.1.man
+++ b/src/preproc/eqn/eqn.1.man
@@ -229,6 +229,158 @@ or
 .
 .
 .\" ====================================================================
+.SS "Anatomy of an equation"
+.\" ====================================================================
+.
+.I eqn
+input consists of tokens.
+.
+Consider a form of Newton's second law of motion.
+.
+The input
+.
+.
+.P
+.RS
+.EX
+\&.EQ
+F =
+m a
+\&.EN
+.EE
+.RE
+.
+.
+.P
+becomes
+.EQ
+F =
+m a.
+.EN
+.
+Each of
+.BR F ,
+.BR = ,
+.BR m ,
+and
+.B a
+is a token.
+.
+.
+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.
+.
+.
+.TP
+.B "{ }"
+Left and right braces perform grouping.
+.
+Whereas
+.RB \[lq] "e sup a b" \[rq]
+expresses
+.ie n .RI \[lq]( e "\~to the\~" a )\~times\~ b \[rq],
+.el \{\
+.EQ
+e sup a b ,
+.EN
+.\}
+.RB \[lq] "e sup { a b }" \[rq]
+means
+.ie n .RI \[lq] e "\~to the\~(" a \~times\~ b )\[rq].
+.el \{\
+.EQ
+e sup { a b } .
+.EN
+.\}
+.
+.
+.TP
+.B \[ha]
+.TQ
+.B \[ti]
+are the
+.I "half space"
+and
+.I "full space,"
+respectively.
+.
+Use them to tune the appearance of the output.
+.
+.
+.P
+Other tokens are primitives,
+macros,
+an argument to either of the foregoing,
+or a component of an equation.
+.
+.
+.P
+.I Primitives
+are fundamental keywords of the
+.I eqn
+language.
+.
+They can configure an aspect of the preprocessor's state,
+such as by setting a \[lq]global\[rq] font selection or type size
+(as with
+.B gfont
+and
+.B gsize),
+declare or delete macros
+(as with
+.B define
+and
+.B undefine);
+these are termed
+.I commands.
+.
+Other primitives perform formatting operations on the tokens after them
+(as with
+.BR big ,
+.BR over ,
+.BR sqrt ,
+or
+.BR up ).
+.
+.
+.P
+.I Macros
+permit primitives and/or components of equations to be grouped together
+for convenience.
+.
+Predefined macros make convenient the preparation of
+.I eqn
+input in a form resembling its spoken expression;
+for example,
+consider
+.BR cos ,
+.BR hat ,
+.BR inf ,
+and
+.BR lim .
+.
+.
+.P
+Equation
+.I components
+include mathematical variables,
+constants,
+numeric literals,
+and operators.
+.
+.
+.\" ====================================================================
 .SS "Automatic spacing"
 .\" ====================================================================
 .
@@ -967,6 +1119,10 @@ The width of subscripts and superscripts is increased by 
this amount.
 This amount of space is automatically inserted after punctuation
 characters.
 .
+It also configures the width of the space produced by the
+.B \[ha]
+token.
+.
 .
 .TP
 .B medium_space
@@ -979,6 +1135,10 @@ binary operators.
 This amount of space is automatically inserted on either side of
 relations.
 .
+It also configures the width of the space produced by the
+.B \[ti]
+token.
+.
 .
 .TP
 .B x_height