man(7) .TH font change, was: groff man(7) `B` macro...

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Sat, Jun 18, 2022 at 10:40:46AM -0500:
> At 2022-06-17T20:53:13+0200, Ingo Schwarze wrote:

>>  * In the top left corner of manual pages written in man(7),
>>    the page name in the header line was set in italic instead
>>    of in the correct roman font.

> This was a deliberate change;

Oh; thanks for pointing to that commit.

But even as it turns out to be a deliberate change,
i still think it is better considered to be a regression.

> when implementing `MR`

I admit there is a (weak) rationale for adding the .MR macro:
Hyperlinking in PDF output.  That is a weak rationale because
PDF is rarely used as an output format for online manual pages.
I don't think HTML output contributes to the argument at all
because groff HTML output is of bad quality anyway and there is
no reasonable way to fix it.  For mandoc(1), no new macro is
needed for the purpose in the first place.  The mandoc TODO file
already contains a todo item to implement hyperlinking support
for manual page cross references in man(7) without needing a
new macro, and i believe it is feasible without too much hassle
(admittedly, i cannot really be sure before actually doing it).

The price to pay for this very small benefit of .MR is that pages
using the new feature will become broken in a very bad way for all
output modes on formatters not yet supporting it.

But maybe that isn't really my problem.  The macro will be reasonably
easy to support in mandoc(1), and BSD systems usually have a
reasonably fast turnaround, so it won't remain broken for long
for most BSD users (except, admittedly, on DragonFly, which often
lags for years).  The people who are going to suffer are those whose
systems update groff only at long intervals, and those who use neither
groff nor mandoc nor Plan 9 to format manual pages.


But i don't think changing the font in the header line has anything
to do with the question whether introducing .MR is a good idea (as
you seem to think) or a bad idea (as i think).

The header line does not contain a cross reference, so there is no
justification for marking it up in the same way as a cross reference.

In fact, there already *is* an established convention for marking up
the page name in the header line: ALL CAPS.  While i support the groff
initiative to drop the all caps convention, the vast majority of
manual pages will continue using it for a long time.  Do you really
want *double* markup (all caps + italic) for almost all real-world
man(7) manual pages in that place, for many years to come?

Finally, we are talking about a header line in the page margin.
This is *not* something that should be emphasized by using
italic or bold font.  Proper places to emphasize the name
of the page are when it appears in the SYNOPSIS and in the
DESCRIPTION, and possibly in the NAME section.

Have you ever seen bottom and top lines in a book or journal,
repeating stuff like chapter titles and numbers, article titles,
author names, publication dates, page numbers and the like
seen typographically emphasized?  (I just noticed Stroustrup, C++
does indeed set those lines in bold face, but that seems both
highly unusual and counter-productive to me.)  Quite to the
contrary, most books and journals appear to set such lines in a
slightly smaller font to actively de-emphasize them.

You might say: "Why do you bother?  You are going to set \*(MF
to R anyway on *BSD.  So it makes no difference to you."
And indeed, *if* you push through with .MR, that's exactly
what i will do in groff on OpenBSD and in mandoc on all *BSDs,
and in mandoc, MF=R will not even be optional but hard-coded.

All the same, i prefer sane defaults over excentric defaults
that need to be patched away, and i prefer common conventions
to markup fragmentation.  Surely you don't expect the font
conventions for mdoc(7) .Xr and .Dd to change now, after
three decades in production, with nothing being broken, right?
You are aware that the syntax and semantics of .MR is completely
identical to the .Xr macro that Cynthia invented 30 years ago?
Making it render differently also looks like a dubious choice
to me, in addition to the topic of this mail.

Yours,
  Ingo