1 |
I basically agree, it's quite a great idea. Just a few comments though. |
2 |
|
3 |
On Sun, 18 Dec 2011 16:49:38 -0500 |
4 |
Alexandre Rostovtsev <tetromino@g.o> wrote: |
5 |
|
6 |
> * The package's documentation may be designed primarily for tools and |
7 |
> viewers which expect to load documentation files from a different |
8 |
> location. |
9 |
|
10 |
That's why I, for instance, use gtk-doc in my libraries. It's just that |
11 |
it has its standard install procedures and locations. |
12 |
|
13 |
> 1. If a package's documentation is designed to be accessed by a |
14 |
> specific documentation viewer tool, then the package should install |
15 |
> the documentation in a location where that tool will look for it (e.g. |
16 |
> devhelp expects to find GNOME API documentation in |
17 |
> /usr/share/gtk-doc/html, and khelpcenter expects to find KDE handbooks |
18 |
> in /usr/share/doc/HTML). This already happens in practice, but some |
19 |
> devs had expressed opposition to this (e.g. bug #312363) because it |
20 |
> had not been formalized as policy. |
21 |
|
22 |
Agree. But that's outside of the GLEP/PMS scope; just an internal policy |
23 |
should fine, I think. |
24 |
|
25 |
> 2. In EAPI-5 and higher, other documentation should be installed under |
26 |
> /usr/share/doc: |
27 |
> a. if SLOT = "0": in /usr/share/doc/$CATEGORY/$PN by default, xor |
28 |
> (at the package maintainer's discretion) in |
29 |
> /usr/share/doc/$CATEGORY/$PN-0. |
30 |
|
31 |
I'd rather not see that -0 there. |
32 |
|
33 |
> b. if SLOT != "0": in /usr/share/doc/$CATEGORY/$PN-$SLOT. |
34 |
|
35 |
[...] |
36 |
|
37 |
> Q3: Why $PN-$SLOT instead of $PN:$SLOT? |
38 |
> A3: So that the directory names are compatible with bash's |
39 |
> tab-completion. |
40 |
|
41 |
What if 'foo' has slot named 'bar', and there is unslotted 'foo-bar' |
42 |
package? :P |
43 |
|
44 |
> Q5: Then why allow package maintainers to alternatively use |
45 |
> $CATEGORY/$PN-0? A5: Why not? It will not hurt anything, will not |
46 |
> cause file collisions, and some maintainers of a multislotted |
47 |
> package, one of which is 0, might prefer to install that slot's docs |
48 |
> in $CATEGORY/$PN-0 to prevent a potential impression that docs in |
49 |
> $CATEGORY/$PN apply to all of that package's slots. |
50 |
|
51 |
This will make the policy less clear, and documentation locations more |
52 |
enigmatic for users. While at this, I think we should somehow move |
53 |
the docs for all EAPIs to avoid this, and probably move installed ones |
54 |
as well. |
55 |
|
56 |
> Q6: Why can't the dodoc/dohtml path be changed before EAPI-5? |
57 |
> A6: Because the path where dodoc and dohtml install files is part of |
58 |
> the PMS. Portage can't just change it on its own. A possible |
59 |
> workaround for current EAPIs is adding new-style dodoc/dohtml |
60 |
> analogues to an eclass. |
61 |
|
62 |
I think some of devs agree we should be allowed to fix past mistakes |
63 |
without waiting another 20 years till the tree is migrated to a new |
64 |
EAPI... |
65 |
|
66 |
-- |
67 |
Best regards, |
68 |
Michał Górny |