When a user requests the generic man page for which alternatives exist, Gentoo tries to provide the man page for the specific implementation in use. However, the way it does so creates an issue when using mandoc instead of man-db. For example, awk.1 simply contains an .so request whose argument is the man page for the actual awk implementation in use: .so gawk.1 However, although this works when using man-db, it doesn't when one is using mandoc. Instead of gawk.1 being sourced, processed and displayed, one gets output along the lines of: () () See the file gawk.1. () However, if the request in awk.1 is changed to: .so man1/gawk.1 then everything works as expected. The example in the entry for .so in mandoc_roff(7) is what led me to try the preceding, but there's no further indication that the requirement for a leading section directory is consciously different from any other roff implementation, or from groff in particular. A comment in roff_so() in mandoc/roff.c[a] says: /* /* Handle `so'. Be EXTREMELY careful, as we shouldn't be * opening anything that's not in our cwd or anything beneath * it. Thus, explicitly disallow traversing up the file-system * or using absolute paths. */ i couldn't find any discussion about .so in the mandoc TODO list[b]. i raised this issue on discuss@mandoc.bsd.lv, groff@gnu.org and man-db-devel@nongnu.org: https://lists.gnu.org/archive/html/groff/2023-04/msg00221.html groff maintainer G. Branden Robinson replied: In practice, as I understand it, `so` doesn't achieve anything for man pages that can't be done with symbolic links and (importantly) a man page indexer that is symlink-aware. although man-db maintainer Colin Watson noted: It is worth noting that today there are at least some real-world cases where it isn't being used as a mere symlink; bash-builtins(7) is one such. i've been waiting for any further comments (e.g. from mandoc mantainer Ingo Schwarze), but there haven't been any. Is there any particular reason why .so requests need to be used when dealing with alternatives, instead of symlinks? [a] https://cvsweb.bsd.lv/mandoc/roff.c?rev=1.395&content-type=text/x-cvsweb-markup [b] https://cvsweb.bsd.lv/mandoc/TODO?rev=1.327&content-type=text/x-cvsweb-markup Reproducible: Always
The problem with symlinks is that they need to be updated to match manpage compression. `.so` works with any compression used for the manpage.
(In reply to Michał Górny from comment #1) > The problem with symlinks is that they need to be updated to match manpage > compression. `.so` works with any compression used for the manpage. Ah, yeah. i've now noted this is the discussion thread: https://lists.gnu.org/archive/html/groff/2023-05/msg00026.html
(In reply to Michał Górny from comment #1) > The problem with symlinks is that they need to be updated to match manpage > compression. `.so` works with any compression used for the manpage. Portage seems to auto-updates these. Some build systems will make symlinks too (e.g. openssl makes a million), and without that we'd need to convert everything to .so $ ls -l /usr/share/man/man3/i2d_TS_TST_INFO_bio.3ossl.zst lrwxrwxrwx 1 root root 18 Apr 26 12:20 /usr/share/man/man3/i2d_TS_TST_INFO_bio.3ossl.zst -> d2i_X509.3ossl.zst zst is uncommon for man pages but it was handled just fine Not that I personally have a problem with either method being used.
... then again scratch that, when the man page is from /another/ package I don't see symlinks working.
*** Bug 917535 has been marked as a duplicate of this bug. ***
