Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF

[Alexandre Rostovtsev]

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.