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



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. 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.


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 would need a few small changes to be able to handle per-category metadata files.

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 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.


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