[no subject]

[G. Branden Robinson]

Date: Mon, 22 May 2023 10:02:03 -0500
From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
To: groff@gnu.org
Subject: Re: Explanations with an EQN User Guide
Message-ID: <20230522150203.dkeyngdn2aja5el5@illithid>
References: <7f8f90ad-8c2-3980-7b27-a6db4ac959df@esi.com.au>
MIME-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha256;
        protocol="application/pgp-signature"; boundary="3eb75myzf7sss5ir"
Content-Disposition: inline
In-Reply-To: <7f8f90ad-8c2-3980-7b27-a6db4ac959df@esi.com.au>


--3eb75myzf7sss5ir
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

At 2023-05-22T15:46:15+1000, Damian McGuckin wrote:
> I am resurrecting my re-write of the EQN User Guide which was itself
> an elaboration of Ted Harding's User Guide. I have used many examples
> from BrianK's and LorindaC's original 2nd Edition EQN document because
> I wanted backwards continuity in the examples. Ted also addresses MM
> which I have also done.

Cool!

> I still need to chase up Nokia to sort out any copyright issues.

Good luck!

> I also need to find Ted to get his permission because I like many of his
> explanations and examples.

I went looking for him about a year ago and had no luck.  Emails
bounced.

> In a section (which Ted did not address) entitled
>=20
>       Adding Spaces to the Input
>=20
> where I use 'eqn' (emboldened) to refer to the program and 'EQN' to
> refer to the language, and before which I have defined EQN delimiters,
> I say (to use my own words with the sloppy words removed):
>=20
>       Luckily, eqn discards any spaces and newlines seen within an
>       expression encapsulated within EQN delimiters. This means that
>       any EQN mathematics can (and should) freely contain spaces and
>       newlines to make that mathematics both easy to read and easy to
>       edit.
>=20
>       ... replicate example from Section 3 of the EQN document ...
>=20
>       Rule: Very long lines in the input to eqn are to be avoided.
>       They are a bad idea. They always reduce readability and can
>       annoyingly hide hard-to-fix bugs.
>=20
> Is that as tight as the original words by BrianK and LorindaC?

I recently updated our eqn(1) man page along similar lines.

  Anatomy of an equation
    eqn input consists of tokens.  Consider a form of Newton=E2=80=99s seco=
nd
    law of motion.  The input

        .EQ
        F =3D
        m a
        .EN

    becomes F=3Dma.  Each of F, =3D, 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).

> Hopefully those words are not considered copyright violations.
>=20
> Now, what about tabs. The original 'eqn' documentation seemed to imply
> that tabs interacted with troff's tabs. I thought I used tabs as white
> space with impunity during the 80s but my memory might be bad.

As far as I can tell, they do interact, but fortunately
straightforwardly.  (I'm still developing my understanding here.)

Here are two things I'm pretty confident of:

1.  Input tab characters are accepted at the "outermost level" of input.
    Basically, a tab occurs within braces, it will be rejected.

(UTF-8 follows.)

$ cat EXPERIMENTS/eqn-using-tab.roff
=2EEQ
a=E2=86=92b sqrt { c=E2=86=92d }
=2EEN
$ ./build/test-groff -Tutf8 -e EXPERIMENTS/eqn-using-tab.roff | cat -s
eqn:EXPERIMENTS/eqn-using-tab.roff:1: error: tabs allowed only at outermost=
 level
a       b=E2=88=9Acd

2.  eqn does not alter the tab stops in any way.

3.  eqn doesn't seem to check for leader characters, but I predict
    they'd cause similar problems that tabs would (when not ignored).
    But I haven't experimented or made a code change along these lines
    yet.  Leaders don't seem like a thing a sane eqn user would employ.

> The last time (2020) I tried to used tabs was when I was embedding
> them in EQN input that contains matrices. They caused total havoc to
> 'eqn' - I think it was release 1.22.3. Not sure. I stopped using them
> and problems went away.

Hard to construct a matrix without using { }.

> Anyway, I now avoid tabs like the plague.
>=20
> What should I say about them?

I don't have any language to suggest yet; I'm still in fact-finding
mode.  But I hope the above helps a bit.

You might be interested in the eqn.1 document from groff Git HEAD, so
I'm attaching it.  In fact this is from my working copy with yet more
changes since my last push a few hours ago.

I think our efforts will prove complementary; I am certainly not trying
to write a user's guide here, but to (finally) document GNU eqn in
sufficient detail than an expert like Doug can use it profitably as a
technical reference.  Right now I'm still working through the very
basics: pretty much lexical analysis issues.  Once I've got that sorted,
there is a long list of primitives to explicate.  Then the predefined
macros.  Then maybe the page will be approximately done.

Regards,
Branden

--3eb75myzf7sss5ir
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iQIzBAABCAAdFiEEh3PWHWjjDgcrENwa0Z6cfXEmbc4FAmRrg+MACgkQ0Z6cfXEm
bc6lIQ/5AXXzMHRbS8B+9dSzidpek6r5oVFhRB5EwqLlk0gkggba0Zow88Wnh7XZ
PXsOYz+4Cb7KSbjPEZK7QykOww96/eg4q2Fi/KQYZvsnFnTRhvN4TsT6PsVxc2u2
oJLof+8GDPaR/eK7zLmYkKbMVomRI5uUaEh02vr272oSu7yP+feyDy5LuKQUsoai
BicVC1ofFTqquIn20uYj2v3FZ9GCDNch8WeNan78l6zMX9YNT3jRWOgEALkX0y0O
indoBrO8ZEhwkIYIi7eDvtb89zepAqK6TXb2CFNhFdpW5OyUdrJIlihDhFeMdl9u
O7NKaKDvw6CWzFTsqM+5fWF+RSn6P8fkG+rfDqQjr6KjbICamv864pThEzDwRfY8
12wOhsaWbu5LQu++26dJD1k+kK5X+y9IRxaB+hE7oPmQgaiuJDdsDZDkT8mGVi69
NZx8ztgsMKnVe5jvM1CeoVCsEE6zBaaWuA/lEMgFjnQMlQJTHlkarqGRWdOeD8uY
Q/JxX2Py7WCwtzx2AljNTDPeF2tZCHdUinPirVzX7qmNv3XeHff0YoiXJjBu7O/s
5QvaJApWixoU1hno49W2YWYzmVg/WXldGjSa6fVtk/wZgQSSXZQy8CYc1Hn7hghL
+zBXXnOkifXjDGrxDGDVqNhNbcYpqTEoHSIAJpaulZqtOXrUnqA=
=ioTc
-----END PGP SIGNATURE-----

--3eb75myzf7sss5ir--