[gentoo-dev] GLEP ??: Per-Category metadata.xml Files

[Ciaran McCreesh <ciaranm@gentoo.org>]

[-- Attachment #1.1: Type: text/plain, Size: 601 bytes --]

Subject pretty much sums it up. I mentioned this in the sys-apps thread
and no-one said it was a horrid idea... Since I'm asking for DTD
additions it probably warrants a GLEP. Also, it'll be nice to get a
quick easy 'Accepted, Implemented' up on the site :) This time, my
efforts will not be thwarted by Donnie and his lame editor!

Attached for your tearing apart pleasure. Grant, please gimme a number,
preferably a prime one.

-- 
Ciaran McCreesh : Gentoo Developer (Vim, Fluxbox, shell tools)
Mail            : ciaranm at gentoo.org
Web             : http://dev.gentoo.org/~ciaranm


[-- Attachment #1.2: glep-metadata.txt --]
[-- Type: text/plain, Size: 3961 bytes --]

GLEP: XX
Title: Per-Category metadata.xml Files
Version: $Revision: $
Author: Ciaran McCreesh <ciaranm@gentoo.org>
Last-Modified: $Date: $
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 03-March-2005
Post-Date: 03-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 ``<catmetadata>`` element shall be added to the DTD to
distinguish category metadata elements from the existing ``<pkgmetadata>``
elements.

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.


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`` checks for category metadata files would not be necessary.

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

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,
       (http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4)
.. [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 document has been placed in the public domain.

 vim: set tw=74 fileencoding=utf-8 :


[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]