groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Learning groff eqn (was: Typesetting Mathematics by Kernighan and Ch


From: Ingo Schwarze
Subject: Re: Learning groff eqn (was: Typesetting Mathematics by Kernighan and Cherry, retypeset)
Date: Sat, 2 Jul 2022 19:47:49 +0200

Hi Branden,

G. Branden Robinson wrote on Sat, Jul 02, 2022 at 11:57:21AM -0500:

> I was thinking this morning that at least groff's lex.cpp for eqn could
> be translated into EBNF for a groff_eqn(7) page; that way the extensions
> would be documented too.

In fact, i'm not a fan of putting BNF into user-facing documentation.
It is good for a language definition in a formal standard because it
is relatively precise for describing syntax, compared to less formal
ways of describing syntax.

But for user documentation, the downside of separating the description
of syntax and semantics, and the downside of BNF being less readable
than a less formal syntax description, usually outweigh the benefit of
higher precision.

To show an extreme exaple, look at:

  https://man.openbsd.org/pf.conf.5#GRAMMAR

Reading that, do you understand what is going on?  At least in that
case, the manual gives the BNF *in addition to* and *after*
describing the syntax and semantics in a more accessible manner.

The reason i so far refrained from changing the structure
of the https://man.openbsd.org/eqn.7 page is that the BNF in there
is reasonably short and simple.  Nonetheless, it's a chunk of rock
that may sit heavily on some people's stomachs, and it is hardly a
model to be followed.

[...]
> So what I would like to see is an _original_ document introducing
> the novice to GNU eqn.
[... reordered ...]
> Before we have such a thing in
> tutorial form, we should probably have a comprehensive eqn language
> _reference_, and a groff_eqn(7) page could well be the vehicle for that.

I certainly don't object to that approach.
What you say sounds reasoable to me.

By the way, it looks like Ted Harding did something like that:

  https://lists.gnu.org/archive/html/groff/2013-10/pdfTyBN2VWR1c.pdf

[...]
> But it's still a good document.  One of my aims has been to play a
> kind of museum (or art) gallery curator: clean it up, increase its
> accessibility, and help the people (including myself) see it and learn
> from it.  For that purpose to be truly fulfilled, it will need to be
> hosted somewhere; we'll see if anyone does so.  :)

Indeed, a mailing list is about the opposite of a museum: Prone to
disappear at some point, completely unstructured and unsorted, and hard
to find - except with web search engines, but those inevitable have a
terrible signal-to-noise ratio.

With respect to hosting, adding it to https://troff.org/papers.html
would seem perfect to me.

Yours,
  Ingo



reply via email to

[Prev in Thread] Current Thread [Next in Thread]