GLEP:56
Title:USE flag descriptions in metadata
Version:1.1
Last-Modified:2008/06/05 05:54:10
Author:Doug Goldstein <cardoe at gentoo.org>
Status:Draft
Type:Standards Track
Content-Type:text/x-rst
Created:03-Jun-2008
Post-History:05-Jun-2008

Contents

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? 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.

Documentation for the Developer Manual 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].

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

<use>
        <flag name='acpi'>Enables HAL to attempt to read from
        /proc/acpi/event, if unavailable, HAL will read events from
        <pkg>sys-power/acpid</pkg>. 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</flag>
        <flag name='spell'>Enables spell checking capability using
        dictionaries found in <cat>app-dict</cat></flag>
</use>

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

[1]http://bugs.gentoo.org/show_bug.cgi?id=199788
[2]http://sources.gentoo.org/viewcvs.py/gentoo-x86/sys-apps/hal/metadata.xml?view=markup
[3]http://sources.gentoo.org/viewcvs.py/gentoo-x86/media-tv/mythtv/metadata.xml?view=markup
[4](1, 2) http://git.overlays.gentoo.org/gitweb/?p=proj/pms.git;a=summary
[5](1, 2) http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4
[6]http://blog.flameeyes.eu/articles/2007/11/19/lets-actually-get-some-metadata
[7]http://blog.cardoe.com/archives/2007/11/19/use-flag-metadata/
[8]http://blog.cardoe.com/archives/2007/11/23/metadataxml-updates-examples/
[9]http://technicalpickles.com/posts/pidgin-idle-time

Copyright

This document is placed into the public domain.