Bug 254466 - sysutils/beadm-devel section (1) and sysutils/beadm section (8) for the two manual pages for beadm; consequences
Summary: sysutils/beadm-devel section (1) and sysutils/beadm section (8) for the two m...
Status: Closed Works As Intended
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Many People
Assignee: freebsd-ports-bugs (Nobody)
URL: https://www.freebsd.org/cgi/man.cgi?q...
Keywords:
Depends on:
Blocks: 256676
  Show dependency treegraph
 
Reported: 2021-03-21 16:25 UTC by Graham Perrin
Modified: 2021-12-01 16:26 UTC (History)
7 users (show)

See Also:
bugzilla: maintainer-feedback? (vermaden)


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Graham Perrin freebsd_committer 2021-03-21 16:25:11 UTC
<https://www.freebsd.org/cgi/man.cgi?beadm(1)> works …

<https://www.freebsd.org/cgi/man.cgi?beadm(8)> does not …

man 8 beadm                                    works …

man 1 beadm                                    does not; 

% man 1 beadm
No manual entry for beadm
% pkg info -x beadm
beadm-1.3.2
% freebsd-version -kru
14.0-CURRENT
14.0-CURRENT
14.0-CURRENT
% 

Is this a FreeBSD documentation bug? For the FreeBSD website view of the page. 

From the "(8)" at <https://github.com/vermaden/beadm/commit/7c1b1de2a6af28ae3c8dc230a715a3096ecb64ad#commitcomment-48517471> I assume that (8) is correct.
Comment 1 Graham Perrin freebsd_committer 2021-03-21 16:33:48 UTC
Sorry, Bugzilla previews are partially broken (a known issue), I couldn't guess that Bugzilla would mangle my angle bracket-enclosed URLs. 

Instead: 

<https://www.freebsd.org/cgi/man.cgi?query=beadm&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

> beadm(1)	

<https://www.freebsd.org/cgi/man.cgi?query=beadm&apropos=0&sektion=8&manpath=FreeBSD+12.2-RELEASE+and+Ports&arch=default&format=html>

