--- GLEP: 56 Title: USE flag descriptions in metadata Author: Doug Goldstein Type: Standards Track Status: Replaced Version: 1 Created: 2008-06-03 Last-Modified: 2023-02-21 Post-History: 2008-06-05, 2008-06-13 Content-Type: text/x-rst 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] https://bugs.gentoo.org/199788 .. [#use-flag-metadata-example1] https://gitweb.gentoo.org/archive/repo/gentoo-2.git/tree/sys-apps/hal/metadata.xml?id=37af07d2465e22f74394aa2ff2fd80698ac2d12b .. [#use-flag-metadata-example2] https://gitweb.gentoo.org/archive/repo/gentoo-2.git/tree/media-tv/mythtv/metadata.xml?id=37af07d2465e22f74394aa2ff2fd80698ac2d12b .. [#devhandbook] https://devmanual.gentoo.org/ebuild-writing/misc-files/metadata/index.html .. [#devmanual] https://devmanual.gentoo.org/ebuild-writing/file-format/index.html .. [#motivators1] https://flameeyes.blog/2007/11/19/lets-actually-get-some-metadata/ .. [#motivators2] https://cardoe.wordpress.com/2007/11/19/use-flag-metadata/ .. [#motivators3] https://cardoe.wordpress.com/2007/11/23/metadataxml-updates-examples/ .. [#motivators4] https://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 4.0 International License. To view a copy of this license, visit https://creativecommons.org/licenses/by-sa/4.0/. .. vim: set ft=glep tw=72 :