Gentoo Archives: gentoo-dev

From: Alastair Tse <liquidx@g.o>
To: gentoo-dev@g.o
Subject: [gentoo-dev] *-doc vs USE="doc"
Date: Sat, 12 Jul 2003 08:43:44
1 Hi,
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.
7 I also note that we have a "doc" useflag with the definition:
9 doc - Adds extra documentation (API, Javadoc, etc)
11 So how should we include documentation with packages? There seems to be
12 three schools of thoughts:
14 1. Include the documentation inside the same package protected by the
15 "doc" USE flag.
17 2. Separate out the documentation into its own package (eg.
18 "python-docs") and make the user install the documentation themselves.
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.
24 So how do we currently handle including documentation and why?
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.
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.
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.
44 Any comments?
46 Cheers,
48 Alastair
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/
56 dev-python/Cheetah-docs
57 dev-python/python-docs
58 dev-python/wxpython-docs
59 gnome-extra/gnome2-user-docs
62 --
63 Alastair 'liquidx' Tse
64 >> Gentoo Developer
65 >> |
66 >> GPG Key :
67 >> FingerPrint : 579A 9B0E 43E8 0E40 EE93 BB1C 38CE 1C7B 3907 14F6


File name MIME type
signature.asc application/pgp-signature


Subject Author
Re: [gentoo-dev] *-doc vs USE="doc" Spider <spider@g.o>
Re: [gentoo-dev] *-doc vs USE="doc" Mamoru KOMACHI <usata@g.o>