[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Explanations with an EQN User Guide
From: |
G. Branden Robinson |
Subject: |
Re: Explanations with an EQN User Guide |
Date: |
Mon, 22 May 2023 10:08:26 -0500 |
[Sorry--my previous email was a botch.]
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
>
> Adding Spaces to the Input
>
> 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):
>
> 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.
>
> ... replicate example from Section 3 of the EQN document ...
>
> 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.
>
> 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’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).
> Hopefully those words are not considered copyright violations.
>
> 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
.EQ
a→b sqrt { c→d }
.EN
$ ./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√cd
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.
>
> 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
eqn.1
Description: Text document
signature.asc
Description: PGP signature