Bug 264054

Summary:	Man page display on web site is confusing
Product:	Documentation	Reporter:	Greg Lehey <grog>
Component:	Website	Assignee:	Wolfram Schneider <wosch>
Status:	Closed FIXED
Severity:	Affects Many People	CC:	carlavilla, grahamperrin, wosch
Priority:	Normal
Version:	Latest
Hardware:	Any
OS:	Any

Description Greg Lehey freebsd_committer

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

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

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

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