Updated code comments + documentation to include key binding examples.

Makefile

@@ -26,10 +26,10 @@ install:
 	@echo "	   You should now edit your $(AWESOME_CFG_DIR)/rc.lua to require the couth"
 	@echo "	   modules that you want to use, and bind them to key bindings."
 	@echo
-	@echo "	    -- you MUST require this to use ANY couth modules: "
+	@echo "	   -- you MUST require this to use ANY couth modules: "
 	@echo "	   require('couth.couth') "
 	@echo
-	@echo "	    -- These are optional. Only require the ones that you want to use. "
+	@echo "	   -- These are optional. Only require the ones that you want to use. "
 	@echo "	   require('couth.alsa') "
 	@echo "	   require('couth.mpc') "
 	@echo	

README.rst

@@ -46,4 +46,66 @@ Installation
 - Run ``make install`` to create symlinks from ``$HOME/.config/awesome/couth``
   to lib directory where you installed the actual files (``$PWD/lib``).
 
-- Configure your ``rc.lua`` to map keybindings to couth functions.
+- Configure your ``rc.lua`` to add::
+
+    -- you MUST require this to use ANY couth modules:
+    require('couth.couth')
+
+    -- These are optional. Only require the ones that you want to use.
+    require('couth.alsa')
+    require('couth.mpc')
+
+- Update your ``rc.lua`` to add a couth.CONFIG section to customize couth, and
+  then add key bindings to couth functions.
+
+----------------------
+rc.lua configuration
+----------------------
+
+I have this in my rc.lua to specify the alsa controls to use with the
+couth.alsa plugin::
+
+    couth.CONFIG.ALSA_CONTROLS = {
+         'Master',
+         'Headphone',
+         'PCM',
+         'Front'
+    }
+
+Search for ``couth.CONFIG`` in ``lib/couth.lua`` to see all the available
+configuration options.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+couth.alsa key binding examples
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here is an example of using your keyboard volume +/- buttons to
+increase/decrease your Master alsa volume. This also binds the mute key on your
+keyboard to toggle the mute/unmute status of your Master volume.::
+
+    awful.key({ }, "XF86AudioLowerVolume",   function () couth.notifier:notify( couth.alsa:setVolume('Master','3dB-')) end),
+    awful.key({ }, "XF86AudioRaiseVolume",   function () couth.notifier:notify( couth.alsa:setVolume('Master','3dB+')) end),
+    awful.key({ }, "XF86AudioMute",          function () couth.notifier:notify( couth.alsa:setVolume('Master','toggle')) end),
+
+I bind control + volume keys to adjust my Headphone volume::
+
+    awful.key({ "Control" }, "XF86AudioLowerVolume",    function () couth.notifier:notify( couth.alsa:setVolume('Headphone','3dB-')) end),
+    awful.key({ "Control" }, "XF86AudioRaiseVolume",    function () couth.notifier:notify( couth.alsa:setVolume('Headphone','3dB+')) end),
+    awful.key({ "Control" }, "XF86AudioMute",           function () couth.notifier:notify( couth.alsa:setVolume('Headphone','toggle')) end),
+
+
+See current volume levels (but do not change any of them)::
+
+    awful.key({ modkey }, "v",                       function () couth.notifier:notify( couth.alsa:getVolume() ) end),
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+couth.mpc key binding examples
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This example binds modkey + shift + volume keys to increase/decrease or view
+the volume on the mpd server running on a host named "pizza"::
+
+    awful.key({ modkey, "Shift" }, "XF86AudioLowerVolume",    function () couth.notifier:notify( couth.mpc:setVolume('pizza','-5')) end),
+    awful.key({ modkey, "Shift" }, "XF86AudioRaiseVolume",    function () couth.notifier:notify( couth.mpc:setVolume('pizza','+5')) end),
+    awful.key({ modkey, "Shift" }, "v",                       function () couth.notifier:notify( couth.mpc:getVolume('pizza') ) end)
+

lib/couth.lua

@@ -19,6 +19,8 @@ if not couth then couth = {} end
 if not couth.CONFIG then 
   couth.CONFIG = {
 
+		-- The width of your volume indicators (the max number of | characters to
+		-- display)
     INDICATOR_MAX_BARS = 20,
 
     -- these are the alsa controls that can be controlled or displayed
@@ -31,6 +33,8 @@ if not couth.CONFIG then
       'PCM',
     },
 
+		-- The font to use for notifications. You should use a mono-space font so
+		-- the columns are evenly aligned.
     NOTIFIER_FONT = 'mono 22',
     NOTIFIER_POSITION = 'top_right',
     NOTIFIER_TIMEOUT = 5,