[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: All caps .TH page title

From: Alejandro Colomar
Subject: Re: All caps .TH page title
Date: Fri, 22 Jul 2022 01:16:49 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.0.2

Hi Branden,

On 7/21/22 20:36, G. Branden Robinson wrote:
Hi Alex,

At 2022-07-21T16:29:21+0200, Alejandro Colomar wrote:
I've never been convinced about the page title being in all caps in
the .TH line.  From recent groff@ discussions, I guess that neither of
you are either.

Well, Ingo was more comfortable with it than I was.

I'd like to know why this has been the case historically, and any
opinions you might have about me changing the man-pages to use the
same caps as the actual identifier that I'm documenting (most of the
time that would mean lowercase).  Basically, the same rules as within

I've read every edition of the Unix manual from Version 1 (1971) to
Version 7 (1979) and my surmise is that it was sheer inertia.  The
Teletype machines that were used to set the original versions of the
manual--remember, this is before troff even existed--might have been
capable of boldface through overstriking, but was not used this way as
far as I can tell in the V1 through V3 manual.

So this means that, for emphasis, you had regular type and underlined
type and that was it.

Under such limitations, the use of full capitals for emphasis is not

That makes sense.

After that--the V4 manual was the first to be typeset with troff--the
practice of full-capping the page titles in the headers was retained.

How deliberate a choice this was is not something I can answer.  The
decision was made in 1972.  You could ask some of the surviving
principal Bell Labs CSRC figures on the TUHS mailing list.

Is Doug one of them? I've seem him on the groff@ list from time to time. I added the groff@ list, in case this is of interest to someone there.

Also, does it have any functional implications?  I'm especially
interested in knowing if that may affect in any way the ability of
man(1) to find a page when invoked as `man TIMESPEC` for example.

My understanding is that mandb(8) indexes based solely on the second
argument to the `TH` macro call and (what it interprets as) the contents
of the "Name" (or "NAME") section of the page.  It parses *roff itself
as best it can to determine this.  So the fact that the _first_ argument
to `TH` might be in full caps doesn't deter it.  (It might in fact have
made mandb(8) authors' job easier if an "honest lettercase" practice had
arisen back in the day--but it didn't).


Since he's a mandb(8) author/maintainer, I would again defer to Colin
Watson's knowledge and expertise in this area.

Added to CC, in case he wants to intervene.

I'm not saying necessarily that I'd like to keep that behavior.  I
wouldn't mind breaking it, if it means that users will be able to
differentiate upper- and lowercase pages.  We're not in Windows (nor
MacOS), anyway.

True, although I would take a jaundiced view toward any software project
that distinguished its man page names, whether internally or from
others' solely by a difference in lettercase.

Heh! You've never tried to clone the Linux man-pages in Windows or MacOS, it seems :p

$ find man* -type f \
  | tr '[:upper:]' '[:lower:]' \
  | sort \
  | uniq -d \
  | while read f; do
        find man* -type f \
        | grep -i $f;

$ find man* -type f \
  | tr '[:upper:]' '[:lower:]' \
  | sort \
  | uniq -d \
  | while read f; do
        find man* -type f \
        | grep -i $f;
  done \
  | while read f; do
        echo ===$f===;
        head -n1 $f;
.so man2/_exit.2
.\" This manpage is Copyright (C) 1992 Drew Eckhardt;
.\" Copyright 2002 Walter Harms (
.so man3/INFINITY.3

At least, _Exit(2) and _exit(2) point to the same page. nan(3) and NAN(3) don't, though!

We can't blame the writers, since the identifiers have those names in C. Luckily, man(1) shows you the right page if you specify the right string.

I feel a need to fix this lack of precision in the page titles. Unless someone opposes to it with some strong reason, which I don't expect.

It'll take some time to do it, but if no-one speaks in a reasonable time, I'll start doing it :).




Alejandro Colomar

Attachment: OpenPGP_signature
Description: OpenPGP digital signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]