spacemacs/layers/+chat/erc/README.org

#+TITLE: ERC layer

#+TAGS: chat|layer

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
  - [[#layer][Layer]]
  - [[#os-x][OS X]]
  - [[#social-graph][Social graph]]
  - [[#disable-notifications][Disable notifications]]
  - [[#enable-sasl-authentication][Enable SASL authentication]]
  - [[#default-servers][Default servers]]
    - [[#security-note][Security Note]]
- [[#key-bindings][Key bindings]]
- [[#spacemacs-layout-support][Spacemacs Layout Support]]

* Description
Layer for [[http://www.emacswiki.org/emacs/ERC][ERC IRC chat]].

** Features:
- Highlight nicks (using [[https://github.com/leathekd/erc-hl-nicks][erc-hl-nicks]])
- Image inline support (using [[https://github.com/kidd/erc-image.el][erc-image]])
- Logging to =~/.emacs.d/.cache/erc-logs= and =ViewLogMode= for viewing logs
  (using [[https://github.com/Niluge-KiWi/erc-view-log][erc-view-log]])
- YouTube videos Thumbnails inline (using [[https://github.com/yhvh/erc-yt][erc-yt]])
- Social Graph for ERC messages (using [[https://github.com/vibhavp/erc-social-graph][erc-social-graph]])
- Optional SASL authentication via the variable =erc-enable-sasl-auth=
  (using [[http://emacswiki.org/emacs/ErcSASL][erc-sasl]])
- D-BUS notifications via the variable =erc-enable-notifications=
- Completion of Emojis using [[https://github.com/dunn/company-emoji][company-emoji]] (still needs a way of showing, either
  using the =emoji= layer or having a proper font) :clap:

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

** OS X
It's recommended to install the [[https://github.com/alloy/terminal-notifier][terminal-notifier gem]] so that you get
notifications via the OS X Notification Center.

** Social graph
[[https://github.com/vibhavp/erc-social-graph][erc-social-graph]] needs graphviz to be installed on your system.

** Disable notifications
By default D-BUS notifications are enabled, to disable them set the layer
variable =erc-enable-notifications= to nil.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
               '((erc :variables erc-enable-notifications nil)))
#+END_SRC

** Enable SASL authentication
To enable SASL authentication set the layer variable =erc-enable-sasl-auth= to
non nil.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
               '((erc :variables erc-enable-sasl-auth t)))
#+END_SRC

** Default servers
You can define the default servers in the ERC custom layout by setting the
variable =erc-server-list=. Setting =:ssl= non nil will connect with =erc-tls=.
You can also use =<leader>aiD= to connect to your default servers outside the
custom layout.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
               '((erc :variables
                      erc-server-list
                      '(("irc.freenode.net"
                         :port "6697"
                         :ssl t
                         :nick "some-user"
                         :password "secret")
                        ("irc.myworkirc.net"
                         :port "1234"
                         :nick "some-suit"
                         :password "hunter2")))))
#+END_SRC

*** Security Note
You should not store your passwords in the clear in your =.spacemacs=, and that
goes double if you version your config file. ERC allows for a number of ways of
protecting this information.

First, ERC will check your =~/.authinfo.gpg=, looking for lines like

#+BEGIN_SRC shell
  machine <irc.server.url> login <yournick> password <yourpassword> port <portnumber>
#+END_SRC

You can omit =:password= in this case.

You could also set an environment variable (or otherwise secret variable) and
read that in =:password=.

* Key bindings

| Key binding | Description                                           |
|-------------+-------------------------------------------------------|
| ~SPC a i e~ | Starts ERC                                            |
| ~SPC a i E~ | Starts ERC via TLS/SSL                                |
| ~SPC a i i~ | Switch to next active ERC buffer                      |
| ~SPC a i D~ | Start ERC with default servers                        |
| ~SPC m b~   | Switch between ERC buffers                            |
| ~SPC m d~   | Interactively input a user action and send it to IRC. |
| ~SPC m D~   | Draw Social Graph using [[https://github.com/vibhavp/erc-social-graph][erc-social-graph]]              |
| ~SPC m j~   | Join a channel, executes the /join command            |
| ~SPC m n~   | Run "/names #channel" in the current channel.         |
| ~SPC m l~   | Run the /list command                                 |
| ~SPC m p~   | Part from the channel                                 |
| ~SPC m q~   | Quit server                                           |

*Note:* If you want to connect securely to an IRC server, you must run =erc-tls=
 command on ~SPC a i E~ instead of the =erc= command.

* Spacemacs Layout Support
ERC buffers are added automatically to the default layout for ERC controlled by
the variable =erc-spacemacs-layout-name= (defaults to "@ERC") and the default
binding ("E") is controlled by =erc-spacemacs-layout-binding=