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

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.

 - Motivator References: [#motivators1]_, [#motivators2]_, [#motivators3]_,
   and [#motivators4]_


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
   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
     `Package Manager Specification` [#pms]_.  This follows the current behavior
     of the ``'restrict'`` attribute in metadata.xml. 
     
     - The ``restrict`` attribute follows the documented ``restrict``
       attribute in the `Gentoo Developer Handbook` [#devhandbook]_.

     - 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
   flag name as it would appear in the IUSE section of the ebuild.
    
    * e.g. "video_cards_i810" or "alsa"

 - 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
   `Package Manager Specification` [#pms]_.

 - 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'``
   attribute value.

   * The ``lang`` attribute follows the documented ``lang`` attribute in the
     `Gentoo Developer Handbook` [#devhandbook]_.

   * The default ``'lang'`` attribute value is "C", which is equivilent to "en".

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

	<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
==========

.. [#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 

.. [#pms] http://git.overlays.gentoo.org/gitweb/?p=proj/pms.git;a=summary

.. [#devhandbook] http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4

.. [#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

Copyright
=========

This document is placed into the public domain.

.. vim: set ft=glep tw=72 :