On going work

1 files changed, 145 insertions, 530 deletions

diff --git a/spec/sound-theme-spec.xml b/spec/sound-theme-spec.xml
index 7554b0f..3bbe4c0 100644
--- a/spec/sound-theme-spec.xml
+++ b/spec/sound-theme-spec.xml
@@ -1,28 +1,19 @@
 <?xml version="1.0"?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
 ]>
 <article id="index">
   <articleinfo>
-    <title>Icon Theme Specification</title>
-    <releaseinfo>Version 0.11</releaseinfo>
-    <date>February 7 2006</date>
+    <title>Sound Theme Specification</title>
+    <releaseinfo>Version 0.1</releaseinfo>
+    <date>February 11 2008</date>
     <authorgroup>
       <author>
-	<firstname>Alexander</firstname>
-	<surname>Larsson</surname>
+	<firstname>Marc-Andre</firstname>
+	<surname>Lureau</surname>
 	<affiliation>
 	  <address>
-	    <email>alexl@redhat.com</email>
-	  </address>
-	</affiliation>
-      </author>
-      <author>
-	<firstname>Frans</firstname>
-	<surname>Englich</surname>
-	<affiliation>
-	  <address>
-	    <email>frans.englich@telia.com</email>
+	    <email>marc-andre.lureau@nokia.com</email>
 	  </address>
 	</affiliation>
       </author>
@@ -32,17 +23,16 @@
   <sect1 id="overview">
     <title>Overview</title>
     <para>
-    An icon theme is a set of icons that share a common look and
-    feel. The user can then select the icon theme that they want to
-    use, and all apps use icons from the theme. The initial user of
-    icon themes is the icon field of the desktop file specification,
-    but in the future it can have other uses (such as mimetype
-    icons).
+    A sound theme is a set of sounds that share a common feel, or
+    instrument set.  The user can then select the sound theme that
+    they want to use, and all apps use sounds from the theme. The
+    initial user of sounds themes is the desktop notification
+    service. But it can have other uses.
     </para>
     <para>
-    From a programmer perspective an icon theme is just a
-    mapping. Given a set of directories to look for icons in and a theme
-    name it maps from icon name and nominal icon size to an icon filename.
+    From a programmer perspective a sound theme is just a
+    mapping. Given a set of directories to look for sounds in and a
+    theme name it maps from sound name to an sound filename.
     </para>
   </sect1>
 
@@ -50,25 +40,23 @@
     <title>Definitions</title>
     <variablelist>
       <varlistentry>
-	<term>Icon Theme</term>
+	<term>Sound Theme</term>
 	<listitem>
 	  <para>
-          An icon theme is a named set of icons. It is used to map
-          from an iconname and size to a file. Themes may inherit
+          A sound theme is a named set of sounds. It is used to map
+          from a sound name. Themes may inherit
           from other themes as a way to extend them.
 	  </para>
 	</listitem>
       </varlistentry>
       <varlistentry>
-	<term>Icon file</term>
+	<term>Sound file</term>
 	<listitem>
 	  <para>
-          An icon file is an image that can be loaded and used as an
-          icon. The supported image file formats are PNG, XPM and SVG.
-          PNG is the recommended bitmap format, and SVG is for
-          vectorized icons. XPM is supported due to backwards
-          compability reasons, and it is not recommended that new
-          themes use XPM files. Support for SVGs is optional. 
+          The supported sound file formats are WAV/PCM 48kHz, 16bits,
+          and OGG/Vorbis.  WAV is the recommended uncompressed format,
+          and OGG/Vorbis is for compressed. Support for OGGs is
+          optional.
 	  </para>
 	</listitem>
       </varlistentry>
@@ -76,7 +64,7 @@
 	<term>Base Directory</term>
 	<listitem>
 	  <para>
-          Icons and themes are searched for in a set of directories,
+          Sounds and themes are searched for in a set of directories,
           called base directories. The themes are stored in
           subdirectories of the base directories.
 	  </para>
@@ -88,26 +76,22 @@
   <sect1 id="directory_layout">
     <title>Directory Layout</title>
     <para>
