Re: [gentoo-dev] per-package USE documentation (from gentoo-doc)

[Joel Konkle-Parker]

Jason Rhinelander wrote:
>  > I whole-heartedly agree with the premise of "putting some order into
>  > it". I still think part of that needs to be some sort of clear
>  > documentation. 'mozilla +java' is pretty clear, but 'xfree +xml2' just
>  > says to me "why does xfree need xml2, what does it do for it, and what
>  > would happen if I didn't include it?". There needs to be some sort of
>  > clear descriptions (optimally per-package) that allow people to make
>  > informed decisions about which flags to include and which they can
>  > safely discard.
>
> It seems to me that a far better approach is the idea of per-package use
> flags, with some documentation in the package - so that something like
> ``emerge -pvv packagename'' would show me not only which use flags are
> in effect, but what they do to the package.
>
> So, yes to better (i.e. per-package) documentation, but no to exploding
> use flags 5 or 6 ways each.
>
> For documentation, I suggest something like the following:
>
> Inside abc-xyz/packagename-1.2.3-r4.ebuild:
> ...
> IUSE="aaa bbb ccc"
>
> WHYIUSE="aaa - gives you aaa client support
> bbb - gives you bbb server support
> ccc - makes <package> do strange and unusual things with ccc"
> ...
>
> Then, when I, Gentoo User, run:
>
> # emerge -pv packagename otherpackage
>
> I'll see (nothing new):
>
> These are the packages that I would merge, in order:
>
> Calculating dependencies ...done!
> [ebuild  N    ] abc-xyz/packagename-1.2.3-r4  +aaa -bbb -ccc
> [ebuild  N    ] abc-xyz/otherpackage-4.3.2-r1  +gnome -curses +cgi
>
> "Ah, that's interesting," I think to myself "I wonder what the cgi use
> flag does for 'otherpackage'?"  So I run:
>
> # emerge -pvv packagename otherpackage
>
> and I see:
>
> These are the packages that I would merge, in order:
>
> Calculating dependencies ...done!
> [ebuild  N    ] abc-xyz/packagename-1.2.3-r4  +aaa -bbb -ccc
>     aaa - gives you aaa client support
>     bbb - gives you bbb server support
>     ccc - makes packagename do strange and unusual things with ccc"
> [ebuild  N    ] abc-xyz/otherpackage-4.3.2-r1  +gnome -curses +cgi
>     gnome - adds gnome control center support
>     curses - adds curses management support
>     cgi - gives you management support via an installed CGI script
>
>
> I think the above would be a VERY useful thing, at least once use flags
> are sorted out - but the sorting out that needs to happen is making use
> flags per-package, not to go in the direction of giving every package
> its own set of use flags.

You read my mind. Here's what I posted on -doc earlier today (I don't 
know if it got through to -dev or not):

"I guess the obvious place for this information would be inside the 
ebuild itself. It could get be parsed out for the packages page. An 
example ebuild (gcc) would have:

USE_DESC="java: compiles the gcj java compiler and associated support 
files; not needed if you're not using gcj"

That would put a small additional load on ebuild creators, yes, but who 
knows their USE flags better than the ebuilders themselves? That short 
one-liner would be extremely helpful on my (the user's) end as well. I'd 
see that (either by looking at packages.gentoo.org, or in the ebuild, or 
with etcat, or similar) and say "Ok, I don't think I'm ever going to use 
gcj, so I'll set USE="-java" without worrying about unintended 
consequences."

-- 
Joel Konkle-Parker
Webmaster [Ballsome.com]

Phone     [[phone]]
E-mail    [jjk3@×××××××.edu]