Re: [gentoo-dev] RFC: Unifying the behavior of the doc use flag and document it
Mart Raudsepp wrote: 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.. You might consider moving these docs to a separate package aimed at people developing using GTK+. gtk+ would then not install these documents at all. We did something similar with kernel docs (see sys-kernel/linux-docs) and there have been no complaints so far. Daniel -- [EMAIL PROTECTED] mailing list
Re: [gentoo-dev] RFC: Unifying the behavior of the doc use flag and document it
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
Re: [gentoo-dev] RFC: Unifying the behavior of the doc use flag and document it
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), increased build time (e.g. Doxygen, which can be > > frickin' slow) or substantially increased disk usage. If there's no > > substantial cost to documentation, it should always be installed. > > > > 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. -- Ciaran McCreesh signature.asc Description: PGP signature
Re: [gentoo-dev] RFC: Unifying the behavior of the doc use flag and document it
Ciaran McCreesh kirjoitti: > On Sat, 23 Jun 2007 17:11:16 +0300 > Petteri Räty <[EMAIL PROTECTED]> wrote: >> My opinion is to make it clear that the doc use flag always controls >> whether or not to install documentation and make it clear in the >> devmanual. > > 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), > increased build time (e.g. Doxygen, which can be frickin' slow) or > substantially increased disk usage. If there's no substantial cost to > documentation, it should always be installed. > Yep but we should for example document what constitues increased disk usage. How about "several megabytes or tens of files"? Regards, Petteri signature.asc Description: OpenPGP digital signature
Re: [gentoo-dev] RFC: Unifying the behavior of the doc use flag and document it
On Sat, 23 Jun 2007 17:11:16 +0300 Petteri Räty <[EMAIL PROTECTED]> wrote: > My opinion is to make it clear that the doc use flag always controls > whether or not to install documentation and make it clear in the > devmanual. 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), increased build time (e.g. Doxygen, which can be frickin' slow) or substantially increased disk usage. If there's no substantial cost to documentation, it should always be installed. -- Ciaran McCreesh signature.asc Description: PGP signature
Re: [gentoo-dev] RFC: Unifying the behavior of the doc use flag and document it
Marius Mauch kirjoitti: > On Sat, 23 Jun 2007 17:11:16 +0300 > Petteri Räty <[EMAIL PROTECTED]> wrote: > >> My opinion is to make it clear that the doc use flag always controls >> whether or not to install documentation and make it clear in the >> devmanual. For what gnome does, they can then add for example a >> gtk-doc use flag to control the building of the cross references and >> have the doc use flag control the installation of the bundled >> documentation. >> >> [EMAIL PROTECTED] ~ $ euse -i doc >> global use flags (searching: doc) >> >> [-] doc - Adds extra documentation (API, Javadoc, etc) >> >> INSTALL_MASK is of course a solution to not installing gtk-doc at all >> but it doesn't give me the ability to install it only for individual >> packages. >> >> What do others think? > > Maybe the flag needs to be renamed/split up to clarify it's meaning, > it's too generic in it's current form (many people enable it blindly and > don't really have any clue what the result is). > Like using USE=apidoc for API documentation, USE=extradoc for extra > user documentation (controlling PDF generation and stuff like that), > USE=rebuild-docs to replace pregenerated documentation with > updated/regenerated versions (like the gtk-doc issue), and so on (don't > know what other use cases there are for USE=doc currently). > > It's a large change, but USE=doc has been a significant problem for > quite a while already (circular deps anyone?) > That does sound like a good idea. Regards, Petteri signature.asc Description: OpenPGP digital signature
Re: [gentoo-dev] RFC: Unifying the behavior of the doc use flag and document it
On Sat, 23 Jun 2007 17:11:16 +0300 Petteri Räty <[EMAIL PROTECTED]> wrote: > My opinion is to make it clear that the doc use flag always controls > whether or not to install documentation and make it clear in the > devmanual. For what gnome does, they can then add for example a > gtk-doc use flag to control the building of the cross references and > have the doc use flag control the installation of the bundled > documentation. > > [EMAIL PROTECTED] ~ $ euse -i doc > global use flags (searching: doc) > > [-] doc - Adds extra documentation (API, Javadoc, etc) > > INSTALL_MASK is of course a solution to not installing gtk-doc at all > but it doesn't give me the ability to install it only for individual > packages. > > What do others think? Maybe the flag needs to be renamed/split up to clarify it's meaning, it's too generic in it's current form (many people enable it blindly and don't really have any clue what the result is). Like using USE=apidoc for API documentation, USE=extradoc for extra user documentation (controlling PDF generation and stuff like that), USE=rebuild-docs to replace pregenerated documentation with updated/regenerated versions (like the gtk-doc issue), and so on (don't know what other use cases there are for USE=doc currently). It's a large change, but USE=doc has been a significant problem for quite a while already (circular deps anyone?) Marius -- Public Key at http://www.genone.de/info/gpg-key.pub In the beginning, there was nothing. And God said, 'Let there be Light.' And there was still nothing, but you could see a bit better. signature.asc Description: PGP signature
[gentoo-dev] RFC: Unifying the behavior of the doc use flag and document it
For example the gnome people use the doc use flag to control whether gtk-doc gets rebuild using cross references: 16:51 <@leio> as far as I'm concerned the doc USE flag means rebuilding documentation to get cross-referencing in docs working 16:51 <@leio> also the lack of doc USE flag does not mean to not install documentation 16:52 <@leio> it means to not take a long time to build documentation, and we are not doing it if doc USE flag is not present This leads to having tons of gtk-doc installed: [EMAIL PROTECTED] ~ $ du -sh /usr/share/gtk-doc/html/ 51M /usr/share/gtk-doc/html/ In for example Java we use it to control Javadoc installation. Javadoc generation rarely takes much time and needs no extra dependencies but having Javadocs for everything would consume a lot of space. My opinion is to make it clear that the doc use flag always controls whether or not to install documentation and make it clear in the devmanual. For what gnome does, they can then add for example a gtk-doc use flag to control the building of the cross references and have the doc use flag control the installation of the bundled documentation. [EMAIL PROTECTED] ~ $ euse -i doc global use flags (searching: doc) [-] doc - Adds extra documentation (API, Javadoc, etc) INSTALL_MASK is of course a solution to not installing gtk-doc at all but it doesn't give me the ability to install it only for individual packages. What do others think? Regards, Petteri signature.asc Description: OpenPGP digital signature
