Title:Per-Category metadata.xml Files
Author:Ciaran McCreesh <ciaranm at>
Last-Modified:2005/03/11 19:07:16
Type:Standards Track



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.


Category names are short and not entirely clear. Adding arbitrary length long descriptions to categories would provide several advantages:


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.


The app-vim category could use a metadata.xml file like the following:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE catmetadata SYSTEM "">
        <longdescription lang="en">
            The app-vim category contains plugins and syntax file
            packages for the Vim text editor.
        <longdescription lang="de">
            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 <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 " 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.


[1](1, 2, 3) Gentoo Metadata, (
[2]GLEP 31: Character Sets for Portage Tree Items (
[3]Gentoo bug 66917 (