spacemacs/contrib/rcirc/README.md

# RCIRC contribution layer for Spacemacs

![logo](img/irc.png)

<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc/generate-toc again -->
**Table of Contents**

- [RCIRC contribution layer for Spacemacs](#rcirc-contribution-layer-for-spacemacs)
    - [Description](#description)
    - [Features](#features)
    - [Install](#install)
        - [Layer](#layer)
        - [Configuration](#configuration)
        - [Storing the credentials in your dotfile](#storing-the-credentials-in-your-dotfile)
        - [Storing the credentials in your Dropbox](#storing-the-credentials-in-your-dropbox)
        - [Storing the credentials in authinfo](#storing-the-credentials-in-authinfo)
        - [Connecting behind a ZNC bouncer and storing the credentials in authinfo](#connecting-behind-a-znc-bouncer-and-storing-the-credentials-in-authinfo)
    - [Key Bindings](#key-bindings)
    - [Rcirc documentation](#rcirc-documentation)

<!-- markdown-toc end -->

## Description

This layer provide support for [rcirc][] with optional support for authinfo
and ZNC.

## Features

- Store channel logs into `~/.emacs.d/.cache/rcirc-logs/<channel>`
- Support for credentials stored in `~/.authinfo.gpg` (need to have gnutls) 
- Support ZNC support (with optional `~/.authinfo.gpg`)
- Colored nicknames
- WIP: Real time change when people use /s/foo/bar in the chats

## Install

### Layer

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

```elisp
(setq-default dotspacemacs-configuration-layers '(rcirc))
```

### Configuration

There are several ways to configure rcirc supported by the layer:
- by storing your credentials in `rcirc-server-alist` in your dotfile
(not secured)
- by storing your credentials in `rcirc-server-alist` in your Dropbox
(better but still not secured)
- by storing your credentials in authinfo (secured)
- by using a ZNC bouncer _and_ storing your credentials (secured)

### Storing the credentials in your dotfile

You can store your servers configuration along with your credentials in the
`dotspacemacs/config` of your dotfile.

**Important** This method is the less secured and it is not recommended since
your dotfile is often stored in a public repository and is not crypted. This
is convenient but not recommended.

Example:

```elisp
(setq rcirc-server-alist
  '(("irc.freenode.net"
      :user "spacemacs_user"
      :port "1337"
      :password "le_passwd"
      :channels ("#emacs"))))
```

### Storing the credentials in your Dropbox

You can store your servers configuration along with your credentials in
your dropbox in the file `~/Dropbox/emacs/pinit-rcirc.el`.

**Important** This method is more secured since your file is stored in
a private location but it is still not crypted on your drive. Moreover
since Dropbox automatically sync your files you may have a lot of copies
of the file containing your credentials. This is convenient but not
recommended.

Example:

```elisp
(setq rcirc-server-alist
  '(("irc.freenode.net"
      :user "spacemacs_user"
      :port "1337"
      :password "le_passwd"
      :channels ("#emacs"))))
```

### Storing the credentials in authinfo

This method is considered secured and is the recommended way to configure
rcirc.

1. If you want to use authinfo.gpg you have to enable the support for it
by setting `rcirc-enable-authinfo-support` to `t` in your dotfile:

```elisp
(setq-default dotspacemacs-configuration-layers '(
  (rcirc :variables rcirc-enable-authinfo-support t)))
```

2. In your `~/.authinfo.gpg` file store your credentials like this:
```
machine irc.freenode.net port nickserv user <user> password <passwd>
```

3. At last you need to provide your servers configuration in the
`dotspacemacs/config` function of your dotfile:

```elisp
(setq rcirc-server-alist
  '(("irc.freenode.net"
      :user "spacemacs_user"
      :port "1337"
      :channels ("#emacs"))))
  ```

### Connecting behind a ZNC bouncer and storing the credentials in authinfo

This methods is also secured since it uses authinfo. ZNC is a popular bouncer
which is easy to setup. A bouncer is a proxy that connects to your IRC
channels on your behalf, instead of connecting to the IRC server you connect
to your ZNC server. The ZNC server can store the discussions in a buffer while
you are not connected.

**Disclaimer**
This assumes that you are familiar with ZNC and you have a ZNC server properly
setup. If it is not the case then it is recommended to read about ZNC
[here][znc]. There is also an installation guide for Ubuntu [here][znc guide].

**Note**
For now authinfo is mandatory to use the ZNC configuration.

1. To enable ZNC support set the variable `rcirc-enable-znc-support` to `t` in
your dotfile:

```elisp
(setq-default dotspacemacs-configuration-layers '(
  (rcirc :variables rcirc-enable-authinfo-support t)))
```

2. In your `~/.authinfo.gpg` file store your credentials like this:

```
machine freenode.spacemacsserver.me port irc user spacemacs_user/freenode password ZNC_PASSWORD
machine geekshed.spacemacsserver.me port irc user spacemacs_user/geekshed password ZNC_PASSWORD
```

**Important** `port` must be set to `irc`. This is a convention of the layer
to retrieve the credentials for the ZNC configuration.

3. Then setup your servers configuration using subdomains in the
`dotspacemacs/config` function of your dotfile. The `:auth` keyword arguments
will be replaced by the credentials stored in your `~/.authinfo.gpg`. 

```elisp
(setq rcirc-server-alist
 ;; This will replace :auth with the correct thing, see the doc for that function
 '(("freenode"
     :host "freenode.spacemacsserver.me"
     :port "1337"
     :auth "spacemacs_user/freenode"
     :channels ("#emacs"))
 ("geekshed"
     :host "geekshed.spacemacsserver.me"
     :port "1337"
     :auth "spacemacs_user/geekshed"
     :channels ("#jupiterbroadcasting"))))
```

## Key Bindings

    Key Binding       |                 Description
----------------------|------------------------------------------------------------
<kbd>SPC a i</kbd>    | Open rcirc
<kbd>SPC L o i</kbd>  | Open rcirc in a custom perspective "@RICRC" (need perspectives layer enabled)


## Rcirc documentation

The rcirc documentation can be found [here][rcirc]. 

[rcirc]: http://www.gnu.org/software/emacs/manual/html_mono/rcirc.html
[znc]: http://wiki.znc.in/ZNC
[znc guide]: https://www.digitalocean.com/community/tutorials/how-to-install-znc-an-irc-bouncer-on-an-ubuntu-vps
[source]: http://git.tapoueh.org/?p=emacs.d.git