1 files changed, 76 insertions, 0 deletions
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..f190f94
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,76 @@
+gnus-desktop-notify.el: Gnus Desktop Notification global minor mode
+===================================================================
+
+.. contents::
+
+Desktop notification integration in `Gnus <http://www.gnus.org/>`_!? `Ohh
+goody!`
+
+
+Basic setup
+-----------
+
+``gnus-desktop-notify.el`` provides a simple mechanism to notify the user when
+new messages are received. For basic usage, to be used in conjunction with
+``gnus-daemon``, put the following:
+
+.. code:: scm
+
+  (require 'gnus-desktop-notify)
+  (gnus-desktop-notify-mode)
+  (gnus-demon-add-scanmail)
+
+into your ``.gnus`` file. The default is to use alert_ if available, which
+works on every operating system and allows the user to customize the
+notification through emacs. See https://github.com/jwiegley/alert#for-users for
+further info. If not available, the ``notifications`` library (part of emacs >=
+24) is used, so no external dependencies are required. With emacs <= 23 instead
+the generic ``notify-send`` program is used, which (in Debian or Ubuntu) is
+available in the ``libnotify-bin`` package.
+
+You can also call any program directly by changing the
+``gnus-desktop-notify-exec-program`` variable, or change the behavior entirely
+by setting a different ``gnus-desktop-notify-function`` function.
+
+The group names are collapsed by default, and a single notification is
+generated containing all the groups with a count of new messages.
+
+
+Mac setup
+---------
+
+If alert_ is available, growl_ notifications are generated by default. No setup
+is required! See the ``alert`` customization group to tweak the generated
+messages to your liking.
+
+You can also download and install growl_ manually, and then customize as
+follows:
+
+.. code:: scm
+
+  (require 'gnus-desktop-notify)
+  (setq gnus-desktop-notify-function 'gnus-desktop-notify-exec
+	gnus-desktop-notify-exec-program "growlnotify -a Emacs.app -m")
+  (gnus-desktop-notify-mode)
+  (gnus-demon-add-scanmail)
+
+
+Advanced setup
+--------------
+
+By default, all groups are notified when new messages are received. You can
+exclude a single group by setting the ``group-notify`` group parameter to
+"t" (this is quite common for spammy groups).
+
+You can also selectively monitor groups instead by changing the
+``gnus-desktop-notify-groups`` variable to ``'gnus-desktop-notify-explicit``
+and then manually selecting which groups to include the same way.
+
+Press "``G c``" in the group buffer to customize group parameters
+interactively.
+
+See the ``gnus-desktop-notify`` customization group for more details.
+
+
+.. _alert: https://github.com/jwiegley/alert
+.. _growl: http://growl.info/