[TUHS] Reconstituted - Program design in the UNIX environment
Arnold Robbins via TUHS
tuhs at tuhs.org
Tue Jul 7 17:32:43 AEST 2026
Hi.
Thanks for these. I have made changes, although not verbatim,
conditionalizing some things on \(.g for groff. I'd like the document
to remain portable to Plan 9 troff.
I've pushed the updates to Github.
W.R.T. the cat(I) man page, I simply put in backspaces to get the
overstriking, and manually converted whatever weird bit was in the
PostScript for the em dashes back into \(em.
Thanks,
Arnold
"G. Branden Robinson via TUHS" <tuhs at tuhs.org> wrote:
> 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/
More information about the TUHS
mailing list