-    Icons and themes are looked for in a set of directories. By
-    default, apps should look in $HOME/.icons (for backwards compatibility),
-    in $XDG_DATA_DIRS/icons and in /usr/share/pixmaps (in that order).
-    Applications may further add
-    their own icon directories to this list, and users may extend or
-    change the list (in application/desktop specific ways).In each of
-    these directories themes are stored as subdirectories. A theme can
-    be spread across several base directories by having subdirectories of
-    the same name. This way users can extend and override system 
-    themes. 
+    Sounds and themes are looked for in a set of directories. By
+    default, apps should look in $XDG_DATA_DIRS/sounds.  Applications
+    may further add their own sound directories to this list, and
+    users may extend or change the list (in application/desktop
+    specific ways).In each of these directories themes are stored as
+    subdirectories. A theme can be spread across several base
+    directories by having subdirectories of the same name. This way
+    users can extend and override system themes.
     </para>
     <para>
     In order to have a place for third party applications to install
-    their icons there should always exist a theme called "hicolor"
-    <footnote><para>This name is chosen for backwards compatibility with the old
-    KDE default theme</para></footnote>.
-    The data for the hicolor theme is available for download at:
-    http://www.freedesktop.org/software/icon-theme/.
-    Implementations are required to look in the "hicolor" theme if
-    an icon was not found in the current theme.
+    their sounds there should always exist a theme called
+    "freedesktop" The data for the freedesktop theme is available for
+    download at: http://www.freedesktop.org/software/sound-theme/.
+    Implementations are required to look in the "freedesktop" theme if
+    a sound was not found in the current theme.
     </para>
     <para>
     Each theme is stored as subdirectories of the base
@@ -125,35 +109,33 @@
     </para>
     <para>
     In the theme directory are also a set of subdirectories containing
-    image files. Each directory contains icons designed for a certain
-    nominal icon size, as described by the index.theme file. The
-    subdirectories are allowed to be several levels deep, e.g. the
-    subdirectory "48x48/apps" in the theme "hicolor" would end up at
-    $basedir/hicolor/48x48/apps.
+    sound files. The subdirectories are allowed to be several levels
+    deep, e.g. the subdirectory "alerts/fr" in the theme "freedesktop"
+    would end up at $basedir/freedesktop/alerts/fr. (FIXME)
     </para>
     <para>
-    The image files must be one of the types: PNG, XPM, or SVG, and
-    the extension must be ".png", ".xpm", or ".svg" (lower case). The
-    support for SVG files is optional. Implementations that do not
-    support SVGs should just ignore any ".svg" files. In
+    The sounds files must be one of the types: WAV/PCM 48kHz, 16 bits or OGG/Vorbis.
+    The extension must be ".wav", or ".ogg" respectively (lower case). The
+    support for OGG files is optional. Implementations that do not
+    support OGGs should just ignore any ".ogg" files. In
     addition to this there may be an additional file with extra
-    icon-data for each file. It should have the same basename as the
-    image file, with the extension ".icon". e.g. if the icon file is
-    called "mime_source_c.png" the corresponding file would be named
-    "mime_source_c.icon".
+    sound-data for each file. It should have the same basename as the
+    sound file, with the extension ".sound". e.g. if the sound file is
+    called "system-log-out.wav" the corresponding file would be named
+    "system-log-out.sound".
     </para>
   </sect1>
 
   <sect1 id="file_formats">
     <title>File Formats</title>
     <para>
-    Both the icon theme description file and the icon data files are
+    Both the sound theme description file and the sound data files are
     ini-style text files, as described in the desktop file
-    specification. They don't have any encoding field. Instead, they 
+    specification. They don't have any encoding field. Instead, they
     must always be stored in UTF-8 encoding.
     </para>
     <para>
-    The index.theme file must start with a section called <citetitle>Icon
+    The index.theme file must start with a section called <citetitle>Sound
     Theme</citetitle>, with contents according to table 1 below. All lists are
     comma-separated.
     <table>
@@ -171,7 +153,7 @@
 	  <row>
 	    <entry>Name</entry>
 	    <entry>
-              short name of the icon theme, used in e.g. lists when
+              short name of the sound theme, used in e.g. lists when
               selecting themes.
 	    </entry>
 	    <entry>localestring</entry>
