[gsound] admin: Update README.md

[Tristan Brindle <tbrindle src gnome org>]

commit 9be29b12b2296944a1ee1d029decf21987605e6f
Author: Tristan Brindle <t c brindle gmail com>
Date:   Mon Dec 1 15:12:10 2014 +0800

    admin: Update README.md

 README.md |  126 +++++++++++++++++++++++++++++++++++++++++++-----------------
 1 files changed, 90 insertions(+), 36 deletions(-)
---
diff --git a/README.md b/README.md
index b2f0667..ed308a6 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,26 @@
-#GSound
+GSound
+======
 
-##What is it?
+What is it?
+-----------
 
-GSound is a small library for playing system sounds. It's designed to be used via GObject Introspection, and 
is a thin wrapper around the [libcanberra](http://0pointer.de/lennart/projects/libcanberra/) C library.
+GSound is a small library for playing system sounds. It's designed to be
+used via GObject Introspection, and is a thin wrapper around the 
[libcanberra](http://0pointer.de/lennart/projects/libcanberra/) C library.
 
-The reference documentation can be found at https://tcbrindle.github.io/gsound-docs
+Homepage: https://wiki.gnome.org/Projects/GSound
+
+Documentation: https://developer.gnome.org/gsound/stable
+
+Source: https://git.gnome.org/browse/gsound
+
+Bugs: https://bugzilla.gnome.org/enter_bug.cgi?product=gsound
 
 ##Usage via GObject Introspection.
 
-As GSound is based on libcanberra it shares a similar API. To use it, you first create and initialise a 
GSound context. You then pass the context a list of (attribute, value) pairs instructing it what to play, 
like so in Python:
+As GSound is based on libcanberra it shares a similar API. To use it,
+you first create and initialise a GSound context. You then pass the
+context a list of (attribute, value) pairs instructing it what to play,
+like so in Python:
 
 ```Python
 from gi.repository import GSound
@@ -38,21 +50,42 @@ try {
 }
 ```
 
-The list of supported attributes can be found in gsound-attr.h, and can be used via GSound.ATTR_* string 
constants if the target language supports this.
+The list of supported attributes can be found in 
+[gsound-attr.h](https://developer.gnome.org/gsound/stable/gsound-GSound-Attributes.html),
+and can be used via GSound.ATTR_* string constants if the target
+language supports this.
 
-## Playing Sounds
+Playing Sounds
+--------------
 
-There are two very similar play commands, `GSound.Context.play_simple()` and the corresponding `play_full()`.
+There are two very similar play commands, `GSound.Context.play_simple()`
+and the corresponding `play_full()`.
 
-The "full" version is an asynchronous function following the GIO model. It takes a callback argument which 
will be called when the sound has finished playing. As with other GIO async functions, you should call 
`GSound.Context.play_finish()` within the callback in order to receive any exceptions which might have 
occurred during playback; note that cancelling playback will result in a `Gio.IOError.CANCELLED` exception 
(or something similar).
+The "full" version is an asynchronous function following the GIO model.
+It takes a callback argument which will be called when the sound has
+finished playing. As with other GIO async functions, you should call
+`GSound.Context.play_finish()` within the callback in order to receive
+any exceptions which might have occurred during playback; note that
+cancelling playback will result in a `Gio.IOError.CANCELLED` exception
+(or something similar).
 
-On the other hand, `play_simple()` does not give you any feedback when the sound finishes. However, it will 
still report any errors which occurred before the sound was submitted to the server (with `play_full()`, 
these are reported in the callback).
+On the other hand, `play_simple()` does not give you any feedback when
+the sound finishes. However, it will still report any errors which
+occurred before the sound was submitted to the server (with
+`play_full()`, these are reported in the callback).
 
-It's important to note that both versions are non-blocking and will return control to your application 
immediately, without waiting for the sound to finish playing (or even start, really).
+It's important to note that both versions are non-blocking and will
+return control to your application immediately, without waiting for the
+sound to finish playing (or even start, really).
 
-##Usage in Vala
+Usage in Vala
+-------------
 
-GSound can be used in Vala via the included VAPI file. The API is slightly different from other introspected 
languages. Since Vala supports varargs, these are used to pass attribute-value pairs rather than 
`GHashTable`s. One neat feature as that since `play_full()` is a proper async function, it can be used with 
`yield` like so:
+GSound can be used in Vala via the included VAPI file. The API is
+slightly different from other introspected languages. Since Vala supports
+varargs, these are used to pass attribute-value pairs rather than
+`GHashTable`s. One neat feature as that since `play_full()` is a proper
+async function, it can be used with `yield` like so:
 
 ```Vala
 public async void play(string filename,
@@ -65,11 +98,16 @@ public async void play(string filename,
 }
 ```
 
-(Note that libcanberra comes with it's own VAPI file, which you could use instead.)
+(Note that libcanberra comes with it's own VAPI file, which you could use
+instead.)
 
-##Usage in C
+Usage in C
+-----------
 
-As a C library, GSound can of course be used from C and C++. If your project is already using  GObject 
libraries then you'll find the style fits right in. Like Vala, the C API uses varargs to pass attributes to 
the backend, for example (error checking omitted for brevity):
+As a C library, GSound can of course be used from C and C++. If your project
+is already using  GObject libraries then you'll find the style fits right in
+Like Vala, the C API uses varargs to pass attributes to the backend, for
+example (error checking omitted for brevity):
 
 ```C
 GSoundContext *ctx = gsound_context_new(NULL, NULL);
@@ -79,34 +117,50 @@ gsound_context_play_simple(ctx, NULL, NULL;
                            NULL);
 ```
 
-##License:
-
-    This program is free software; you can redistribute it and/or modify it
-    under the terms of the GNU Lesser General Public License as published
-    by the Free Software Foundation, either version 2.1 of the License, or
-    (at your option) any later version.
+License
+-------
 
-    This program is distributed in the hope that it will be useful, but
-    WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
-    General Public License for more details.
+> This program is free software; you can redistribute it and/or modify it
+> under the terms of the GNU Lesser General Public License as published
+> by the Free Software Foundation, either version 2.1 of the License, or
+> (at your option) any later version.
 
-#Prerequisites:
+> This program is distributed in the hope that it will be useful, but
+> WITHOUT ANY WARRANTY; without even the implied warranty of
+> MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
+> General Public License for more details.
 
-Building GSound from git requires a fairly modern Gnome development environment; so far it's only been 
tested on Fedora 20. At a minimum, you'll need headers 
-for GObject (at least 2.36.0) and libcanberra, as well as the needed machinery to generate GObject 
introspection data and the Vala VAPI. 
+Prerequisites
+-------------
 
-#Differences from libcanberra
+Building GSound from git requires a fairly modern Gnome development
+environment; so far it's only been tested on Fedora 20. At a minimum,
+you'll need headers for GObject (at least 2.36.0) and libcanberra, as well
+as the needed machinery to generate GObject introspection data and the Vala
+VAPI. 
 
-GSound wraps the libcanberra API very closely, with the following differences:
+Differences from libcanberra
+----------------------------
 
-1) Attribute/value pairs are passed using `GHashTable`s instead of `ca_proplists`. This is because most GI 
consumers have automatic conversion from native associative array types (e.g. Python's `dict`) to 
`GHashTable`. The Vala and C APIs instead use varargs, as libcanberra does in those languages.
+GSound wraps the libcanberra API very closely, with the following
+differences:
 
-2) Errors are reported using GErrors rather than using integer return values. Most GI consumers map GErrors 
to native exceptions, and they work mostly like exceptions in Vala too.
+1) Attribute/value pairs are passed using `GHashTable`s instead of
+   `ca_proplists`. This is because most GI consumers have automatic conversion
+   from native associative array types (e.g. Python's `dict`) to `GHashTable`.
+   The Vala and C APIs instead use varargs, as libcanberra does in those
+   languages.
 
-3) Callbacks use the standard GIO async pattern (i.e. call a finish() function on a GAsyncResult that's 
handed to a callback you supply).
+2) Errors are reported using `GError`s rather than using integer return values.
+   Most GI consumers map `GError`s to native exceptions, and they work mostly like
+   exceptions in Vala too.
 
-4) GCancellables are used for cancelling sounds in progress, again for consistency with GIO.
+3) Callbacks use the standard GIO async pattern (i.e. call a `finish()` function
+   on a `GAsyncResult` that's handed to a callback you supply).
 
-5) What libcanberra calls "properties" are called "attributes" in GSound to avoid confusing them with 
GObject properties. The actual strings (e.g. "media.filename") are the same, however.
+4) `GCancellable`s are used for cancelling sounds in progress, again for
+   consistency with GIO.
 
+5) What libcanberra calls "properties" are called "attributes" in GSound to
+   avoid confusing them with GObject properties. The actual strings (e.g.
+   "media.filename") are the same, however.