Bug#94995: [PROPOSAL] Clarifying instructions on linking man pages
Package: debian-policy
Version: 3.5.3.0
Severity: wishlist
[I've clarified this proposal slightly from what I originally posted on
debian-policy, in response to Chris Waters' comments.]
A recent discussion on debian-mentors [1] brought it to my attention
that packages frequently rely on an implementation detail of man: that
it holds a database of whatis entries and happens to be able to find
pages even if the file containing the man page has a different name that
doesn't appear in the filesystem. For instance, look at xli(1), which
says it describes "xli, xsetbg, xview" - but xsetbg(1x) is a different
man page provided by the xloadimage package, and xli doesn't provide
xsetbg.1.gz itself. (Nor does it provide any executable called xsetbg,
in fact, but that's a different bug. builtins(1) is perhaps a better
example.)
If you don't have xloadimage installed, 'man xsetbg' will eventually
work, but if the man database happens not to be up to date (because
you've just installed some new man pages, for instance) then it has to
grovel through all your manual page hierarchies to find the most
appropriate page to show. If you have neither xli nor xloadimage
installed, then man might have to look through lots of man pages anyway
just to be able to tell you that it can't find anything appropriate.
The current implementation of all of this could be improved somewhat,
but that's not really the point. Since it's fundamentally a horrible
mess, I'd like to deprecate the practice of relying on man working this
out (very ... slowly ...) for itself and have packages install symlinks
instead (or .so links or hard links, although those are already mildly
deprecated). man's database is meant for supporting apropos and that
sort of thing, not for doing a job that really should be kept in the
filesystem. In addition, some other implementation of man might well not
handle this: in point of fact, Andries Brouwer's implementation, used in
several other GNU/Linux distributions, doesn't.
As I read it, current policy seems to implicitly expect that packages
should use the filesystem for this purpose:
If one manpage needs to be accessible via several names it is better
to use a symbolic link than the .so feature, but there is no need to
fiddle with the relevant parts of the upstream source to change from
.so to symlinks--don't do it unless it's easy. You should not create
hard links in the manual page directories, nor put absolute filenames
in .so directives. The filename in a .so in a manpage should be
relative to the base of the manpage tree (usually /usr/share/man).
It doesn't even consider the possibility that packages might not install
any kind of link (.so, symbolic, or hard) in the filesystem. I propose
the following diff to policy to clarify this:
--- policy.sgml.orig Sat Apr 21 14:05:54 2001
+++ policy.sgml Sat Apr 21 18:15:04 2001
@@ -6528,7 +6528,24 @@
absolute filenames in <tt>.so</tt> directives. The filename
in a <tt>.so</tt> in a manpage should be relative to the
base of the manpage tree (usually
- <tt>/usr/share/man</tt>).</p></sect>
+ <tt>/usr/share/man</tt>). If you do not create any links
+ (whether symlinks, hard links, or .so directives) in the
+ filesystem to the alternate names of the manpage, then you
+ should not rely on <prgn>man</prgn> finding your manpage
+ under those names based solely on the information in the
+ manpage's header.
+ <footnote>
+ <p>
+ Supporting this in <prgn>man</prgn> often requires
+ unreasonable processing time to find a manual page or to
+ report that none exists, and moves knowledge into man's
+ database that would be better left in the filesystem.
+ This support is therefore deprecated and will cease to be
+ present in the future.
+ </p>
+ </footnote>
+ </p>
+ </sect>
<sect>
Before woody is released, I'd like to drop support for this in man
(perhaps unless you use some option or other).
Currently, my count on auric [2] gives 1810 secondary names of man
pages, excluding non-US, that rely on this 'feature' of man; these names
are referred to in 377 unique man pages. For comparison, there are 6974
man page names referred to via .so, symbolic, or hard links.
The effect on packages of removing this feature will be that man pages
will only be guaranteed to be accessible by names in the filesystem,
which I don't expect to be a major problem in the short term considering
how much more usable the whole thing will become for people with even
moderately substantial numbers of packages installed. I'll file (normal)
bugs as necessary, and fixing these will be a matter of installing
additional symlinks.
Given that the man package used in many other distributions doesn't
support this, and that in fact the feature seems to be a non-standard
extension in the man-db package we use, I don't expect this to cause any
significant interoperability problems.
I'm looking for seconders for this proposal.
[1] http://lists.debian.org/debian-mentors-0104/msg00202.html
[2] for x in `grep-dctrl -rnsFilename . \
/org/ftp.debian.org/ftp/dists/sid/*/*/Packages | sort -u`; \
do dpkg --fsys-tarfile /org/ftp.debian.org/ftp/$x | \
tar -xkf - {./,}usr/{,share/,X11R6/}man/ 2>/dev/null; \
done; \
cp /usr/lib/man-db/mandb .; \
for x in usr/{,share/,X11R6/}man; do ./mandb $x; done; \
for x in usr/{,share/,X11R6/}man; \
do echo $x:; /usr/sbin/accessdb $x/index.bt | \
perl -nle \
'if (/ -> "[^ ]* [^ ]* [^ ]* C (.+?) /) {
$count++; $ref{$1}++;
}
END {
print "$count names in ", scalar keys %ref, " unique pages";
}'; \
done
Thanks,
--
Colin Watson (man-db maintainer) [cjw44@flatline.org.uk]
Reply to: