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

[Ingo Schwarze]

Hi Alejandro,

Alejandro Colomar wrote on Sun, Jun 19, 2022 at 03:32:16PM +0200:

> TL;DR: let's think in improving things in the long term,

I'm not opposed to introducing new syntax in each and every case.
I'm merely saying new syntax needs strong justification,
and new backward-incompatible syntax needs very strong justification.

In this case, justification is not completely absent: there is a
benefit for PDF output, which, however, i consider minor for the
stated reasons.  Also, in this particular case, i deplore that the
design was rushed in a reckless manner.

I don't think it was seriously considered whether the same can be
achieved *without* new syntax, even though Jonathan Gray already
suggested in 2014 that it is likely possible and the suggestion
is publicly documented in the mandoc TODO file.

The same very definitely *is* possible with backard-compatible
syntax.  For example, a syntax like the following can be made
to achieve the same effect and is fully backward compatible:

  .MR
  name(section)

That probably isn't the only way to achieve it in a backward-compatible
way.  Unfortunately, I think options for backward-compatibility weren't
seriously considered either.

Design discussions mostly revolved around details that had no
bearing on compatibility.

> The same applies to man(7) .MR, I think.

Absolutely not.  The argument you made about the C standard does not
apply to manual pages at all.

When programmers maintain a piece of software and decide to use the
latest compiler features, they are used to the fact that they need
the latest compiler(s).  They also usually document the build system
requirements in installation instructions (e.g., "requires C11").
Porters and packagers are used to the fact that if the software
they wish to package requires a particular compiler, that compiler
needs to be installed at build time during packaging.

Manual pages, on the other hand, are usually installed as source
code on end-user machines.  If programmers decide to use the
latest markup features in their manual pages, they usually do not
say so in installation notes.  Even if they wanted too, what
would they be supposed to say?  All that groff_man(7) currently
tells them is

   History
       [...]
       The plan9port project's troff introduced .MR in 2020.

So what are they supposed to say?  "Formatting our documentation
requires plan9port troff from 2020 or later, groff 1.23.0 or later, or
mandoc 1.14.7 or later and will not work with other implementations of
the man(7) language"?  That would require doing some serious research
on their part, and i expect that most programmers, even experienced
and competent ones, do not have the required domain knowledge about
manual page markup to correctly research and explain such a requirement.
And even when stated correctly, such a statement would be highly
cumbersome and eventually become incomplete and outdated.

Even if such an unsusual statement would be made, what the hell
is the packager supposed to do with it?  They have no idea whether
the end-users they are making their packages for will choose to
install man-db+groff or mandoc when these options exist.
The packager for some random piece of software likely has no control
over which version of groff or mandoc other packagers may package
for the same operating system.  And what are they supposed to do
if their system uses a completely different man(1) and *roff(1)
implementation in the first place?
At the end of the day, there isn't much they can do in *any*
case, and the statement "Formatting our documentation requires..."
will likely be completely ignored by most packagers, all the more so
as this will usually *not* result in build-time problems that become
apparent to the packager, which means end-users will see random
gaps in manual pages without having the slightest idea why, without
having any diagnostic tools at hand, nor any of the skills needed
to fix such issues.  And even if they knew what was going on, what
*should* an end-user do?  Manually ditch the packaged version of groff
or mandoc installed on their computer and compile a newer version
from source?  That's completely unrealistic and would seriously annoy
even highly capable, technically-minded people.

You see, what you say about compilers has basically nothing to do
with what we are dealing with here, at least not from any practical
perspective.

It *is* possible to carefully evolve manual page markup syntax,
but compatibility concerns are significantly more important
and harder to handle than when going from one C standard to
the next, or from one version of a shared library to the next.

Yours,
  Ingo