| 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 |
Archives