Bug 264054 - Man page display on web site is confusing
Summary: Man page display on web site is confusing
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Website (show other bugs)
Version: Latest
Hardware: Any Any
: Normal Affects Many People
Assignee: Wolfram Schneider
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2022-05-18 00:36 UTC by Greg Lehey
Modified: 2024-03-21 00:18 UTC (History)
3 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Greg Lehey freebsd_committer freebsd_triage 2022-05-18 00:36:22 UTC
This is a resubmission of part of https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=264036

Currently the man page choice on the web site (https://www.freebsd.org/cgi/man.cgi) defaults to ”13-1-RELEASE and Ports”.  This causes several issues, illustrated by a search for the man page gpart(8):

1. Ports can have priority over the base system, so unless the person searching for a man page in the base system knows the section number, he could end up with the man page for a port.
2. There's no way for the user to know which port he has found.  In this example, the man page carries the title “Scotch user's manual”, but that's the only clue.
3. There's no way for the user to know that there are more man pages with the same name in different sections.

My suggestion:

1.  In the short term, update the man page display to explain this situation, something like

    There may be more than one man page with this name.  If you don't
    find what you're looking for, try 13.1-RELEASE without ports, or
    try selecting a specific section of the manual.

2.  Longer term, rearrange the priorities: base system first, then ports.

3.  When displaying port man pages, include information on the name of the port.
Comment 1 Graham Perrin freebsd_committer freebsd_triage 2022-05-18 00:58:17 UTC
See also (request for discussion): 

RFD: disambiguating online manual page name collisions between different ports
https://lists.freebsd.org/archives/freebsd-doc/2021-December/000914.html>

Cross-reference: 

Manual pages online: RFD – share your thoughts on changes to design | The FreeBSD Forums
<https://forums.freebsd.org/threads/83217/>

– skip to post 10 <https://forums.freebsd.org/posts/548250>, if you like; 

> … I did not realise that Pau Amma had parallel thoughts, about 
> improvements, until some weeks after my thoughts began forming. …
Comment 2 plastickey 2022-05-18 19:48:34 UTC
It would be helpful if the actual port version and package name were displayed on a port man page. I also disagree with wosch that people want the latest version. I think they want to see the version that they are working with. I think it would be a worthwhile addition to add a selector to choose which package to get a man page from only if there are duplicates. The selector would be greyed out/disabled until a man page is a part of a duplicate series. Maybe it would default to non-devel, but at least there would be choice.
Comment 3 commit-hook freebsd_committer freebsd_triage 2022-09-28 06:12:26 UTC
A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/doc/commit/?id=f42891ebcfffa433f1826a102014e68a284f1c0a

commit f42891ebcfffa433f1826a102014e68a284f1c0a
Author:     Wolfram Schneider <wosch@FreeBSD.org>
AuthorDate: 2022-09-28 06:09:26 +0000
Commit:     Wolfram Schneider <wosch@FreeBSD.org>
CommitDate: 2022-09-28 06:09:26 +0000

    Give base manual page higher priority than ports manual pages

    First look in the FreeBSD base manual pages (aka /usr/share/man) and then
    in FreeBSD ports (aka /usr/local/man). This avoids confusion when manual pages have
    have the same name, but are in different sections. In this case, a ports manual
    pages would win because of the higher section priority. Now, searching for "socket"
    will always show socket(2) from the base system and not socket(1) from ports

    PR: 264054
    Reported by: grog

 website/content/en/cgi/man.cgi | 50 +++++++++++++++++++++++++++++++++++++-----
 1 file changed, 45 insertions(+), 5 deletions(-)
Comment 4 Jonathan Gross 2023-04-12 07:20:36 UTC
MARKED AS SPAM
Comment 5 Sergio Carlavilla Delgado freebsd_committer freebsd_triage 2023-08-27 11:31:17 UTC
Fixed, thanks for the report.
Comment 6 DylanWalker 2024-03-20 04:44:10 UTC
MARKED AS SPAM