GLEP: 56 Title: USE flag descriptions in metadata Version: $Revision$ Last-Modified: $Date$ Author: Doug Goldstein Status: Final Type: Standards Track Content-Type: text/x-rst Created: 03-Jun-2008 Post-History: 05-Jun-2008, 13-Jun-2008 Replaced-By: 68 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: [#motivators1]_, [#motivators2]_, [#motivators3]_, and [#motivators4]_ 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 ``'name'`` attribute with the following exception: * 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` [#devhandbook]_. 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 ```` 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` [#devmanual]_. - 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 ``'lang'`` attribute value. * The ``lang`` attribute follows the documented ``lang`` attribute in the `Gentoo Developer Handbook` [#devhandbook]_. Documentation for the `Gentoo Developer Handbook` [#devhandbook]_ and the metadata.dtd can be found in Gentoo's Bugzilla [#use-flag-metadata-bug]_ bug #199788. The following are two concrete examples in tree, [#use-flag-metadata-example1]_ and [#use-flag-metadata-example2]_. And the following is an embedded example and not from a real package:: Enables HAL to attempt to read from /proc/acpi/event, if unavailable, HAL will read events from sys-power/acpid. If you need multiple acpi readers, ensure acpid is in your default runlevel (rc-update add acpid default) along with HAL. This will also enable HAL to read Toshiba and IBM acpi events which do not get sent via /proc/acpi/event Enables spell checking capability using dictionaries found in app-dict 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 ========== .. [#use-flag-metadata-bug] http://bugs.gentoo.org/show_bug.cgi?id=199788 .. [#use-flag-metadata-example1] http://sources.gentoo.org/viewcvs.py/gentoo-x86/sys-apps/hal/metadata.xml?view=markup .. [#use-flag-metadata-example2] http://sources.gentoo.org/viewcvs.py/gentoo-x86/media-tv/mythtv/metadata.xml?view=markup .. [#devhandbook] https://devmanual.gentoo.org/ebuild-writing/misc-files/metadata/index.html .. [#devmanual] http://devmanual.gentoo.org/ebuild-writing/file-format/index.html .. [#motivators1] http://blog.flameeyes.eu/articles/2007/11/19/lets-actually-get-some-metadata .. [#motivators2] http://blog.cardoe.com/archives/2007/11/19/use-flag-metadata/ .. [#motivators3] http://blog.cardoe.com/archives/2007/11/23/metadataxml-updates-examples/ .. [#motivators4] http://technicalpickles.com/posts/pidgin-idle-time 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 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. 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``. 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/. .. vim: set ft=glep tw=72 :