Re: [gentoo-dev] RFC: Unifying the behavior of the doc use flag and document it

[Mart Raudsepp]

On L, 2007-06-23 at 15:57 +0100, Ciaran McCreesh wrote:
> On Sat, 23 Jun 2007 17:45:02 +0300
> Petteri Räty <betelgeuse@g.o> 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: leio@g.o
Weblog: http://planet.gentoo.org/developers/leio