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

[Ulrich Mueller <ulm@gentoo.org>]

[Why are there different Reply-To: headers in -dev and in -pms MLs?
Following up to both lists.]

>>>>> On Sun, 18 Dec 2011, Alexandre Rostovtsev wrote:

> At the moment, Gentoo documentation is supposed to be installed in
> /usr/share/doc/$PF. [...]

> I propose the following changes, and will write them up in GLEP form
> if the feedback is positive.

> 1. If a package's documentation is designed to be accessed by a
> specific documentation viewer tool, then the package should install
> the documentation in a location where that tool will look for it
> (e.g. devhelp expects to find GNOME API documentation in
> /usr/share/gtk-doc/html, and khelpcenter expects to find KDE
> handbooks in /usr/share/doc/HTML). This already happens in practice,
> but some devs had expressed opposition to this (e.g. bug #312363)
> because it had not been formalized as policy.

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.

> 2. In EAPI-5 and higher, other documentation should be installed
> under /usr/share/doc:
>    a. if SLOT = "0": in /usr/share/doc/$CATEGORY/$PN by default, xor
> (at the package maintainer's discretion) in
> /usr/share/doc/$CATEGORY/$PN-0.
>    b. if SLOT != "0": in /usr/share/doc/$CATEGORY/$PN-$SLOT.

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

Or, to say it in your own words: "${CATEGORY}/${PN} seems nearly as
silly as would be e.g. prepending ${CATEGORY} to the filenames of
installed man pages." ;-)

> [...]

> 4. In EAPI-0,1,2,3,4, ebuilds may, at the maintainer's discretion,
> install documentation in the old /usr/share/doc/$PF location xor in
> the new EAPI-5 location.

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.

Ulrich