[TUHS] Reconstituted - Program design in the UNIX environment

Tue Jul 7 16:05:05 AEST 2026

Hi Arnold,

At 2026-07-06T15:32:16+0300, Aharon Robbins via TUHS wrote:
> Last week, with some spare time and a desire to stop doing things
> that really needed doing, I decided to try to reconstitute the troff
> source for "Program design in the UNIX environment" which had
> apparently been lost.
> 
> This version fixes a few issues in the existing PostScript version
> of the document from http://harmful.cat-v.org.
> 
> I've made it available at https://github.com/arnoldrobbins/unix-program-design
> also.

Thanks for doing this work!

> Comments and/or fixes are welcome.

I have several observations.  They are not necessarily critiques.  Some
are notes to myself, or to anyone interested in contributing to groff to
improve it, or are simply things to keep in mind about how the ms(7)
package has evolved over the years.

 1.  It's nice to see the dagger reappearing in the document title.

 2.  groff ms's default line length is longer than that used by the
     original version of this document.  groff ms uses symmetrical left
     and right margins by default (about 190 px on my screen); the
     original PostScript file did not (left: ~190px, right: ~290 px).

 3.  Figure 1 now looks reasonable.  I think Clem Cole asked me to look
     into why the original version formatted so weirdly.  I wanted to
     answer his question, but I couldn't come up with one: I checked out
     my copy of the V1 cat.1 man page, but it is a truly plain text
     document.  No overstriking is evident.  I therefore cannot account
     for the appearance of the underscores in the original PostScript
     file.

 4.  The bibliographic references are set as footnotes instead of end
     notes.  Arnold has a comment in the reconstruction:

.\" Notable differences:
.\"     - The formatting of the references is different. Anyone who knows
.\"       how to make GNU refer mimic the original markup, please
.\"       let me know.

    When formatting the document for myself with groff 1.24.1, I got a
    couple of diagnostics.

$ groff -R -m s -T pdf unix_prog_design.ms >| unix_prog_design.pdf
refer:unix_prog_design.ms:687: error: found '$LIST$' but not accumulating references
troff:unix_prog_design.ms:145: warning: font name 'CW' is deprecated

    Seeing that hint, with the following patch, the footnotes become end
    notes like in the original document.

$ git diff

diff --git a/unix_prog_design.ms b/unix_prog_design.ms
index 35de433..dd34f47 100644
--- a/unix_prog_design.ms
+++ b/unix_prog_design.ms
@@ -21,6 +21,9 @@
 .\"    - Thanks to Brian Kernighan's CSTR 100 macros for .P1 and .P2.
 .\"
 .so prog.mac
