GLEP:56

Abstract
This GLEP proposes to add per-package USE flag descriptions to each package's metadata.

Motivation
Gives Gentoo users the ability to better identify how USE flags affect their installations of a given package. For example, many global USE flags have very generic descriptions but no specifics on how it affects a certain package. Specifically speaking, an example would be net-print/cups and the 'jpeg' USE flag. Does this flag mean you won't be able to print jpeg files? You can print them directly? Its interface won't use jpeg files.

- Motivator References:, , , and

Specification
This GLEP proposes the addition of  XML tag that is only allowed to appear inside of a   XML tag.
 * Inside the  XML tag, the   XML tag is allowed to appear once per USE flag as specified by the   attribute with the following exception:
 * The  atttribute can limit to specific versions of the package, where the attribute value must be a valid CPV as defined by the Gentoo Developer Handbook .  This follows the current behavior of the   attribute in metadata.xml.
 * e.g. A USE flag may have one behavior for version 0.1 of a package, while version 0.2, the USE flag may differ slightly.
 * Each  XML tag requires a 'name' attribute which is the full USE flag name as it would appear in the IUSE section of the ebuild.
 * e.g. "video_cards_i810" or "alsa"
 * Each  XML tag allows 0 or more nested   XML tags whose character data is a valid CP or CPV as defined by the Gentoo Development Manual - Ebuild File Format.
 * Each  XML tag allows 0 or more nested   XML tags whose character data is a valid category.
 * The  XML tag may appear multiple times inside of the   XML tag if and only if it contains a different   attribute value.
 * The  attribute follows the documented   attribute in the Gentoo Developer Handbook.

Documentation for the Gentoo Developer Handbook and the metadata.dtd can be found in Gentoo's Bugzilla bug #199788.

The following are two concrete examples in tree, and.

And the following is an embedded example and not from a real package::

Credits
Thanks to the following persons for their input on or related to this GLEP (even though they might not have known it): Diego Pettenò (flameeyes), Alec Warner (antarus), Joshua Nichols (nichoj), Steve Dibb (beandog), and Tiziano Müller (dev-zero)

Backwards Compatibility
No changes are necessary to existing  files. Information in the new tags is not mandatory. Tools that currently read  files may break if written poorly, while well written tools should just ignore the additional elements. Tools which are capable of handling the new tags should prefer their data over  and.

USE flags still must be defined in  or. If the USE flag is not found in either  or , the information contained within the new tags in   must be ignored and QA tools should warn as they currently do.

Once this GLEP is approved, the Gentoo Infrastructure Team will work to remove the  file from CVS and it will be auto-generated for rsync. This will ensure that backwards compatibility is not broken for users of non-CVS trees. At this time, QA tools will need to be updated to verify the contents of  containing the necessary tags which would appear in.

Copyright
This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/.