--- xml/htdocs/proj/en/glep/glep-0056.html 2008/07/10 22:14:40 1.3 +++ xml/htdocs/proj/en/glep/glep-0056.html 2010/04/07 22:14:20 1.4 @@ -4,253 +4,9 @@ - + GLEP 56 -- USE flag descriptions in metadata - - + @@ -271,17 +27,17 @@ - + - + - + - + @@ -290,25 +46,25 @@
-
-

Contents

+
+

Contents

-
-

Abstract

+
+

Abstract

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

-
-

Motivation

+
+

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. @@ -317,32 +73,32 @@ them directly? It's interface won't use jpeg files.

-
-

Specification

-

This GLEP proposes the addition of <use> XML tag that is only allowed to -appear inside of a <pkgmetadata> XML tag.

+
+

Specification

+

This GLEP proposes the addition of <use> XML tag that is only allowed to +appear inside of a <pkgmetadata> XML tag.

    -
  • Inside the <use> XML tag, the <flag> XML tag is allowed to appear -once per USE flag as specified by the 'name' attribute with the +

  • Inside the <use> XML tag, the <flag> XML tag is allowed to appear +once per USE flag as specified by the 'name' attribute with the following exception:

      -
    • The 'restrict' atttribute can limit to specific versions of the +
    • The 'restrict' 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 [4]. This follows the current -behavior of the 'restrict' attribute in metadata.xml.
        +Gentoo Developer Handbook [4]. This follows the current +behavior of the 'restrict' 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 <flag> XML tag requires a 'name' attribute which is the full USE +

    • Each <flag> XML tag requires a 'name' attribute which is the full USE flag name as it would appear in the IUSE section of the ebuild.

        @@ -350,28 +106,28 @@
    • -
    • Each <flag> XML tag allows 0 or more nested <pkg> XML tags whose +

    • Each <flag> XML tag allows 0 or more nested <pkg> XML tags whose character data is a valid CP or CPV as defined by the -Gentoo Development Manual - Ebuild File Format [5].

      +Gentoo Development Manual - Ebuild File Format [5].

    • -
    • Each <flag> XML tag allows 0 or more nested <cat> XML tags whose +

    • Each <flag> XML tag allows 0 or more nested <cat> XML tags whose character data is a valid category.

    • -
    • The <use> XML tag may appear multiple times inside of the -<pkgmetadata> XML tag if and only if it contains a different 'lang' +

    • The <use> XML tag may appear multiple times inside of the +<pkgmetadata> XML tag if and only if it contains a different 'lang' attribute value.

        -
      • The lang attribute follows the documented lang attribute in the -Gentoo Developer Handbook [4].
      • +
      • The lang attribute follows the documented lang attribute in the +Gentoo Developer Handbook [4].
-

Documentation for the Gentoo Developer Handbook [4] and the -metadata.dtd can be found in Gentoo's Bugzilla [1] +

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

-

The following are two concrete examples in tree, [2] -and [3].

+

The following are two concrete examples in tree, [2] +and [3].

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

 <use>
@@ -387,90 +143,90 @@
 </use>
 
-
-

Credits

+
+

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)

-
-

References

+ -
-

Backwards Compatibility

-

No changes are necessary to existing metadata.xml files. Information in -the new tags is not mandatory. Tools that currently read metadata.xml +

+

Backwards Compatibility

+

No changes are necessary to existing metadata.xml files. Information in +the new tags is not mandatory. Tools that currently read metadata.xml 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 use.desc and use.local.desc.

-

USE flags still must be defined in use.desc or use.local.desc. If the -USE flag is not found in either use.desc or use.local.desc, the -information contained within the new tags in metadata.xml must be ignored +should prefer their data over use.desc and use.local.desc.

+

USE flags still must be defined in use.desc or use.local.desc. If the +USE flag is not found in either use.desc or use.local.desc, the +information contained within the new tags in metadata.xml 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 use.local.desc file from CVS and it will be auto-generated for rsync. +the use.local.desc 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 metadata.xml containing the necessary tags which would appear -in use.local.desc.

+contents of metadata.xml containing the necessary tags which would appear +in use.local.desc.

-
-

Copyright

+ @@ -478,11 +234,10 @@
-