@@ -189,15 +171,15 @@
 	    <entry>Inherits</entry>
 	    <entry>
               <para>
-              The name of the theme that this theme inherits from. If an icon
+              The name of the theme that this theme inherits from. If a sound
               name is not found in the current theme, it is searched for in the
               inherited theme (and recursively in all the inherited themes).
               </para>
               <para>
               If no theme is specified implementations are required to add
-              the "hicolor" theme to the inheritance tree. An implementation
+              the "freedesktop" theme to the inheritance tree. An implementation
               may optionally add other default themes in between the last
-              specified theme and the hicolor theme.
+              specified theme and the freedesktop theme.
               </para>
 	    </entry>
 	    <entry>strings</entry>
@@ -226,8 +208,8 @@
 	  <row>
 	    <entry>Example</entry>
 	    <entry>
-              The name of an icon that should be used as an example of
-              how this theme looks.
+              The name of a sound that should be used as an example of
+              how this theme sounds like.
 	    </entry>
 	    <entry>string</entry>
 	    <entry>NO</entry>
@@ -254,9 +236,9 @@
 	</thead>
 	<tbody>
 	  <row>
-	    <entry>Size</entry>
+	    <entry>Length</entry>
 	    <entry>
-              Nominal size of the icons in this directory.
+              Nominal length in seconds of the sounds in this directory. (FIXME)
 	    </entry>
 	    <entry>integer</entry>
 	    <entry>YES</entry>
@@ -264,57 +246,12 @@
 	  <row>
 	    <entry>Context</entry>
 	    <entry>
-              The context the icon is normally used in. This 
+              The context the icon is normally used in. This
               is in detail discussed in <xref linkend="context"/>.
 	    </entry>
 	    <entry>string</entry>
 	    <entry>NO</entry>
 	  </row>
-	  <row>
-	    <entry>Type</entry>
-	    <entry>
-              The type of icon sizes for the icons in this
-              directory. Valid types are Fixed, Scalable and
-              Threshold. The type decides what other keys in the
-              section are used. If not specified, the default is
-              Threshold.
-	    </entry>
-	    <entry>string</entry>
-	    <entry>NO</entry>
-	  </row>
-	  <row>
-	    <entry>MaxSize</entry>
-	    <entry>
-              Specifies the maximum size that the icons in this
-              directory can be scaled to. Defaults to the value
-              of Size if not present.
-	    </entry>
-	    <entry>integer</entry>
-	    <entry>NO</entry>
-	    <entry>Scalable</entry>
-	  </row>
-	  <row>
-	    <entry>MinSize</entry>
-	    <entry>
-              Specifies the minimum size that the icons in this
-              directory can be scaled to. Defaults to the value
-              of Size if not present.
-	    </entry>
-	    <entry>integer</entry>
-	    <entry>NO</entry>
-	    <entry>Scalable</entry>
-	  </row>
-	  <row>
-	    <entry>Threshold</entry>
-	    <entry>
-              The icons in this directory can be used if the size differ
-              at most this much from the desired size. Defaults to 2 if not
-              present.
-	    </entry>
-	    <entry>integer</entry>
-	    <entry>NO</entry>
-	    <entry>Threshold</entry>
-	  </row>
 	</tbody>
       </tgroup>
     </table>
@@ -324,13 +261,13 @@
     index.theme file in order to extend it. These extensions must
     begin with "X-", and can be used to add desktop specific
     information to the theme file. Example group names would be "X-KDE
-    Icon Theme" or "X-Gnome Icon Theme".
+    Sound Theme" or "X-Gnome Sound Theme".
     </para>
     <para>
-    The optional filename.icon file contains a group called "Icon
+    The optional filename.sound file contains a group called "Sound
     Data", with the content listed in table 3.
     <table>
-      <title>Icon Data Keys</title>
+      <title>Sound Data Keys</title>
       <tgroup cols="4">
 	<thead>
 	  <row>
@@ -350,42 +287,12 @@
 	    <entry>localestring</entry>
 	    <entry>NO</entry>
 	  </row>
