On 10/30/21 19:53, Ingo Schwarze wrote:
Hi James,
James K. Lowden wrote on Sat, Oct 30, 2021 at 12:08:03PM -0400:
A longstanding complaint of mine regarding Linux man pages is that they
frequently have broken SEE ALSO references. I wonder if there's not
something the groff project could do to encourage packaging systems to
avoid such errors.
I think the basic idea expressed here is a terrible one, and we should
better not even consider how to implement it.
In an operating system that is an operating system in the BSD sense,
that is, consisting of a consistent and reasonably complete base system
on the one hand and the option to install additional third-party packages
on the other hand, these so-called "errors" do not occur in the first
place: it is the job of the operating system maintainers to make sure
that manual pages do not contain .Xr references to manual pages that do
not exist in the base system, and mandoc(1) already supports authors who
want to contribute to that goal by warning about .Xr references pointing
into the void when it is run in -T lint mode.
In an operating system that is not an operating system in the above
sense, for example GNU/Linux, but instead a toolbox where every user can
pick whatever components they want and where consequently every user
is responsible for making sure that whatever set of tools they pick
actually results in a working operating system, such dangling links
are unavoidable. I have often run into Linux machines were the system
administrator had decided to not install the most fundamental tools,
for example where cpp(1) or make(1) were unavailable. Heck, i have even
bumped into Linux machines where not even man(1) was installed.
On such a system that is just a random bunch of eclectically heaped up
components, the dangling links are not only unavoidable, but also highly
useful. They tell you that functionality is available out there that
is related to the manual you are reading right now, but that you failed
to install. So hiding the dead links would be a blatant disservice to
the reader, *in particular* on systems where such dead links frequently
occur, like on Linux.
Amen to that.
I'll also quote man-pages(7) which explicitly recommends this practice:
[
Given the distributed, autonomous nature of FOSS
projects and their documentation, it is sometimes
necessary—and in many cases desirable—that the SEE
ALSO section includes references to manual pages
provided by other projects.
]
BTW, I yesterday patched a page to add a reference to a package that is
rarely installed (libbsd), and I find that reference very useful.
And at least on my particular GNU/Linux system, which is Debian, it's
easy to fix those. I for example referenced readpassphrase(3bsd) in the
patch mentioned above, so you'd do the following:
$ apt-file find readpassphrase.3bsd
libbsd-dev: /usr/share/man/man3/readpassphrase.3bsd.gz
And now you can install whatever you were recommended to read about.
Otherwise, much software would be like Isla de Muerta[1].
Regards,
Alex
[...]
[1]: https://pirates.fandom.com/wiki/Quote:Hector_Barbossa
"Captain Barbossa, and his crew of miscreants, sail from the dreaded
Isla de Muerta. It's an island that cannot be found, except by those who
already know where it is."
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
