Rename all GLEPs to .rst

1 files changed, 127 insertions, 0 deletions

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 <ciaranm@gentoo.org>
+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 ``<catmetadata>`` element shall be added to the DTD. This
+is necessary because the existing ``<pkgmetadata>`` 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 ``<longdescription>`` 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 ``<herd>`` and ``<maintainer>`` 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: ::
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    <!DOCTYPE catmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
+    <catmetadata>
+            <longdescription lang="en">
+                The app-vim category contains plugins and syntax file
+                packages for the Vim text editor.
+            </longdescription>
+            <longdescription lang="de">
+                Die Kategorie app-vim enthält Plugins und Syntax-Pakete
+                für den Vim Texteditor.
+            </longdescription>
+    </catmetadata>
+
+Implementation Requirements
+---------------------------
+
+The DTD file would need to be updated to include the ``<catmetadata>``
+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 :