Re: PROBLEM/FIX: groff 1.22.4 and earlier won't render post-1.23 mdoc man page headers and footers

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Sat, Jul 24, 2021 at 07:34:29AM +1000:

> The mdoc macros of groff 1.22.4 and earlier won't render the page
> headers and footers ("titles") of groff 1.23.0's groff_mdoc(7) page.
> Nor will they of any mdoc(7) page that adopts mixed-case section titles.
> 
> The root cause is that groff 1.22.4's mdoc implementation only sets up
> the page titles if it sees a section heading called exactly "NAME"[1].
> "Name", as will appear in 1.23's groff_mdoc(7)[2], doesn't match.

This is nothing special, it is just the generic effect of adding a
new feature to a widely-used library; the slang term for that is
"minor bump".

If a program (in this case, a third-party manual page) uses a library
(in this case, groff or mandoc) and relies on a new feature of that
library (in this case, allowing .Sh Name), then it requires the new
version of the library (in this case, a new version of groff and
mandoc).  Admittedly, mandoc is more robust than groff and does not
misformat the page, but it has a similar problem, even in -current:

   $ makewhatis -DDt $(man -w groff_mdoc) | head -n 2
  /usr/local/man/man7/groff_mdoc.7: Adding key Sh=Name
  /usr/local/man/man7/groff_mdoc.7: Adding name groff_mdoc, bits=0x8

The "bits=0x8" part here indicates that mandoc does not recognize
a "Name" section as as "NAME" section yet, either, but treats it
as a custom section.  Otherwise, another line with "bits=0x6"
would be expected.  In this case, no information is lost, but if
the Name section would contain one or more names not contained in
the .Dt line, the mandoc implementation of man(1) would not find
the page under these additional names.

People are used to the fact that now and then, they need to update
libraries on their system, and besides, library versioning schemes
and dependency management in packages make sure they don't forget
when installing a new version of an application program.

People are not used to the fact that installing new or updated
manual pages may require a new version of the manual page parser,
and indeed it rarely does.

That is why i advocate that we only very sparingly add new features
to the manual page formatting languages man(7) and mdoc(7).  It is
also why i was very careful when designing and implementing the new
mdoc(7) .Tg macro in January 2020 - the only new macro in about a
decade.  I made sure manual pages using it do *not* misrender
with old manual page parsers.  That was among the most important
considerations when designing it.

That said, i don't think anything can be done in the case of the
NAME -> Name change.  Updating existing pages is probably still the
right thing to do even if they then misrender with some old parsers
because there is no better way of getting the desired effect of
better typography and better accessibility.  Because there are so
many pages, updating them all will take many years, and because
there are so many operating systems, getting groff updated in all
of them will also take many years.  Neither can be helped...

Well, one approach could somewhat mitigate the problem: trying to
contact as many groff package maintainers in as many operating
systems as you can, explain the problem to them, and say that
updating their groff package will benefits their users, and offer
help updating their package if they need it.

> I'm not sure where to document this;

Trying to tell end-users is not going to help at all.  If all
somebody wants to do is read documentation, telling them "you need
to update groff(1) first" is not going to meet with sympathy, even
if a way to contact all people who want to read documentation would
exist.  Most of the people affected by this issue likely never made
a conscious decision to install groff, most certainly don't read any
groff documentation or announcements, and maybe the majority doesn't
even know groff exists.

> (B) how aggressively authors of mdoc(7) pages in general adopt
> mixed-case section headings.

My expectation is that when it happens in OpenBSD - i'm not yet
sure that it will, but it seems likely - it will probably happen
consistently and within a quite limited time frame, some months
at most from the first to the last related commit.  That it will
happen at all in NetBSD or FreeBSD seems less likely to me, and in
Illumos even less likely.

> Please find attached a 4-line patch to the (stripped, installed)
> groff 1.22.4 mdoc macros to work around the problem.

That's useful to understand the issue, but won't help end users
because patching indidual files installed by system-provided
packages is usually a very bad idea.

Yours,
  Ingo