1 |
At the moment, Gentoo documentation is supposed to be installed in |
2 |
/usr/share/doc/$PF. Given the existence of slots, this directory |
3 |
scheme makes little sense; versioning documentation directories with |
4 |
$PF seems nearly as silly as would be e.g. appending $PVR to the |
5 |
filenames of installed man pages. Moreover, /usr/share/doc/$PF results |
6 |
in a number of problems: |
7 |
|
8 |
* Since $PF changes on every revision bump and minor version change, |
9 |
one cannot bookmark a documentation file for a frequently updated |
10 |
package without using custom portage hooks or scripts that create |
11 |
stable symlinks to docs. |
12 |
* Since $PF changes on every revision bump and minor version change, |
13 |
it's unnecessarily inconvenient to see which documentation files were |
14 |
added or removed when upgrading a package. |
15 |
* The package's documentation may be designed primarily for tools and |
16 |
viewers which expect to load documentation files from a different |
17 |
location. |
18 |
|
19 |
I propose the following changes, and will write them up in GLEP form |
20 |
if the feedback is positive. |
21 |
|
22 |
1. If a package's documentation is designed to be accessed by a |
23 |
specific documentation viewer tool, then the package should install |
24 |
the documentation in a location where that tool will look for it (e.g. |
25 |
devhelp expects to find GNOME API documentation in |
26 |
/usr/share/gtk-doc/html, and khelpcenter expects to find KDE handbooks |
27 |
in /usr/share/doc/HTML). This already happens in practice, but some |
28 |
devs had expressed opposition to this (e.g. bug #312363) because it |
29 |
had not been formalized as policy. |
30 |
|
31 |
2. In EAPI-5 and higher, other documentation should be installed under |
32 |
/usr/share/doc: |
33 |
a. if SLOT = "0": in /usr/share/doc/$CATEGORY/$PN by default, xor |
34 |
(at the package maintainer's discretion) in |
35 |
/usr/share/doc/$CATEGORY/$PN-0. |
36 |
b. if SLOT != "0": in /usr/share/doc/$CATEGORY/$PN-$SLOT. |
37 |
|
38 |
3. In EAPI-5 and higher, dodoc/newdoc/dohtml will install documentation in: |
39 |
a. If SLOT = "0": /usr/share/doc/$CATEGORY/$PN/<docinto path> |
40 |
(/usr/share/doc/$CATEGORY/$PN/html for dohtml); |
41 |
b. If SLOT != "0": /usr/share/doc/$CATEGORY/$PN-$SLOT/<docinto |
42 |
path> (/usr/share/doc/$CATEGORY/$PN-$SLOT/html for dohtml). |
43 |
Corresponding changes will also have to be made to docompress, and |
44 |
to the eclasses that currently use /usr/share/doc/${PF} as docdir. |
45 |
|
46 |
4. In EAPI-0,1,2,3,4, ebuilds may, at the maintainer's discretion, |
47 |
install documentation in the old /usr/share/doc/$PF location xor in |
48 |
the new EAPI-5 location. |
49 |
|
50 |
Answers to anticipated questions: |
51 |
|
52 |
Q1: Why let docs designed to be viewed with special viewers be |
53 |
installed outside /usr/share/doc? |
54 |
A1: To match upstream expectations and to minimize maintenance burden. |
55 |
This burden can be significant; for example, if documentation for |
56 |
package A contains explicit links to documentation pages for package |
57 |
B, then if the documentation pages are not installed where upstream |
58 |
expects them, those links would have to be adjusted, probably via a |
59 |
fragile script with untested corner cases. |
60 |
|
61 |
Q2: Why /usr/share/doc/$CATEGORY/$PN-$SLOT instead of /usr/share/doc/$PN-$SLOT? |
62 |
A2: To prevent file collisions between packages in different |
63 |
categories but with identical package and slot names. |
64 |
|
65 |
Q3: Why $PN-$SLOT instead of $PN:$SLOT? |
66 |
A3: So that the directory names are compatible with bash's tab-completion. |
67 |
|
68 |
Q4: Why install slot 0 docs in $CATEGORY/$PN by default instead of |
69 |
$CATEGORY/$PN-0? |
70 |
A4: Purely for aesthetics. A vast number of packages in the main tree |
71 |
are only slot 0 and are unlikely to ever become slotted in the future, |
72 |
so installing their docs in /usr/share/doc/$CATEGORY/$PN is logical, |
73 |
pleasing to the eye, and results in shorter directory names. |
74 |
|
75 |
Q5: Then why allow package maintainers to alternatively use $CATEGORY/$PN-0? |
76 |
A5: Why not? It will not hurt anything, will not cause file |
77 |
collisions, and some maintainers of a multislotted package, one of |
78 |
which is 0, might prefer to install that slot's docs in |
79 |
$CATEGORY/$PN-0 to prevent a potential impression that docs in |
80 |
$CATEGORY/$PN apply to all of that package's slots. |
81 |
|
82 |
Q6: Why can't the dodoc/dohtml path be changed before EAPI-5? |
83 |
A6: Because the path where dodoc and dohtml install files is part of |
84 |
the PMS. Portage can't just change it on its own. A possible |
85 |
workaround for current EAPIs is adding new-style dodoc/dohtml |
86 |
analogues to an eclass. |
87 |
|
88 |
Q7: Why allow package maintainers to start using the new naming scheme |
89 |
in earlier EAPIs? |
90 |
A7: Because /usr/share/doc/$PF really is quite inconvenient for users |
91 |
wanting to browse API documentation, and package maintainers may wish |
92 |
to alleviate the users' pain before the EAPI-5 becomes finalized and |
93 |
support for it is added to the eclasses that the ebuild needs. |
94 |
|
95 |
-Alexandre. |