Re: Typesetting Mathematics by Kernighan and Cherry, retypeset

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Fri, Jul 01, 2022 at 12:58:35AM -0500:

> Joerg van den Hoff's recent question on the bug-groff list motivated me
> to look again at eqn.  groff's eqn(1) man page is not useful to learn
> the program, even Schwarze-style--it is avowedly incomplete, mostly
> documenting only differences from the AT&T implementation.

https://man.openbsd.org/eqn.7 is useful in that sense, though.
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.

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

> 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?

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.

*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 made some very small changes to the source material, but none to
> anything one might consider narrative; they are all commented and
> explained.  The most important avoids lying about when the document was
> rendered.  I used groff extensions unapologetically (but there wasn't
> much to do).

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

Yours,
  Ingo