More docs

README.org

@@ -18,7 +18,7 @@
 
 *** Requirements
 
-    - Linux (somebody please port this to OSX/Win32!)
+    - Linux (somebody please port this to OS X)
     - [[http://www.kfish.org/software/xsel/][xsel]]
     - [[apt:libnotify-bin][libnotify-bin]]
 
@@ -27,6 +27,22 @@
     : sudo gem install firetower
     : firetower setup
 
+*** Usage
+***** Say something in campfire
+      : firetower say 'blah blah blah'
+***** Say something to a non-default room
+      : firetower say subdomain='mycompany' room='Water Cooler' 'blah blah blah'
+***** Paste a code snippet into campfire
+      : firetower paste < hello.rb
+***** Paste from the clipboaord
+      : firetower paste --from=clip
+***** Paste the selected text
+      : firetower paste --from=sel
+***** Start server (for notifications, bots, etc.)
+      : firetower start
+***** Stop server
+      : firetower stop
+
 *** Configuration
     Edit $HOME/.firetower/firetower.conf
 
@@ -39,9 +55,10 @@
 
     : use NotifyPlugin
 
-*** A simple bot
+***** A simple bot
     Drop this in ~/.firetower/firetower.conf for a simple (and VERY UNSAFE!) demo
-    of a Campfire bot which will eval arbitrary Ruby code:
+    of a Campfire bot which will eval arbitrary Ruby code whenever someone
+    prefaces a message with "!eval":
 
 #+BEGIN_SRC ruby
   receive do |session, event|
@@ -51,22 +68,47 @@
   end
 #+END_SRC
 
-*** Usage
-***** Say something in campfire
-      : firetower say 'blah blah blah'
-***** Say something to a non-default room
-      : firetower say subdomain='mycompany' room='Water Cooler' 'blah blah blah'
-***** Paste a code snippet into campfire
-      : firetower paste < hello.rb
-***** Paste from the clipboaord
-      : firetower paste --from=clip
-***** Paste the selected text
-      : firetower paste --from=sel
-***** Start server (for notifications, bots, etc.)
-      : firetower start
-***** Stop server
-      : firetower stop
+  The event hooks are [[http://hookr.rubyforge.org][HookR]] events, so any number of handlers can be stacked on
+  a given event. And more advanced usage are possible; for instance, you can
+  attach a Listener object to receive all types of events. In fact, this last is
+  how plugins are implemented.
+
+*** Plugin API
+  If you want to write your own Firetower plugins, you should create a gem
+  that contains a path something like this:
+
+    : lib/firetower/plugins/my_awesome_plugin/init_v1.rb
+
+  Firetower will load the init_v1.rb file on startup. Typically, a plugin
+  will define a Firetower::Session::Listener class (or more than one) in the
+  Firetower::Plugins namespace:
+
+#+BEGIN_SRC ruby
+  module Firetower
+    module Plugins
+      class MyAwesomePlugin < Firetower::Session::Listener
+        def startup(session)
+          # Some one-time startup code...
+        end
+
+        def receive(session, event)
+          # Some event-handling code...
+        end
+      end
+    end
+  end
+#+END_SRC
+
+  Users can then enable your plugin by installing your gem and adding a line
+  line to their firetower.conf:
+
+#+BEGIN_SRC ruby
+  use MyAwesomePlugin
+#+END_SRC
 
+*** Not yet implemented:
+***** TODO Join/leave rooms when subscribing/unsubscribing
+***** TODO Fire all defined hooks, including :shutdown and :leave
 *** License
 
 (The MIT License)

Rakefile

@@ -14,6 +14,8 @@ Bones {
   email    'avdi@avdi.org'
   url      'http://github.com/avdi/firetower'
 
+  summary "A command-line interface to Campfire chats"
+
   readme_file 'README.org'
 
   depend_on 'twitter-stream',   '~> 0.1.6'

bin/firetower

@@ -4,10 +4,56 @@ require File.expand_path(
     File.join(File.dirname(__FILE__), %w[.. lib firetower]))
 
 Main do
-  description "Interact with Campfire chat rooms"
+  description <<-"END"
+    A command-line interface to Campfire chats.
+
+    #{program} provides two primary services: a command-line syntax for posting
+    messages and code pastes to a Campfire chat room; and a daemon which can
+    monitor any number of Campfire rooms on multiple accounts and take
+    configurable actions when chat room events occur. Both usage modes share a
+    common simple Ruby-based configuration file.
+  END
 
   author 'Avdi Grimm <avdi@avdi.org>'
 
+  examples [
+    "#{program} setup",
+    "#{program} say 'hello, Campfire'",
+    "#{program} say subdomain=mycompany room='Watercooler' 'hello room'",
+    "echo 'hello, Campfire' | #{program} say",
+    "#{program} paste '2+2 => 4'",
+    "#{program} paste subdomain=mycompany room='Watercooler' 'foobar'",
+    "#{program} paste --from=sel",
+    "#{program} paste --from=clip",
+    "#{program} paste --from=file hello.rb",
+    "#{program} paste --from=stdin < hello.rb",
+    "#{program} start",
+    "#{program} stop"
+  ]
+
+  usage["CONFIGURATION"] = <<-"END"
+    #{program} is configured by editing the file
+    $HOME/.firetower/firetower.conf. The file consists of Ruby code which is
+    evaluated in the context of a Firetower::Session object. You can generate a
+    starter configuration by running '#{program} setup'.
+
+    In addition to setting up accounts and rooms and enabling plugins, the
+    config file can also be used to attach arbitrary event handlers to Campfire
+    events. For instance, the following code plays a sound when someone says
+    something in Campfire:
+
+      receive do |session, event|
+        if event['type'] == 'TextMessage'
+          system 'paplay ding.wav'
+        end
+      end
+
+    The event hooks are HookR events (http://hookr.rubyforge.org), so any number
+    of handlers can be stacked on a given event. And more advanced usage are
+    possible; for instance, you can attach a Listener object to receive all
+    types of events. In fact, this last is how plugins are implemented.
+  END
+
   fattr(:config_path) { dir + 'firetower.conf'   }
   fattr(:log_path)    { dir + 'firetower.log' }
   fattr(:pid_path)    { dir + 'firetower.pid' }
@@ -234,6 +280,10 @@ EOS
     end
   end
 
+  def run
+    help!
+  end
+
   def firetower_daemon
     Servolux::Daemon.new(
       :name            => File.basename($PROGRAM_NAME),
@@ -282,3 +332,5 @@ EOS
   end
 end
 
+
+