Bug#94995: marked as done ([ACCEPTED 16/05/2001] Clarifying instructions on linking man pages)
Your message dated Fri, 8 Jun 2001 00:30:50 +0100
with message-id <20010608003050.A3838@polya>
and subject line debian-policy_3.5.5.0_i386.changes INSTALLED
has caused the attached Bug report to be marked as done.
This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.
(NB: If you are a system administrator and have no idea what I am
talking about this indicates a serious mail system misconfiguration
somewhere. Please contact me immediately.)
Darren Benham
(administrator, Debian Bugs database)
--------------------------------------
Received: (at submit) by bugs.debian.org; 23 Apr 2001 16:11:17 +0000
>From cjw44@flatline.org.uk Mon Apr 23 11:11:17 2001
Return-path: <cjw44@flatline.org.uk>
Received: from mta01-svc.ntlworld.com [62.253.162.41]
by master.debian.org with esmtp (Exim 3.12 1 (Debian))
id 14rivk-0006Hf-00; Mon, 23 Apr 2001 11:11:16 -0500
Received: from riva.ucam.org ([62.253.132.58]) by mta01-svc.ntlworld.com
(InterMail vM.4.01.02.27 201-229-119-110) with ESMTP
id <20010423161107.CPJQ283.mta01-svc.ntlworld.com@riva.ucam.org>
for <submit@bugs.debian.org>; Mon, 23 Apr 2001 17:11:07 +0100
Received: from cjw44 by riva.ucam.org with local (Exim 3.22 #1 (Debian))
for submit@bugs.debian.org
id 14rivb-0001Bg-00; Mon, 23 Apr 2001 17:11:07 +0100
Date: Mon, 23 Apr 2001 17:11:06 +0100
From: Colin Watson <cjw44@flatline.org.uk>
To: submit@bugs.debian.org
Subject: [PROPOSAL] Clarifying instructions on linking man pages
Message-ID: <20010423171106.A3109@riva.ucam.org>
References: <20010421185748.A16532@riva.ucam.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
User-Agent: Mutt/1.3.17i
In-Reply-To: <20010421185748.A16532@riva.ucam.org>; from cjw44@riva.ucam.org on Sat, Apr 21, 2001 at 06:57:48PM +0100
Organization: riva.ucam.org
Sender: Colin Watson <cjw44@riva.ucam.org>
Delivered-To: submit@bugs.debian.org
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]
---------------------------------------
Received: (at 94995-done) by bugs.debian.org; 7 Jun 2001 23:34:03 +0000
>From J.D.Gilbey@qmw.ac.uk Thu Jun 07 18:34:02 2001
Return-path: <J.D.Gilbey@qmw.ac.uk>
Received: from murphy.debian.org [::ffff:216.234.231.6]
by master.debian.org with smtp (Exim 3.12 1 (Debian))
id 1589Hu-0002qu-00; Thu, 07 Jun 2001 18:34:02 -0500
Received: (qmail 3860 invoked from network); 7 Jun 2001 23:31:27 -0000
Received: from mserv1e.vianw.co.uk (195.102.240.97)
by murphy.debian.org with SMTP; 7 Jun 2001 23:31:27 -0000
Received: from [195.102.197.85] (helo=polya)
by mserv1e.vianw.co.uk with esmtp (Exim 3.22 #5)
id 1589Er-0007Ry-00; Fri, 08 Jun 2001 00:30:54 +0100
Received: from jdg by polya with local (Exim 3.22 #1 (Debian))
id 1589Eo-000103-00; Fri, 08 Jun 2001 00:30:50 +0100
Date: Fri, 8 Jun 2001 00:30:50 +0100
From: Julian Gilbey <jdg@debian.org>
To: 66023-done@bugs.debian.org, 89473-done@bugs.debian.org,
89674-done@bugs.debian.org, 91249-done@bugs.debian.org,
91252-done@bugs.debian.org, 91257-done@bugs.debian.org,
91259-done@bugs.debian.org, 91260-done@bugs.debian.org,
91261-done@bugs.debian.org, 92744-done@bugs.debian.org,
94995-done@bugs.debian.org, 95906-done@bugs.debian.org,
97072-done@bugs.debian.org, 98712-done@bugs.debian.org
Subject: debian-policy_3.5.5.0_i386.changes INSTALLED
Message-ID: <20010608003050.A3838@polya>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
User-Agent: Mutt/1.3.18i
Sender: Julian Gilbey <J.D.Gilbey@qmw.ac.uk>
Delivered-To: 94995-done@bugs.debian.org
----- Forwarded message from Debian Installer <installer@ftp-master.debian.org> -----
Date: Mon, 04 Jun 2001 10:23:07 -0400
From: Debian Installer <installer@ftp-master.debian.org>
Subject: debian-policy_3.5.5.0_i386.changes INSTALLED
To: Julian Gilbey <jdg@debian.org>,
Debian Policy List <debian-policy@lists.debian.org>
Installing:
debian-policy_3.5.5.0.tar.gz
to pool/main/d/debian-policy/debian-policy_3.5.5.0.tar.gz
policy-process.txt.gz byhand
libc6-migration.txt byhand
fhs.txt byhand
debian-policy_3.5.5.0_all.deb
to pool/main/d/debian-policy/debian-policy_3.5.5.0_all.deb
perl-policy.txt.gz byhand
menu-policy.txt.gz byhand
mime-policy.txt.gz byhand
virtual-package-names-list.txt byhand
upgrading-checklist.txt byhand
fhs-2.1.html.tar.gz byhand
policy.pdf.gz byhand
menu-policy.html.tar.gz byhand
policy.html.tar.gz byhand
mime-policy.html.tar.gz byhand
debconf_specification.html byhand
debconf_specification.txt.gz byhand
policy.txt.gz byhand
policy-process.html.tar.gz byhand
perl-policy.html.tar.gz byhand
debian-policy_3.5.5.0.dsc
to pool/main/d/debian-policy/debian-policy_3.5.5.0.dsc
policy.ps.gz byhand
Changes: debian-policy (3.5.5.0) unstable; urgency=low
.
* Fixed up incorrect entries in the changelog (there was an erroneous
3.5.0.1 revision which never happened; it has now been correctly
merged with the 3.5.3.0 changelog entry)
* Add section numbers to upgrading-checklist for all revisions from
3.0.0 onwards
* Complete rewrite (and renumbering) of sections 9.1 and 9,2
* This time *really* include the HTML version of the FHS
* Added doc-base support for all of the HTML files
* Added several more files to the byhand list and rewrote chunks of
debian/rules to do this
* Add patched versions of debiandoc-sgml stuff to source package until
patches are incorporated upstream
* Versioned Build-Depend on debiandoc-sgml for fixed Text.pm
* Improved mkdir example in 10.1.2 closes: Bug#92744
* Made the "where examples live" entry in the upgrading-checklist
clearer (add "for use by scripts")
* Add a dpkg-statoverride description section closes: Bug#89473
* Fix the ldconfig usage description (remove "only if")
closes: Bug#89674
* Clarification of package priority issues vis-a-vis the X Windows
system closes: Bug#91249
* Enhanced x-terminal-emulator policy closes: Bug#91252
* Minor changes to X app-defaults policy closes: Bug#91259
* Clarification of X policy in respect to FHS closes: Bug#91260
* OpenMotif has the same rules as OSF/Motif closes: Bug#91261
* The X Font policy rewrite closes: Bug#91257
* The "man" program is no longer guaranteed to read header information
to find alternative manpage names closes: Bug#94995
* Correction to meaning of Standards-Version closes: Bug#97072
* Split section 12.8 (X Window System) into subsections for readability
* Plug-ins != shared libraries (at last) closes: Bug#66023
* Add packaging manual remnants to policy document as appendices, and
mention this in control file closes: Bug#95906
* Clarification in Perl policy closes: Bug#98712
Announcing to debian-devel-changes@lists.debian.org
Setting bugs to severity fixed: 66023 89473 89674 91249 91252 91257 91259 91260 91261 92744 94995 95906 97072 98712
Thank you for your contribution to Debian.
----- End forwarded message -----
Reply to: