From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 15025 invoked by uid 1002); 12 Jul 2003 10:25:12 -0000 Mailing-List: contact gentoo-dev-help@gentoo.org; run by ezmlm Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@gentoo.org Received: (qmail 16452 invoked from network); 12 Jul 2003 10:25:12 -0000 Date: Sat, 12 Jul 2003 12:25:08 +0200 From: Spider To: gentoo-dev@gentoo.org Message-Id: <20030712122508.33796f7d.spider@gentoo.org> In-Reply-To: <1057999358.30632.25.camel@mcvaio.liquidx.net> References: <1057999358.30632.25.camel@mcvaio.liquidx.net> Organization: Chaotic X-Mailer: Sylpheed version 0.9.3 (GTK+ 1.2.10; i686-pc-linux-gnu) Mime-Version: 1.0 Content-Type: multipart/signed; protocol="application/pgp-signature"; micalg="pgp-sha1"; boundary="=.cS'ie5rf1TdeTI" Subject: Re: [gentoo-dev] *-doc vs USE="doc" X-Archives-Salt: 45bb35f6-3c5a-4055-8295-c0d064ad6763 X-Archives-Hash: 4b3853466eadd0d602d51e9d5b204c1c --=.cS'ie5rf1TdeTI Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit begin quote On 12 Jul 2003 09:42:39 +0100 Alastair Tse wrote: > 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: > 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. Well, this is an no-issue issue, from the beginning doc was used to differentiate wether to build the (costly, dependencywise and timewise) .ps, pdf. html and other versions of documentation from the original templates, actions which required jade, tetex and a lot of cpupower, or wether to just install the basic pregenerated documentation. This too goes for source-included things like gtk-doc (library documentation) So, any case that uses "doc" to differentiate manpages or general > 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. Actually, helpfiles -should- be installed for all applications, and should definitely not be protected by the USE="doc" statement, as to remove helpfiles or basic package documentation is to cripple a package, which we should not do to a user. (if they want their packages crippled they can tell cron to rm -rf /usr/share/doc/* ) To separate devleoper-documentation is a common thing to do, since API's tend to change less frequently, so for say java 1.2.* could well use the documentation from any java-1.2 standard + some errata I'd suggest marking all packages that separate end-user documentation with USE="doc" are flawed and should be fixed. All those who have extra developer-centric documentation (api, examples and so on) could well have them separated in RDEPEND="doc? (${PN}-api-documentation )" > 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 This isn't separated but an individual package, pulled in by the gnome metapackage. //Spider -- begin .signature This is a .signature virus! Please copy me into your .signature! See Microsoft KB Article Q265230 for more information. end --=.cS'ie5rf1TdeTI Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.2 (GNU/Linux) iD8DBQE/D+IGZS9CZTi033kRAhYdAKCP8eUhgb0M5vpJuHOIGxDpxhGCdACfWsQq iWfdMNVRqUObZCk0UfKeGog= =QiNR -----END PGP SIGNATURE----- --=.cS'ie5rf1TdeTI--