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
On Mon, 2011-12-19 at 05:23 +0100, Ulrich Mueller wrote:
> Thinking about it a little more, I believe that ${CATEGORY} shouldn't > appear anywhere in the path of installed files, for the following > reasons: > > 1. Users may not know the category of a package, therefore it's not > obvious for them where to find its documentation. (Think of it from > the perspective of a user on a multiuser system, who didn't install > the packages on that system.) OTOH, the name of the package (PN) is > obvious in most cases, since it will coincide with the upstream > name. > > 2. It doesn't play well with bash completion. When searching for > documentation of a specific package (and only knowing PN), one can > currently type the pathname up to PN and press tab which will > complete PVR. With CATEGORY _before_ PN this would no longer work.
I am forced to agree with your points #1 and #2. $CATEGORY/$PN-$SLOT is optimized for the "bookmark a document and go back to it a week later" use case, but you are correct that it would work poorly for the "quickly look up a doc that you had not cared about until now" use case. Using /usr/share/doc/$PN-$SLOT with exceptions for packages that have the same ($PN, $SLOT) but different categories would not scale: it turns out there are >100 of them in the main tree. Using /usr/share/doc/$P would be worse than the current situation: doc locations would still shift on minor version bumps, and packages with multiple slots in the same $P (e.g. webkit-gtk) would collide. And using $CATEGORY after $PN is simply too ugly to contemplate. Fortunately, there *is* a neat solution. Symlinks. In other words: no change to dodoc/newdoc/dohtml, they will continue to install documentation in /usr/share/doc/$PF like they do today. BUT the package manager will automatically create a symlink from /usr/share/doc/$CATEGORY/$PN (for slot 0) or from /usr/share/doc/$CATEGORY/$PN-$SLOT (for slot != 0) to /usr/share/doc/$PF. This would have to be done after the end of src_install() so that the symlink goes in the VDB. I think that this change, similarly to the automatic .la file fixing, could be implemented by portage without waiting for a new EAPI.
> 3. CATEGORY and SLOT are Gentoo specific, related to the way how we > organise our packages. Neither of them should appear in the > directory structure of installed packages.
Slot 0 really is Gentoo-specific; that is why I propose to omit it. Non-zero slots, however, are usually based on some obvious upstream property, for example on the major version of the package or on the name of the pkgconfig file. You are correct that categories are Gentoo-specific and are therefore not ideal for installed paths. However, for generating a stable path to documentation files, one that does not shift on version bumps and revbumps, there doesn't seem to be any alternative. -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>