From nobody Thu Dec 02 02:06:28 2021 X-Original-To: doc@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 3C5B918C81F0 for ; Thu, 2 Dec 2021 02:06:36 +0000 (UTC) (envelope-from pauamma@gundo.com) Received: from mail.gundo.com (gibson.gundo.com [75.145.166.65]) by mx1.freebsd.org (Postfix) with ESMTP id 4J4K7v2mJfz4fxf for ; Thu, 2 Dec 2021 02:06:35 +0000 (UTC) (envelope-from pauamma@gundo.com) Received: from webmail.gundo.com (variax.gundo.com [75.145.166.70]) by mail.gundo.com (Postfix) with ESMTP id 19B104C12E1 for ; Wed, 1 Dec 2021 20:06:29 -0600 (CST) List-Id: Documentation project List-Archive: https://lists.freebsd.org/archives/freebsd-doc List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-freebsd-doc@freebsd.org MIME-Version: 1.0 Date: Thu, 02 Dec 2021 02:06:28 +0000 From: Pau Amma To: doc@freebsd.org Subject: RFD: disambiguating online manual page name collisions between different ports User-Agent: Roundcube Webmail/1.4.8 Message-ID: X-Sender: pauamma@gundo.com Content-Type: text/plain; charset=US-ASCII; format=flowed Content-Transfer-Encoding: 7bit X-Rspamd-Queue-Id: 4J4K7v2mJfz4fxf X-Spamd-Bar: --- Authentication-Results: mx1.freebsd.org; dkim=none; dmarc=none; spf=pass (mx1.freebsd.org: domain of pauamma@gundo.com designates 75.145.166.65 as permitted sender) smtp.mailfrom=pauamma@gundo.com X-Spamd-Result: default: False [-3.22 / 15.00]; ARC_NA(0.00)[]; NEURAL_HAM_MEDIUM(-1.00)[-0.998]; FREEFALL_USER(0.00)[pauamma]; FROM_HAS_DN(0.00)[]; RWL_MAILSPIKE_GOOD(0.00)[75.145.166.65:from]; TO_MATCH_ENVRCPT_ALL(0.00)[]; R_SPF_ALLOW(-0.20)[+a]; MIME_GOOD(-0.10)[text/plain]; PREVIOUSLY_DELIVERED(0.00)[doc@freebsd.org]; TO_DN_NONE(0.00)[]; RCPT_COUNT_ONE(0.00)[1]; NEURAL_HAM_LONG(-0.93)[-0.927]; DMARC_NA(0.00)[gundo.com]; RCVD_IN_DNSWL_MED(-0.20)[75.145.166.65:from]; NEURAL_HAM_SHORT(-0.90)[-0.899]; RCVD_NO_TLS_LAST(0.10)[]; FROM_EQ_ENVFROM(0.00)[]; R_DKIM_NA(0.00)[]; MIME_TRACE(0.00)[0:+]; ASN(0.00)[asn:7922, ipnet:75.144.0.0/13, country:US]; RCVD_COUNT_TWO(0.00)[2]; MID_RHS_MATCH_FROM(0.00)[] X-ThisMailContainsUnwantedMimeParts: N 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 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?