Gentoo Archives: gentoo-dev

From: Alexandre Rostovtsev <tetromino@g.o>
To: gentoo-dev@l.g.o
Subject: Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF
Date: Mon, 19 Dec 2011 01:53:33
Message-Id: 1324259574.12311.86.camel@rook
In Reply to: Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF by Ulrich Mueller
1 On Mon, 2011-12-19 at 01:08 +0100, Ulrich Mueller wrote:
2 > [Why are there different Reply-To: headers in -dev and in -pms MLs?
3 > Following up to both lists.]
5 I apologize for the mess; I had intended to bring the question up before
6 a wider audience, but failed to think through the consequences of two
7 mailing lists ending up in the reply-to.
9 For the sake of keeping discussion in one thread, I ask that further
10 replies should be made to gentoo-dev, not gentoo-pms.
12 > How do you handle FEATURES="nodoc" if you spread the documentation all
13 > over the filesystem? Should Portage learn about all the special cases?
14 > IMHO it would make more sense to leave the documentation under
15 > /usr/share/doc and either configure the documentation viewer to find
16 > it there, or (if that's not possible) create symlinks.
18 It's not "all over the filesystem"; in practice, the number of locations
19 I believe is fairly small (/usr/share/gtk-doc and /usr/lib/monodoc for
20 API documentation, and /usr/share/help, /usr/share/omf,
21 and /usr/share/doc/HTML for end-user help files are the only ones that I
22 know of), and adding them to portage's nodoc list seems much easier than
23 editing hundreds of ebuilds that already install docs there.
25 Documentation in Gentoo-specific /usr/share/doc subdirectories would not
26 be able to link to documentation pages in other packages without
27 fragile, hard-to-maintain scripts - and even with the best scripts,
28 things would break on package renames. Symlinks could work, but (if the
29 nodoc situation is resolved) would give package maintainers extra work
30 for no real benefit.
32 > Can we please avoid the bloat of another directory level here?
33 > ${CATEGORY}/${PN} will be even longer than ${PF} in most cases.
35 The problem is that ($PN, $CATEGORY) pairs are not unique. Think of
36 x11-terms/terminal:0 and gnustep-apps/terminal:0, or app-misc/beagle:0
37 and sci-libs/beagle:0, or app-misc/nut:0 and sys-power/nut:0. I could
38 not think of any better solution than using $CATEGORY/$PN-$SLOT. Do you
39 have a better proposal that does not rely on $PVR?
41 > If we change our policy, then we should move everything to the new
42 > location (with a transition period of course). It would be very
43 > inconvenient for users if they had to search two different places
44 > for documentation.
46 If everything is to be moved to the new locations, we will need an
47 eclass-based solution to replace dodoc/dohtml for existing EAPIs.
49 -Alexandre.


Subject Author
Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF Ulrich Mueller <ulm@g.o>
Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF Maciej Mrozowski <reavertm@×××××.com>