GLEP:34
Title:Per-Category metadata.xml Files
Version:1.1
Author:Ciaran McCreesh <ciaranm at gentoo.org>
Last-Modified:2005/03/11 19:07:16
Status:Draft
Type:Standards Track
Content-Type:text/x-rst
Created:03-March-2005
Post-Date:03-March-2005

Contents

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:

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](1, 2, 3) 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)