#+TITLE: Starter Kit Gnus
#+OPTIONS: toc:nil num:nil ^:nil

This is part of the [[file:starter-kit.gnus][Emacs Starter Kit]].

* Starter Kit Gnus
Configuration for the notoriously difficult to configure [[http://www.gnus.org/][Gnus]] email
client

** IMAP
  :PROPERTIES:
  :CUSTOM_ID: imap
  :END:
Based on the instructions at [[http://www.emacswiki.org/emacs/GnusGmail#toc2][emacswiki:GnusGmail]].

to use this file:
1) /personal information/ in this file (specifically in the code
   blocks which will be tangled in the next step) globally replace
   "your-name" with your gmail username, and "your-password" with your
   gmail password.

2) /tangle this file/ Run the =org-babel-tangle= command to extract
   the code embedded in this file into a =starter-git-gnus-imap.el=
   file which can be added to your configuration, and a =~/.authinfo=
   file which will be used by gnus.

3) /load this configuration/ If you have a recent version of Org-mode
   (i.e. after 7.0) or are using the [[http://eschulte.github.com/emacs24-starter-kit/][literate Emacs Starter Kit]], then
   this file can be loaded directly using the =org-babel-load-file=
   function, or by placing it in your load path (if you're using the
   starter kit).
     
   Alternately ensure that the =gnus-gmail.el= file generated by the
   previous step is loaded by your configuration.

4) /fire up gnus/ This can be done with the command =M-x gnus=

5) /view your mail/ After gnus boots up you will see the "Group
   Buffer" (see [[http://www.gnu.org/software/emacs/manual/html_node/gnus/index.html#toc_Group-Buffer][Group-Buffer]]).  Each line is a mail "Group", hit
   =SPACE= or =ENTER= on a group to view it's contents.  You should
   see an "INBOX" group which contains the mail in your gmail account.
   If not, you can jump to the "INBOX" group by
     - pressing =j= for "jump"
     - tab completing the name "INBOX"
     - pressing =U= for "unkill" meaning this will now always be
       displayed in your Group buffer when you have new mail

6) /customize/ Gnus has unrivalled capacity for customization.  Once
   your comfortable with basic usage, take some time to browse through
   the very readable [[http://www.gnu.org/software/emacs/manual/html_node/gnus/index.html][Gnus Manual]] to learn untold tricks (see also
   [[file:starter-kit-gnus.org::#customization][Starter-kit-gnus:Customizations]]).

*** saving mail locally
Where your mail will be saved locally default value will be =~/gmail=.
#+begin_src emacs-lisp
  (require 'gnus)
  (setq nnml-directory "~/gmail")
  (setq message-directory "~/gmail")
#+end_src

All Gmail groups will be ignored by the default value of
=gnus-ignored-newsgroups=, so let's change that default value.
#+begin_src emacs-lisp
  (setq gnus-ignored-newsgroups "^to\\.\\|^[0-9. ]+\\( \\|$\\)\\|^[\”]\”[#’()]")
#+end_src

*** getting mail
Set Gmail as the primary source for incoming mail (Gnus can aggregate
many email and/or newsgroup sources).
#+begin_src emacs-lisp
  (setq gnus-select-method
        '(nnimap "gmail"
                 (nnimap-address "imap.gmail.com")
                 (nnimap-server-port 993)
                 (nnimap-stream ssl)))
#+end_src

Place a line like the following in =~/.authinfo=
#+begin_src fundamental :tangle ~/.authinfo
  machine imap.gmail.com login your-name@gmail.com password your-password port 993
#+end_src

and make sure that no-one else can read it with
#+begin_src sh
  chmod 600 ~/.authinfo
#+end_src

*** sending mail
/Requirement/: gnus uses the [[http://en.wikipedia.org/wiki/STARTTLS][starttls]] tool for encrypted sending of
email to the Gmail SMTP server.  This is easily installed on modern
Debian (including Ubuntu) systems with
#+begin_src sh
  apt-get install starttls
#+end_src

The following configures gnus to use the Gmail SMTP server for sending
email.
#+begin_src emacs-lisp
  (setq message-send-mail-function 'smtpmail-send-it
        smtpmail-starttls-credentials '(("smtp.gmail.com" 587 nil nil))
        smtpmail-auth-credentials '(("smtp.gmail.com" 587 "your-name@gmail.com" nil))
        smtpmail-default-smtp-server "smtp.gmail.com"
        smtpmail-smtp-server "smtp.gmail.com"
        smtpmail-smtp-service 587)
#+end_src

If you don't want to be prompted for a password on every mail sent,
you can add the following line to your =~/.authinfo=.
#+begin_src fundamental :tangle ~/.authinfo
  machine smtp.gmail.com login your-name@gmail.com your-password secret port 587
#+end_src

** Pop
  :PROPERTIES:
  :CUSTOM_ID: pop
  :END:
This file can be used to jump start a working Gnus instillation.  The
following steps will result in a working vanilla Gnus POP
instillation.
1) install the [[required-packages]]
2) follow the [[gmail]] specific instructions
3) tangle this file with `org-babel-tangle' (with C-c M-b t) creating
   the =starter-kit-gnus-pop.el= file which can be loaded by Emacs

(if you run into any problems -- the [[http://www.gnus.org/manual.html][gnus manual]] is very thorough)

*** Basic configuration
First off, load up =gnus=
#+begin_src emacs-lisp
  (require 'gnus)
#+end_src

Tell gnus that your mainly going to be using it for email not as a
news reader -- after all it's not longer the late 80s.
#+begin_src emacs-lisp
  (setq gnus-select-method '(nnml ""))
#+end_src

*** Required packages
   :PROPERTIES:
   :CUSTOM_ID: required-packages
   :END:
A [[http://en.wikipedia.org/wiki/STARTTLS][starttls]] client allows encrypted communication with remote pop3 and
IMAP email clients.

[[http://www.openssl.org/][openssl]] implements the Secure Socket Layer (SSL) secure communication
protocol.

On Debian systems (including Ubuntu) instillation of =starttls= and
=openssl= client is as simple as
: sudo apt-get install starttls openssl

*** Gmail Setup
   :PROPERTIES:
   :CUSTOM_ID: gmail
   :END:
For more information on configuring Gnus with Gmail see [[http://www.emacswiki.org/emacs/GnusGmail][GnusGmail]] on
the Emacs Wiki.

For a simple pop3 setup, simply replace =your-gmail-email-address= and
=your-gmail-password= with your gmail account information in the
following tables.

#+results: gmail-configuration
| email    | your-gmail-email-address |
| password | your-gmail-password      |

#+begin_src emacs-lisp :var config=gmail-configuration
  (let ((email (second (first config)))
        (passwd (second (second config))))
    ;; The following adds Gmail as a source of mail for Gnus
    (add-to-list 'mail-sources
                 `(pop :server "pop.gmail.com"
                       :port 995
                       :user ,email
                       :password ,passwd
                       :stream ssl))
    ;; The following is used for sending email through gmail using SMTP.
    (setq message-send-mail-function 'smtpmail-send-it
          smtpmail-starttls-credentials '(("smtp.gmail.com" 25 nil nil))
          smtpmail-default-smtp-server "smtp.gmail.com"
          smtpmail-smtp-server "smtp.gmail.com"
          smtpmail-smtp-service 25
          user-mail-address email
          smtpmail-starttls-credentials '(("smtp.gmail.com" 587 nil nil))
          smtpmail-auth-credentials `(("smtp.gmail.com" 587 ,email ,passwd))
          smtpmail-default-smtp-server "smtp.gmail.com"
          smtpmail-smtp-server "smtp.gmail.com"
          smtpmail-smtp-service 587))
#+end_src

** Customizations
  :PROPERTIES:
  :CUSTOM_ID: customization
  :END:
Once gnus is installed and working, here are some recommended Gnus
customizations.

*** BBDB
    :PROPERTIES:
    :CUSTOM_ID: bbdb
    :END:
[[http://bbdb.sourceforge.net/][BBDB]] -- _The Insidious Big Brother Database_ is Emacs' contact manager
which is very useful for keeping all of your contacts organized for
use with gnus.

#+begin_src emacs-lisp
  ;;; bbdb
  (require 'bbdb)
  (require 'bbdb-autoloads)
  (setq
   bbdb-file "~/.bbdb"
   bbdb-offer-save 'auto
   bbdb-notice-auto-save-file t
   bbdb-expand-mail-aliases t
   bbdb-canonicalize-redundant-nets-p t
   bbdb-always-add-addresses t
   bbdb-complete-name-allow-cycling t
   )
#+end_src

*** More attractive Summary View
    :PROPERTIES:
    :CUSTOM_ID: pretty-summary
    :END:
Thanks to Dan Davison.

#+begin_src emacs-lisp
  ;; http://groups.google.com/group/gnu.emacs.gnus/browse_thread/thread/a673a74356e7141f
  (when window-system
    (setq gnus-sum-thread-tree-indent "  ")
    (setq gnus-sum-thread-tree-root "") ;; "● ")
    (setq gnus-sum-thread-tree-false-root "") ;; "◯ ")
    (setq gnus-sum-thread-tree-single-indent "") ;; "◎ ")
    (setq gnus-sum-thread-tree-vertical        "│")
    (setq gnus-sum-thread-tree-leaf-with-other "├─► ")
    (setq gnus-sum-thread-tree-single-leaf     "╰─► "))
  (setq gnus-summary-line-format
        (concat
         "%0{%U%R%z%}"
         "%3{│%}" "%1{%d%}" "%3{│%}" ;; date
         "  "
         "%4{%-20,20f%}"               ;; name
         "  "
         "%3{│%}"
         " "
         "%1{%B%}"
         "%s\n"))
  (setq gnus-summary-display-arrow t)
#+end_src