-	  <row>
-	    <entry>EmbeddedTextRectangle</entry>
-	    <entry>
-              If this exists, it specifies the four corners of a
-              rectangle where the program displaying the icon can
-              embed text. This is normally used by e.g. file managers
-              that want to display a preview of text file contents in
-              the icon. The corners are specified by a list of four
-              values: x0,y0,x1,y1. The values are pixel coordinates
-              from the top left corner of the icon, except for SVG
-              files, where they are specified in a 1000x1000
-              coordinate space that is scaled to the final rendered
-              size of the icon.
-	    </entry>
-	    <entry>integers</entry>
-	    <entry>NO</entry>
-	  </row>
-	  <row>
-	    <entry>AttachPoints</entry>
-	    <entry>
-              A list of points, separated by "|" that may be used as
-              anchor points for emblems/overlays. The points are pixel
-              coordinates from the top left corner of the icon, except
-              for SVG files, where they are specified in a 1000x1000
-              coordinate space that is scaled to the final rendered
-              size of the icon.
-	    </entry>
-	    <entry>points</entry>
-	    <entry>NO</entry>
-	  </row>
 	</tbody>
       </tgroup>
     </table>
     </para>
     <para>
-    Extensions to the filename.icon file are allowed, but the
+    Extensions to the filename.sound file are allowed, but the
     keys must be begin with "X-" to avoid collisions with future
     standardized extensions to this format.
     </para>
@@ -393,10 +300,10 @@
     <sect2 id="context">
 	<title>Context</title>
 
-	<para>The <systemitem>Context</systemitem> allows 
-    	  the designer to group icons on a conceptual level. 
-	  It doesn't act as a namespace in the file system, such 
-	  that icons can have identical names, but allows 
+	<para>The <systemitem>Context</systemitem> allows
+    	  the designer to group sounds on a conceptual level.
+	  It doesn't act as a namespace in the file system, such
+	  that sounds can have identical names, but allows
 	  implementations to categorize and sort by it, for example.
  	</para>
 
@@ -405,87 +312,79 @@
 
 	  <listitem>
 	    <formalpara>
-	    <title>Actions</title>
-	    <para>Icons representing actions which the user initiates, such as <action>Save As</action>.</para>
+	    <title>Alerts</title>
+	    <para>Sounds to alert the user of an action or event
+	    which may have a major imact on the system or their
+	    current use case, such as
+	    <action>dialog-error</action>.</para>
 	    </formalpara>
 	  </listitem>
 
 	  <listitem>
 	    <formalpara>
-	    <title>Devices</title>
-	    <para>Icons representing real world devices, 
-		    such as printers and mice. It's not for 
-		    file system nodes such as character or block devices.</para>
+	    <title>Notifications</title>
+	    <para>Sounds to notify the user that the system, or their
+	    current use case has changed state in some way, e.g. new email
+	    arriving, new non-critical update available...</para>
 	    </formalpara>
 	  </listitem>
 
 	  <listitem>
 	    <formalpara>
-	      <title>FileSystems</title>
-	      <para>Icons for objects which are represented as 
-		 part of the file system. This is for example, 
-		 the local network, <quote>Home</quote>, 
-		 and <quote>Desktop</quote> folders.</para>
+	      <title>Support</title>
+	      <para>Sounds that give the user feedback on their
+	      actions. Sounds on window opening / closing for
+	      example.</para>
 	    </formalpara>
 	  </listitem>
 
-	  <listitem>
-	  <formalpara>
-	  <title>MimeTypes</title>
-	  <para>Icons representing MIME types.</para>
-	  </formalpara>
-	  </listitem>
-
 	</itemizedlist>
-		
+
     </sect2>
   </sect1>
 
-  <sect1 id="icon_lookup">
-    <title>Icon Lookup</title>
+  <sect1 id="sound_lookup">
+    <title>Sound Lookup</title>
     <para>
-    The icon lookup mechanism has two global settings, the list of
+    The sound lookup mechanism has two global settings, the list of
     base directories and the internal name of the current theme. Given
-    these we need to specify how to look up an icon file from the icon
-    name and the nominal size.
+    these we need to specify how to look up  sound file from the sound
+    name.
     </para>
     <para>
     The lookup is done first in the current theme, and then
