--- GLEP: 34 Title: Per-Category metadata.xml Files Author: Ciaran McCreesh Type: Standards Track Status: Replaced Version: 1 Created: 2005-03-11 Last-Modified: 2017-10-13 Post-History: 2005-03-11, 2005-03-13, 2005-05-02 Content-Type: text/x-rst Replaced-By: 68 --- 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 "packages.gentoo.org 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, (https://devmanual.gentoo.org/ebuild-writing/misc-files/metadata/#category-metadata) .. [2] GLEP 31: Character Sets for Portage Tree Items (https://www.gentoo.org/glep/glep-0031.html) .. [3] Gentoo bug 66917 (http://bugs.gentoo.org/show_bug.cgi?id=66917) Copyright ========= This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License. To view a copy of this license, visit https://creativecommons.org/licenses/by-sa/3.0/. .. vim: set tw=74 fileencoding=utf-8 :