Gentoo Archives: gentoo-dev

From: Ulrich Mueller <ulm@g.o>
To: gentoo-dev@l.g.o, gentoo-pms@l.g.o
Subject: Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF
Date: Mon, 19 Dec 2011 00:09:43
Message-Id: 20206.32890.171045.50686@a1i15.kph.uni-mainz.de
In Reply to: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF by Alexandre Rostovtsev
[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

Replies

Subject Author
Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF Alexandre Rostovtsev <tetromino@g.o>