Gentoo Archives: gentoo-dev

From: Alexandre Rostovtsev <tetromino@g.o>
To: gentoo-dev@l.g.o
Subject: Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF
Date: Mon, 19 Dec 2011 06:41:42
Message-Id: 1324276860.12311.177.camel@rook
In Reply to: Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF by Ulrich Mueller
1 On Mon, 2011-12-19 at 05:23 +0100, Ulrich Mueller wrote:
2 > Thinking about it a little more, I believe that ${CATEGORY} shouldn't
3 > appear anywhere in the path of installed files, for the following
4 > reasons:
5 >
6 > 1. Users may not know the category of a package, therefore it's not
7 > obvious for them where to find its documentation. (Think of it from
8 > the perspective of a user on a multiuser system, who didn't install
9 > the packages on that system.) OTOH, the name of the package (PN) is
10 > obvious in most cases, since it will coincide with the upstream
11 > name.
12 >
13 > 2. It doesn't play well with bash completion. When searching for
14 > documentation of a specific package (and only knowing PN), one can
15 > currently type the pathname up to PN and press tab which will
16 > complete PVR. With CATEGORY _before_ PN this would no longer work.
18 I am forced to agree with your points #1 and #2. $CATEGORY/$PN-$SLOT is
19 optimized for the "bookmark a document and go back to it a week later"
20 use case, but you are correct that it would work poorly for the "quickly
21 look up a doc that you had not cared about until now" use case.
23 Using /usr/share/doc/$PN-$SLOT with exceptions for packages that have
24 the same ($PN, $SLOT) but different categories would not scale: it turns
25 out there are >100 of them in the main tree.
27 Using /usr/share/doc/$P would be worse than the current situation: doc
28 locations would still shift on minor version bumps, and packages with
29 multiple slots in the same $P (e.g. webkit-gtk) would collide.
31 And using $CATEGORY after $PN is simply too ugly to contemplate.
33 Fortunately, there *is* a neat solution.
35 Symlinks.
37 In other words: no change to dodoc/newdoc/dohtml, they will continue to
38 install documentation in /usr/share/doc/$PF like they do today.
40 BUT the package manager will automatically create a symlink
41 from /usr/share/doc/$CATEGORY/$PN (for slot 0) or
42 from /usr/share/doc/$CATEGORY/$PN-$SLOT (for slot != 0)
43 to /usr/share/doc/$PF. This would have to be done after the end of
44 src_install() so that the symlink goes in the VDB.
46 I think that this change, similarly to the automatic .la file fixing,
47 could be implemented by portage without waiting for a new EAPI.
49 > 3. CATEGORY and SLOT are Gentoo specific, related to the way how we
50 > organise our packages. Neither of them should appear in the
51 > directory structure of installed packages.
53 Slot 0 really is Gentoo-specific; that is why I propose to omit it.
54 Non-zero slots, however, are usually based on some obvious upstream
55 property, for example on the major version of the package or on the name
56 of the pkgconfig file.
58 You are correct that categories are Gentoo-specific and are therefore
59 not ideal for installed paths. However, for generating a stable path to
60 documentation files, one that does not shift on version bumps and
61 revbumps, there doesn't seem to be any alternative.
63 -Alexandre.


Subject Author
Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF Ulrich Mueller <ulm@g.o>
Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF "Michał Górny" <mgorny@g.o>