> … Sorry, no data found for `beadm(8)'.
Comment 2 Slawomir Wojciech Wojtczak 2021-03-21 19:22:23 UTC
Its my fault (man 1 beadm not being present anymore ...).

When I introduced beadm the man page was written as '1' section (beadm.1) but as we know '1' is section for user utilities and '8' is section for sysadmin utils.

So with some version I 'fixed' that and renamed beadm.1 to beadm.8 along with making all references to beadm(8) now as its purely sysadmin tool ...

Sorry for that.

Regards.
Comment 3 Graham Perrin freebsd_committer 2021-03-21 19:44:27 UTC
No need to apologise, I'm quite accustomed to using (1) for the web page, although I sometimes forget which one of the two (beadm and bectl) is misplaced :-)
Comment 4 Slawomir Wojciech Wojtczak 2021-04-25 21:09:42 UTC
Is there something to be add here?
Comment 5 Graham Perrin freebsd_committer 2021-06-30 06:06:40 UTC
Consistency. 

man beadm

– finds the page in section 8

<https://www.freebsd.org/cgi/man.cgi>

– finds the page in first section 1. 

Using the pull-down menu to switch to section 8 finds a different version of the page in section 8.
Comment 6 Slawomir Wojciech Wojtczak 2021-11-22 10:09:26 UTC
Is that still relevant or should we close that?
Comment 8 Slawomir Wojciech Wojtczak 2021-11-22 11:57:46 UTC
All 4 links work.
Comment 9 Pau Amma freebsd_committer freebsd_triage 2021-11-22 12:10:28 UTC
(In reply to Slawomir Wojciech Wojtczak from comment #8)

The ones in section 1 shouldn't. That's the whole point, unless I completely misunderstand what the submitter is asking in https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=254466#c5. (And they should definitely not *return different content*.)
Comment 10 Slawomir Wojciech Wojtczak 2021-11-22 12:22:08 UTC
(In reply to PauAmma from comment #9)

I am not in charge for the Man Pages section on FreeBSD website so I can not help here.
Comment 11 Wolfram Schneider freebsd_committer 2021-11-22 12:54:02 UTC
Apparently, our packages for FreeBSD 13.0 contains manual pages for beadm(1) *and* beadm(8). I don't know why, maybe this will be fixed in FreeBSD 13.1 or the next quarterly updates.

see

https://www.freebsd.org/cgi/man.cgi?query=beadm&apropos=1&sektion=0&manpath=FreeBSD+Ports+13.0&arch=default&format=html
Comment 12 Daniel Ebdrup Jensen freebsd_committer 2021-11-22 13:50:27 UTC
I can't see how beadm(1) can exist without being specified in a Makefile as MLINKS but `find /usr/src -type f -exec grep "beadm 1" {} +` reveals a list of places where bectl(8) and beinstall(8) refers to beadm(1) instead of beadm(8), so I don't know how if that can be the reason for why man.cgi displays it if it doesn't work on a live system (if I understood the problem correctly).

Another option is that beadm.1 wasn't added to ObsoleteFiles when it was moved, which means that it'd be retained across upgrades but wouldn't exist on a new system.
Comment 13 Wolfram Schneider freebsd_committer 2021-11-22 15:58:42 UTC
There are two beadm ports

https://cgit.freebsd.org/ports/tree/sysutils/beadm
https://cgit.freebsd.org/ports/tree/sysutils/beadm-devel

$ pkg search beadm
beadm-1.3.2                    Solaris-like utility to manage Boot Environments on ZFS
beadm-devel-1.2.99.20180708_1  Solaris-like utility to manage Boot Environments on ZFS

pkg fetch beadm-1.3.2
tar tfv /var/cache/pkg/beadm-1.3.2.pkg |grep /man/man
-r--r--r--  0 root   wheel    1883 Nov 11 02:20 /usr/local/man/man8/beadm.8.gz

pkg fetch beadm-devel-1.2.99.20180708_1
tar tfv /var/cache/pkg/beadm-devel-1.2.99.20180708_1.pkg | grep man/man
-r--r--r--  0 root   wheel    1827 Nov 11 10:21 /usr/local/man/man1/beadm.1.gz

Two ports, two manual pages - everything works as expected ;-)
Comment 14 Slawomir Wojciech Wojtczak 2021-11-22 16:07:30 UTC
I think that *sysutils/beadm-devel* can be deleted as it was not updated since 3 years ...
Comment 15 Allan Jude freebsd_committer 2021-11-22 17:27:28 UTC
So the man page used to be in section 1, and was moved to section 8 on Dec 2, 2020:

https://cgit.freebsd.org/ports/commit/sysutils/beadm/Makefile?id=5bc2ab493eece5179eaa80e269c838e7aaf1ab55

So the cache is man pages has both versions.

I don't know how often old ones get purged, or how that process works.
Comment 16 Pau Amma freebsd_committer freebsd_triage 2021-11-22 18:24:53 UTC
(In reply to Wolfram Schneider from comment #13)
"Two ports, two manual pages - everything works as expected ;-)" the problem is the POLA violation works too well. :-)
Comment 17 Wolfram Schneider freebsd_committer 2021-11-22 18:47:11 UTC
(In reply to Allan Jude from comment #15)

The ports manual pages will be updated every 3 month (quarterly), based on
http://pkg.freebsd.org/FreeBSD:13:amd64/quarterly/

There is no cache, everything will be build from scratch.

The last build of the beadm(1) page is from 11-Nov-2021

pkg fetch beadm-devel-1.2.99.20180708_1
tar tfv /var/cache/pkg/beadm-devel-1.2.99.20180708_1.pkg | grep man/man
-r--r--r--  0 root   wheel    1827 Nov 11 10:21 /usr/local/man/man1/beadm.1.gz
Comment 18 Bryan Drewery freebsd_committer 2021-11-23 23:49:18 UTC
(In reply to Wolfram Schneider from comment #17)

Please see https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=256676 ; please delete poudriere from this manpage build and do not publish it on freebsd.org.
Comment 19 Graham Perrin freebsd_committer 2021-11-27 10:55:47 UTC
(In reply to Wolfram Schneider from comment #13)

Most insightful, thanks. I'll edit the summary line accordingly. 

From a 'Manual Pages' (Bugzilla component) perspective, there's temptation for me to close this bug – works as intended – however it's a thought-provoking edge case so for now, I'll leave it open. 

Triagers: maybe change the product to 'Ports & Packages'? 

----

(In reply to Slawomir Wojciech Wojtczak from comment #14)

That seems reasonable, thanks, in that 
<https://www.freshports.org/sysutils/beadm/#description> and 
<https://www.freshports.org/sysutils/beadm-devel/#description> share the same WWW link to your repo. Deletion only if you foresee no future end use of beadm-devel as a distinct port …

----

For giggles and/or mind-bending: <https://forums.freebsd.org/posts/544082> where the coding in XenForo causes recommended markup to not find the manual page for beadm(8) in this edge case, although (with reference to the new summary line) I'm unsure whether to treat the non-find as a partial "consequence" of bug 254466 :-)

Thanks to all.
Comment 20 Wolfram Schneider freebsd_committer 2021-12-01 16:05:50 UTC
Closing the issue. Feel free to open an new report regarding the differences for the ports sysutils/beadm-devel and sysutils/beadm