spacemacs/layers/+email/gnus/README.org

#+TITLE: Gnus layer

#+TAGS: e-mail|layer

[[file:img/gnus.gif]]

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
- [[#basic-concepts][Basic Concepts]]
- [[#adding-news-sources][Adding news sources]]
- [[#configuring-gmail][Configuring gmail]]
- [[#org-mime-in-org-layer][Org MIME in Org layer]]
- [[#setup-variables][Setup variables]]
- [[#key-bindings][Key bindings]]

* Description
This layer integrates a general purpose email/newsgroup client into Spacemacs.

** Features:
- Support for reading RSS feeds, newsgroups and mails directly within Emacs via [[http://www.gnus.org/][Gnus]].
- Support for beautiful HTML mails generated from any =org= buffer.
- Support for credential management via [[https://gnupg.org/][GnuPG]].

* Install
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =gnus= to the existing =dotspacemacs-configuration-layers= list in this
file.

* Basic Concepts
Gnus is a news reading application. The Gnus terminology can be confusing for
new users so the basics are listed here:
- A Newsgroup but can also be a RSS Feed or a mail directory
- 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 [[#key-bindings][key bindings 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_EXAMPLE
  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_EXAMPLE

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 in Org layer
It is possible to send beautiful HTML emails using org mode.

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

* Setup variables
The Gnus layer defines the following variables like this:

#+BEGIN_SRC emacs-lisp
  gnus-summary-line-format "%U%R%z %(%&user-date;  %-15,15f  %B (%c) %s%)\n"
  gnus-user-date-format-alist '((t . "%Y-%m-%d %H:%M"))
  gnus-group-line-format "%M%S%p%P%5y:%B %G\n";;"%B%(%g%)"
  gnus-summary-thread-gathering-function 'gnus-gather-threads-by-references
  gnus-thread-sort-functions '(gnus-thread-sort-by-most-recent-date)
  gnus-ignored-newsgroups "^to\\.\\|^[0-9. ]+\\( \\|$\\)\\|^[\”]\”[#’()]"
  gnus-sum-thread-tree-false-root ""
  gnus-sum-thread-tree-indent " "
  gnus-sum-thread-tree-leaf-with-other "├► "
  gnus-sum-thread-tree-root ""
  gnus-sum-thread-tree-single-leaf "╰► "
  gnus-sum-thread-tree-vertical "│"
  gnus-article-browse-delete-temp t
  gnus-treat-strip-trailing-blank-lines 'last
  gnus-keep-backlog 'nil
  gnus-summary-display-arrow nil ; Don't show that annoying arrow:
  gnus-mime-display-multipart-related-as-mixed t ; Show more MIME-stuff:
  gnus-auto-select-first nil ; Don't get the first article automatically:
  smiley-style 'medium
  gnus-keep-backlog '0
#+END_SRC

They can be configured as layer variables or from the =dotspacemacs/user-config=
section of =.spacemacs=.

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

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

| Key binding          | Gnus mode - Description                             |
|----------------------+-----------------------------------------------------|
| ~SPC a e g~          | Starts Gnus                                         |
| ~m~                  | New Message                                         |
| ~O R~, ~G R~ (emacs) | Group Buffer - Add RSS feed                         |
| ~g r~                | Group Buffer - Check for new mail                   |
| ~^~                  | 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 |