[gentoo-dev] *-doc vs USE="doc"

[Alastair Tse <liquidx@gentoo.org>]

[-- Attachment #1: Type: text/plain, Size: 2373 bytes --]

Hi,

I've noticed that there are a couple of *-docs packages[1] in the
portage tree. These are usually either developer documentation or user
documentation. 

I also note that we have a "doc" useflag with the definition:

doc - Adds extra documentation (API, Javadoc, etc)

So how should we include documentation with packages? There seems to be
three schools of thoughts:

1. Include the documentation inside the same package protected by the
"doc" USE flag. 

2. Separate out the documentation into its own package (eg.
"python-docs") and make the user install the documentation themselves.

3. Separate out the documentation into its own package and make the
parent package RDEPEND or PDEPEND the documentation package using the
"doc" USE flag. 

So how do we currently handle including documentation and why? 

I believe we should handle documentation installation uniformly
portage-wide. I would like to see some discussion into how we should
handle this situation and what exceptions there are. 

Also, it seems to me that the "doc" USE flag is too encompassing. It is
used for both installing user documentation (user guides, application
user help) and also to install developer documentation (APIs,
programming tutorials, Javadoc, etc). I think we should have a "devdoc"
USE flag to differentiate between the two.

For instance, as a user, if I want to install help for all my
applications, I would put "doc" in my USE flags. But this means it will
pull in developer documentation from supporting libraries which I don't
know, use or care about. By differentiating between the two, then
developers can get their documentation nicely installed along with their
packages, and also users will get less cruft and more useful
documentation if they have the "doc" USE flag enabled.

Any comments?

Cheers,

Alastair

.. [1] Current -docs packages in portage
app-doc/php-docs
app-doc/qt-docs
app-doc/root-docs
dev-db/firebird-docs
dev-java/java-sdk.docs
dev-python/Cheetah-docs
dev-python/python-docs
dev-python/wxpython-docs
gnome-extra/gnome2-user-docs


-- 
Alastair 'liquidx' Tse
 >> Gentoo Developer 
 >> http://www.liquidx.net/ | http://dev.gentoo.org/~liquidx/
 >> GPG Key : http://dev.gentoo.org/~liquidx/liquidx_gentoo_org.asc
 >> FingerPrint : 579A 9B0E 43E8 0E40 EE93  BB1C 38CE 1C7B 3907 14F6

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]