From c6fe2071a2e83be2203196ad7f9459941821a034 Mon Sep 17 00:00:00 2001 From: Michał Górny Date: Thu, 14 Sep 2017 23:14:39 +0200 Subject: Rename all GLEPs to .rst --- glep-0034.rst | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 glep-0034.rst (limited to 'glep-0034.rst') diff --git a/glep-0034.rst b/glep-0034.rst new file mode 100644 index 0000000..e2e855b --- /dev/null +++ b/glep-0034.rst @@ -0,0 +1,127 @@ +GLEP: 34 +Title: Per-Category metadata.xml Files +Version: $Revision$ +Author: Ciaran McCreesh +Last-Modified: $Date$ +Status: Final +Type: Standards Track +Content-Type: text/x-rst +Created: 11-Mar-2005 +Post-History: 11-Mar-2005, 13-Mar-2005, 2-May-2005 +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 + (http://www.gentoo.org/proj/en/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 +http://creativecommons.org/licenses/by-sa/3.0/. + +.. vim: set tw=74 fileencoding=utf-8 : -- cgit v1.2.3-65-gdbad