Bug 254466
| Summary: | sysutils/beadm-devel section (1) and sysutils/beadm section (8) for the two manual pages for beadm; consequences | ||
|---|---|---|---|
| Product: | Documentation | Reporter: | Graham Perrin <grahamperrin> |
| Component: | Manual Pages | Assignee: | freebsd-ports-bugs (Nobody) <ports-bugs> |
| Status: | Closed Works As Intended | ||
| Severity: | Affects Many People | CC: | allanjude, bdrewery, debdrup, doc, pauamma, vermaden, wosch |
| Priority: | --- | Flags: | bugzilla:
maintainer-feedback?
(vermaden) |
| Version: | Latest | ||
| Hardware: | Any | ||
| OS: | Any | ||
| URL: | https://www.freebsd.org/cgi/man.cgi?query=beadm&manpath=Ports&sektion=8 | ||
| Bug Depends on: | |||
| Bug Blocks: | 256676 | ||
|
Description
Graham Perrin
2021-03-21 16:25:11 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)'. 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. 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 :-) Is there something to be add here? 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. Is that still relevant or should we close that? (In reply to Slawomir Wojciech Wojtczak from comment #6) Still happening, eg: https://www.freebsd.org/cgi/man.cgi?query=beadm&apropos=0&sektion=0&manpath=FreeBSD+13.0-RELEASE+and+Ports&arch=default&format=html or https://www.freebsd.org/cgi/man.cgi?query=beadm&manpath=FreeBSD+13.0-RELEASE+and+Ports beadm -- Utility to manage Boot Environments with ZFS https://www.freebsd.org/cgi/man.cgi?query=beadm&apropos=0&sektion=8&manpath=FreeBSD+13.0-RELEASE+and+Ports&arch=default&format=html or https://www.freebsd.org/cgi/man.cgi?query=beadm&sektion=8&manpath=FreeBSD+13.0-RELEASE+and+Ports beadm -- manage boot environments with ZFS (Notice the "Utility to" and the tab present in the first one.) All 4 links work. (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*.) (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. 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 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.
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 ;-) I think that *sysutils/beadm-devel* can be deleted as it was not updated since 3 years ... 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. (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. :-) (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 (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. (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. Closing the issue. Feel free to open an new report regarding the differences for the ports sysutils/beadm-devel and sysutils/beadm |