Clarifying instructions on linking man pages
A recent discussion on debian-mentors 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. 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.
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 make packages install symlinks
instead. 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.
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
a link in the filesystem. I intend to 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,23 @@
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 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>
Currently, my count on auric [1] 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. Before woody is released, I'd
like to drop support for this in man (perhaps unless you use some option
or other).
The effect of this on packages will be that man pages will only 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 reasonable numbers of packages
installed. I'll file (normal) bugs as necessary.
Any comments?
[1] 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
--
Colin Watson [cjw44@flatline.org.uk]
Reply to: