[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Alejandro Colomar
Subject: Re: the compatibility of man(7) (was: man(7) .TH font change, was: groff man(7) `B` macro...)
Date: Mon, 1 Aug 2022 15:47:19 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.0.2

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.



Alejandro Colomar

Attachment: OpenPGP_signature
Description: OpenPGP digital signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]