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