-    recursively in each of the current theme's parents, and
-    finally in the default theme called "hicolor" (implementations may
-    add more default themes before "hicolor", but "hicolor" must be
-    last). As soon as there is an icon of any size that matches in a
-    theme, the search is stopped. Even if there may be an icon with a
-    size closer to the correct one in an inherited theme, we don't want
-    to use it. Doing so may generate an inconsistant change in an icon
-    when you change icon sizes (e.g. zoom in).
+    recursively in each of the current theme's parents, and finally in
+    the default theme called "freedesktop" (implementations may add
+    more default themes before "freedesktop", but "freedesktop" must
+    be last). As soon as there is a sound that matches in a theme, the
+    search is stopped.
     </para>
     <para>
     The lookup inside a theme is done in three phases. First all the
     directories are scanned for an exact match, e.g. one where the
-    allowed size of the icon files match what was looked up. Then all
-    the directories are scanned for any icon that matches the name. If
-    that fails we finally fall back on unthemed icons. If we fail to
-    find any icon at all it is up to the application to pick a good
+    locale of the sound match what was looked up. Then all
+    the directories are scanned for any sound that matches the name. If
+    that fails we finally fall back on unthemed sound. If we fail to
+    find any sound at all it is up to the application to pick a good
     fallback, as the correct choice depends on the context.
     </para>
     <para>
-    The exact algorithm (in pseudocode) for looking up an icon in a theme
-    (if the implementation supports SVG) is:
+    The exact algorithm (in pseudocode) for looking up a sound in a theme
+    (if the implementation supports OGG) is:
     <programlisting>
