1 |
Hi, |
2 |
|
3 |
I've noticed that there are a couple of *-docs packages[1] in the |
4 |
portage tree. These are usually either developer documentation or user |
5 |
documentation. |
6 |
|
7 |
I also note that we have a "doc" useflag with the definition: |
8 |
|
9 |
doc - Adds extra documentation (API, Javadoc, etc) |
10 |
|
11 |
So how should we include documentation with packages? There seems to be |
12 |
three schools of thoughts: |
13 |
|
14 |
1. Include the documentation inside the same package protected by the |
15 |
"doc" USE flag. |
16 |
|
17 |
2. Separate out the documentation into its own package (eg. |
18 |
"python-docs") and make the user install the documentation themselves. |
19 |
|
20 |
3. Separate out the documentation into its own package and make the |
21 |
parent package RDEPEND or PDEPEND the documentation package using the |
22 |
"doc" USE flag. |
23 |
|
24 |
So how do we currently handle including documentation and why? |
25 |
|
26 |
I believe we should handle documentation installation uniformly |
27 |
portage-wide. I would like to see some discussion into how we should |
28 |
handle this situation and what exceptions there are. |
29 |
|
30 |
Also, it seems to me that the "doc" USE flag is too encompassing. It is |
31 |
used for both installing user documentation (user guides, application |
32 |
user help) and also to install developer documentation (APIs, |
33 |
programming tutorials, Javadoc, etc). I think we should have a "devdoc" |
34 |
USE flag to differentiate between the two. |
35 |
|
36 |
For instance, as a user, if I want to install help for all my |
37 |
applications, I would put "doc" in my USE flags. But this means it will |
38 |
pull in developer documentation from supporting libraries which I don't |
39 |
know, use or care about. By differentiating between the two, then |
40 |
developers can get their documentation nicely installed along with their |
41 |
packages, and also users will get less cruft and more useful |
42 |
documentation if they have the "doc" USE flag enabled. |
43 |
|
44 |
Any comments? |
45 |
|
46 |
Cheers, |
47 |
|
48 |
Alastair |
49 |
|
50 |
.. [1] Current -docs packages in portage |
51 |
app-doc/php-docs |
52 |
app-doc/qt-docs |
53 |
app-doc/root-docs |
54 |
dev-db/firebird-docs |
55 |
dev-java/java-sdk.docs |
56 |
dev-python/Cheetah-docs |
57 |
dev-python/python-docs |
58 |
dev-python/wxpython-docs |
59 |
gnome-extra/gnome2-user-docs |
60 |
|
61 |
|
62 |
-- |
63 |
Alastair 'liquidx' Tse |
64 |
>> Gentoo Developer |
65 |
>> http://www.liquidx.net/ | http://dev.gentoo.org/~liquidx/ |
66 |
>> GPG Key : http://dev.gentoo.org/~liquidx/liquidx_gentoo_org.asc |
67 |
>> FingerPrint : 579A 9B0E 43E8 0E40 EE93 BB1C 38CE 1C7B 3907 14F6 |