Bug#27869: [PROPOSED] Icon location policy
Package: debian-policy
Priority: wishlist
This is a proposal to debian-policy in accordance with the method
Manoj has set up using the Bug Tracking System for proposed policy
changes.
This covers the locations of icons.
------------------------------------------------------------------
Rationale
There currently is no policy on where icons should end up; (the only
thing approaching policy is the documentation that comes with the menu
package - no, the FHS doesn't specify this even though it should) as a
result, xpm icons can end up almost anywhere. This makes it difficult
to write icon paths that do what users expect; that is, to configure
our respective window managers so that all the proper icons are found.
The Debian 2.0 (i.e. hamm) practice among the fvwm* crowd was to dump
all icons into /usr/X11R6/include/X11/{bitmap,pixmap} - this has at
least two problems:
1. icons are shareable data, and as such should really wind up
somewhere under /usr/share.
2. If all window managers place their icons in one central directory,
there's bound to eventually be collisions. While these can be
papered over with a Replaces: header, the better solution is for
this collision to never happen in the first place. (One stupid
little pixmap is the reason that the hamm fvwm95 is listed as
Replace:-ing the bo afterstep)
Also, this system doesn't really give the local sysadmin a place to
put her own icons where she can be confident they won't be overridden
by some installed package. There should be a place under /usr/local
that all window managers look in to find icons as well.
Requirements for packages which supply icons
Packages that have some icon which identifies them (like the
xemacs.xpm icon in xemacs20-support) should place that icon into
/usr/share/icons/. Such icons should have a name that is specific to
that package. (so "icon.xpm" should only be used by the "icon"
package) If packages have some sort of "mini" icon that identifies
them as well, it should go into /usr/share/icons/mini/ and should have
a filename starting with "mini-" or "mini.".
The rationale for choosing /usr/share/icons/ over /usr/share/pixmaps/
is that we're not talking about just .xpm files anymore. The
rationale of a second directory for mini icons is to keep down on
directory clutter. The rationale for starting the mini icon with
"mini" is that some window managers which can make nice use of mini
icons in menus lack the ability to specify a separate icon path for
"regular size" and "mini" icons.
Packages with icons intended for use only by themselves should place
those icons somewhere under /usr/lib/<package> or /usr/share/<package>
(or even /usr/X11R6/lib/<package> or /usr/X11R6/lib/X11/<package>)
Specifically, these icons should not go into areas used by multiple
packages like /usr/share/icons or /usr/X11R6/lib/X11/include/pixmaps.
If a package has a large number of such files, they should probably
get split off into a separate "Architecture: all" package which stores
them under /usr/share/<package>.
Requirements for packages which use other packages' icons
Now, window managers when searching for icons should (by default)
search in this order:
* User's ~/.<package>/icons (optional)
* User's ~/.icons
* /usr/local/share/<package>/icons (optional)
* /usr/local/share/icons
* /usr/share/<package>/icons (optional)
* /usr/share/icons
* Backwards compatibility path of:
+ /usr/share/pixmaps
+ /usr/X11R6/include/X11/pixmaps
+ /usr/X11R6/include/X11/bitmaps
+ /usr/X11R6/include/pixmaps
+ /usr/X11R6/include/bitmaps
A few notes about the three paths I listed with "optional":
1. A maintainer can leave out any or all of these paths, although
leaving out /usr/local/share/<package>/icons while including
/usr/share/<package>/icons seems a bit odd.
2. If for your package it makes more sense to internally store your
icons under /usr/share/<package>/iconthingys (that is, if it makes
more sense to use a different path under /usr/share/<package>/),
use that instead, and change the name of the directory searched
under /usr/local/share/<package>/ to match this.
3. If it makes sense to use a differently named user-specific,
package-specific icon directory go ahead and do so, but document
it in the /usr/doc/<package>/README.debian file.
Actually, documenting the default icon path in
/usr/doc/<package>/README.debian (even if it's exactly this) is
generally a good idea.
Also, other directories may be added at any point in the path (for
example, /usr/local/share/pixmaps) by a maintainer if they feel
like it.
In addition, this combined with current /usr/local policy implies that
in the postinst window managers should attempt to create the directory
structure under /usr/local that appears in their icon path. Also, the
postinst must not fail if these directories couldn't be created.
Window managers (in fact any package) must not contain anything in the
/usr/local tree.
Postscript
Redhat appears to follow something like this - the RedHat 5.1 packages
I checked (AnotherLevel and fvwm2-icons) seem to use /usr/share/icons
as a place to dump icons (which makes gnome's use of
/usr/share/pixmaps a bit surprising). RedHat compatibility in this
regard would be nice for those people installing commercial apps that
only come as RPMs.
This proposal represents the consensus of those maintainers of
window managers as cared to participate in the discussion.
Specifically, at least the maintainers of the fvwm* packages, KDE
packages, and window maker packages cared to participate. The
maintainers of other packages, while they haven't signed off on
this specifically, have received copies of this and haven't
objected.
It is intended that window managers will implement the new search
path in slink or in the first upload in whatever is to be after
slink. Packages which supply icons for general use will move the
locations of their icons into /usr/share/icons after slink. This
should provide for a smooth transition.
Reply to: