added hook documentation

git-svn-id: svn://rubyforge.org/var/svn/sup/trunk@611 5c8cc53c-5e98-4d25-b20a-d8db53a31250

diff --git a/Manifest.txt b/Manifest.txt
index 1f3e316277bf98e6e551876a6fdd56d15065de21..86a4ec2b8d126b2433e2ee5f006e4409d0e6938c 100644 (file)
--- a/Manifest.txt
+++ b/Manifest.txt
@@ -12,6 +12,7 @@ bin/sup-recover-sources
 bin/sup-sync
 bin/sup-sync-back
 doc/FAQ.txt
+doc/Hooks.txt
 doc/NewUserGuide.txt
 doc/Philosophy.txt
 doc/TODO

diff --git a/doc/Hooks.txt b/doc/Hooks.txt
new file mode 100644 (file)
index 0000000..a97b2a3
--- /dev/null
+++ b/doc/Hooks.txt
@@ -0,0 +1,38 @@
+Sup's Hook System
+-----------------
+
+Sup can be easily customized via its hook system, which allows custom
+user code to be injected into Sup's execution path by "hooking" the
+code onto pre-defined events. When those events occur, the code is
+executed.
+
+To see which hooks are available, simply run sup -l. Each hook sits in
+a file in ~/.sup/hooks/. Hooks are written in Ruby, and require no
+class or method definitions, just the executable code itself.
+
+Information passes from Sup to the hook code via Ruby variables
+(actually method calls), and from the hook code back to Sup via a
+return value. Each hook description lists the variables and return
+value expected, if any.
+
+Some example hooks:
+
+before-poll:
+  ## runs fetchmail before polling
+  if (@last_fetchmail_time || Time.now) < Time.now - 60
+    say "Running fetchmail..."
+    system "fetchmail >& /dev/null"
+    say "Done running fetchmail."
+  end
+  @last_fetchmail_time = Time.now
+
+
+mime-decode:
+  ## turn text/html attachments into plain text, unless they are part
+  ## of a multipart/alternative pair
+  unless sibling_types.member? "text/plain"
+    case content_type
+    when "text/html"
+      `/usr/bin/w3m -dump -T #{content_type} '#{filename}'`
+    end
+  end

diff --git a/doc/TODO b/doc/TODO
index 6cde5a17cb392a8c17cf5eeeb96d1f3c4fc1af13..8f351aaf0c2be0ffa90b3bf99f3c2e61fce93d0a 100644 (file)
--- a/doc/TODO
+++ b/doc/TODO
@@ -1,9 +1,9 @@
-for 0.2
+for 0.3
 -------
 _ mailing list subscribe/unsubscribe
 _ forward attachments
 _ messages as attachments
-_ gpg integration
+_ flesh out gpg integration: sign & encrypt outgoing
 _ mbox: don't keep filehandles open, and protect all reads with dotlockfile
 _ bugfix: screwing with the headers when editing causes a crash
 _ bugfix: need a better way to force an address to a particular name,