GLEP: 34 Title: Per-Category metadata.xml Files Version: $Revision: 1.3 $ Author: Ciaran McCreesh Last-Modified: $Date: 2005/03/17 23:57:56 $ Status: Accepted Type: Standards Track Content-Type: text/x-rst Created: 11-March-2005 Post-Date: 11-March-2005, 13-March-2005 Abstract ======== A ``metadata.xml`` file [1]_ is currently used to provide extra metadata (long descriptions, herd and maintainer information) about a package. It is proposed that these files also be used to describe the purpose of a category. Motivation ========== Category names are short and not entirely clear. Adding arbitrary length long descriptions to categories would provide several advantages: * It would clarify the meaning of categories for users, who may not be aware of some of the abbreviations or acronyms we use. * With the use of XML ``lang=""`` attributes, it would allow for additional non-English descriptions (simply using longer category names would not allow this). * It would help developers better select a relevant category for their package, rather than dumping everything into ``sys-apps`` and ``app-misc`` as is done currently. * It would help illustrate which categories are too broad or badly defined in scope, making any future category splits easier. Specification ============= It is proposed that the existing ``metadata.xml`` format [1]_ be used. Even though XML sucks, there is already a framework in place for these files. The filename will be ``blah-misc/metadata.xml``. The character set used shall be UTF-8 for consistency with GLEP 31 [2]_. A new top level ```` element shall be added to the DTD. This is necessary because the existing ```` element is not appropriately named, and doing a global rename would be impractical. Using a different element would also permit additional category-specific data to be added at a later date. The existing ```` elements shall be used for descriptions. The ``lang`` attribute shall be used to indicate the human language of the description -- all categories must have at least an English (``en``) description. The ```` and ```` elements are not generally relevant at the category level. They may be specified as a fall-back "assume that everything in this category is maintained by these people", but this must not be used as a replacement for proper per-package metadata. Examples -------- The ``app-vim`` category could use a ``metadata.xml`` file like the following: :: The app-vim category contains plugins and syntax file packages for the Vim text editor. Die Kategorie app-vim enthält Plugins und Syntax-Pakete für den Vim Texteditor. Implementation Requirements --------------------------- The DTD file would need to be updated to include the ```` element. A metadata file would have to be added to every category in the tree. This could be done over a period of time. ``repoman`` would need a few small changes to be able to handle per-category metadata files. The " metadata" bug [3]_ would need to be updated to ask for category descriptions as well. The metadata documentation [1]_ would require some additions. Backwards Compatibility ======================= The metadata DTD will remain backwards compatible. The category metadata files will need to be considered "optional until implemented" rather than immediately becoming mandatory. References ========== .. [1] Gentoo Metadata, ( .. [2] GLEP 31: Character Sets for Portage Tree Items ( .. [3] Gentoo bug 66917 ( Copyright ========= This document has been placed in the public domain. .. vim: set tw=74 fileencoding=utf-8 :