Updated readme

README.md

@@ -1,2 +0,0 @@
-# A collection of StumpWM modules
-

media/amixer/README.org

@@ -0,0 +1,17 @@
+** USAGE
+ Make sure you have your media keys (or whatever) mapped to the appropriate
+ keysyms (using =xmodmap=), then put:
+#+BEGIN_SRC lisp
+     (load "/path/to/amixer.lisp")
+#+END_SRC
+ ...in your =~/.stumpwmrc=, followed by some keybindings (according
+ to your preference)
+
+** Tasks
+
+*** TODO Make the `defvolcontrol' macro create all the necessary commands at once.
+ - Should it just create, say, amixer-pcm, which would be passed an
+   argument? i.e., (define-key *this-map* (kbd "e") "amixer-pcm 1-")
+ - Else, figure out how to make the macro not error when converting a
+   string to a symbol for the name of the command
+

media/aumix/README.org

@@ -0,0 +1,9 @@
+** Usage
+Put:
+#+BEGIN_SRC lisp
+    (load-module "aumix")
+#+END_SRC
+In your =~/.stumpwmrc=
+
+** Tasks
+*** TODO Document This module

minor-mode/mpd/README.org

@@ -0,0 +1,25 @@
+** Usage
+Put:
+#+BEGIN_SRC 
+    (load-module "mpd")
+#+END_SRC
+into your =~/.stumpwmrc=
+
+Then you can use "%m" in your mode line format, as well as various commands
+defined at the end of the file.
+
+You can customize the modeline format (*mpd-modeline-fmt*), the status
+message displayed by the command mpd-status (*mpd-status-fmt*; note that
+this is also used on the modeline), and the status message displayed by the
+command mpd-current-song (*mpd-current-song-fmt*). See the documentation for
+*mpd-modeline-fmt* for more information.
+
+** Notes
+
+See http://mpd.wikia.com/wiki/Protocol_Reference for full protocol
+
+** Tasks
+*** TODO Implement optional shortening for formatting functions
+*** TODO Implement notification window on song change etc...
+
+

minor-mode/notifications/README.org

@@ -0,0 +1,51 @@
+** Usage
+This StumpWM module acts as notification monitor for external applications.
+ They can send messages via `stumpish' which will be displayed in the
+ mode-line.  (Thus `stumpish' has to be in your PATH.)
+
+ To use it add this to your ~/.stumpwmrc.lisp:
+#+BEGIN_SRC lisp
+(load-module "notifications")
+#+END_SRC
+
+Then add the formatter %N to your mode-line spec, i.e. like this:
+
+#+BEGIN_SRC lisp
+   (setf *screen-mode-line-format* "[%W] {%g} (%N)")
+#+END_SRC
+
+You might want to bind *notifications-map* to a key:
+
+#+BEGIN_SRC lisp
+   (define-key *root-map* (kbd "N") '*notifications-map*)
+#+END_SRC
+
+ With this map you can add notifications with a, reset them with r, delete
+ the first/last with d/D or show them in a popup with s.
+
+ External applications can add notification messages using stumpish:
+#+BEGIN_SRC sh
+   $ stumpish notifications-add 'Foo Bar Baz'
+#+END_SRC
+
+For example this is the elisp code that I use to let rcirc (an Emacs IRC
+client) notify me when a message with my nickname or a IM message arrives:
+#+BEGIN_SRC lisp
+ (defun th-rcirc-notification (process sender response target text)
+   (let ((my-nick (rcirc-nick process)))
+     (when (and (string= response "PRIVMSG")
+                (not (string= sender my-nick))
+                (or
+                 ;; BitlBee IM messages
+                 (string-match "localhost" (format "%s" process))
+                 ;; Messages that mention my name
+                 (string-match my-nick text)))
+       (th-notifications-add (concat "rcirc: " target)))))
+
+ (add-hook 'rcirc-print-hooks 'th-rcirc-notification)
+
+ (defun th-notifications-add (str)
+   (interactive "sNotification: ")
+   (start-process "notifications-add" nil
+                  "stumpish" "notifications-add" str))
+#+END_SRC

modeline/battery-portable/README.org

@@ -0,0 +1,15 @@
+** Usage
+To load this module, place
+#+BEGIN_SRC lisp
+    (load-module "battery-portable")
+#+END_SRC
+
+in your =.stumpwmrc=. Battery information is then available via %B
+in your mode-line config.
+
+If you have an older kernel and the above doesn't work, add
+#+BEGIN_SRC lisp
+    (setf stumpwm.contrib.battery-portable:*prefer-sysfs* nil)
+#+END_SRC
+below the above line.
+

modeline/battery/README.org

@@ -0,0 +1,12 @@
+** Usage
+Put:
+#+BEGIN_SRC lisp
+(load-module "battery")
+#+END_SRC
+In your =~/.stumpwmrc=
+
+Then you can use "%b" in your mode line format.
+
+** Notes
+This is specific to Linux.
+

modeline/cpu/README.org

@@ -0,0 +1,12 @@
+** Usage
+Put:
+#+BEGIN_SRC lisp
+(load-module "cpu")
+#+END_SRC
+In your =~/.stumpwmrc=
+
+Then you can use "%c %t" in your mode line format.
+
+** Notes
+
+This is specific to Linux.

modeline/disk/README.org

@@ -0,0 +1,26 @@
+** Usage
+
+Put:
+#+BEGIN_SRC 
+    (load-module "disk")
+#+END_SRC
+
+into your =~/.stumpwmrc=
+
+Then you can use "%D" in your mode line format.
+You can customize the modeline format (*disk-modeline-fmt*). 
+
+The default value for displaying disk usage information on the modeline.
+
+|------+----------------------------------|
+| Code | Result                           |
+|------+----------------------------------|
+| %%   | A literal '%'                    |
+| %d   | Filesystem device                |
+| %s   | Filesystem size                  |
+| %u   | Filesystem used space            |
+| %a   | Filesystem available space       |
+| %p   | Filesystem used space in percent |
+| %m   | Filesystem mount point           |
+|------+----------------------------------|
+

modeline/maildir/README.org

@@ -0,0 +1,15 @@
+** Usage
+
+Put:
+#+BEGIN_SRC lisp
+    (load-module "maildir")
+#+END_SRC
+into your =~/.stumpwmrc=
+
+Then you can use "%M" in your mode line format.
+You can customize the modeline format (*maildir-modeline-fmt*). See the
+documentation for *maildir-modeline-fmt* for more information.
+
+** Tasks
+*** TODO Add per mailbox formatter
+

modeline/mem/README.org

@@ -0,0 +1,14 @@
+** Usage
+
+Put:
+#+BEGIN_SRC lisp
+(load-module "mem")
+#+END_SRC
+
+In your =~/.stumpwmrc=
+
+Then you can use "%M" and/or "%N in your mode line format.
+
+** Notes
+This is specific to Linux.
+

modeline/net/README.org

@@ -0,0 +1,13 @@
+** Usage
+
+Put:
+#+BEGIN_SRC lisp
+(load-module "net")
+#+END_SRC
+In your =~/.stumpwmrc=
+
+Then you can use "%l" in your mode line format.
+
+** Notes
+This is specific to Linux.
+

modeline/wifi/README.org

@@ -0,0 +1,23 @@
+** Usage
+
+Place the following in your ~/.stumpwmrc file:
+
+#+BEGIN_SRC lisp
+    (load-module "wifi")
+#+END_SRC
+
+Then you can use "%I" in your mode line format (both "w" and "W"
+were taken. Think _I_EEE 802.11 :-)).
+
+** Notes
+This gets information through sysfs, so it only works on Linux with a
+mounted =sysfs=.
+
+* WARNING
+
+This triggers a yet to be discovered bug in SBCL, which causes
+stumpwm to freeze.
+ 
+
+<2014-03-16 Sun> This is a fairly old file, maybe the bug was fixed?
+Can someone confirm?

util/app-menu/README.org

@@ -0,0 +1,6 @@
+** Usage
+#+BEGIN_SRC lisp
+(load-module "app-menu")
+#+END_SRC
+** Tasks
+*** TODO Document this module

util/logitech-g15-keysyms/README.org

@@ -0,0 +1,11 @@
+** Usage
+ Put:
+#+BEGIN_SRC lisp
+(load-module "logitech-g15-keysyms")
+;; depending of the model you have.
+(g15-original)
+(g15-revised)  
+#+END_SRC
+In your =~/.stumpwmrc=
+
+

util/passwd/README.org

@@ -0,0 +1,7 @@
+** Usage
+#+BEGIN_SRC lisp
+   (load-module "passwd")
+#+END_SRC
+
+** Tasks
+*** TODO Document this module

util/productivity/README.org

@@ -0,0 +1,78 @@
+** Commentary
+There are those for whom simply using a window manager like StumpWM
+is enough to force them to buckle down and work, mostly because
+they don't know how to play around with it (due to a lack of
+frills). However, there are also those who know how to move around
+in StumpWM and who may find themselves falling into the same bad
+habits as those who use "normal" WMs; that is, switching between
+windows a lot and fiddling with random functions the WM has
+available. This fixes that by temporarily disabling StumpWM.
+
+Incidentally, I'm not positive, but I believe that this may be
+StumpWM's first Minor Mode.
+
+** Usage
+
+Just add the following line to your .stumpwmrc file:
+#+BEGIN_SRC lisp
+(load-module "productivity")
+#+END_SRC
+...and then bind `productivity-mode-toggle' to a key in your
+=*top-map*=. I recommend =H-#= (Hyper-shift-3).
+
+When you activate productivity-mode, you won't be able to access
+any of your StumpWM keymaps. That's right--the window manager is
+effectively disabled! If you try to leave the window, or display
+the time, or go to another group, or control MPD, or switch frames,
+or whatever, you will instead be presented with a curt reminder of
+what you're supposed to be doing. To escape from this mode, just
+hit the key you have =productivity-mode-toggle= bound to again.
+
+Absolutely DO NOT start productivity-mode from your .stumpwmrc file
+unless you (a) are absolutely *sure* you have
+productivity-mode-toggle bound to a key already, (b) automatically
+switch to a window capable of controlling StumpWM (i.e., Emacs or a
+terminal) in your .stumpwmrc, (c) want to convince your friends
+your computer is broken, or (d) are crazy.
+
+** Configuration
+
+The following can be customized. If no example is given, please see
+the code.
+
+=*productivity-keys*=: Any and all keys you have bound to the
+ =*top-map*= and their associated commands.
+ex:
+#+BEGIN_SRC lisp
+    (setf *productivity-keys*
+          '(("H-t" *root-map*)
+            ("C-;" *rat-map*)
+            ("Print" "screenshot")))
+#+END_SRC
+
+=*productivity-start-message*=: What StumpWM should print when you
+    start productivity-mode.
+
+=*productivity-stop-message*=: What StumpWM should print when you
+    stop productivity-mode
+
+=*productivity-back-to-work-message*=: What StumpWM should print
+    when you attempt to waste time (you lazy, lazy, um...lazy
+    person).
+
+** Tasks
+*** TODO Implement these features
+- [ ] Add an option to toggle the mode-line on and off.
+- [ ] Add an option to display a notifier for this mode, when on,
+      in the mode-line (a la Emacs' minor modes).
+      - Perhaps this could be integrated into a "minor modes"
+        package? (Just in case somebody insinuates that StumpWM
+        doesn't have *everything*.)
+- [ ] Add a timer feature (i.e., have it toggle itself at a given
+      interval or hour, so you can have your work time and
+      messing-around-on-the-computer time predetermined).
+- [ ] Add an option to disable stumpish, slime and/or
+      stumpwm-mode.el (choose your poison/s).
+- [ ] Make it do your work for you.
+      - Note to self: Finish this one first, then have it write the
+        rest for you.

util/stumptray/README.org

@@ -0,0 +1,13 @@
+System Tray for stumpwm.
+
+** Usage
+Add 
+#+BEGIN_SRC lisp
+(load-module "stumptray")
+#+END_SRC
+to =.stumpwmrc=
+
+** Tasks
+*** TODO Do something about the errors that happen when resuming from hibernation
+*** TODO Modify the modeline command or add a wrapper to start the tray together with the modeline
+

util/surfraw/README.org

@@ -0,0 +1,27 @@
+** Commentary
+
+I like surfraw (http://surfraw.alioth.debian.org). If you're
+reading this, you probably like surfraw. I've got surfraw-related
+code in my .stumpwmrc, and (judging from some judicious googling
+for RC files early on in my use of stumpwm) I know that I'm not the
+only one. So it seemed like a good idea to just put that code in
+a library.
+
+** Usage
+
+Just add the following line to your =.stumpwmrc= file:
+#+BEGIN_SRC lisp
+(load-module "surfraw")
+#+END_SRC
+
+...and then either call the functions here with "colon" (C-t ;) or
+bind them to a key. I figure other people will probably have
+different key preferences than I have, so I leave them entirely up
+to you.
+
+If you want to use the bookmark functions, don't forget to tell
+stumpwm where your =*surfraw-bookmark-file*= is.
+
+Note that there are also "=surfraw-selection=" variants on each
+command that work on the X selection.
+

util/undocumented/README.org

@@ -0,0 +1,8 @@
+** Commentary
+ Look for stuff that should probably be in the manual that isn't
+** Usage
+#+BEGIN_SRC lisp
+(load-module "undocumented")
+#+END_SRC
+** Tasks
+*** TODO Document this module

util/windowtags/README.org

@@ -0,0 +1,11 @@
+** Commentary
+Window tags. Window tags are special window properties (stored in
+X11 window properties) that can be used for window
+manipulations. They can survive temporary WM change and allow more
+flexible classification of windows than selecting window groups for
+them.
+** Usage
+Add this to your =.stumpwmrc=:
+#+BEGIN_SRC lisp
+(load-module "windowtags")
+#+END_SRC