1 |
[Why are there different Reply-To: headers in -dev and in -pms MLs? |
2 |
Following up to both lists.] |
3 |
|
4 |
>>>>> On Sun, 18 Dec 2011, Alexandre Rostovtsev wrote: |
5 |
|
6 |
> At the moment, Gentoo documentation is supposed to be installed in |
7 |
> /usr/share/doc/$PF. [...] |
8 |
|
9 |
> I propose the following changes, and will write them up in GLEP form |
10 |
> if the feedback is positive. |
11 |
|
12 |
> 1. If a package's documentation is designed to be accessed by a |
13 |
> specific documentation viewer tool, then the package should install |
14 |
> the documentation in a location where that tool will look for it |
15 |
> (e.g. devhelp expects to find GNOME API documentation in |
16 |
> /usr/share/gtk-doc/html, and khelpcenter expects to find KDE |
17 |
> handbooks in /usr/share/doc/HTML). This already happens in practice, |
18 |
> but some devs had expressed opposition to this (e.g. bug #312363) |
19 |
> because it had not been formalized as policy. |
20 |
|
21 |
How do you handle FEATURES="nodoc" if you spread the documentation all |
22 |
over the filesystem? Should Portage learn about all the special cases? |
23 |
IMHO it would make more sense to leave the documentation under |
24 |
/usr/share/doc and either configure the documentation viewer to find |
25 |
it there, or (if that's not possible) create symlinks. |
26 |
|
27 |
> 2. In EAPI-5 and higher, other documentation should be installed |
28 |
> under /usr/share/doc: |
29 |
> a. if SLOT = "0": in /usr/share/doc/$CATEGORY/$PN by default, xor |
30 |
> (at the package maintainer's discretion) in |
31 |
> /usr/share/doc/$CATEGORY/$PN-0. |
32 |
> b. if SLOT != "0": in /usr/share/doc/$CATEGORY/$PN-$SLOT. |
33 |
|
34 |
Can we please avoid the bloat of another directory level here? |
35 |
${CATEGORY}/${PN} will be even longer than ${PF} in most cases. |
36 |
|
37 |
Or, to say it in your own words: "${CATEGORY}/${PN} seems nearly as |
38 |
silly as would be e.g. prepending ${CATEGORY} to the filenames of |
39 |
installed man pages." ;-) |
40 |
|
41 |
> [...] |
42 |
|
43 |
> 4. In EAPI-0,1,2,3,4, ebuilds may, at the maintainer's discretion, |
44 |
> install documentation in the old /usr/share/doc/$PF location xor in |
45 |
> the new EAPI-5 location. |
46 |
|
47 |
If we change our policy, then we should move everything to the new |
48 |
location (with a transition period of course). It would be very |
49 |
inconvenient for users if they had to search two different places |
50 |
for documentation. |
51 |
|
52 |
Ulrich |