From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from lists.gentoo.org ([140.105.134.102] helo=robin.gentoo.org) by nuthatch.gentoo.org with esmtp (Exim 4.62) (envelope-from ) id 1I28WL-0005IB-D4 for garchives@archives.gentoo.org; Sat, 23 Jun 2007 16:31:33 +0000 Received: from robin.gentoo.org (localhost [127.0.0.1]) by robin.gentoo.org (8.14.0/8.14.0) with SMTP id l5NGUMr9007274; Sat, 23 Jun 2007 16:30:37 GMT Received: from smtp-out.neti.ee (smtp-out.neti.ee [194.126.126.41]) by robin.gentoo.org (8.14.0/8.14.0) with ESMTP id l5NGSXqM004955 for ; Sat, 23 Jun 2007 16:28:33 GMT Received: from localhost (localhost [127.0.0.1]) by MXR-5.estpak.ee (Postfix) with ESMTP id 4F2531D3F77 for ; Sat, 23 Jun 2007 19:28:32 +0300 (EEST) X-Virus-Scanned: by amavisd-new-2.4.3 (20060930) (Debian) at neti.ee Received: from smtp-out.neti.ee ([127.0.0.1]) by localhost (MXR-2.estpak.ee [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 535x-U0hi5Xo for ; Sat, 23 Jun 2007 19:28:27 +0300 (EEST) Received: from Relayhost2.neti.ee (Relayhost2 [88.196.174.142]) by MXR-5.estpak.ee (Postfix) with ESMTP id 3B6831D5017 for ; Sat, 23 Jun 2007 19:28:27 +0300 (EEST) Subject: Re: [gentoo-dev] RFC: Unifying the behavior of the doc use flag and document it From: Mart Raudsepp To: gentoo-dev@lists.gentoo.org In-Reply-To: <20070623155739.47099922@snowflake> References: <467D2A04.6080504@gentoo.org> <20070623151917.35bd2b01@snowflake> <467D31EE.4030109@gentoo.org> <20070623155739.47099922@snowflake> Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="=-qNwjayQD/G3HT4KwcOAW" Date: Sat, 23 Jun 2007 19:27:16 +0300 Message-Id: <1182616036.26111.36.camel@localhost> Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@gentoo.org Reply-to: gentoo-dev@lists.gentoo.org Mime-Version: 1.0 X-Mailer: Evolution 2.10.1 X-Archives-Salt: f71bb30f-2297-44f2-8fb1-cd4bea0e57c7 X-Archives-Hash: b3a74b872c2cf771a8d7c674d3b6c2a6 --=-qNwjayQD/G3HT4KwcOAW Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable On L, 2007-06-23 at 15:57 +0100, Ciaran McCreesh wrote: > On Sat, 23 Jun 2007 17:45:02 +0300 > Petteri R=E4ty wrote: > > > The doc use flag is used where there is a reason to make > > > documentation optional rather than mandatory. Examples of such > > > reasons include increased dependencies (e.g. Doxygen, which pulls > > > in a fair bit), Rebuilding of gtk-doc driven documentation means a gtk-doc dep and in turn a big bunch of xslt and xml and other doc building stuff. > increased build time (e.g. Doxygen, which can be > > > frickin' slow) gtk+ documentation rebuilding can take as much as 30 to 60 minutes with the doc USE flag for example. The benefit is cross references to glib, pango and cairo documentation - upstream can not do that as they do not know where the other docs will be found on disk. Though I should see if they can not use relative paths somehow.. On the other hand the release tarballs already include a prebuilt documentation, that is mostly API docs, but also chapters like 'running gtk+ applications' > or substantially increased disk usage. $ du -hs /usr/share/gtk-doc/html/ 72M /usr/share/gtk-doc/html/ $ ls /usr/share/gtk-doc/html/ |wc -l 76 Less than a megabyte per package in average. gtk+ and pygtk docs are over 10MB and might warrant a reconsideration of doc installation, but the rest are all less than 3MB, mostly less than a megabyte and 675KB in average. I would say there is no reason to not install documentation for other packages than gtk+ and pygtk. Even if gtk+ and pygtk docs are always installed it's not very bad. > If there's no > > > substantial cost to documentation, it should always be installed As dang pointed out further on IRC, doc USE flag also takes care of not depending on a big bunch of extra dependencies. Additionally the doc USE flag means 'extra' documentation in the sense of extra value for the docs. It also means substantially longer build times with the doc USE flag, which seems to be often the practice of when the doc USE flag is used by a package - substantial time cost. > >=20 > > Yep but we should for example document what constitues increased disk > > usage. How about "several megabytes or tens of files"? >=20 > It's a package dependent quantity, and should be left up to individual > maintainers. Vim's documentation, for example, is a lot of files and a > lot of disk space, but it isn't shipped via USE=3D"doc" because it's > considered by upstream to be a vital part of the package. Regarding ungeneralizing the doc USE flag: For gnome that would probably mean just using apidoc instead of doc across the board, as it is taken care of by the eclass right now for all gnome packages, plus gtk-doc docs are almost all for API docs. If we need to make doc installation optional, it will mean another extra USE flag for all gnome packages, as I see it as some want to rebuild the docs, and some do not see the extra value to outweight the much bigger build times. What if we made the biggest docs optional but keep all the remaining gtk-docs installed always, filterable by INSTALL_MASK, as they are typically less than a megabyte? Though a gentoo-wide ungeneralizing of doc USE flag doesn't sound bad indeed. --=20 Mart Raudsepp Gentoo Developer Mail: leio@gentoo.org Weblog: http://planet.gentoo.org/developers/leio --=-qNwjayQD/G3HT4KwcOAW Content-Type: application/pgp-signature; name=signature.asc Content-Description: This is a digitally signed message part -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.4 (GNU/Linux) iD8DBQBGfUnkkeYb6olFHJcRAlYpAKCrOL7+D7uyhu2TAUPT4kylAOEx6wCfah4I Pk5JMoIAq/NQ5AIysi/yOBA= =vYXR -----END PGP SIGNATURE----- --=-qNwjayQD/G3HT4KwcOAW-- -- gentoo-dev@gentoo.org mailing list