-FindIcon(icon, size) {
-  filename = FindIconHelper(icon, size, user selected theme);
+FindSound(sound, locale) {
+  filename = FindSoundHelper(sound, locale, user selected theme);
   if filename != none
     return filename
 
-  filename = FindIconHelper(icon, size, "hicolor");
+  filename = FindSoundHelper(sound, locale, "freedesktop");
   if filename != none
     return filename
 
-  return LookupFallbackIcon (icon)
+  return LookupFallbackSound (sound)
 }
-FindIconHelper(icon, size, theme) {
-  filename = LookupIcon (icon, size, theme)
+FindSoundHelper(sound, locale, theme) {
+  filename = LookupIcon (sound, locale, theme)
   if filename != none
     return filename
 
@@ -493,7 +392,7 @@ FindIconHelper(icon, size, theme) {
     parents = theme.parents
 
   for parent in parents {
-    filename = FindIconHelper (icon, size, parent)
+    filename = FindSoundHelper (sound, locale, parent)
     if filename != none
       return filename
   }
@@ -502,46 +401,32 @@ FindIconHelper(icon, size, theme) {
      </programlisting>
      With the following helper functions:
      <programlisting>
-LookupIcon (iconname, size, theme) {
+LookupSound (sound, locale, theme) {
   for each subdir in $(theme subdir list) {
     for each directory in $(basename list) {
-      for extension in ("png", "svg", "xpm") {
-        if DirectoryMatchesSize(subdir, size) {
-          filename = directory/$(themename)/subdir/iconname.extension
+      for extension in ("wav", "ogg") {
+        if DirectoryMatchesLocale(subdir, size) {
+          filename = directory/$(themename)/subdir/sound.extension
           if exist filename
 	    return filename
         }
       }
     }
   }
-  minimal_size = MAXINT
-  for each subdir in $(theme subdir list) {
-    for each directory in $(basename list) {
-      for extension in ("png", "svg", "xpm") {
-        filename = directory/$(themename)/subdir/iconname.extension
-        if exist filename and DirectorySizeDistance(subdir, size) &lt; minimal_size {
-	   closest_filename = filename
-	   minimal_size = DirectorySizeDistance(subdir, size)
-        }
-      }
-    }
-  }
-  if closest_filename set
-     return closest_filename
   return none
 }
 
-LookupFallbackIcon (iconname) {
+LookupFallbackSound (sound) {
   for each directory in $(basename list) {
-    for extension in ("png", "svg", "xpm") {
-      if exists directory/iconname.extension
-        return directory/iconname.extension
+    for extension in ("wav", "ogg") {
+      if exists directory/sound.extension
+        return directory/sound.extension
     }
   }
   return none
 }
 
-DirectoryMatchesSize(subdir, iconsize) {
+DirectoryMatchesLocale(subdir, locale) {
   read Type and size data from subdir
   if Type is Fixed
     return Size == iconsize
@@ -550,51 +435,34 @@ DirectoryMatchesSize(subdir, iconsize) {
   if Type is Threshold
     return Size - Threshold &lt;= iconsize &lt;= Size + Threshold
 }
-
-DirectorySizeDistance(subdir, size) {
-  read Type and size data from subdir
-  if Type is Fixed
-    return abs(Size - iconsize)
-  if Type is Scaled
-    if iconsize &lt; MinSize
-        return MinSize - iconsize
-    if iconsize &gt; MaxSize
-        return iconsize - MaxSize
-    return 0
-  if Type is Threshold
-    if iconsize &lt; Size - Threshold
-        return MinSize - iconsize
-    if iconsize &gt; Size + Threshold
-        return iconsize - MaxSize
-    return 0
-}
 </programlisting>
     </para>
     <para>
-    In some cases you don't always want to fall back to an icon in an
-    inherited theme. For instance, sometimes you look for a set of
-    icons, prefering any of them before using an icon from an inherited
-    theme. To support such operations implementations can contain a
-    function that finds the first of a list of icon names in the inheritance
-    hierarchy. I.E. It would look something like this:
+      In some cases you don't always want to fall back to a sound in
+      an inherited theme. For instance, sometimes you look for a set
+      of sounds, prefering any of them before using a sound from an
+      inherited theme. To support such operations implementations can
+      contain a function that finds the first of a list of sound names
+      in the inheritance hierarchy. I.E. It would look something like
+      this:
 <programlisting>
-FindBestIcon(iconList, size) {
-  filename = FindBestIconHelper(iconList, size, user selected theme);
+FindBestSound(soundlist, size) {
+  filename = FindBestSoundHelper(iconList, size, user selected theme);
   if filename != none
     return filename
 
-  filename = FindBestIconHelper(iconList, size, "hicolor");
+  filename = FindBestSoundHelper(iconList, size, "freedesktop");
   if filename != none
     return filename
 
   for icon in iconList {
-    filename = LookupFallbackIcon (icon)
+    filename = LookupFallbackSound (icon)
     if filename != none
       return filename
   }
   return none;
 }
-FindBestIconHelper(iconList, size, theme) {
+FindBestSoundHelper(soundlist, size, theme) {
   for icon in iconList {
     filename = LookupIcon (icon, size, theme)
     if filename != none
@@ -621,43 +489,19 @@ FindBestIconHelper(iconList, size, theme) {
     <title>Example</title>
     <para>
      Here is an example index.theme file:
-     <programlisting>[Icon Theme]
+     <programlisting>[Sound Theme]
 Name=Birch
-Name[sv]=Björk
-Comment=Icon theme with a wooden look
-Comment[sv]=Träinspirerat ikontema
+Name[fr]=Bouleau
+Comment=Sound theme using wooden instruments
+Comment[fr]=Theme utilisant des instruments en bois
 Inherits=wood,default
-Directories=48x48/apps,48x48/mimetypes,32x32/apps,scalable/apps,scalable/mimetypes
+Directories=
 
 [scalable/apps]
-Size=48
-Type=Scalable
-MinSize=1
-MaxSize=256
-Context=Applications
-
-[scalable/mimetypes]
-Size=48
-Type=Scalable
-MinSize=1
-MaxSize=256
-Context=MimeTypes
-
-[32x32/apps]
-Size=32
-Type=Fixed
-Context=Applications
-
-[48x48/apps]
-Size=48
-Type=Fixed
 Context=Applications
 
-[48x48/mimetypes]
-Size=48
-Type=Fixed
-Context=MimeTypes</programlisting>
-     The corresponding directory tree in the /usr/share/icons
+</programlisting>
+     The corresponding directory tree in the /usr/share/sounds
      directory could look like this:
      <programlisting>birch/index.theme
 birch/scalable/apps/mozilla.svg
@@ -686,17 +530,17 @@ AttachPoints=20,20|40,40|50,10|10,50</programlisting>
 
   </sect1>
 
-  <sect1 id="install_icons">
-    <title>Installing Application Icons</title>
+  <sect1 id="install_sounds">
+    <title>Installing Application Sounds</title>
     <para>
-    So, you're an application author, and want to install application icons
-    so that they work in the KDE and Gnome menus. Minimally you should install
-    a 48x48 icon in the hicolor theme. This means installing a PNG file in
-    $prefix/share/icons/hicolor/48x48/apps. Optionally you can install icons in different
-    sizes. For example, installing a svg icon in $prefix/share/icons/hicolor/scalable/apps
+    So, you're an application author, and you want to install sounds
+    so that they can be used by your application. Minimally you should install
+    the sound file in the "freedesktop" theme. This means installing a WAV file in
+    $XDG_DATA_DIRS/sounds/freedesktop/. Optionally you can install sounds in different
+    languages. For example, installing a svg icon in $prefix/share/icons/hicolor/scalable/apps
     means most desktops will have one icon that works for all sizes. You might even want to
     install icons with a look that matches other well known themes so your application
-    will fit in with some specific desktop environment. 
+    will fit in with some specific desktop environment.
     </para>
     <para>
     It is recommended that the icons installed in the hicolor theme look neutral,
@@ -717,7 +561,7 @@ AttachPoints=20,20|40,40|50,10|10,50</programlisting>
     information.
     </para>
     <para>
-    This caching can make it impossible for users to add icons without
+    This caching can make it impossible for users to add sounds without
     having to restart applications. In order to handle this, any
     implementation that does caching is required to look at the mtime
     of the toplevel icon directories when doing a cache lookup, unless
@@ -738,245 +582,16 @@ AttachPoints=20,20|40,40|50,10|10,50</programlisting>
     description files and removes a few references to kde in them.
     </para>
   </sect1>
-  
+
   <appendix id="changes">
     <title>Change history</title>
     <formalpara>
-      <title>Version 0.12, 24 December 2006, Octavio Alvarez</title>    
-      <para>
-	<itemizedlist>
-	  <listitem>
-	    <para>
-            Fixed "hicolor" lookup in the pseudocode, so it works with multiple
-            parents.
-	    </para>
-	  </listitem>
-	</itemizedlist>
-      </para>
-    </formalpara>
-    <formalpara>
-      <title>Version 0.11, 7 February 2006, Alexander Larsson</title>    
-      <para>
-	<itemizedlist>
-	  <listitem>
-	    <para>
-            Fixed icon lookup clarification to work with multiple inheritance.
-	    </para>
-	  </listitem>
-	</itemizedlist>
-      </para>
-    </formalpara>
-    <formalpara>
-      <title>Version 0.10, 7 February 2006, Alexander Larsson</title>    
-      <para>
-	<itemizedlist>
-	  <listitem>
-	    <para>
-            Clarify that icon lookup looks in all parent themes before
-            falling back to nonthemed icons.
-	    </para>
-	  </listitem>
-	  <listitem>
-	    <para>
-            Added lookup function that takes a list of icon names (FindBestIcon)
-	    </para>
-	  </listitem>
-	</itemizedlist>
-      </para>
-    </formalpara>
-    <formalpara>
-      <title>Version 0.9, 4 April 2005, Alexander Larsson</title>    
-      <para>
-	<itemizedlist>
-	  <listitem>
-	    <para>
-            Cleanups and fixes to language from Rodney Dawes and
-            Frans Englich.
-	    </para>
-	  </listitem>
-	  <listitem>
-	    <para>
-            Added section describing Contexts in more details (by
-            Frans Englich).
-	    </para>
-	  </listitem>
-	</itemizedlist>
-      </para>
-    </formalpara>
-    <formalpara>
-      <title>Version 0.8, 5 February 2004, Alexander Larsson</title>    
-      <para>
-	<itemizedlist>
-	  <listitem>
-	    <para>
-            Fix language problems as pointed out by Rodney Dawes and
-            Michael Terry.
-	    </para>
-	  </listitem>
-	  <listitem>
-	    <para>
-            Added background section.
-	    </para>
-	  </listitem>
-	</itemizedlist>
-      </para>
-    </formalpara>
-    <formalpara>
-      <title>Version 0.7, 13 September 2003, Heinrich Wendel</title>    
-      <para>
-	<itemizedlist>
-	  <listitem>
-	    <para>
-            Converted to basedir spec.
-	    </para>
-	  </listitem>
-	  <listitem>
-	    <para>
-            Changed type of MaxSize, MinSize and Threshold to integer.
-	    </para>
-	  </listitem>
-	  <listitem>
-	    <para>
-            Removed typo in code example.
-	    </para>
-	  </listitem>
-	  <listitem>
-	    <para>
-            Corrected path to default-icon-theme.
-	    </para>
-	  </listitem>
-	</itemizedlist>
-      </para>
-    </formalpara>
-    <formalpara>
-      <title>Version 0.6, 2 December 2002, Alexander Larsson</title>    
-      <para>
-	<itemizedlist>
-	  <listitem>
-	    <para>
-            Added Hidden key.
-	    </para>
-	  </listitem>
-	  <listitem>
-	    <para>
-            Removed multiple inheritance.
-	    </para>
-	  </listitem>
-	  <listitem>
-	    <para>
-            Renamed the default theme hicolor.
-	    </para>
-	  </listitem>
-	  <listitem>
-	    <para>
-            Added the application icon install section.
-	    </para>
-	  </listitem>
-	  <listitem>
-	    <para>
-            Fixed some xml issues.
-	    </para>
-	  </listitem>
-	</itemizedlist>
-      </para>
-    </formalpara>
-    <formalpara>
-      <title>Version 0.5, 18 September 2002, Alexander Larsson</title>    
-      <para>
-	<itemizedlist>
-	  <listitem>
-	    <para>
-            Added DisplayName to icon data.
-	    </para>
-	  </listitem>
-	  <listitem>
-	    <para>
-            Fixed up example svg icon data.
-	    </para>
-	  </listitem>
-	  <listitem>
-	    <para>
-            Fixed some spelling and grammar errors.
-	    </para>
-	  </listitem>
-	</itemizedlist>
-      </para>
-    </formalpara>
-    <formalpara>
-      <title>Version 0.4, 16 May 2002, Alexander Larsson</title>    
-      <para>
-	<itemizedlist>
-	  <listitem>
-	    <para>
-            Fixed some spelling and grammar errors.
-	    </para>
-	  </listitem>
-	</itemizedlist>
-      </para>
-    </formalpara>
-    <formalpara>
-      <title>Version 0.3, 14 May 2002, Alexander Larsson</title>    
-      <para>
-	<itemizedlist>
-	  <listitem>
-	    <para>
-            Made support for SVGs optional.
-	    </para>
-	  </listitem>
-	  <listitem>
-	    <para>
-            Added a default fallback theme.
-	    </para>
-	  </listitem>
-	  <listitem>
-	    <para>
-            Changed the example directory layout a bit to
-            match the default theme.
-	    </para>
-	  </listitem>
-	</itemizedlist>
-      </para>
-    </formalpara>
-    <formalpara>
-      <title>Version 0.2, 29 April 2002, Alexander Larsson</title>    
-      <para>
-	<itemizedlist>
-	  <listitem>
-	    <para>
-              Changed search order to png, svg, xpm.
-	    </para>
-	  </listitem>
-	  <listitem>
-	    <para>
-              Added comment to say that xpm is supported for backwards
-              compat and not recommended in new themes.
-	    </para>
-	  </listitem>
-	  <listitem>
-	    <para>
-              Default Type for a directory is now Threshold
-	    </para>
-	  </listitem>
-	  <listitem>
-	    <para>
-              Added implementation notes section.
-	    </para>
-	  </listitem>
-	  <listitem>
-	    <para>
-              Added Example key.
-	    </para>
-	  </listitem>
-	</itemizedlist>
-      </para>
-    </formalpara>
-    <formalpara>
-      <title>Version 0.1, 22 April 2002, Alexander Larsson</title>    
+      <title>Version 0.1, 11 February 2008, Marc-Andre Lureau</title>
       <para>
 	<itemizedlist>
 	  <listitem>
 	    <para>
-              Created initial draft.
+	      Initial draft.
 	    </para>
 	  </listitem>
 	</itemizedlist>