Learning groff eqn (was: Typesetting Mathematics by Kernighan and Cherry, retypeset)

[G. Branden Robinson]

Hi Ingo,

At 2022-07-02T16:40:40+0200, Ingo Schwarze wrote:
> G. Branden Robinson wrote on Fri, Jul 01, 2022 at 12:58:35AM -0500:
> https://man.openbsd.org/eqn.7 is useful in that sense, though.

D'oh!  I forgot to look there.

> It isn't Schwarze-style either but Kristaps-style instead.
> The main advantage of that document is probably conciseness.
> Then again, the original Kernighan/Cherry user guides have the
> same advantage of not being long, and in addition to that,
> they do make learning easier.

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.

> > Also befuddled by the fact that our man page talks about "macros"
> > (for eqn, not *roff), but the AT&T documentation pointedly doesn't,
> > I decided to go back to the widely praised User's Guide by Kernighan
> > & Cherry with as few assumptions as possible and see what I could
> > learn.
> 
> The mandoc eqn(7) page linked above avoids the term "macro", too,
> precisely because it invites confusion with roff(7) macros.

In the event I get around to writing any eqn documentation, I think I'd
prefer to just confront the difficulty.  pic(7) permits macro definition
in its own little language as well; see §10 of CSTR #116.  It further
supports macro calls with arguments, as groff's extended eqn does, so I
reckon future user-facing groff documentation should emphasize the
similarities here.  The cost, of course, is reminding the user to pay
attention to which language they're writing and expanding macros in.

> > I furthermore wanted to retypeset this document with groff since its
> > source is available and the V7 Unix Programmer's Manual Volume 2
> > scans on the Web are caked with flyspecks and other unpleasantness.
> 
> I understand UNIX v7 is under this BSD-style license by Caldera Inc.:
> 
>   https://www.tuhs.org/Archive/Caldera-license.pdf
> 
> Does that include the directory usr/doc/eqn/?  It seems likely because
> the license contains the words "source code and documentation",
> and a "User Guide" very probably qualifies as documentation.
> Then again, the word "documentation" is only mentioned in the
> context of requirements for redistribution.  In the context of
> granting rights, the license only says:
> 
>   The following copyright notice applies to the source code files
>   for which this license is granted.
> 
> So if you read it in a very picky way, you might suspect that no
> license whatsoever is granted for documentation files, and the
> subsequent requirement regarding documentation has no effect
> because these files aren't licensed in the first place.
> But i think Caldera probably *intended* to also license the
> documentation and simply failed to make that unambiguous -
> surprising as that may seem given that the "Director, Licensing
> Services" signed the letter, and i would expect such a person to
> know what they are doing.  What do you think?

I think an argument can be made for this perspective.  I would hope a
successful one, if it ever had to be litigated.

> If we feel unsure about the licensing status of this document, we
> could also ask Brian Kernighan directly.  It seems possible to me
> (though not certain) that maybe he never re-assigned Copyright of
> this document to AT&T; remember that originally, it was an article
> in the "Communications of the ACM", so it may or may not have been
> subject to his working contract with Bell Labs, and i don't know
> what that contract said.

My impression is that articles submitted to CACM enjoy extra legal
entanglements that other 1970s AT&T Unix documentation did not, probably
because of the ACM's desire to retain reprint rights.  According to the
TUHS list recently, there has been a sea change in ACM's attitude toward
open access recently, but it will apparently take years, somehow, for
its back catalogue to migrate out of their (pay-)walled garden.

On top of that, much of this stuff is often licensed for non-commercial
redistribution, or without permission to modify, so it's not Free
Software.  The document in this thread seems unencumbered enough to be
traded on mailing lists, particularly when also turned to the purpose of
measuring groff's performance as a renderer of materials.  The bar to
become part of a GNU package distribution is, obviously, higher.

> *If* this document is indeed freely licensed, would it make sense
> to include it in the groff distribution?  It could serve three
> useful roles: (1) supplementary, high quality tutorial-style
> documentation, (2) providing informatiuon about portability,
> and (3) a classical example for the use of groff_ms(7).

I agree that it possesses all of these virtues.

> Putting the document into the GNU roff tree would also provide
> the benefit of putting these changes under version control (of
> course, they should be kept minimal).

That's where my enthusiasm falters, and why I don't particularly want to
pester Mr. Kernighan on this point.  I'm happy to maintain documentation
of differences between AT&T implementations of things and groff
extensions, but I don't think tutorial materials should artificially
confine themselves to the capabilities of the historical
implementations.  I think a tutorial document for GNU eqn should take a
synoptic view and limit remarks on feature availability in other
implementations to footnotes or a dedicated section on portability.

For an example of the approach I prefer, see the "meref.me" document
that groff builds (produced from Git HEAD).  I thoroughly revised it,
making most of my changes last December.  (On the other hand, I touched
"meintro.me" barely at all.)

So what I would like to see is an _original_ document introducing the
novice to GNU eqn.  The easiest thing for me to do would be to
progressively perturb K&C from its current state to what I envision.
But there are provenance and possible licensing issues with that
approach.  An original document could also be born copyleft without any
charges of harm to Kernighan & Cherry's legacy (at least on the grounds
of somehow "perverting" or "capturing" their work).

In summary, "keeping changes minimal" is not, I think, compatible in
principle with sticking a document into a Git repository (though in
practice it could remain static through neglect).  A fortiori, it's not
compatible with my working methods.  I already found myself experiencing
strong urges to reverse several of K&C's `tr` tricks, and arguably
incorrect glyph usage (the old bugaboo of the acute accent vs.
apostrophe as quotation marks).  More substantively, there is no reason
to discuss the GCOS operating system anymore, nor any of the terminal
types mentioned.

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.  :)

It's shown me several things groff can do better, which I am glad to be
made aware of.  But I think we should make our own "living document",
more tightly coupled to groff eqn.  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.

Regards,
Branden

signature.asc
Description: PGP signature