Hi folks, 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.
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. 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. So I did. Highlights: 1. A few bugs in vertical space management in groff ms were exposed. https://savannah.gnu.org/bugs/?62686 https://savannah.gnu.org/bugs/?62688 2. An outright bug (arguably) in groff ms's MINGW register was revealed. Its value was ignored if there were only two columns. https://savannah.gnu.org/bugs/?62687 3. Some stuff added to groff ms in 2007 was confirmed as being unnecessary. https://savannah.gnu.org/bugs/?62690 4. Again arguably, a feature is missing from troff; character translations should be properties of the environment, not global. You will notice that the puncuation bracketing the page numbers is inconsistent. Please discuss at the Savannah ticket if interested. https://savannah.gnu.org/bugs/?62691 5. An equation was missing from the Unix V7 C/A/T-typeset rendition of this manual. It is now restored. This does not appear to have been a problem with the source. Did something go wrong with old troff? 6. A feature is arguably missing from GNU eqn with respect to its "set" extension. People shouldn't have to source-dive to recover default values for these pernickety parameters. https://savannah.gnu.org/bugs/?62692 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). Please find attached: A. The re-typeset document in PostScript format. (Until we give ms(7) support for pdfmark, I don't see much point in rendering to PDF.) https://savannah.gnu.org/bugs/?58946 B. A diff to groff's s.tmac file, fixing issues 1, 2, and 3 above. C. A diff between the sources as and my hacked-up version. This includes a Makefile for convenience and a new file, "sbtl", implementing the only 2 AT&T Unix V7 ms macros it requires that groff doesn't implement, or implements differently (MH and UX). D. A compressed tar(1) archive of this hacked-up version's sources. You will need to alter the `GROFF` macro defined in the Makefile. If you patch s.tmac in your groff installation, defining the macro as simply "groff" should work fine. Feedback is appreciated. Regards, Branden
eqnuser.ps
Description: eqnuser.ps
diff --git a/tmac/s.tmac b/tmac/s.tmac index f72a8d698..258431e14 100644 --- a/tmac/s.tmac +++ b/tmac/s.tmac @@ -519,11 +519,7 @@ along with this program. If not, see <http://www.gnu.org/licenses/>. .. .nr pg*P1 0 .de P1 -.ie r bell_localisms \{\ -. DS L -. ft CW -.\} -.el .nr pg*P1 1 +.nr pg*P1 1 .. .wh -\n[FM]u pg@bottom .wh -\n[FM]u/2u pg*footer @@ -541,8 +537,8 @@ along with this program. If not, see <http://www.gnu.org/licenses/>. . \} .\} .ie !\\n(.$ \{\ -. nr pg@colw \\n[LL]*7/15 -. nr pg*gutw \\n[LL]-(2*\\n[pg@colw]) +. nr pg*gutw \\n[MINGW] +. nr pg@colw \\n[LL]-\\n[pg*gutw]/2u . nr pg@ncols 2 .\} .el \{\ @@ -555,10 +551,10 @@ along with this program. If not, see <http://www.gnu.org/licenses/>. . el .nr pg*gutw 0 .\} .DEVTAG ".mc \\n[pg@ncols] \\n[pg@colw] \\n[pg*gutw]" -.ns .nr pg*col-num 0 .nr pg@fn-colw \\n[pg@colw]*\\*[FR] .par@reset +.ns .mk pg*col-top .. .de 2C @@ -976,6 +972,7 @@ along with this program. If not, see <http://www.gnu.org/licenses/>. .de DE .ds*end!\\n[\\n[.ev]:ds-type] .nr \\n[.ev]:ds-type 0 +.ns .. .de ds@auto-end .if \\n[\\n[.ev]:ds-type] \{\ @@ -1884,6 +1881,7 @@ along with this program. If not, see <http://www.gnu.org/licenses/>. . if !'\\*[eqn*num]'' .nr eqn*have-num 1 . ie \\n[dl]:\\n[eqn*have-num] \{\ . sp \\n[DD]u +. ns . par@reset . ds eqn*tabs \\n[.tabs] . nf @@ -1912,6 +1910,7 @@ along with this program. If not, see <http://www.gnu.org/licenses/>. . \} .\". if !'\*(.T'html' .sp \\n[DD]u . sp \\n[DD]u +. ns . ta \\*[eqn*tabs] . \} . el \{\ @@ -2130,41 +2129,6 @@ along with this program. If not, see <http://www.gnu.org/licenses/>. .\} .. .par@load-init -.\" **************************** -.\" ******** module bell ******** -.\" **************************** -.\" Emulate Bell Labs localisms. Note, (a) they're not documented, and -.\" (b) the .P1 and .UC macros collide with different ones in Berkeley -.\" ms. -.\" -.\" [Correction 2022-04-17: 10th Edition AT&T ms also collides with -.\" Berkeley's (undocumented) FP macro.] -.\" -.\" We hack around this by conditionalizing the behavior of P1; UC was -.\" not defined by groff and will be a no-op if called Berkeley style -.\" with no arguments, so there is no problem with hijacking it here. -.\" -.\" What's done here is sufficient to give back the Guide to EQN (1976) -.\" its section headings and restore some text that had gone missing as -.\" macro arguments; no warranty express or implied is given as to how -.\" well the typographic details these produce match the original Bell -.\" Labs macros. -.\" -.\" P1 is now defined in module pg. -.de SC -.nr bell_localisms 1 -.NH -\\$* -.. -.de UC -.if r bell_localisms \f(CR\\$*\fP -.. -.de P2 -.if r bell_localisms \{\ -. ft -. DE -.\} -.. .\" Local Variables: .\" mode: nroff .\" fill-column: 72
diff -uN eqn-v7-pure/Makefile eqn-v7-hacked/Makefile
--- eqn-v7-pure/Makefile 1969-12-31 18:00:00.000000000 -0600
+++ eqn-v7-hacked/Makefile 2022-06-30 22:46:04.799551162 -0500
@@ -0,0 +1,11 @@
+GROFF:=/home/branden/src/GIT/groff/build/test-groff
+
+ALL=eqnuser.ps
+
+EQNUSER=g.mac g0 g1 g2 g3 g4 g5
+
+eqnuser.ps: sbtl.tmac $(EQNUSER)
+ $(GROFF) -ww -e -m s -M . -m sbtl -T ps $(EQNUSER) >$@
+
+clean:
+ rm -f $(ALL)
diff -uN eqn-v7-pure/g0 eqn-v7-hacked/g0
--- eqn-v7-pure/g0 2022-06-30 18:38:30.234150358 -0500
+++ eqn-v7-hacked/g0 2022-07-01 00:17:09.484900630 -0500
@@ -1,9 +1,23 @@
+.\" These values more accurately reflect the pitch of GSI's Times font.
+.nr LL 5.4i
+.nr PO 1.55i
+.\" Define a fake Bell System logo.
+.char \[bs] \o'\[ci]|'
.EQ
delim $$
.EN
-\".ND "June 2, 1976"
-.RP
-\".TM "76-1273-4 76-1271-4" 39199 39199-11
+.
+.af year 000
+.af mo 00
+.af dy 00
+.ND "August 15, 1978 \fI(retypeset with \fPgroff\fI\
+ \n[year]-\n(mo-\n(dy)"
+.RP no \" suppress repeat of document description on first body page
+.\" Force page 1 to be numbered; it follows the cover page and the Unix
+.\" Programmer's Manual page headings (which these sources don't produce
+.\" anyway) are not appropriate for us.
+.nr pg*P1 1
+.\"TM "76-1273-4 76-1271-4" 39199 39199-11
.TL
Typesetting Mathematics _ User's Guide
\&\ \ \ \ \ (Second\ Edition)
@@ -12,13 +26,16 @@
.AI
.MH
.AB
-.in
-.ll
+.\" This document uses the full page width for the abstract.
+.\"in
+.\"ll
+.nr 0:li 0
+.nr 0:ri 0
.PP
This is the user's guide for a system for typesetting
mathematics,
using
-the phototypesetters on the
+the \%photo\%typesetters on the
.UX
and
.UC GCOS
@@ -30,7 +47,7 @@
Enough of the language to set in-line expressions like
$lim from {x-> pi /2} ( tan~x) sup{sin~2x}~=~1$
or display equations like
-.in .5i
+.\"in .5i
.EQ I
G(z)~mark =~ e sup { ln ~ G(z) }
~=~ exp left (
@@ -56,7 +73,7 @@
{ S sub m sup {k sub m} } over {m sup k sub m k sub m ! }
right ) z sup m
.EN
-.in 0
+.\"in 0
can be learned in an hour or so.
.PP
The language interfaces directly with
@@ -73,11 +90,11 @@
.UC UNIX
formatter
.UC NROFF
-to set mathematical expressions on
+to set mathematical \%expressions on
.UC DASI
and
.UC GSI
terminals
and Model 37 teletypes.
.AE
-.CS 11 0 11 0 0 3
+.\"CS 11 0 11 0 0 3
diff -uN eqn-v7-pure/g1 eqn-v7-hacked/g1
--- eqn-v7-pure/g1 2022-06-30 16:28:19.984161912 -0500
+++ eqn-v7-hacked/g1 2022-06-30 23:30:06.042516578 -0500
@@ -1,3 +1,6 @@
+.\" Force extra-large blank area at top of page to match original.
+.sp 10v
+.nr MINGW 5.875n
.if t .2C
.SC Introduction
.PP
@@ -400,6 +403,7 @@
e sup {i omega t}
.P2
is
+.\" This equation got lost in the V7 Volume 2 manual!
.EQ
e sup {i omega t}
.EN
@@ -523,6 +527,7 @@
.EQ
sqrt a+b + 1 over sqrt {ax sup 2 +bx+c}
.EN
+.KS
Warning _ square roots of tall quantities look lousy,
because a root-sign
big enough to cover the quantity is
@@ -534,6 +539,7 @@
.EQ
sqrt{a sup 2 over b sub 2}
.EN
+.KE
Big square roots are generally better written as something
to the power \(12:
.EQ
diff -uN eqn-v7-pure/g2 eqn-v7-hacked/g2
--- eqn-v7-pure/g2 2022-06-30 16:28:19.984161912 -0500
+++ eqn-v7-hacked/g2 2022-06-30 22:42:34.436500637 -0500
@@ -181,9 +181,11 @@
is not subject to any of the font changes and spacing
adjustments normally done by the equation setter.
This provides a way to do your own spacing and adjusting if needed:
+.KS
.P1
italic "sin(x)" + sin (x)
.P2
+.KE
is
.EQ
italic "sin(x)" + sin (x)
@@ -281,6 +283,7 @@
if at all possible.
Thus, for example,
you can say
+.KS
.P1
^EQ I
x+y mark = z
@@ -296,6 +299,7 @@
.EQ I
x lineup = 1
.EN
+.KE
For reasons too complicated to talk about,
when you use
.UC EQN
@@ -428,11 +432,18 @@
right ]
.P2
will make
+.\" Cheat #1: AT&T eqn stacked piles more tightly than GNU eqn.
.EQ
+set baseline_sep 1v
A ~=~ left [
pile { a above b above c } ~~ pile { x above y above z }
right ]
.EN
+.\" Reset equation baseline separation to the default, which is not
+.\" documented anywhere and has no syntactical access. :-/
+.EQ
+set baseline_sep 140
+.EN
The elements of the pile (there can be as many as you want)
are centered one above another, at the right height for
most purposes.
@@ -466,6 +477,9 @@
.ul
cpiles
than it is for ordinary piles.
+.\" Cheat #2: Shrink the display distance a bit to fit this display on
+.\" the page.
+.nr DD -0.25v
.P1 2
roman sign (x)~=~
left {
@@ -473,6 +487,7 @@
~~ lpile
{if~x>0 above if~x=0 above if~x<0}
.P2
+.nr DD +0.25v
makes
.EQ
roman sign (x)~=~
diff -uN eqn-v7-pure/sbtl.tmac eqn-v7-hacked/sbtl.tmac
--- eqn-v7-pure/sbtl.tmac 1969-12-31 18:00:00.000000000 -0600
+++ eqn-v7-hacked/sbtl.tmac 2022-06-30 21:04:56.846814044 -0500
@@ -0,0 +1,15 @@
+.de MH
+Bell Laboratories
+Murray Hill, New Jersey 07974
+..
+.de UX
+.nr btl*seen-UX-macro 0
+.ds btl*UX-suffix \(dg\"
+\s[\\n[.s]*8u/10u]UNIX\s0\\$1\\*[btl*UX-suffix]
+.if !\\n[btl*seen-UX-macro] \{\
+. FS \\*[btl*UX-suffix]
+. nop UNIX is a Trademark of Bell Laboratories.\" sic
+. FE
+. nr btl*seen-UX-macro 1
+.\}
+..
eqn-v7-hacked.tar.gz
Description: eqn-v7-hacked.tar.gz
signature.asc
Description: PGP signature
