On L, 2007-06-23 at 15:57 +0100, Ciaran McCreesh wrote: > On Sat, 23 Jun 2007 17:45:02 +0300 > Petteri Räty <[EMAIL PROTECTED]> 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. > > > > Yep but we should for example document what constitues increased disk > > usage. How about "several megabytes or tens of files"? > > 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="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. -- Mart Raudsepp Gentoo Developer Mail: [EMAIL PROTECTED] Weblog: http://planet.gentoo.org/developers/leio
signature.asc
Description: This is a digitally signed message part
