Subject: Re: History of UNIX manpages: TH vs th -man macros
From: Douglas McIlroy
Date: 22/03/2026, 05:49
To: Kristaps Dzonsons

Of course the Labs had always provided manuals for its operating
systems: L1 for the IBM 650, then several iterations of BESYS for the
IBM 700/7000 series. For BESYS the manual took the form of a
loose-leaf binder containing a collection of documents: system API,
hardware manual, assembler manual, etc. Each was written in its own
style. By the time of the Multics the software base had burgeoned. The
MSPM was an attempt to uniformize the treatment of the many
components.

The MSPM had something going for it that its predecessors lacked: a
word processor. A corollary of that was that the manual could exist
online as well as on paper. I think this may be the substance of the
precedent that Ken cited.

Dennis was largely responsible for the format of the Unix manual. So I
believe anyway; and nobody contradicted me when I made a big deal of
that in my remarks at the Japan-Prize ceremony at Murray Hill.

There was considerable discussion about the organization of v1. The
top level arrangement of the MSPM seemed generally reasonable, but how
about the lower levels: file handling, text processing, bootstrapping,
libraries, etc? The deeper one went, the less clear the categories
were. In everyday life one skipped around among categories from minute
to minute.

Therein I made my contribution: alphabetic rather than categorical
order. My exhibit #1 for this was the Encyclopedia Britannica. The
15th edition began with a "Propedia" that provided an outline of
knowledge, bringing pointers to related articles together in one
place. Unfortunately, knowledge isn't tree-organized[ it's a thicket.
People simply did not use the Propedia. I had solid evidence of that.
The white spine of the public library's Propedia remained pristine,
while the darker spines of the 30-or-so  alphabetically ordered text
volumes showed dirt and wear.

But even the top level organization was imperfect. The arrangement of
sections 4-7 changed over time.

Doug

On Sat, Mar 21, 2026 at 4:06 PM Kristaps Dzonsons wrote:
> >
> > Doug,
> >
> > Thank you for your clarifying remarks---this is incredibly helpful to
> > get the record straight.
> >
> > I found the pre-man(7) macros (e.g., `th`, not `TH`) bundled directly in
> > as early as the V4 Unix Programmer's Manual:
> > https://github.com/dspinellis/unix-history-repo/blob/Research-V4/man/man0/naa.
> >   V3, however, still uses straight roff:
> > https://github.com/dspinellis/unix-history-repo/blob/Research-V3/man/man0/intro.
> >
> > Question: I would guess that either dmr or ken wrote the pre-man(7)
> > macros in V4--V6: can you possibly confirm?  (I'm yet to hear back from
> > ken.)
> >
> > Speaking of, ken wrote a long while back citing the influence of the
> > Multics System Programmer's Manual for Unix's sectional layout.
> > However, the MSPM doesn't really style anything, while the CTSS
> > Programmer's Guide does, using underline for commands etc.
> >
> > Another question: would you hazard a guess as to whether the CTSS
> > document would have been an inspiration for the style enshrined in the
> > Unix programmer's manual?
> >
> > If I may bother you with a more vague question: it would seem to me that
> > the existence of ken's in-system man(1) script would be a huge deal
> > given the hassle of hauling around the printed documents.  Can you
> > comment on how the developers at the time responded to it?  Was there
> > discussion prior to V2 about the need for such a tool, or did ken pretty
> > much do it without input?
> >
> > Putting together your responses, Kirk McKusick's (on behalf of Bill Joy
> > and Keith Bostic), and Cynthia Livingston (of mdoc(7) fame), I think
> > this about covers the key ideas.  I'm yet to hear from any of the GNU
> > folks involved in man(1)'s re-write, unfortunately.
> >
> > Thank you again, and best wishes from a rainy Portland, Oregon,
> >
> > Kristaps
> >
> > On 15/03/2026 06:54, Douglas McIlroy wrote:
>> > > You are correct. I did a major revision of the man-page macros for v7.
>> > > Every macro name was in caps, a custom pioneered by -ms. The
>> > > alternating-font macros, e.g. .BR, were a generalization of the
>> > > font-change macros in -ms, that brought to light (and to intuitive
>> > > order) the second and third arguments of .B. The indented-paragraph
>> > > macros, .HP, .TF, etc., filled a lacuna in the historic -man, where
>> > > the ubiquitous tagged indented paragraphs had to be handled on a
>> > > case-by-case basis.
>> > >
>> > > Sometimes .BR-style macros are insufficient and need \f in some
>> > > argument, but I couldn't think of any intuitive 2-letter names for
>> > > what could be called .BRI and the like in groff.
>> > >
>> > > .EX/.EE provided uniformity in presenting examples, and encouragement to do so.
>> > >
>> > > I was particularly proud of adding the "literal" font,.L, to the
>> > > normal budget of .R, .I, .B. It made synopses look like real
>> > > code--preferable, I think, to the Algol gimmick of a distinct
>> > > publication language with bold keywords. It has been a great
>> > > disappointment that the rest of the world dropped this innovation
>> > > while adopting the rest of the package.
>> > >
>> > > You are welcome to quote these remarks.
>> > >
>> > > Doug
>> > >
>> > > On Sat, Mar 14, 2026 at 6:44 PM Kristaps Dzonsons wrote:
>>> > >>
>>> > >> Hello Doug,
>>> > >>
>>> > >> This is Kristaps Dzonsons: I wrote to you what feels like a long time
>>> > >> ago about UNIX troff history, https://manpages.bsd.lv/history.html.
>>> > >> It's been a long while!
>>> > >>
>>> > >> In looking over all this again quite recently, I realised that while
>>> > >> I've documented the tooling history, I didn't say much about the
>>> > >> *format*, and I'd like to address that by reaching out to you and others
>>> > >> involved in its inception (Cynthia Livingston for mdoc.7, Ken Thompson
>>> > >> for his work on the original Programmer's Manual, etc.).
>>> > >>
>>> > >> If you have a moment, do you think I might e-mail you a few questions
>>> > >> about your role in the roff -man macros, specifically in formulating the
>>> > >> new macros TH-based macros for V7 UNIX?
>>> > >>
>>> > >> Specifically, and as a way of getting into it:
>>> > >>
>>> > >>    - From what I read, you were responsible for re-writing the pre-V7
>>> > >> macro set (the original used `th` instead of `TH` as its first macro),
>>> > >> writing man.7, *and* migrating the existing manpage macros to use the
>>> > >> new format.  Is that correct?  Can you comment on what inspired you into
>>> > >> this huge effort?  There were a lot of manpages!
>>> > >>
>>> > >>    - While V7 has all of its tmacs in place, I can't find the actual
>>> > >> macro definitions for the `th` -man used in V4--V6.  In at least V6, I
>>> > >> can find the -ms and -mr macros in /usr/lib, but not the proto-man ones.
>>> > >>    Is there any reference or source code you know of for the original
>>> > >> `th` macros?
>>> > >>
>>> > >> If it's alright with you, like with the original history website, I'll
>>> > >> retain (redacted) e-mails with any response so as to keep a first-person
>>> > >> account.  No worries if you'd rather I not include them!
>>> > >>
>>> > >> Thank you,
>>> > >>
>>> > >> Kristaps
> >