diff --git a/plugins/available/_xterm.plugins.bash b/plugins/available/_xterm.plugins.bash
index 9c8c668..b3810e7 100644
--- a/plugins/available/_xterm.plugins.bash
+++ b/plugins/available/_xterm.plugins.bash
@@ -6,6 +6,9 @@
 #
 # [issue 108]: https://github.com/revans/bash-it/issues/108
 
+cite about-plugin
+about-plugin 'automatically set your xterm title with host and location info'
+
 set_xterm_title () {
     local title="$1"
     echo -ne "\e]0;$title\007"
diff --git a/plugins/available/battery.plugin.bash b/plugins/available/battery.plugin.bash
old mode 100644
new mode 100755
index 4b9d4b9..4c0e380
--- a/plugins/available/battery.plugin.bash
+++ b/plugins/available/battery.plugin.bash
@@ -1,11 +1,17 @@
 #!/usr/bin/env bash
 
+cite about-plugin
+about-plugin query and display info about your battery charge level
+
 battery_percentage(){
+  about 'displays battery charge as a percentage of full (100%)'
+  group battery
+
   if command_exists acpi;
   then
     local ACPI_OUTPUT=$(acpi -b)
     case $ACPI_OUTPUT in
-      *" Unknown"*) 
+      *" Unknown"*)
         local PERC_OUTPUT=$(echo $ACPI_OUTPUT | head -c 22 | tail -c 2)
         case $PERC_OUTPUT in
           *%)
@@ -16,7 +22,7 @@
             ;;
         esac
         ;;
-      *" Discharging"*) 
+      *" Discharging"*)
         local PERC_OUTPUT=$(echo $ACPI_OUTPUT | head -c 26 | tail -c 2)
         case $PERC_OUTPUT in
           *%)
@@ -27,7 +33,7 @@
             ;;
         esac
         ;;
-      *" Charging"*) 
+      *" Charging"*)
         local PERC_OUTPUT=$(echo $ACPI_OUTPUT | head -c 23 | tail -c 2)
         case $PERC_OUTPUT in
           *%)
@@ -38,7 +44,7 @@
             ;;
         esac
         ;;
-      *" Full"*) 
+      *" Full"*)
         echo '99'
         ;;
       *)
@@ -52,7 +58,7 @@
     #local IOREG_OUTPUT_10_5=$(ioreg -l | grep -i capacity | grep -v Legacy| tr '\n' ' | ' | awk '{printf("%.2f%%", $14/$7 * 100)}')
     local IOREG_OUTPUT=$(ioreg -n AppleSmartBattery -r | awk '$1~/Capacity/{c[$1]=$3} END{OFMT="%.2f%%"; max=c["\"MaxCapacity\""]; print (max>0? 100*c["\"CurrentCapacity\""]/max: "?")}')
     case $IOREG_OUTPUT in
-      100*) 
+      100*)
         echo '99'
         ;;
       *)
@@ -65,6 +71,9 @@
 }
 
 battery_charge(){
+  about graphical display of your battery charge
+  group battery
+
   # Full char
   local F_C='▸'
   # Depleted char
diff --git a/plugins/available/browser.plugin.bash b/plugins/available/browser.plugin.bash
index fdfba4f..7ad2f4b 100644
--- a/plugins/available/browser.plugin.bash
+++ b/plugins/available/browser.plugin.bash
@@ -1,42 +1,34 @@
 # based on https://gist.github.com/318247
 
-# Usage: browser
-# pipe html to a browser
-# e.g.
-# $ echo "<h1>hi mom!</h1>" | browser
-# $ ron -5 man/rip.5.ron | browser
+cite about-plugin
+about-plugin 'render commandline output in your browser'
 
 function browser() {
+    about pipe html to a browser
+    example '$ echo "<h1>hi mom!</h1>" | browser'
+    example '$ ron -5 man/rip.5.ron | browser'
+    group browser
+
     if [ -t 0 ]; then
         if [ -n "$1" ]; then
             open $1
         else
-            cat <<usage
-Usage: browser
-pipe html to a browser
-
-$ echo '<h1>hi mom!</h1>' | browser
-$ ron -5 man/rip.5.ron | browser
-usage
-
-    fi
+            reference browser
+        fi
 
     else
         f="/tmp/browser.$RANDOM.html"
         cat /dev/stdin > $f
-        open $f 
+        open $f
     fi
 }
 
 
-# pipe hot spicy interwebs into textmate and cleanup!
-#
-# Usage: wmate
-# wget into a pipe into TextMate and force Tidy (you can undo in textmate)
-# e.g.
-# $ wmate google.com
-
 function wmate() {
+    about 'pipe hot spicy interwebs into textmate and cleanup!'
+    example '$ wmate google.com'
+    group browser
+
     if [ -t 0 ]; then
         if [ -n "$1" ]; then
             wget -qO- $1 | /usr/bin/mate
@@ -64,34 +56,21 @@
 EOT`
 
         else
-            cat <<usage
-Usage: wmate google.com
-wget into a pipe into TextMate and force Tidy (you can undo in textmate)
-
-$ wmate google.com
-usage
-
+            reference wmate
       fi
     fi
 }
 
-#
-# Usage: raw google.com
-# wget into a temp file and pump it into your browser
-#
-# e.g.
-# $ raw google.com
 function raw() {
+    about 'write wget into a temp file and pump it into your browser'
+    example '$ raw google.com'
+    group browser
+
     if [ -t 0 ]; then
         if [ -n "$1" ]; then
             wget -qO- $1 | browser
         else
-            cat <<usage
-Usage: raw google.com
-wget into a temp file and pump it into your browser
-
-$ raw google.com
-usage
-      fi
+            reference raw
+        fi
     fi
 }