a bit more eqn documentation (was: thin_space causes collateral damage in eqn)

[G. Branden Robinson]

Hi folks,

At 2023-05-17T15:17:55+1000, Damian McGuckin wrote:
> On Tue, 16 May 2023, Douglas McIlroy wrote (but in not the same order)
> 
> > Apparently thin_space serves double duty--to control automatic
> > spacing and to set the width of ^.
> 
> > This coupling of function strikes me as a bug. One thinks of ^ and ~
> > as groff keywords, not characters. And even if they are characters,
> > they represent white space placed deliberately, not "automatically
> > inserted".
> 
> I would agree with Doug 100%
> 
> > Another parameter, thick_space, has the same effect on ~.
[...]
> The documentation says that *_space are only for automatic spacing.
> 
> I actually cannot see where the meaning of either '~' or '^' is
> defined in the GNU eqn(1) manual page. But maybe my eyes are getting
> old. Or I should consider Branden's comment and take that as a delta
> against some implied expert's understanding of EQN. Sadly I am not an
> expert yet because I am still learning things about EQN after 40
> years.
> 
> I note that the Plan 9 eqn(1) man page says
> 
>       "Tokens within eqn are separated by spaces, tabs, newlines,
>       braces, double quotes, tildes or circumflexes. Braces {} are
>       used for grouping; generally speaking, anywhere a single
>       character like x could appear, a complicated construction
>       enclosed in braces may be used instead. Tilde ~ represents a
>       full space in the output, circumflex ^ half as much."
> 
> Maybe text along those lines needs to go into GNU eqn's man page.

I have prepared the following documentation-only change to our eqn(1)
man page for push to the master branch, which means it can appear in
groff 1.23.0 final (hoping to hear from Bertrand soon re: that or RC5).
My hope is that it is enough to get more people on the eqn bicycle.

My presentation isn't _quite_ like Plan 9's; I slept on the subject for
a day and then prepared it from a look-see at groff's
src/preproc/eqn/lex.cpp and a little experimentation.  I may be one of
the few people in the world who has ever deliberately put a leader
character into an eqn equation.  Alas, it wasn't in anger, but just to
see what would happen.

First, the formatted form in context, then the diff.

    • GNU eqn sets the input token “...” as three periods or low dots,
      rather than the three centered dots of AT&T eqn.  To get three
      centered dots, write cdots or “cdot cdot cdot”.
[new stuff follows]

  Anatomy of an equation
    eqn input consists of tokens.  Consider a form of Newton’s second
    law of motion.  The input

        .EQ
        F =
        m a
        .EN

    becomes F=ma.  Each of F, =, m, and 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 eqn input).

    A handful of tokens manage the grouping and spacing of other tokens.

    { } Left and right braces perform grouping.  Whereas “e sup a b”
        expresses “(e to the a) times b”, “e sup { a b }” means “e to
        the (a times b)”.

    ^
    ~   are the half space and full space, respectively.  Use them to
        tune the appearance of the output.

    Other tokens are primitives, macros, an argument to either of the
    foregoing, or a component of an equation.

    Primitives are fundamental keywords of the eqn language.  They can
    configure an aspect of the preprocessor’s state, such as by setting
    a “global” font selection or type size (as with gfont and gsize),
    declare or delete macros (as with define and undefine); these are
    termed commands.  Other primitives perform formatting operations on
    the tokens after them (as with big, over, sqrt, or up).

    Macros permit primitives and/or components of equations to be
    grouped together for convenience.  Predefined macros make convenient
    the preparation of eqn input in a form resembling its spoken
    expression; for example, consider cos, hat, inf, and lim.

    Equation components include mathematical variables, constants,
    numeric literals, and operators.
[old stuff follows]

  Automatic spacing
    eqn imputes a type to each component of an equation, adjusting the
    spacing between them accordingly.  Recognized types are as follows.
[...]

There is also the matter Doug originally raised:

        thin_space
            This amount of space is automatically inserted after
            punctuation characters.  It also configures the width of the
            space produced by the ^ token.
[...]
        thick_space
            This amount of space is automatically inserted on either
            side of relations.  It also configures the width of the
            space produced by the ~ token.

That isn't a fix, but it might guide the perplexed.

commit 08f6c1d79f9aa9c2a14d5dcc1da2f869d05acc69
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   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.

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 @@ .SH Description
 .
 .
 .\" ====================================================================
+.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 @@ .SS Customization
 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 @@ .SS Customization
 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

Regards,
Branden

signature.asc
Description: PGP signature