+.R1
+accumulate
+.R2
 .TL
 Program design in the UNIX\(dg
 .FS

     This means that it appears that GNU refer's `-e` option, which
     means the same thing, didn't work.  I'll have to file a Savannah
     ticket about that.

 5.  Regarding the other diagnostic:

troff:unix_prog_design.ms:145: warning: font name 'CW' is deprecated

     ...font names are a known portability grievance.  You can either
     change "prog.mac" to use groff's name for Courier roman, "CR", or
     use groff ms's font selection macros.  Here's an example of each
     solution.

$ git diff
diff --git a/prog.mac b/prog.mac
index 21a61fe..a14fbba 100644
--- a/prog.mac
+++ b/prog.mac
@@ -19,7 +19,7 @@
 .nf
 .ps -\\n(dP
 .vs -\\n(dVu
-.ft CW
+.ft CR
 .nr t \\n(dT*\\w'x'u
 .ta 1u*\\ntu 2u*\\ntu 3u*\\ntu 4u*\\ntu 5u*\\ntu 6u*\\ntu 7u*\\ntu 8u*\\ntu 9u*\\ntu 10u*\\ntu 11u*\\ntu 12u*\\ntu 13u*\\ntu 14u*\\ntu
 ..

$ git diff
diff --git a/prog.mac b/prog.mac
index 21a61fe..a3ae43f 100644
--- a/prog.mac
+++ b/prog.mac
@@ -19,7 +19,7 @@
 .nf
 .ps -\\n(dP
 .vs -\\n(dVu
-.ft CW
+.CW
 .nr t \\n(dT*\\w'x'u
 .ta 1u*\\ntu 2u*\\ntu 3u*\\ntu 4u*\\ntu 5u*\\ntu 6u*\\ntu 7u*\\ntu 8u*\\ntu 9u*\\ntu 10u*\\ntu 11u*\\ntu 12u*\\ntu 13u*\\ntu 14u*\\ntu
 ..
@@ -28,7 +28,7 @@
 .ps \\n(PS
 .vs \\n(VSp
 .vs \\nvu
-.ft 1
+.R
 .in
 .di
 .br

     However, there are other uses of `\f(CW` in the document, and they
     warn too.  Due to the unpopularity of repeated font availability
     warnings, GNU troff emits only one per font name.[1]  In the
     future, I'd like GNU troff to work more like a proper linter in
     this respect, and issue a warning on each occurrence, there by
     making it easier to drive an editor session by redirecting its
     stderr to a file, and then editing that file with `vi -q`.

     Here's a patch to reformat the table of Pike-disapproved cat(1)
     options more similarly to the original PostScript file.  I have no
     idea if K&P originally used tbl(1) for this purpose.  I also
     reduced the type size, as is apparent in the original PostScript,
     and changed the option dashes to use the "correct" glyph, `\-`.[2]

@@ -292,16 +292,19 @@ with features. This list comes from
 .CW cat
 on the Berkeley distribution of the UNIX system:
 .PP
-.nf
-.in .5i
-\f(CW-s\fP             strip multiple blank lines to a single instance
-\f(CW-n\fP             number the output lines
-\f(CW-b\fP             number only the non-blank lines
-\f(CW-v\fP             make non-printing characters visible
-               \f(CW-ve\fP             mark ends of lines
-               \f(CW-vt\fP             change representation of tab
-.in -.5i
-.fi
+.RS
+.TS
+Lf(CR)p-1 Lp-1 S.
+\-s    strip multiple blank lines to a single instance
+\-n    number the output lines
+\-b    number only the non-blank lines
+\-v    make non-printing characters visible
+.T&
+L Lf(CR)p-1 Lp-1.
+\&     \-ve    mark ends of lines
+\&     \-vt    change representation of tab
+.TE
+.RE
 .PP
 In System V, there are similar options and even a clash of naming:
 .CW -s

     (One could alternatively eschew the `p` column modifiers to the
     table, and bracket the whole thing in `.ps -1` and `.ps` instead.)

     Using tbl(1) of course requires modification of the command line.

     $ groff -Rt -m s -T pdf unix_prog_design.ms >| unix_prog_design.pdf

 6.  Cleaning up another occurrences of font `CW`, I saw further
     opportunities to use `\-` for Unix option dashes and also to employ
     ms(7)'s `Q` and `U` strings for typographer's quotation marks.
     However, the latter are 4.2BSD ms extensions--a fact I had not
     documented in groff's ms(7) man page and "ms.ms" document!  So I'll
     take a note to myself to fix that.  Using `` and '' appears to kern
     the symbols more closely to the original.  On the gripping hand,
     passing 3 arguments to the `CW` macro _is_ a GNU extension in groff
     ms(7).  You can always get around that with `\c`, though.

@@ -353,7 +356,8 @@ But what about
 .CW -v ?
 That prints non-printing characters in a visible
 representation. Making strange characters visible is a genuinely new
-function, for which no existing program is suitable. (``\f(CWsed -n l\fP'',
+function, for which no existing program is suitable.
+.CW "sed \-n l" ``, ''
 the closest standard possibility, aborts when given very long input
 lines, which are more likely to occur in files containing non-printing
 characters.) So isn't it appropriate to add the

@@ -535,7 +539,8 @@ pr -$0 -t -l1 $*
 is the program name (\c
 .CW 2 ,
 .CW 3 ,
-etc.), so \-\f(CW$0\fP
+etc.), so
+.CW $0 "" \-
 becomes \-\fIn\fP
 where
 .I n

 7.  I see that the em dashes in the "use of cat" footnote now actually
     appear.

Great work!

Regards,
Branden

[1] https://lists.gnu.org/archive/html/groff/2024-10/msg00066.html
[2] https://lwn.net/Articles/947941/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://www.tuhs.org/pipermail/tuhs/attachments/20260707/52b78eb1/attachment.sig>
