Gentoo Logo
Gentoo Spaceship

Note: Due to technical difficulties, the Archives are currently not up to date. GMANE provides an alternative service for most mailing lists.
c.f. bug 424647
List Archive: gentoo-pms
Lists: gentoo-pms: < Prev By Thread Next > < Prev By Date Next >
To: gentoo-dev@g.o, gentoo-pms@g.o
From: Ulrich Mueller <ulm@g.o>
Subject: Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF
Date: Mon, 19 Dec 2011 01:08:26 +0100
[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.


Re: Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF
-- Alexandre Rostovtsev
RFC: deprecate /usr/share/doc/$PF
-- Alexandre Rostovtsev
Lists: gentoo-pms: < Prev By Thread Next > < Prev By Date Next >
Previous by thread:
Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF
Next by thread:
Re: Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF
Previous by date:
Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF
Next by date:
Re: Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF

Updated Jul 18, 2012

Summary: Archive of the gentoo-pms mailing list.

Donate to support our development efforts.

Copyright 2001-2013 Gentoo Foundation, Inc. Questions, Comments? Contact us.