Bug 118579 – Useless descriptions provided for many flags in 'use.desc'

• Product: Gentoo Linux
• Status: RESOLVED NEEDINFO

[Description Nathanael Hoyle 2006-01-10 13:57:20 UTC]

The Gentoo handbook, as well as other documentation, suggest to the reader that (s)he reference to 'use.desc' file for clarification when in doubt as to the function, feature, or behavior controlled by a given USE flag.  In practice, many of these descriptions are highly uninformative and leave the curious enquirer just as unenlightened as (s)he was prior to looking up the USE flag.  For instance:

gcj - Enable building with gcj

This would be far better as:

gcj - Enable building with gcj (the GNU Compiler for Java)

This at least indicates that gcj is a compiler rather than a shared library, a security patch, a nifty feature, etc.

Similarly, 'ffmpeg' is explained as:

ffmpeg - Enable ffmpeg support

Again, in the absence of foreknowledge regarding ffmpeg, indicating that turning on the USE flag enables support for it is rather uninformative.  Along the lines of 'duh, it says ffmpeg, it turns it on, what is it?'  In the interest of better transparency of USE flags for (particularly new) users, if the 'use.desc' file is to remain the only real documentation available, it should probably be made somewhat more informative.  A simple policy regarding non-recursive descriptions (as would be expected in, e.g., a dictionary) and/or the inclusion of an URL providing more information about the technology or feature would go a long way to improving Gentoo's 'face' to its users as well as being a useful documentation aid to all.

[Comment 1 SpanKY 2006-01-10 16:46:44 UTC]

thats life

if you have a better description for a flag, submit it