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

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

[Ciaran McCreesh]

[-- 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 --]

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

[Dan Meltzer]

This a useful enough prime number for your tastes?

2^25964951-1


On Fri, 11 Mar 2005 16:24:21 +0000, Ciaran McCreesh <ciaranm@gentoo.org> wrote:
> 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
> 
> 
> 

--
--
gentoo-dev@gentoo.org mailing list

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

[Michael Cummings]

[-- Attachment #1: Type: text/plain, Size: 871 bytes --]

For what it's worth, I like it and was actually wondering about this
myself last night when I had trouble falling asleep (no joke). Would
really come in handy that terrible day when we split dev-perl into
multiple categories so that their contents make sense to someone other
than a perl-dweeb like myself while still being succinctly short names.

On Fri, 2005-03-11 at 16:24 +0000, Ciaran McCreesh wrote:
> 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.
> 

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

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

[Michael Cummings]

[-- Attachment #1: Type: text/plain, Size: 871 bytes --]

For what it's worth, I like it and was actually wondering about this
myself last night when I had trouble falling asleep (no joke). Would
really come in handy that terrible day when we split dev-perl into
multiple categories so that their contents make sense to someone other
than a perl-dweeb like myself while still being succinctly short names.

On Fri, 2005-03-11 at 16:24 +0000, Ciaran McCreesh wrote:
> 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.
> 

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

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

[Donnie Berkholz]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Ciaran McCreesh wrote:
> 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!

I don't see any need to thwart this one, since it depends on GLEP 31
already. =P

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

If it's difficult to search/browse, it may not help much.

> A new top level ``<catmetadata>`` element shall be added to the DTD to
> distinguish category metadata elements from the existing ``<pkgmetadata>``
> elements.

Why does it needs to be distinguished?

> The ``<herd>`` and ``<maintainer>`` elements are not generally relevant at
> the category level.

If they are, can they be used?
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.0 (GNU/Linux)

iD8DBQFCMfqeXVaO67S1rtsRAtaZAKDtIr+cSQzbpwbNvTTv61KsJzOQQgCaApIp
L0zHo+bThPqTfmxIyRsqn44=
=bRlL
-----END PGP SIGNATURE-----
--
gentoo-dev@gentoo.org mailing list

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

[Chris Gianelloni]

[-- Attachment #1: Type: text/plain, Size: 763 bytes --]

On Fri, 2005-03-11 at 12:07 -0800, Donnie Berkholz wrote:
> > * 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.
> 
> If it's difficult to search/browse, it may not help much.

It's a lot easier to make a tool to search/browse them once they're in
place.

> > The ``<herd>`` and ``<maintainer>`` elements are not generally relevant at
> > the category level.
> 
> If they are, can they be used?

I would like this one, too, as games-* is all owned by the same herd,
minus a few select packages here and there.

-- 
Chris Gianelloni
Release Engineering - Strategic Lead/QA Manager
Games - Developer
Gentoo Linux

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

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

[Chris Gianelloni]

[-- Attachment #1: Type: text/plain, Size: 1106 bytes --]

On Fri, 2005-03-11 at 20:21 +0000, Ciaran McCreesh wrote:
> | > The ``<herd>`` and ``<maintainer>`` elements are not generally
> | > relevant at the category level.
> | 
> | If they are, can they be used?
> 
> The DTD says they can be. Or, at least, I see no reason to impose
> additional restrictions saying that they can't. I wouldn't consider them
> an appropriate substitute for per-package metadata, however.

I honestly wouldn't mind seeing inheritance allowed at some point in the
future, but I also understand the amount of additional work that would
entail and would much rather get this implemented in its current form,
than to hold it up waiting for all the necessary tools be updated to
support inheritance.  It definitely would be cool, though.  It would end
up making the tree smaller, as many packages (again, I'll use games-* as
an example) wouldn't need a metadata.xml, at all.  Then there are
packages like ut2004-*, which could inherit the metadata from ut2004.

-- 
Chris Gianelloni
Release Engineering - Strategic Lead/QA Manager
Games - Developer
Gentoo Linux

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]