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

[Alejandro Colomar]

Hi Ingo and Branden,

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

[...]

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

Maybe adding "(since groff 1.23.0)" next to the description of MR in the 
groff manual should be enough to trigger some doubts in programmers.

When programmers see that next to the documentation of a syscall flag, 
they better make sure that kernel is usable for them in all platforms 
they support.  The same should be true for man(7) pages; and I'd say 
even more, because when you do something you're not very comfortable 
doing, you should be even more careful.

Checking which versions of a program are packaged for different 
distros/OSes should be trivial in most cases.

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

Hopefully, when I get a stable `make lint-man` (and for that I need to 
fix many warnings in the pages), I'll start asking contributors to run 
it when they write incorrect man(7) code, and maybe they realize they 
can do something similar for their own pages.

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

I think the think that will save us is that people usually don't even 
know that groff exists or that it's used internally by man(1) to render 
the pages.  So, programmers are unlikely to run `man groff_man`, and 
instead will go for `man 7 man`, which will not talk about MR.

Cheers,

Alex

--
Alejandro Colomar
<http://www.alejandro-colomar.es/>

OpenPGP_signature
Description: OpenPGP digital signature