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

[G. Branden Robinson]

Hi Ingo,

I've addressed your grievances with the `MR` macro at length in other
mails so, apart from a few remarks at the end, I will confine my
response here to your objection to the slightly changed rendering of
man(7) headers and footers in groff.  (For those needing a refresher,
the change is to set the page title the same as a page cross reference.
However, in headers and footers, the page title is not hyperlinked.)

At 2022-06-18T21:05:09+0200, Ingo Schwarze wrote:
> 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.

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.

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

I think we've agreed in past arguments that most readers of man pages do
so in terminal emulators, and not necessarily in very featureful ones at
that.  I know some people regard grotty's acquisition of ISO
6429/ECMA-48 escape sequences as abhorrent, and they turn this feature
off if they know how (or their distributor does it for them).  I seem to
remember you're one of them.  For these populations, it won't even be
italicized (or oblique) capitals, but underlined capitals.

I therefore expect few to notice and fewer to complain.  And if they do,
I know how to tell them to alter their system to suit their preferences.

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

Surveying the handful of software engineering books I have readily
available, I see the following.

* Nemeth et al.'s _Unix and Linux System Administration Handbook_ (5e)
  uses bold page numbers and furthermore draws a horizontal rule under
  the entire heading (_except_ for verso page numbers)[1].

* Schimmel's _UNIX® Systems for Modern Architectures similarly uses a
  horizontal rule.  (More recent titles in Addison-Wesley's Professional
  Computing Series, like Donovan & Kernighan's _The Go Programming
  Language_, seem to eschew the horizontal rule and conform to your
  claim.)

* Klabnik et al.'s _The Rust Programming Language_ puts bold page
  numbers in the footers.  The chapter term and number are verso and the
  chapter title recto.

* Seacord's _The CERT C Coding Standard_ (2e) uses bold page numbers, a
  horizontal rule like Schimmel, _and_ a vertical rule inboard of the
  page number.  The vertical rule runs below the baseline so you get a
  kind of inverted dagger shape.[2]

* Beyer et al.'s _Site Reliability Engineering_ sets all of the footer
  content (page number; and (verso) chapter term, number, and title or
  (recto) section title) in boldface, draws a horizontal rule above, and
  has a pipe-like symbol inboard of the page number.

* Spinellis's _Effective Debugging_ sets the entire header in bold and
  does not use rules, but is otherwise similar to Beyer.

* McKusick et al.'s _The Design and Implementation of the FreeBSD
  Operating System_ uses bold page numbers; it is like Klabnik.
  (Leffler et al.'s earlier 4.3BSD book from 1989 appears the same.)

* CLR, excuse me, Cormen et al.'s _Introduction to Algorithms_ (3e) sets
  the chapter term, number, and title in italics.

* Pierce's _Types and Programming Languages_ sets the entire header in
  italics.  Verso pages have the chapter number and title, recto pages
  the section number and title.  Page numbers are on both.

* Gehani's _Document Formatting and Typesetting on the UNIX System_ has
  the chapter term, number, a colon, and title, all in boldface in the
  header.  The page number seems to be at normal weight and size but the
  other header text seems slightly smaller than the body text.  Since
  this book was almost certainly typeset with AT&T troff my guess is
  that it's a 1 point difference.

* Metcalf et al.'s _Modern Fortran Explained_ (go ahead, laugh) sets the
  header mostly in italics.  The page numbers are roman.  Verso pages
  have the _work_ title and recto pages the chapter title.

* Kernighan and Plauger's _Software Tools in Pascal_ uses small caps for
  all of the header _except_ the page number, which seems to be at body
  text size.  Work title, chapter term, and number are verso; chapter
  term, number, and title are recto.

* Kernighan's _UNIX: A History and Memoir_ has headers set in sans serif
  capitals (the body text has serifs); page numbers appear to be at a
  _smaller_ point size.  Recto and verso are not distinct except for
  mirrored layout.

I've drawn these from a variety of publishers, imprints, or series, so
as not to overweight my findings with a single house style, as one might
do by sampling only O'Reilly books from 2005, for instance.

I went through this tedious exercise to try to persuade--if not you,
then others--that there is a wide variety of stylistic practices in
header and footer layout and style, even within the technical literature
of our field.[3]

More important than any of this is groff man(7)'s support for site
redefinition of the `PT` and `BT` macros, so if someone hates the
default headers and footers, they can do something about it without
touching _any_ man page.  Larry Kollar added this capability to groff
1.19 (2004).

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

Yes, I've found myself increasingly annoyed by the lack of style markup
in the "Name" sections of groff's man pages.  Thank you for this
reminder to do something about it.  Now than man-db has won the man
librarian wars, I think we can afford some more confidence in that area.
Brouwer/Lucifredi man seemed to spend years nearly as abandonware.

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

Why, yes, I have.

> (I just noticed Stroustrup, C++ does indeed set those lines in bold
> face, but that seems both highly unusual

No, he's far from alone.  See above.

> and counter-productive to me.)

Unless you have a valid metric for evaluating productivity with header
and footer typefaces as the independent variable(s), this is manifestly
a subjective claim.

> Quite to the contrary, most books and journals appear to set such
> lines in a slightly smaller font to actively de-emphasize them.

"Most".  Describe your method of measurement.

> 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 and a configurable line
length.  Since even Salzer's RUNOFF had the latter, one could argue that
mandoc isn't in the typesetting business, nor even in the document
formatting business beyond the way go/format conceives of it.[4]

But groff is.

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

> with nothing being broken, right?

I have no way to verify this claim.

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

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

It's okay to hate things, but to command the world to share, or conform
to, your preferences is, I daresay, un-neighborly.

Regards,
Branden

[1] 4.2BSD added an `HD` macro hook to ms(7) to support this sort of
    thing, but Tuthill didn't document it.  Larry Kollar did, for groff,
    as far as back as 2001, maybe earlier.
[2] Slayer fans will likely see something else.
[3] also to do a private library flex because I'm a miserable sod
    (and _most_ of my books are in _storage_ >sob<)
[4] https://pkg.go.dev/go/format

signature.asc
Description: PGP signature