Merge sound-theme from git://git.0pointer.de/sound-theme-spec.gitsound-theme

4 files changed, 1952 insertions, 0 deletions

diff --git a/sound-theme/.gitignore b/sound-theme/.gitignore
new file mode 100644
index 0000000..2d19fc7
--- /dev/null
+++ b/sound-theme/.gitignore
@@ -0,0 +1 @@
+*.html
diff --git a/sound-theme/Makefile b/sound-theme/Makefile
new file mode 100644
index 0000000..c53e3e9
--- /dev/null
+++ b/sound-theme/Makefile
@@ -0,0 +1,9 @@
+DOCS = sound-naming-spec.html sound-theme-spec.html
+
+%.html: %.xml
+	xsltproc http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl $< > $@
+
+all: $(DOCS)
+
+clean:
+	rm -f $(DOCS)
diff --git a/sound-theme/sound-naming-spec.xml b/sound-theme/sound-naming-spec.xml
new file mode 100644
index 0000000..d94e593
--- /dev/null
+++ b/sound-theme/sound-naming-spec.xml
@@ -0,0 +1,1186 @@
+<?xml version="1.0"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<article id="index">
+  <articleinfo>
+    <title>Sound Naming Specification</title>
+    <releaseinfo>Post-0.3 Snapshot</releaseinfo>
+    <date>Post 2008</date>
+    <authorgroup>
+      <author>
+	<firstname>Marc-Andre</firstname>
+	<surname>Lureau</surname>
+	<authorblurb><para>Sound Naming Specification</para></authorblurb>
+	<affiliation>
+	  <address>
+	    <email>marcandre.lureau@gmail.com</email>
+	  </address>
+	</affiliation>
+      </author>
+      <author>
+	<firstname>Lennart</firstname>
+	<surname>Poettering</surname>
+	<authorblurb><para>PulseAudio Project</para></authorblurb>
+	<affiliation>
+	  <address>
+	    <email>lennart@poettering.net</email>
+	  </address>
+	</affiliation>
+      </author>
+      <author>
+	<firstname>Rodney</firstname>
+	<surname>Dawes</surname>
+	<authorblurb><para>Icon Naming Specification</para></authorblurb>
+	<affiliation>
+	  <address>
+	    <email>dobey.pwns@gmail.com</email>
+	  </address>
+	</affiliation>
+      </author>
+      <author>
+	<firstname>Jon</firstname>
+	<surname>Bold</surname>
+	<authorblurb><para>Bango! Project</para></authorblurb>
+	<affiliation>
+	  <address>
+	    <email>jon.wordescapes@co.uk</email>
+	  </address>
+	</affiliation>
+      </author>
+    </authorgroup>
+  </articleinfo>
+
+  <sect1 id="overview">
+    <title>Overview</title>
+    <para>
+This specification gives direction on how to name the sounds that are
+available for use by applications, when creating a sound theme. It
+does so by laying out a standard naming scheme for sound creation, as
+well as providing a minimal list of must have sounds, and a larger
+list with many more examples to help with the creation of extended
+sounds for third party applications, with different event types and
+usage.
+    </para>
+  </sect1>
+
+  <sect1 id="context">
+    <title>Context</title>
+
+    <para>
+      The list of default contexts for the sound theme are:
+    </para>
+
+    <table>
+      <title>Standard Contexts</title>
+
+      <tgroup cols="3">
+	<thead>
+	  <row>
+	    <entry>Name</entry>
+	    <entry>Description</entry>
+	    <entry>Directory</entry>
+	  </row>
+	</thead>
+	<tbody>
+	  <row>
+	    <entry>Alerts</entry>
+	    <entry>
+	      Sounds to alert the user of an action or event which may
+	      have a major impact on the system or their current use,
+	      such as <action>dialog-error</action>.
+	    </entry>
+	    <entry>alert</entry>
+	  </row>
+	  <row>
+	    <entry>Notifications</entry>
+	    <entry>
+	      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...
+	    </entry>
+	    <entry>notification</entry>
+	  </row>
+	  <row>
+	    <entry>Actions</entry>
+	    <entry>
+	      Sounds that give the user feedback on their
+	      actions.
+	    </entry>
+	    <entry>action</entry>
+	  </row>
+	  <row>
+	    <entry>Input Feedback</entry>
+	    <entry>
+	      Sounds that give direct response to input events from the user, such as mouse clicks or key presses.
+	    </entry>
+	    <entry>action</entry>
+	  </row>
+	  <row>
+	    <entry>Game</entry>
+	    <entry>
+	      Sound used in games.
+	    </entry>
+	    <entry>game</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </table>
+  </sect1>
+
+  <sect1 id="guidelines">
+    <title>Sound Naming Guidelines</title>
+
+    <para>
+      Here we define some guidelines for when creating new sounds that
+      extend the standardized list of sound names defined here, in
+      order to provide sounds for more specific events and usages.
+      <itemizedlist>
+	<listitem>
+	  <para>
+	    Sound names are in the en_US.US_ASCII locale. This means
+	    that the characters allowed in the sound names must
+	    fall within the US-ASCII character set. As a further
+	    restriction, all sound names may only contain lowercase
+	    letters, numbers, underscore, dash, or period
+	    characters. Spaces, colons, slashes, and backslashes are
+	    not allowed. Also, sound names must be spelled as they are
+	    in the en_US dictionary.
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	    The dash <quote>-</quote> character is used to separate
+	    levels of specificity in sound names.  For instance, we
+	    use <quote>search-results</quote> as the generic item for
+	    all search results, and we use
+	    <quote>search-results-empty</quote> for an empty search
+	    result. However, if the more specific item does not exist
+	    in the current theme, and does exist in a parent theme,
+	    the generic sound from the current theme is preferred, in
+	    order to keep consistent style. From left to right the
+	    words in a sound name become more specific. In some cases
+	    what word in a name is more specific is
+	    ambiguous. (i.e. "dialog-error" and "error-dialog" both
+	    make sense, the former would ease defining the same sound
+	    for all dialogs popping up, regardless of its context, the
+	    latter would ease defining the same sound for all errors,
+	    regardless of how it is presented to the user). In such
+	    cases it is generally preferred to put the UI element noun
+	    left -- if there is one --, however exceptions of this
+	    rule are acceptable.
+	  </para>
+	</listitem>
+        <listitem>
+          <para>
+	    Sounds for branded applications should be named the same
+	    as the binary executable for the application, prefixed by
+	    the string <quote>x-</quote>, to avoid name space clashes with future
+	    standardized names. Example: <quote>x-openoffice-foobar</quote>.
+	  </para>
+	</listitem>
+        <listitem>
+          <para>
+            Please send suggestions for new standardized names to the XDG mailing list: <email>xdg@lists.freedesktop.org</email>
+          </para>
+        </listitem>
+      </itemizedlist>
+    </para>
+  </sect1>
+
+  <sect1 id="names">
+    <title>Standard Sounds Names</title>
+
+    <para>
+      This section describes the standard sounds names that should be
+      used by artists when creating themes, and by developers when
+      writing applications which will use the Sound Theme
+      Specification.
+    </para>
+
+    <sect2 id="alerts">
+      <title>Alerts</title>
+      <para>
+	This is to notify the user of an action or event which may
+	have a major impact on the system or their current use case.
+      </para>
+
+      <table id="alerts-table">
+	<title>Standard Alert Sounds</title>
+	<tgroup cols="2">
+	  <thead>
+	    <row>
+	      <entry>Name</entry>
+	      <entry>Description</entry>
+	    </row>
+	  </thead>
+	  <tbody>
+	    <row>
+	      <entry>network-connectivity-lost</entry>
+	      <entry>
+		The sound used when network connectivity is lost.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>network-connectivity-error</entry>
+	      <entry>
+		The sound used when an error occurs when it is tried
+		to initialize the network connection of the computing
+		device.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>dialog-error</entry>
+	      <entry>
+		The sound used when a dialog is opened to explain an
+		error condition to the user.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>battery-low</entry>
+	      <entry>
+		The sound used when the battery is low (below 20%, for
+		example).
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>suspend-error</entry>
+	      <entry>
+		The machine failed to suspend.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>software-update-urgent</entry>
+	      <entry>
+		The sound used when an urgent update is available
+		through the system software update program.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>power-unplug-battery-low</entry>
+	      <entry>
+		The power cable has been unplugged and the battery level is low.
+	      </entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+    </sect2>
+
+    <sect2 id="notification">
+      <title>Notifications</title>
+      <para>
+	This is to alert the user that the system, or their current
+	use case has changed state in some way - mew email arriving,
+	new non-critical update to an application available.
+      </para>
+
+      <table id="notifications-table">
+	<title>Standard Notifications Sounds</title>
+	<tgroup cols="2">
+	  <thead>
+	    <row>
+	      <entry>Name</entry>
+	      <entry>Description</entry>
+	    </row>
+	  </thead>
+	  <tbody>
+	    <row>
+	      <entry>message-new-instant</entry>
+	      <entry>
+		The sound used when a new IM is recieved.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>message-new-email</entry>
+	      <entry>
+		The sound used when a new email is recieved.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>complete-media-burn</entry>
+	      <entry>
+		The sound used when an optical medium completed burning.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>complete-media-burn-test</entry>
+	      <entry>
+		The sound used when an optical medium completed a dummy burn run.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>complete-media-rip</entry>
+	      <entry>
+		The sound used when an (optical) medium completed ripping.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>complete-media-format</entry>
+	      <entry>
+		The sound used when a disk/medium completed formatting/blanking.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>complete-download</entry>
+	      <entry>
+		The sound used when a file completed downloading.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>complete-copy</entry>
+	      <entry>
+		The sound used when a file completed copying.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>complete-scan</entry>
+	      <entry>
+		The sound used when a scanner completed image acquisition and software completed image processing.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>phone-incoming-call</entry>
+	      <entry>
+		The sound used when an phone/voip call is coming in. Usually some kind of ring sound.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>phone-outgoing-busy</entry>
+	      <entry>
+		The sound used when a phone/voip call is dialed out and the responder is not available.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>phone-hangup</entry>
+	      <entry>
+		The sound used when a phone/voip call is ended due to hangup.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>phone-failure</entry>
+	      <entry>
+		The sound used when a phone/voip call is canceled due to some error.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>network-connectivity-established</entry>
+	      <entry>
+		The sound used when network connectivity is established.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>system-bootup</entry>
+	      <entry>
+		The sound used when the computer is being booted up, played as as early in bootup as possible.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>system-ready</entry>
+	      <entry>
+		The sound used when the computer is booted up and shows the login screen.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>system-shutdown</entry>
+	      <entry>
+		The sound used when the computer is being shut down.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>search-results</entry>
+	      <entry>
+		The sound used when one or more search results are
+		returned.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>search-results-empty</entry>
+	      <entry>
+		The sound used when no search results are returned.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>desktop-login</entry>
+	      <entry>
+		The sound used when a user logs into the system, played as a welcome sound immediately after the login screen disappeared.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>desktop-logout</entry>
+	      <entry>
+		The sound used when a user logs out of the system.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>desktop-screen-lock</entry>
+	      <entry>
+		The sound used when the user locks their current
+		session.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>service-login</entry>
+	      <entry>
+		The sound used when a user logs into a service
+		(i.e. Gaim login)
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>service-logout</entry>
+	      <entry>
+		The sound used when a user logs out of a service
+		(i.e. Gaim logout)
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>battery-caution</entry>
+	      <entry>
+		The sound used when the battery is nearing exhaustion (below 40%, for
+		example)
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>battery-full</entry>
+	      <entry>
+		The sound used when the battery is fully loaded up.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>dialog-warning</entry>
+	      <entry>
+		The sound used when a dialog is opened to give
+		information to the user that may be pertinent to the
+		requested action.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>dialog-information</entry>
+	      <entry>
+		The sound used when a dialog is opened to give
+		information to the user that may be pertinent to the
+		requested action.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>dialog-question</entry>
+	      <entry>
+		The sound used when a dialog is opened to ask the user a question.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>software-update-available</entry>
+	      <entry>
+		The sound used when an update is available for
+		software installed on the computing device, through
+		the system software update program.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>device-added</entry>
+	      <entry>
+		The sound used when a device has become available to the desktop, i.e. due to USB plugging.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>device-added-audio</entry>
+	      <entry>
+		The sound used when an audio device has become available to the desktop, i.e. due to USB plugging.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>device-added-media</entry>
+	      <entry>
+		The sound used when a disk/medium has become available to the desktop, i.e. due to USB plugging.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>device-removed</entry>
+	      <entry>
+		The sound used when a device has become unavailable to the desktop, i.e. due to USB unplug.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>device-removed-media</entry>
+	      <entry>
+		The sound used when a disk/medium has become unavailable to the desktop, i.e. due to USB unplug.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>device-removed-audio</entry>
+	      <entry>
+		The sound used when an audio device has become unavailable to the desktop, i.e. due to USB unplug.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>window-new</entry>
+	      <entry>
+		The sound used when a new window or dialog is opened.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>power-plug</entry>
+	      <entry>
+		The power cable has been plugged in.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>power-unplug</entry>
+	      <entry>
+		The power cable has been unplugged.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>suspend-start</entry>
+	      <entry>
+		The machine is about to suspend.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>suspend-resume</entry>
+	      <entry>
+		The machine has returned from suspended state.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>lid-open</entry>
+	      <entry>
+		The lid has been opened (for laptops, mobile devices)
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>lid-close</entry>
+	      <entry>
+		The lid has been closed (for laptops, mobile devices)
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>alarm-clock-elapsed</entry>
+	      <entry>
+		A user configured alarm elapsed.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>window-attention-active</entry>
+	      <entry>
+		An active/visible window demands attention.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>window-attention-inactive</entry>
+	      <entry>
+		An inactive/invisible window demands attention.
+	      </entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+    </sect2>
+
+    <sect2 id="actions">
+      <title>Actions</title>
+      <para>
+	Action sounds are used as feedback for user operations.
+      </para>
+
+      <table id="actions-table">
+	<title>Standard Action Sounds</title>
+	<tgroup cols="2">
+	  <thead>
+	    <row>
+	      <entry>Name</entry>
+	      <entry>Description</entry>
+	    </row>
+	  </thead>
+	  <tbody>
+	    <row>
+	      <entry>phone-outgoing-calling</entry>
+	      <entry>
+		The sound used when a phone/voip call is dialed out.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>message-sent-instant</entry>
+	      <entry>
+		The sound used when a new IM is sent.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>message-sent-email</entry>
+	      <entry>
+		The sound used when a new email is sent.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>bell-terminal</entry>
+	      <entry>
+		The sound to use as a terminal bell.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>bell-window-system</entry>
+	      <entry>
+		The sound to use as a generic bell for X11 or other window systems.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>trash-empty</entry>
+	      <entry>
+		The sound used when the user empties the trash.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>item-deleted</entry>
+	      <entry>
+		The sound used when a item is deleted.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>file-trash</entry>
+	      <entry>
+		The sound used when a file or folder is sent to the
+		trash.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>camera-shutter</entry>
+	      <entry>
+		A photo has been shot.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>camera-focus</entry>
+	      <entry>
+		A camera has the focus.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>screen-capture</entry>
+	      <entry>
+		A screenshot was made.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>count-down</entry>
+	      <entry>
+		A countdown (e.g. for a photo shooting) sound that is repeated each second.
+	      </entry>
+	    </row>
+            <row>
+              <entry>completion-sucess</entry>
+	      <entry>
+                A text completion was attempted and was successful.
+	      </entry>
+	    </row>
+            <row>
+              <entry>completion-fail</entry>
+	      <entry>
+                A text completion was attempted and was not successful.
+	      </entry>
+	    </row>
+            <row>
+              <entry>completion-partial</entry>
+	      <entry>
+                A text completion was attempted and was partially successful.
+	      </entry>
+	    </row>
+            <row>
+              <entry>completion-rotation</entry>
+	      <entry>
+                A text completion was attempted and the list of available options reached the end and completion started from the beginning.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>audio-volume-change</entry>
+	      <entry>
+		The test sound that is used to make volume changes noticeable by the user when he uses a volume slider.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>audio-channel-left</entry>
+	      <entry>
+		The test sound for identifying the left speaker. A mono file with a voice saying "left".
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>audio-channel-right</entry>
+	      <entry>
+		The test sound for identifying the right speaker. A mono file with a voice saying "right".
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>audio-channel-front-left</entry>
+	      <entry>
+		The test sound for identifying the front-left speaker. A mono file with a voice saying "front left".
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>audio-channel-front-right</entry>
+	      <entry>
+		The test sound for identifying the front-right speaker. A mono file with a voice saying "front right".
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>audio-channel-front-center</entry>
+	      <entry>
+		The test sound for identifying the front-center speaker. A mono file with a voice saying "front center".
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>audio-channel-rear-left</entry>
+	      <entry>
+		The test sound for identifying the front-left speaker. A mono file with a voice saying "rear left".
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>audio-channel-rear-right</entry>
+	      <entry>
+		The test sound for identifying the front-right speaker. A mono file with a voice saying "rear right".
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>audio-channel-rear-center</entry>
+	      <entry>
+		The test sound for identifying the front-center speaker. A mono file with a voice saying "rear center".
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>audio-channel-lfe</entry>
+	      <entry>
+		The test sound for identifying the lfe/subwoofer speaker. A mono file with a voice saying "subwoofer", alternatively a low frequency noise.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>audio-channel-side-left</entry>
+	      <entry>
+		The test sound for identifying the side-left speaker. A mono file with a voice saying "side left".
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>audio-channel-side-right</entry>
+	      <entry>
+		The test sound for identifying the side-right speaker. A mono file with a voice saying "side right".
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>audio-test-signal</entry>
+	      <entry>
+		The test sound for testing audio.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>theme-demo</entry>
+	      <entry>
+                A sound that should be played for demoing this
+                theme. Usually this should just be an alias for a very
+                representative sound (such as desktop-login) of a theme that would work nicely
+                as a demo sound for a theme in the theme selector
+                dialog.
+	      </entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+    </sect2>
+
+    <sect2 id="inputfeedback">
+      <title>Input Feedback</title>
+      <para>
+	Actions sounds are used as feedback for user input events,
+	such as mouse clicks, or key presses. In contrast to the
+	sounds listed as "Actions" these sounds contain much less
+	context information are are solely used to give the user
+	audible feedback to input events the user himself directly
+	caused.
+      </para>
+
+      <table id="inputfeedback-table">
+	<title>Standard Input Feedback Sounds</title>
+	<tgroup cols="2">
+	  <thead>
+	    <row>
+	      <entry>Name</entry>
+	      <entry>Description</entry>
+	    </row>
+	  </thead>
+	  <tbody>
+	    <row>
+	      <entry>window-close</entry>
+	      <entry>
+		The sound used when an existing window is closed.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>window-slide-in</entry>
+	      <entry>
+		The sound used when a window is slided in by some means. Example: panel.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>window-slide-out</entry>
+	      <entry>
+		The sound used when a window is slided out by some means. Example: panel.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>window-minimized</entry>
+	      <entry>
+		The sound used when an existing window is minimized.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>window-unminimized</entry>
+	      <entry>
+		The sound used when an existing window is unminimized.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>window-maximized</entry>
+	      <entry>
+		The sound used when an existing window is maximized.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>window-unmaximized</entry>
+	      <entry>
+		The sound used when an existing window is unmaximized.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>window-inactive-click</entry>
+	      <entry>
+		The sound used when the user clicks on an inactive window.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>window-move-start</entry>
+	      <entry>
+		A window move started.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>window-move-end</entry>
+	      <entry>
+		A window move ended.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>window-resize-start</entry>
+	      <entry>
+		A window resize started.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>window-resize-end</entry>
+	      <entry>
+		A window resize ended.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>desktop-switch-left</entry>
+	      <entry>
+		The sound used when the window manager switches to another desktop which is located to the left of the current screen.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>desktop-switch-right</entry>
+	      <entry>
+		The sound used when the window manager switches to another desktop which is located to the right of the current screen.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>window-switch</entry>
+	      <entry>
+		The sound used when the window manager switches to another window.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>notebook-tab-changed</entry>
+	      <entry>
+		The sound used when a notebook tab is changed.
+	      </entry>
+	    </row>
+            <row>
+              <entry>scroll-up</entry>
+	      <entry>
+                Some window was scrolled up.
+	      </entry>
+	    </row>
+            <row>
+              <entry>scroll-down</entry>
+	      <entry>
+                Some window was scrolled down.
+	      </entry>
+	    </row>
+            <row>
+              <entry>scroll-left</entry>
+	      <entry>
+                Some window was scrolled left.
+	      </entry>
+	    </row>
+            <row>
+              <entry>scroll-right</entry>
+	      <entry>
+                Some window was scrolled right.
+	      </entry>
+	    </row>
+            <row>
+              <entry>scroll-up-end</entry>
+	      <entry>
+                Some window was scrolled up and reached the end of the scrollbar.
+	      </entry>
+	    </row>
+            <row>
+              <entry>scroll-down-end</entry>
+	      <entry>
+                Some window was scrolled down and reached the end of the scrollbar.
+	      </entry>
+	    </row>
+            <row>
+              <entry>scroll-left-end</entry>
+	      <entry>
+                Some window was scrolled left and reached the end of the scrollbar.
+	      </entry>
+	    </row>
+            <row>
+              <entry>scroll-right-end</entry>
+	      <entry>
+                Some window was scrolled right and reached the end of the scrollbar.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>dialog-ok</entry>
+	      <entry>
+		The sound used when a windows is closed by clicking on the OK button for a window.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>dialog-cancel</entry>
+	      <entry>
+		The sound used when a windows is closed by clicking on the Cancel button for a window.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>drag-start</entry>
+	      <entry>
+		The sound used when drag of a file/item is started.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>drag-accept</entry>
+	      <entry>
+		The sound used when a file/item drag is accepted by a window,
+		such as a folder or IM conversation.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>drag-fail</entry>
+	      <entry>
+		The sound used when a file/item drag is not accepted by a window,
+		such as a folder or IM conversation.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>link-pressed</entry>
+	      <entry>
+		The sound used when a link in a web or help browser is pressed.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>link-released</entry>
+	      <entry>
+		The sound used when a link in a web or help browser is releaed.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>button-pressed</entry>
+	      <entry>
+		The sound used when a button is pressed.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>button-released</entry>
+	      <entry>
+		The sound used when a button is released.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>menu-click</entry>
+	      <entry>
+		The sound used when a menu item is clicked.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>button-toggle-on</entry>
+	      <entry>
+		The sound used when a toggle/check/radio button is activated.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>button-toggle-off</entry>
+	      <entry>
+		The sound used when a toggle/check/radio button is deactivated.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>expander-toggle-on</entry>
+	      <entry>
+		The sound used when an expander is activated.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>expander-toggle-off</entry>
+	      <entry>
+		The sound used when an expander is deactivated.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>menu-popup</entry>
+	      <entry>
+		The sound used when a menu is popped up.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>menu-popdown</entry>
+	      <entry>
+		The sound used when a menu is popped down.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>menu-replace</entry>
+	      <entry>
+		The sound used when replacing an active menu with another menu.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>tooltip-popup</entry>
+	      <entry>
+		The sound used when a tooltip is popped up.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>tooltip-popdown</entry>
+	      <entry>
+		The sound used when a tooltip is popped down.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>item-selected</entry>
+	      <entry>
+		The sound used when an item is selected.
+	      </entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+    </sect2>
+
+
+    <sect2 id="games">
+      <title>Game</title>
+      <para>
+      Sounds for usage in games.
+      </para>
+
+      <table id="games-table">
+	<title>Standard Games Sounds</title>
+	<tgroup cols="2">
+	  <thead>
+	    <row>
+	      <entry>Name</entry>
+	      <entry>Description</entry>
+	    </row>
+	  </thead>
+	  <tbody>
+	    <row>
+	      <entry>game-over-winner</entry>
+	      <entry>
+		Guess what...!
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>game-over-loser</entry>
+	      <entry>
+		Guess what...!
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>game-card-shuffle</entry>
+	      <entry>
+		In card games, when the cards are shuffled.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>game-human-move</entry>
+	      <entry>
+		When the user makes a move.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>game-computer-move</entry>
+	      <entry>
+		When the a computer makes a move.
+	      </entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="background">
+    <title>Background</title>
+    <para>
+    The sound naming specification is heavily based on the "Icon
+    Naming Specification" by Rodney Dawes and the "Bango Project"
+    started by Jon Bolt.
+    </para>
+  </sect1>
+
+  <appendix id="changelog">
+    <title>Change History</title>
+    <formalpara>
+      <title>Version 0.3, 25 July 2008, Lennart Poettering</title>
+      <para>
+        <itemizedlist>
+          <listitem>
+	    <para>
+              Split out section about "Input Feedback" sounds.
+	    </para>
+	  </listitem>
+          <listitem>
+	    <para>
+              Document the logic behind choosing "dialog-error" instead of "error-dialog".
+	    </para>
+	  </listitem>
+	</itemizedlist>
+      </para>
+    </formalpara>
+    <formalpara>
+      <title>Version 0.2, 4 June 2008, Marc-Andre Lureau and Lennart Poettering</title>
+      <para>
+        <itemizedlist>
+          <listitem>
+	    <para>
+              Naming changes.
+	    </para>
+	  </listitem>
+	</itemizedlist>
+      </para>
+    </formalpara>
+    <formalpara>
+      <title>Version 0.1, February 12 2008, Marc-Andre Lureau</title>
+      <para>
+        <itemizedlist>
+          <listitem>
+	    <para>
+              Created initial draft.
+	    </para>
+	  </listitem>
+	</itemizedlist>
+      </para>
+    </formalpara>
+  </appendix>
+</article>
+<!-- TODO: inverting naming--><!-- TODO: jack sensing -->
diff --git a/sound-theme/sound-theme-spec.xml b/sound-theme/sound-theme-spec.xml
new file mode 100644
index 0000000..5aa1d4f
--- /dev/null
+++ b/sound-theme/sound-theme-spec.xml
@@ -0,0 +1,756 @@
+<?xml version="1.0"?>
+<!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>Sound Theme Specification</title>
+    <releaseinfo>Post-0.5 Snapshot</releaseinfo>
+    <date>Post 2008</date>
+    <authorgroup>
+      <author>
+	<firstname>Marc-Andre</firstname>
+	<surname>Lureau</surname>
+	<authorblurb><para>Sound Theme Specification</para></authorblurb>
+	<affiliation>
+	  <address>
+	    <email>marcandre.lureau@gmail.com</email>
+	  </address>
+	</affiliation>
+      </author>
+      <author>
+	<firstname>Lennart</firstname>
+	<surname>Poettering</surname>
+	<authorblurb><para>PulseAudio Project</para></authorblurb>
+	<affiliation>
+	  <address>
+	    <email>lennart@poettering.net</email>
+	  </address>
+	</affiliation>
+      </author>
+      <author>
+	<firstname>Patryk</firstname>
+	<surname>Zawadzki</surname>
+	<authorblurb><para>Initial Sound Theme Specification draft proposal</para></authorblurb>
+	<affiliation>
+	  <address>
+	    <email>patrys@pld-linux.org</email>
+	  </address>
+	</affiliation>
+      </author>
+      <author>
+	<firstname>Alexander</firstname>
+	<surname>Larsson</surname>
+	<authorblurb><para>Icon Theme Specification author</para></authorblurb>
+	<affiliation>
+	  <address>
+	    <email>alexl@redhat.com</email>
+	  </address>
+	</affiliation>
+      </author>
+      <author>
+	<firstname>Frans</firstname>
+	<surname>Englich</surname>
+	<authorblurb><para>Icon Theme Specification author</para></authorblurb>
+	<affiliation>
+	  <address>
+	    <email>frans.englich@telia.com</email>
+	  </address>
+	</affiliation>
+      </author>
+    </authorgroup>
+  </articleinfo>
+
+  <sect1 id="overview">
+    <title>Overview</title>
+    <para>
+    A sound theme is a set of event sounds that share a common feel,
+    or instrument set.  The user can then select the sound theme that
+    they want to use, and all applications use sounds from the theme.
+    </para>
+    <para>
+    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 a sound filename.
+    </para>
+  </sect1>
+
+  <sect1 id="definitions">
+    <title>Definitions</title>
+    <variablelist>
+      <varlistentry>
+	<term>Sound Theme</term>
+	<listitem>
+	  <para>
+          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>Sound file</term>
+	<listitem>
+	  <para>
+          The mandatory supported sound file formats are WAV/PCM
+          8-48kHz, 8/16bits, and OGG/Vorbis I. WAV at 48kHz/Stereo is
+          the recommended uncompressed format, and OGG/Vorbis I is the
+          recommended compressed format.  The sample must be
+          normalized, in order to be mixed down nicely with a suitable
+          average replay level.
+	  </para>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>Base Directory</term>
+	<listitem>
+	  <para>
+          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>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+  </sect1>
+
+  <sect1 id="directory_layout">
+    <title>Directory Layout</title>
+    <para>
+    Sounds and themes are looked for in a set of directories. By
+    default, applications 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 sounds there should always exist a theme called
+    "freedesktop". The data for the freedesktop theme is available for
+    download
+    at: <ulink url="http://www.freedesktop.org/software/sound-theme/"><citetitle>freedesktop.org
+    sound theme specification page</citetitle></ulink>.
+    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
+    directories. The internal name of the theme is the name of the
+    subdirectory, although the user-visible name as specified by the
+    theme may be different. Hence, theme names are case sensitive, and
+    are limited to ASCII characters. Theme names may also not contain
+    comma or space.
+    </para>
+    <para>
+    In at least one of the theme directories there must be a file
+    called index.theme that describes the theme. The first index.theme
+    found while searching the base directories in order is used. This
+    file describes the general attributes of the theme.
+    </para>
+    <para>
+    In the theme directory are also a set of subdirectories containing
+    sound files. The subdirectories are allowed to be several levels
+    deep, e.g. the subdirectory "stereo/alerts" in the theme "freedesktop"
+    would end up at $basedir/freedesktop/stereo/alerts.
+    </para>
+    <para>
+    The sounds files must be one of the types: WAV/PCM 8-48kHz, 8/16
+    bits or OGG/Vorbis I.  The extension must be ".wav", or ".oga"
+    respectively (in lower case). It is not recommended to use ".ogg"
+    extension, but it is also supported for legacy reasons.
+    </para>
+    <para>
+    Besides the sound files, there may be an additional file with
+    extra 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-shutdown.wav" the corresponding file would
+    be named "system-shutdown.sound".
+    </para>
+    <para>
+    Finally, a pseudo file format ".disabled" is used for disabling
+    sounds in a theme that inherits from another theme. If the sound
+    lookup algorithms detects a file with the suffix ".disabled" it
+    shall immediately terminate the lookup logic and consider the
+    sound not available. All files with ".disabled" suffix should be
+    of length zero.
+    </para>
+    <para>
+    To save disk space Vorbis I encoded sound files are recommended.
+    </para>
+    <para>
+    The sound samples must be normalized with a suitable average
+    replay level, in order to be properly mixed down. For more
+    informations, please read
+    <ulink url="http://replaygain.hydrogenaudio.org/calculating_rg.html"><citetitle>Replay
+    Gain Calculation from hydrogenaudio.org</citetitle></ulink> and
+    check that your volume level is reasonable.
+    </para>
+    <para>
+    Sounds for different output profiles (i.e. for Stereo, Surround
+    4.1, Surround 5.1 and so on) may be part of a theme. All
+    implementations are required to fallback to the "stereo" output
+    profile as last resort.
+    </para>
+  </sect1>
+
+  <sect1 id="file_formats">
+    <title>File Formats</title>
+    <para>
+    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 an 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>Sound Theme</citetitle>, with contents according to
+    table 1 below. All lists are comma-separated.
+    <table>
+      <title>Standard Keys</title>
+      <tgroup cols="4">
+	<thead>
+	  <row>
+	    <entry>Key</entry>
+	    <entry>Description</entry>
+	    <entry>Value Type</entry>
+	    <entry>Required</entry>
+	  </row>
+	</thead>
+	<tbody>
+	  <row>
+	    <entry>Name</entry>
+	    <entry>
+              Short name of the sound theme, used in e.g. lists when
+              selecting themes.
+	    </entry>
+	    <entry>localestring</entry>
+	    <entry>YES</entry>
+	  </row>
+	  <row>
+	    <entry>Comment</entry>
+	    <entry>
+              Longer string describing the theme
+	    </entry>
+	    <entry>localestring</entry>
+	    <entry>YES</entry>
+	  </row>
+	  <row>
+	    <entry>Inherits</entry>
+	    <entry>
+              <para>
+              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 "freedesktop" theme to the inheritance tree. An implementation
+              may optionally add other default themes in between the last
+              specified theme and the freedesktop theme.
+              </para>
+	    </entry>
+	    <entry>strings</entry>
+	    <entry>NO</entry>
+	  </row>
+	  <row>
+	    <entry>Directories</entry>
+	    <entry>
+             List of subdirectories for this theme. For every
+             subdirectory there must be a section in the index.theme
+             file describing that directory.
+	    </entry>
+	    <entry>strings</entry>
+	    <entry>YES</entry>
+	  </row>
+	  <row>
+	    <entry>Hidden</entry>
+	    <entry>
+            Whether to hide the theme in a theme selection user interface.
+            This is used for things such as fallback-themes that are not supposed
+            to be visible to the user.
+	    </entry>
+	    <entry>boolean</entry>
+	    <entry>NO</entry>
+	  </row>
+	  <row>
+	    <entry>Example</entry>
+	    <entry>
+              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>
+	  </row>
+	</tbody>
+      </tgroup>
+    </table>
+    </para>
+    <para>
+    Each directory specified in the Directory key has a corresponding section
+    with the same name as the directory. The contents of this section is
+    listed in table 2 below.
+    <table>
+      <title>Per-Directory Keys</title>
+      <tgroup cols="4">
+	<thead>
+	  <row>
+	    <entry>Key</entry>
+	    <entry>Description</entry>
+	    <entry>Value Type</entry>
+	    <entry>Required</entry>
+	    <entry>Type</entry>
+	  </row>
+	</thead>
+	<tbody>
+	  <row>
+	    <entry>Context</entry>
+	    <entry>
+              The context the sound is normally used in. This
+              is in detail discussed in <xref linkend="context"/>.
+	    </entry>
+	    <entry>string</entry>
+	    <entry>NO</entry>
+	  </row>
+	  <row>
+	    <entry>OutputProfile</entry>
+	    <entry>
+	      Define the output profile for which the sounds are made
+	      for. It can be "stereo" or "5.1", or any other output configuration.
+	    </entry>
+	    <entry>string</entry>
+	    <entry>NO</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </table>
+    </para>
+    <para>
+    In addition to these groups you may add extra groups to the
+    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
+    Sound Theme" or "X-Gnome Sound Theme".
+    </para>
+    <para>
+    The optional file filename.sound contains a group "Sound
+    Data", with the content listed in table 3.
+    <table>
+      <title>Sound Data Keys</title>
+      <tgroup cols="4">
+	<thead>
+	  <row>
+	    <entry>Key</entry>
+	    <entry>Description</entry>
+	    <entry>Value Type</entry>
+	    <entry>Required</entry>
+	  </row>
+	</thead>
+	<tbody>
+	  <row>
+	    <entry>DisplayName</entry>
+	    <entry>
+              A translated UTF8 string that can be displayed instead
+              of the sound by a user interface.
+	    </entry>
+	    <entry>localestring</entry>
+	    <entry>NO</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </table>
+    </para>
+    <para>
+    Extensions to filename.sound are allowed, but the
+    keys must be begin with "X-" to avoid collisions with future
+    standardized extensions to this format.
+    </para>
+
+    <sect2 id="context">
+	<title>Context</title>
+
+	<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>
+
+	<para>These are the available contexts:</para>
+	<itemizedlist>
+
+	  <listitem>
+	    <formalpara>
+	    <title>Alert</title>
+	    <para>Sounds to alert the user of an action or event
+	    which may have a major impact on the system or their
+	    current use, such as
+	    <action>dialog-error</action>.</para>
+	    </formalpara>
+	  </listitem>
+
+	  <listitem>
+	    <formalpara>
+	    <title>Notification</title>
+	    <para>Sounds to notify the user that the system, or their
+	    current use has changed state in some way, e.g. new email
+	    arriving, new non-critical updates available...</para>
+	    </formalpara>
+	  </listitem>
+
+	  <listitem>
+	    <formalpara>
+	      <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>Game</title>
+	      <para>Sounds used for games.</para>
+	    </formalpara>
+	  </listitem>
+
+	</itemizedlist>
+
+    </sect2>
+  </sect1>
+
+  <sect1 id="sound_lookup">
+    <title>Sound Lookup</title>
+    <para>
+    The sound lookup mechanism has two global settings, the list of
+    base directories and the internal name of the current theme. Given
+    these we 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 "freedesktop" (implementations may add
+    more default themes before "freedesktop", but "freedesktop" must
+    be last). A last fallback is unthemed sound. As soon as there is
+    a sound that matches in a theme, the search is stopped.
+    </para>
+    <para>
+    To support localized sounds we first lookup the sound in the
+    LC_MESSAGES locale setting of the program. If that fails, the
+    locale string is truncated at the "@" if it includes it and it is
+    tried again. Then, the locale string is truncated at the "_" if it
+    includes it and it is tried again. Then it is looked for a sound
+    in the "C" locale. Finally non-localized sound files are searched.
+    </para>
+    <para>
+    If a sound name is not found, it is truncated at the last "-" and
+    it is tried again. This is done again until no further "-" are
+    present in the name string. This is useful to define common sounds
+    for similar events. i.e. instead of defining two seperate sounds
+    for "new-message-im" and "new-message-email" it might make sense
+    to define just "new-message" instead.
+    </para>
+    <para>
+    The lookup is done first in the requested output profile, followed
+    by a lookup in "stereo" on failure and then without any output
+    profile.
+    </para>
+    <para>
+    The lookup algorithm should check for ".disabled" files first,
+    followed by ".oga" (then ".ogg", although this might be removed
+    later) and finally for ".wav".
+    </para>
+    <para>
+    Configuration programs that allow limited user manipulation of the
+    selected sound theme (i.e. for disabling or replacing certain
+    sounds), should create a dynamicly created theme "__custom" that
+    inherits from the selected theme and store it in the
+    "~/.local/share/sounds/__custom" directory. Its index.theme should
+    list a single directory ".". The sounds defined in that theme
+    should not be attached to any output profile and should not be
+    localized. The overwritten sounds should thus be stored directly
+    below the aforementioned directory.
+    </para>
+    <para>
+    The exact algorithm (in pseudocode) for looking up a sound in a
+    theme is:
+
+    <programlisting>
+FindSound(sound, locale, outputprofile, theme) {
+  filename = LookupSound (sound, locale, outputprofile, theme)
+  if filename != none
+    return filename
+
+  if theme has parents
+    for parent in theme.parents {
+      filename = LookupSound (sound, locale, outputprofile, parent)
+      if filename != none
+        return filename
+    }
+
+  return none
+}
+     </programlisting>
+
+     With the following helper functions:
+
+     <programlisting>
+LookupSound (requestedname, requestedlocale, requestedoutputprofile, requestedtheme) {
+  for theme in (requestedtheme,
+                "freedesktop",
+                "") {
+    for profile in (requestedoutputprofile, "stereo", "") {
+      for each subdir in $(theme subdir list) {
+        if DirectoryMatchesOutputProfile(subdir, profile) {
+          for each directory in $(basename list) {
+            for each name in (requestedname,
+                              truncatesuffix(requestedname, "-"),
+                              truncatesuffix(truncatesuffix(requestedname, "-"), "-"),
+                              truncatesuffix(truncatesuffix(truncatesuffix(requestedname, "-"), "-"), "-"),
+                              ...) {
+              for each locale in (requestedlocale,
+                                  truncatesuffix(requestedlocale, "@"),
+                                  truncatesuffix(requestedlocale, "_"),
+                                  "C",
+                                  "") {
+                for extension in ("disabled", "oga", "ogg", "wav") {
+	          filename = directory/theme/subdir/locale/name.extension
+                  if exist filename
+                    return filename
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return none
+}
+
+DirectoryMatchesOutputProfile(subdir, profile) {
+  read OutputProfile from subdir
+  if OutputProfile == profile
+    return true
+  return false
+}
+</programlisting>
+
+    </para>
+  </sect1>
+
+  <sect1 id="example">
+    <title>Example</title>
+    <para>
+     Here is an example index.theme file:
+     <programlisting>
+[Sound Theme]
+Name=Birch
+Name[fr]=Bouleau
+Comment=Sound theme using wooden instruments
+Comment[fr]=Theme utilisant des instruments en bois
+Inherits=wood,default
+Directories=stereo 5.1
+
+[stereo]
+OutputProfile=stereo
+
+[5.1]
+OutputProfile=5.1
+</programlisting>
+
+The corresponding directory tree in the /usr/share/sounds
+directory could look like this:
+
+<programlisting>
+birch/index.theme
+birch/stereo/evolution-urgent-message.oga
+birch/stereo/evolution-urgent-message.wav
+birch/stereo/fr/evolution-urgent-message.oga
+birch/stereo/evolution-urgent-message.sound
+birch/5.1/evolution-urgent-message.oga
+</programlisting>
+
+Where birch/stereo/evolution-urgent-message.sound contains:
+
+<programlisting>
+[Sound Data]
+DisplayName=Evolution urgent message
+DisplayName[fr]=Message urgent dans Evolution
+</programlisting>
+
+    </para>
+    <para>
+    In this example a lookup of "evolution-urgent-message", with a 5.1
+    system preference and no localization, would get the
+    "birch/5.1/evolution-urgent-message.oga" sound file.
+    </para>
+
+  </sect1>
+
+  <sect1 id="install_sounds">
+    <title>Installing Application Sounds</title>
+    <para>
+    If you're an application author and you want to install sounds
+    so that they can be used by your application, you should
+    at least install the sound file in the "freedesktop" theme. This means
+    installing a stereo WAV file in
+    $XDG_DATA_DIRS/sounds/freedesktop/stereo/.
+    </para>
+    <para>
+    Optionally you can install sounds in different formats and
+    languages. For example, installing a localized OGG/Vorbis 5.1 game
+    sound in $prefix/share/sounds/freedesktop/5.1/fr.
+    </para>
+    <para>
+    You might even want to install sounds that match other well
+    known themes so your application will fit in with some specific
+    desktop environment.
+    </para>
+    <para>
+    It is recommended that the sounds installed in the freedesktop
+    theme sound neutral, since it is a fallback theme that will be
+    used in combination with some very different sounds from any
+    origin. But if you don't have any neutral sound, please install
+    whatever sound you have in the freedesktop theme so that all your
+    application can at least produce some sounds in all themes.
+    </para>
+    <para>
+    After installing/updating a sound in a theme directory, make sure
+    to update the mtime of the theme directory itself (i.e. touch
+    $XDG_DATA_DIRS/sounds/freedesktop or similar), so that caches can
+    be kept up-to-date.
+    </para>
+  </sect1>
+
+  <sect1 id="implementation_notes">
+    <title>Implementation Notes</title>
+    <para>
+    The algorithm as described in this document works by always
+    looking up filenames in directories (a stat in unix
+    terminology). A good implementation is expected to read the
+    directories once, and do all lookups in memory using that
+    information.
+    </para>
+    <para>
+    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 sound theme directories when doing a cache
+    lookup, unless it already did so less than 5 seconds ago. This
+    means that any sound editor or theme installation program may
+    change the mtime of the the toplevel theme directory (such as
+    $XDG_DATA_DIRS/sounds/freedesktop) where it changed the theme to
+    make sure that the new sounds will eventually get used.
+    </para>
+  </sect1>
+
+  <sect1 id="background">
+    <title>Background</title>
+    <para>
+    The sound theme specification is heavily based on the "Icon Theme
+    Specification" by Alexander Larsson and Frans Englich.
+    </para>
+  </sect1>
+
+  <appendix id="changes">
+    <title>Change history</title>
+    <formalpara>
+      <title>Version 0.5, 2 September 2008, Marc-Andre Lureau</title>
+      <para>
+	<itemizedlist>
+	  <listitem>
+	    <para>
+	      Deprecate usage of ".ogg" extension in favor of ".oga"
+	      (according
+	      to <ulink url="http://wiki.xiph.org/index.php/MIME_Types_and_File_Extensions"><citetitle>MIME
+	      Types and File Extensions from xiph.org</citetitle></ulink>)
+	    </para>
+	  </listitem>
+	</itemizedlist>
+      </para>
+    </formalpara>
+    <formalpara>
+      <title>Version 0.4, 29 July 2008, Lennart Poettering</title>
+      <para>
+	<itemizedlist>
+	  <listitem>
+	    <para>
+	      Document that every time a theme is updated to changed the directory needs to be touched.
+	    </para>
+	  </listitem>
+	</itemizedlist>
+      </para>
+    </formalpara>
+    <formalpara>
+      <title>Version 0.3, 25 July 2008, Lennart Poettering</title>
+      <para>
+	<itemizedlist>
+	  <listitem>
+	    <para>
+	      Reordered lookup algorithm, to allow easy overwriting of sounds from inherited themes.
+	    </para>
+	  </listitem>
+	  <listitem>
+	    <para>
+	      Document "__custom" theme.
+	    </para>
+	  </listitem>
+	  <listitem>
+	    <para>
+	      Document ".disabled" sound files.
+	    </para>
+	  </listitem>
+	  <listitem>
+	    <para>
+	      Other fixes
+	    </para>
+	  </listitem>
+	</itemizedlist>
+      </para>
+    </formalpara>
+    <formalpara>
+      <title>Version 0.2, 4 June 2008, Marc-Andre Lureau and Lennart Poettering</title>
+      <para>
+	<itemizedlist>
+	  <listitem>
+	    <para>
+	      Updated the Lookup algorithm.
+	    </para>
+	  </listitem>
+	  <listitem>
+	    <para>
+	      Remove Length and Locale from directory property.
+	    </para>
+	  </listitem>
+	  <listitem>
+	    <para>
+	      Use OutputProfile instead of SoundSystem.
+	    </para>
+	  </listitem>
+	  <listitem>
+	    <para>
+	      Add ReplayGain note.
+	    </para>
+	  </listitem>
+	</itemizedlist>
+      </para>
+    </formalpara>
+    <formalpara>
+      <title>Version 0.1, 11 February 2008, Marc-Andre Lureau</title>
+      <para>
+	<itemizedlist>
+	  <listitem>
+	    <para>
+	      Initial draft.
+	    </para>
+	  </listitem>
+	</itemizedlist>
+      </para>
+    </formalpara>
+  </appendix>
+</article>