Mailing List Archive

On 25/04/06, Jakub Moc <jakub@gentoo.org> wrote:
> Hello here,
>
> I'd like to see some clarification of intended doc use flag usage, so
> that we wouldn't force users to download/install 40+ megs of docs for a
> ~3 meg package, with the only reason being that USE=doc is for developer
> documentation only. [1]

The handbook states that "doc" is for package documentation. I've
never heard of it being restricted to developer docs only, and if
that's true, there are many packages which break that policy.

As I always understood it, "doc" is there for all optional
documentation such as manuals, APIs etc. Non-optional documentation
would be things like online docs accessible from within the program
(eg. "help" menu items for gui apps), which if missing generate
run-time errors.

--
gentoo-dev@gentoo.org mailing list

On Tue, 25 Apr 2006 20:03:00 +0200
Jakub Moc <jakub@gentoo.org> wrote:

> I'd like to see some clarification of intended doc use flag usage

From what I've gleaned over time, USE=doc is supposed to enable docs
that are one or more of:

(1) large
(2) take a significant amount of resource to build
(3) cause extra deps

(2) and (3) are usually co-incident.

IMHO, of course ;)

Whatever we decide USE=doc means, it should be documented as such in
use.desc

--
Kevin F. Quinn

Jakub Moc posted <444E6454.5040907@gentoo.org>, excerpted below, on Tue,
25 Apr 2006 20:03:00 +0200:

> I'd like to see some clarification of intended doc use flag usage, so that
> we wouldn't force users to download/install 40+ megs of docs for a ~3 meg
> package, with the only reason being that USE=doc is for developer
> documentation only. [1]
>
> And no, I don't think we need yet another use flag. ;) FEATURES="nodoc" is
> also not exactly useful as it's forcing users to download stuff they are
> not interested in at all. (To make it more clear, I'm talking about
> ebuilds that download docs in a separate tarball here.)
>
> [1] http://bugs.gentoo.org/show_bug.cgi?id=122265

Maybe I'll get shot down for this, but IMO, there's nothing wrong with
individual packages having a local userdoc USE flag. I don't believe it
needs to be global, and in the general case its use would be discouraged,
but it seems reasonable in extreme cases like the above, where the docs
tarball is ten times the size of the source tarball. Maybe make it a
policy that the flag is only to be used when docs are a minimum of three
times (or twice?) the source tarball size and at least 10 MB, and then dev
discretion is advised?

--
Duncan - List replies preferred. No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master." Richard Stallman in
http://www.linuxdevcenter.com/pub/a/linux/2004/12/22/rms_interview.html


--
gentoo-dev@gentoo.org mailing list