RFD: disambiguating online manual page name collisions between different ports

From: Pau Amma <pauamma_at_gundo.com>
Date: Thu, 02 Dec 2021 02:06:28 UTC
Summary: Two recent Bugzilla reports about poor UX caused by manual page 
name collisions between different ports 
(https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=256676 and 
https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=254466) were both 
closed as "Works As Intended". I think the current intent (lump all 
ports into a single namespace) is not the best in all use cases and 
should be changed or extended to allow user-guided disambiguation.

Use cases discussion:

In https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=256676#c9, Wolfram 
Schneider <wosch@FreeBSD.org> wrote: "This is a common problem with the 
ports and several dozen packages are affected. I don't think there is an 
easy solution for this. But I also think that it is fine that the higher 
version number or the devel packages wins. Our users want to use the 
latest and best version, aren't they?"

I think not all do, or not exactly as stated. As an example, on the 
FreeBSD laptop which I use 99% of the time (in no particular order for 
puns, sarcasm web browsing, email, IRC, and more relevantly for FreeBSD 
submitting or reviewing documentation change requests), I'm content with 
using the latest production version of ports but would rather stay away 
from -devel ports. When I need to check a manual page, I use a terminal 
window, not a web browser (indeed, in some cases, my network connection 
may not even work). When answering questions in IRC, however, I need to 
look at manual pages from the same port the user installed, which may be 
a production port or a -devel port, and to be able to point the user at 
it specifically. (I don't need access to old versions of a given port. 
I'm fine with telling the user to upgrade, or to explicitly switch to a 
legacy port if they can't or won't.) Occasionally, there may be 
collisions between conflicting unrelated ports, and in this case as 
well, being able to check manual pages from a specific port and pointing 
others to them would be nice.

Others who for whatever reason need to check a manual page but won't or 
can't do it in a terminal window (perhaps the computer the port is 
installed on is down and their boss or a customer is breathing down 
their neck) would probably appreciate being able to do that too.

Suggested design:

In addition to the current restriction fields (section, FreeBSD base 
version, and architecture), have a category/port field or field group. 
If left unfilled or with the default value, this would search across 
whatever non-conflicting subset of all port manual pages is currently 
accessible, for compatibility. If the user selects a given port, only 
manual pages for that port are searched.

What do others think?