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

[Ingo Schwarze]

Hi Alejandro,

Alejandro Colomar (man-pages) wrote on Mon, Aug 01, 2022 at 01:22:50AM +0200:
> On 8/1/22 00:55, Ingo Schwarze wrote:
>> Branden Robinson wrote:

>>> Yes, distributors that incorporate packages with man pages using the new
>>> `MR` macro, racing ahead of those same distributors' update of groff
>>> 1.23.0 (whenever that happens), run the risk of some unhappy man page
>>> readers.

>> As i explained earlier, people doing packaging will rarely be
>> aware what the technical requirements for formatting any given
>> manual page are, and when i watch packagers, i don't usually see
>> them scrutinizing manual pages for good formatting.  And again, the
>> choice of using .MR will not be made by *any* packager, but by the
>> upstream project.  So the packages would only have the choice to
>> delay the package update, waiting for a typically *different*
>> packager to update groff.  It is not clear delaying a software
>> update for such a reason is even a good idea.

> I usually consider it bad practice for upstream developers to make use 
> of features not yet released, or not yet packaged to mainstream distros.
> 
> It's not nice to tell someone building your source that they also need 
> to build the dependencies from source (I've seen some projects that 
> require building LLVM from source to be able to build their program; of 
> course I'm not building LLVM from source just to build a random program).
> 
> IMO, dependencies should always be used from the system, and should be 
> stated clearly (including versions if necessary) somewhere.  That's part 
> of why I think providing an upstream package is good: it forces you to 
> specify Build-Depends.
> 
> I don't think any upstream project should use a feature that's not 
> released at least in a distro, and preferably in a reasonable set 
> (Debian unstable, Fedora, Arch, OpenSUSE Tumbleweed).
> 
> Only for experimental features that are not intended to be used by most 
> users or even contributors, can one use an unreleased feature (as I did 
> for example with some subtargets of the `make lint` target; I don't 
> expect it to be run by anyone other than me for now).
> 
> So, if upstream programmers follow some basic common-sense rules, 
> packagers shouldn't even have to look at these problems.

This all makes sense to me.

However, it may not be trivial for maintainers of portable software
projects to judge when the time is ripe for using a new man(7)
feature.  They may be unfamiliar with man(7) implementations except
the one used by their own system.  Once the next groff is released,
some distros are likely to pick it up quickly (for example, Alpine,
Void, and Gentoo are usually very fast in picking up new stuff),
and when a developer using one of these fast-turnaround systems sees
documentation for .MR in their own groff installation, they may not
be aware it's a new feature and even even less so in which groff
release it appeared and what the status in other operating systems or
even other distros is.  Maintainers of some random portable software
are *not* likely to read groff or mandoc release announcements.

So i see a substantial chance some will honestly think using the
feature is just fine.  Even if they get others to test on other
platforms before releasing, the issue may very well just slip through.
My impression is most people doing release testing are content with
testing the build of the software and running the regression suite,
if there is one.  Some may also test installing and running the
software for their own typical needs.  But i don't think many people
consider *reading the manual pages* as part of release testing of
their favourite portable software on their own platform.

But let's just wait and see what happens...
Maybe we get lucky.  I certainly hope so, in spite of all my doubts.

Yours
  Ingo