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

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Sat, Jul 16, 2022 at 10:38:47AM -0500:
> At 2022-06-18T21:05:09+0200, Ingo Schwarze wrote:

>> 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.

> I think there is, because that way the man page you are looking for
> announces itself to your eyes in precisely the same typefaces you saw
> when you read a cross reference to it.  I think this eases recognition
> and constitutes better ergonomics, but that's my opinion.

I don't think the congruence between .TH and .MR you describe really
matters.  The name(number) syntax stands out so much in English text
that is is instantly recognizable no matter the typeface.

If you really think the congruence matters, i understand your
argument even less.  In mdoc(7), this was always consistent:
both .Dt and .Xr always render in roman font.  By contrast,
man(7) was much less consistent in the past:

 - man(7) always used roman font for .TH
 - For cross references, AT&T UNIX Sixth Edition used R(R)
   inside SEE ALSO and an inconsistent mixture of R(R), I(R),
   and I(I) outside SEE ALSO.
 - For cross references, AT&T UNIX Seventh Edition used R(R)
   inside SEE ALSO and I(R) outside SEE ALSO (as discussed on
   this list around August 4, 2021).
 - various man(7) pages from various projects also used bold face
   for cross references.

You say it matters that .TH appears in the same font as the .MR it
came from?  Well, that won't be the case when linking from mdoc(7) to
man(7) pages nor when linking from man(7) to mdoc(7) pages with your
changes.  The consistency in the header lines even decreases.

[...]
>> 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.

> I have to wonder where you get your evidence from sometimes.

Ouch.  I'm sorry you spent so much time on this claim.

[...]
> "Most".  Describe your method of measurement.

Looking at a smaller sample of books on my shelf, and finding only
Stroustrup as a counter-example.  It appears my sample was too small
and my claim that using bold or italic typefaces in header lines
is unusual is not true (I should really know Poisson statistics
better *blush*).  Your larger sample proves that practice varies
widely.

>> 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.

> Okay.  It's free software.  I don't think mandoc's users will be
> distressed; you already deny them hyphenation

True.

> and a configurable line length.

No longer true; mandoc supports both the -O width= argument,
and even lets the manual page override that by the roff(7) .ll
request.  If the terminal window is narrower than 80 columns,
it even reduces the default line length automatically, with no
need for -O width=.

[...]
>> 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,

> I don't expect _you_ to change it.

Well, i'm also thinking about groff_mdoc(7).

I usally strive for mandoc(1) -T ascii and -T utf8 output to be
byte-for-byte identical to groff output.

But when output from groff_man(7) is inconsistent with output from
groff_mdoc(7), i usually decide to let mandoc(1) follow the mdoc(7)
conventions for both languages, for consistency, and let the mandoc
implementation of man(7) diverge from groff_man(7) so far as that
cannot be helped.  And then i patch the OpenBSD groff port to be
consistent with itself and with mandoc, even if that makes it diverge
from upstream groff.

[...]
>> You are aware that the syntax and semantics of .MR is completely
>> identical to the .Xr macro that Cynthia invented 30 years ago?

> How is that a bad thing?  You spent another prong of this thread
> derogating its design intensely.

If you were designing man(7) from scratch, it would be a good design.

I criticised the design of .MR for its lack of backward compatibility,
not for any *intrinsic* design problems.

>> Making it render differently also looks like a dubious choice
>> to me, in addition to the topic of this mail.

> The sources of your doubt seem to be to be your personal preference
> backed up by unfounded assertions that are readily contradicted by
> observation.

True, you can consider my rash claim that bold and italic fonts
it header lines are unusual disproven.

But all the same, what you did here is copy the design of .Xr
to .MR and then change the formatting of the macro such that
even though both have exactly the same syntax, cross references
look different between mdoc(7) and man(7).  I still see no
necessity for that inconsistency because man(7) wasn't very
consistent in the past in that respect, so since you are copying
the macro anyway, why not use the opportunity of also making the
formatting consistent?

I fear we are starting to go in circles, though.
So if you think this is going nowhere, i'll use man.local
as you suggested and live with the fact that cross references
and header lines look inconsistent on systems other than OpenBSD.

Yours,
  Ingo