#+TITLE: Gnus contribution layer for Spacemacs

[[file:img/gnus.gif]]

* Table of Contents                                                   :TOC@4:
 - [[#install][Install]]
 - [[#basic-concepts][Basic Concepts]]
 - [[#adding-news-sources][Adding news sources]]
 - [[#configuring-gmail][Configuring gmail]]
 - [[#org-mime-integration][Org MIME integration]]
 - [[#keybindings][Keybindings]]

* Install

To use this contribution layer add it to your =~/.spacemacs=

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(gnus))
#+END_SRC

* Basic Concepts

Gnus is a news reading application. The Gnus terminology can be confusing for
new users so the basics are listed here:

- Group :: A Newsgroup but can also be a RSS Feed or a mail directory
- Topic :: Newsgroups can be assigned to topics which will be used to structure
     the Group Buffer if Topic Mode is enabled(default).
  
* Adding news sources

Adding news sources can be done in your =.spacemacs= file by adding the
following:

#+BEGIN_SRC emacs-lisp
  ;; Get email, and store in nnml
  (setq gnus-secondary-select-methods
    '(
      (nntp "gmane"
             (nntp-address "news.gmane.org"))
      (nntp "news.eternal-september.org")
      (nntp "nntp.aioe.org")
      (nntp "news.gwene.org")
      ))
#+END_SRC

For adding RSS Feeds please see the [[#Keybindings][keybindings section]].

* Configuring gmail

To configure Gnus with gmail support you can add the following to your
=.spacemacs= file. 

#+BEGIN_SRC emacs-lisp
;; Get email, and store in nnml
(setq gnus-secondary-select-methods
'(
  (nnimap "gmail"
           (nnimap-address
            "imap.gmail.com")
           (nnimap-server-port 993)
           (nnimap-stream ssl))
  ))

;; Send email via Gmail:
(setq message-send-mail-function 'smtpmail-send-it
  smtpmail-default-smtp-server "smtp.gmail.com")

;; Archive outgoing email in Sent folder on imap.gmail.com:
(setq gnus-message-archive-method '(nnimap "imap.gmail.com")
    gnus-message-archive-group "[Gmail]/Sent Mail")

;; set return email address based on incoming email address
(setq gnus-posting-styles
    '(((header "to" "address@outlook.com")
       (address "address@outlook.com"))
  ((header "to" "address@gmail.com")
     (address "address@gmail.com"))))

;; store email in ~/gmail directory
(setq nnml-directory "~/gmail")
(setq message-directory "~/gmail")
#+END_SRC

Authentication for your gmail account is best stored in an =authinfo= or
=authinfo.pgp= file. It must be of the form:

#+BEGIN_SRC
machine smtp.gmail.com login name@gmail.com password SUPER_SECRET_PASS
machine imap.gmail.com login name@gmail.com port 993 password SUPER_SECRET_PASS
#+END_SRC

If you use two-step verification the password has to be an [[https://support.google.com/accounts/answer/185833?hl=en][application specific
password]].

* Org MIME integration

It is possible to send beautiful HTML emails using org mode.

Pressing ~SPC m o~ in a message buffer will convert the current message
from org mode to html.  A org mode buffer can be sent via html email by pressing
~SPC m h~ in any org mode buffer.

* Keybindings

Gnus has very modal default keybindings.
Please see the [[http://www.gnus.org/manual.html][manual]] for a complete list.

Basic and Spacemacs specific keybindings can be found in the following table.

| Key Binding | Gnus mode - Description                                  |
|-------------+----------------------------------------------------------|
| ~SPC a g~   | Starts Gnus                                              |
| ~m~         | New Message                                              |
| ~G R~       | Group Buffer - Add RSS feed                              |
| ~^~         | Open Server Buffer. Browse Newsgroups.                   |
| ~T n~       | Group Buffer - new Topic                                 |
| ~T m~       | Group Buffer - Move Group to Topic                       |
| ~K~         | Article Buffer - Previous article                        |
| ~J~         | Article Buffer - Next article                            |
| ~RET~       | Summary Buffer(RSS) - Open article Link in browser       |
| ~TAB~       | Summary Buffer(RSS) - Open article and switch to it      |
| ~SPC m h~   | Message Buffer - Use org mode to convert into html email |
| ~SPC m H~   | Org Mode - Send current buffer as HTML email message     |