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

[Alexandre Rostovtsev]

On Mon, 2011-12-19 at 01:08 +0100, Ulrich Mueller wrote:
> [Why are there different Reply-To: headers in -dev and in -pms MLs?
> Following up to both lists.]

I apologize for the mess; I had intended to bring the question up before
a wider audience, but failed to think through the consequences of two
mailing lists ending up in the reply-to.

For the sake of keeping discussion in one thread, I ask that further
replies should be made to gentoo-dev, not gentoo-pms.

> How do you handle FEATURES="nodoc" if you spread the documentation all
> over the filesystem? Should Portage learn about all the special cases?
> IMHO it would make more sense to leave the documentation under
> /usr/share/doc and either configure the documentation viewer to find
> it there, or (if that's not possible) create symlinks.

It's not "all over the filesystem"; in practice, the number of locations
I believe is fairly small (/usr/share/gtk-doc and /usr/lib/monodoc for
API documentation, and /usr/share/help, /usr/share/omf,
and /usr/share/doc/HTML for end-user help files are the only ones that I
know of), and adding them to portage's nodoc list seems much easier than
editing hundreds of ebuilds that already install docs there.

Documentation in Gentoo-specific /usr/share/doc subdirectories would not
be able to link to documentation pages in other packages without
fragile, hard-to-maintain scripts - and even with the best scripts,
things would break on package renames. Symlinks could work, but (if the
nodoc situation is resolved) would give package maintainers extra work
for no real benefit.

> Can we please avoid the bloat of another directory level here?
> ${CATEGORY}/${PN} will be even longer than ${PF} in most cases.

The problem is that ($PN, $CATEGORY) pairs are not unique. Think of
x11-terms/terminal:0 and gnustep-apps/terminal:0, or app-misc/beagle:0
and sci-libs/beagle:0, or app-misc/nut:0 and sys-power/nut:0. I could
not think of any better solution than using $CATEGORY/$PN-$SLOT. Do you
have a better proposal that does not rely on $PVR?

> If we change our policy, then we should move everything to the new
> location (with a transition period of course). It would be very
> inconvenient for users if they had to search two different places
> for documentation.

If everything is to be moved to the new locations, we will need an
eclass-based solution to replace dodoc/dohtml for existing EAPIs.

-Alexandre.