On Mon, 19 Dec 2011 01:41:00 -0500
Alexandre Rostovtsev <tetromino@gentoo.org> wrote:

> 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.

And I hope there will be more. We should seriously start splitting
packages rather than using old Gentoo bloat like IUSE='perl python
foobar foobaz'.

> Fortunately, there *is* a neat solution.
> 
> Symlinks.

Symlinks are never neat. In this particular case, they just mean
someone has failed horribly and now is hoping to fix it taking
the path of least resistance.

> > 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.
> 
> 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.

To be honest, the whole ${PF} is Gentoo-specific. Package names not
necessarily follow upstream ones; sometimes we need to change versions
as well to match ${PV} semantics or logic. Perl modules are quite
a large case here.

Sometimes packages in different categories collide. Right now, devs
have to be aware not to install colliding docs -- usually through
renaming files. Using category will at least partially fix this.

Shifting is unavoidable. SLOTs can change, categories can change,
package names can change. Of course, all the mentioned cases are much
rarer than PF changing but -- as pointed out before -- these could
change without reinstalling packages.

If we decided to use such names, the most correct approach would be to
have PM handle docmoves as well. But -- on the other hand -- there will
be always some hardwired paths which will be updated only on real
package rebuild...

-- 
Best regards,
Michał Górny