Re: [gentoo-dev] doc categories

[Tod M. Neidt]

On Tue, 2002-01-08 at 19:09, Aron Griffis wrote:
> tvon@×××××.org wrote:	[Tue Jan 08 2002, 06:41:58PM EST]
> > Speaking of which (which being docs for packages), is there any
> > validity to having a USE for 'docs' which determines weather or not
> > varios package docs are built along with the package they go with?
>
> This sounds like a really good idea to me.
>
Hi!

I have been thinking about this also. My thoughts.

Possible USE variables: dochtml, docpdf, docinfo
Most Gnu packages have all the documetation in the package tarball and
allow you to build to a variety of formats.  I personally prefer html
for reading locally in a browser.  Other people may want info for in
console and emacs and others pdf for printing.  Building pdf
documentation from source would require a PAPER environmental variable
to set the users preference, i.e. letter, A4, etc.  Most (but not all)
Linux Documentation Project stuff is available in sgml so it can be
built to preference also.  I have played around with this for some gnu
packages and python.  (Unfortunately, I have never been able to build
the python documentation from the source tarball)

Advantages:

1. fewer megabytes downloaded (especially nice for those on dial-up)
2. fewer megabytes archived on ibiblio
3. fewer doc ebuilds required in app-doc
4. user flexibility

Disadvantages:

1. added size and complication of ebuilds.
2. not all packages include extensive documentation (manuals, tutorials,
etc) in the source tarball or if they do, include prebuilt html and/or
pdf but not necessarily both. How to handle case where docpdf is set,
but only html is available.
3. program may build ok, but buggy documentation build could cause the
merge to fail.

tod