Added README file

README.org

@@ -0,0 +1,149 @@
+#+TITLE: README
+
+Alert is a Growl-workalike for Emacs which uses a common notification
+interface and multiple, selectable "styles", whose use is fully customizable
+by the user.
+
+* For module writers
+
+Just use =alert= instead of =message= as follows:
+
+#+begin_src emacs-lisp
+  (require 'alert)
+
+  ;; This is the most basic form usage
+  (alert "This is an alert")
+
+  ;; You can adjust the severity for more important messages
+  (alert "This is an alert" :severity 'high)
+
+  ;; Or decrease it for purely informative ones
+  (alert "This is an alert" :severity 'trivial)
+
+  ;; Alerts can have optional titles.  Otherwise, the title is the
+  ;; buffer-name of the (current-buffer) where the alert originated.
+  (alert "This is an alert" :title "My Alert")
+
+  ;; Further, alerts can have categories.  This allows users to
+  ;; selectively filter on them.
+  (alert "This is an alert" :title "My Alert" :category 'debug)
+#+end_src
+
+* For users
+
+For the user, there are several variables to control when and how alerts
+are presented.  By default, they appear in the minibuffer much the same
+as a normal Emacs message.  But there are many more possibilities:
+
+  - alert-fade-time ::
+    Normally alerts disappear after this many seconds, if the style
+    supports it.  The default is 5 seconds.
+
+  - alert-default-style ::
+    Pick the style to use if no other config rule matches.  The
+    default is =message=, but =growl= works well too.
+
+  - alert-reveal-idle-time ::
+    If a config rule choose to match on =idle=, this is how many
+    seconds idle the user has to be.  Defaults to 5 so that users
+    don't miss any alerts, but 120 is also good.
+
+  - alert-persist-idle-time ::
+    After this many idle seconds, alerts will become sticky, and not
+    fade away more.  The default is 15 minutes.
+
+  - alert-log-messages ::
+    By default, all alerts are logged to *Alerts* (and to *Messages*,
+    if the =message= style is being used).  Set to nil to disable.
+
+  - alert-hide-all-notifications ::
+    Want alerts off entirely?  They still get logged, however, unless
+    you've turned that off too.
+
+  - alert-user-configuration ::
+    This variable lets you control exactly how and when a particular
+    alert, a class of alerts, or all alerts, get reported -- or if at
+    all.  Use this to make some alerts use Growl, while others are
+    completely silent.
+
+* Programmatically adding rules
+
+Users can also programmatically add configuration rules, in addition to
+customizing =alert-user-configuration=.  Here is one that the author
+currently uses with ERC, so that the fringe gets colored whenever people
+chat on BitlBee:
+
+#+begin_src emacs-lisp
+ (alert-add-rule :status   '(buried visible idle)
+                 :severity '(moderate high urgent)
+                 :mode     'erc-mode
+                 :predicate
+                 #'(lambda (info)
+                     (string-match (concat "\\`[^&].*@BitlBee\\'")
+                                   (erc-format-target-and/or-network)))
+                 :persistent
+                 #'(lambda (info)
+                     ;; If the buffer is buried, or the user has been
+                     ;; idle for `alert-reveal-idle-time' seconds,
+                     ;; make this alert persistent.  Normally, alerts
+                     ;; become persistent after
+                     ;; `alert-persist-idle-time' seconds.
+                     (memq (plist-get info :status) '(buried idle)))
+                 :style 'fringe
+                 :continue t)
+#+end_src
+
+* Builtin alert styles
+
+There are several builtin styles, and it is trivial to create new ones.
+The builtins are:
+
+  | message | Uses the Emacs =message= facility                   |
+  | log     | Logs the alert text to *Alerts*, with a timestamp   |
+  | ignore  | Ignores the alert entirely                          |
+  | fringe  | Changes the current frame's fringe background color |
+  | growl   | Uses Growl on OS X, if growlnotify is on the PATH   |
+
+* Defining new styles
+
+To create a new style, you need to at least write a "notifier", which is
+a function that receives the details of the alert.  These details are
+given in a plist which uses various keyword to identify the parts of the
+alert.  Here is a prototypical style definition:
+
+#+begin_src emacs-lisp
+ (alert-define-style 'style-name :title "My Style's title"
+                     :notifier
+                     (lambda (info)
+                       ;; The message text is :message
+                       (plist-get info :message)
+                       ;; The :title of the alert
+                       (plist-get info :title)
+                       ;; The :category of the alert
+                       (plist-get info :category)
+                       ;; The major-mode this alert relates to
+                       (plist-get info :mode)
+                       ;; The buffer the alert relates to
+                       (plist-get info :buffer)
+                       ;; Severity of the alert.  It is one of:
+                       ;;   `urgent'
+                       ;;   `high'
+                       ;;   `moderate'
+                       ;;   `normal'
+                       ;;   `low'
+                       ;;   `trivial'
+                       (plist-get info :severity)
+                       ;; Whether this alert should persist, or fade away
+                       (plist-get info :persistent)
+                       ;; Data which was passed to `alert'.  Can be
+                       ;; anything.
+                       (plist-get info :data))
+
+                     ;; Removers are optional.  Their job is to remove
+                     ;; the visual or auditory effect of the alert.
+                     :remover
+                     (lambda (info)
+                       ;; It is the same property list that was passed to
+                       ;; the notifier function.
+                       ))
+#+end_src