Customizing Emacs

Now you have installed Emacs1 and have been using it for a while (see my advice or even my quick start guide), you want to level up on the Dark Arts of Emacs and take advantage of the largest Emacs selling-point: customization.

You know the saying, “opinions are like .init files, in that every Emacs user has one.” So I’m going to give you a very opinionated perspective: customize Emacs with org-mode.

Git Repository

You know the drill. Create a directory, and immediately run git init to begin the fun. Yes, you might as well commit your changes to yourself.

No, you do not need to share them…but you could.

Create emacs-init.org

This org-mode file will host your basic Emacs configuration. You can type any notes and hyperlinks in this file, but you’ll want to have the following data at the top of the file:

#+TITLE:  Emacs Configuration File
#+AUTHOR: {your name here}
#+EMAIL:  {your email address here}
#+PROPERTY:    results silent
#+PROPERTY:    header-args:sh  :tangle no
#+PROPERTY:    tangle ~/.emacs.d/init.el
#+PROPERTY:    eval no-export
#+PROPERTY:    comments org

Any time you make a change, type: C-c C-v C-t

However, you can evaluate any changes live by creating source code blocks and hitting C-c C-c inside it. That’s groovy.

What extra information would you add? I put all sorts of things in mine, including how to build Emacs. This file is just a text file, after all.

Package Installation

You will want to install various packages, so create a header in your file called, Package Installation, and add the following:

Emacs has, like every other operating system, a [[http://tromey.com/elpa/][package manager]] with
its own collection repository.  Adding the following repositories:

#+BEGIN_SRC elisp
   (require 'package)

   (setq package-archives '(("org"       . "http://orgmode.org/elpa/")
                            ("gnu"       . "http://elpa.gnu.org/packages/")
                            ("melpa"     . "http://melpa.milkbox.net/packages/")
                            ("marmalade" . "http://marmalade-repo.org/packages/")))
   (package-initialize)
   (package-refresh-contents)
#+END_SRC

This will allow you to issue a M-x package-list-packages and see almost every package available to install.

More Lisp Source

You will create and download Emacs Lisp source code files that are not part of any package. We will store them all in the elisp directory:

All individual source code files (that don’t below to any package),
go into the =elisp= directory.

#+BEGIN_SRC elisp
  (add-to-list 'load-path "~/.emacs.d/elisp")
#+END_SRC

Use-Package

While I have not completely converted to it, I highly recommend using use-package:

#+BEGIN_SRC elisp
  (require 'use-package)
#+END_SRC

This does mean that whenever you have a new Emacs installation, you will need to issue: M-x package-install and type: use-package. Small price to pay for the advantages of installation and configuration that it gives you.

What does it give you? See the web site for details, but let’s suppose you are, like me, a big fan of the Silver Searcher. Here is its configuration:

Since I use latest version of =ag=, highlight keywords:

#+BEGIN_SRC elisp
  (use-package ag
    :init      (setq ag-highlight-search t)
    :config    (add-to-list 'ag-arguments "--word-regexp"))
#+END_SRC

In this case, the ag package will be installed whenever you want to use it.

Sub-File Customization

As your configuration file grows, you’ll want to break it into pieces, and then selectively load the parts based on need. For instance, as a polyglot programmer, some sprints find me programming Ruby and other times, Clojure or JavaScript. Instead of always loading my configuration for every language I sometimes use, I pull those out.

Let’s create an example init script that is optionally called by your primary script, e.g. emacs-example.org

#+TITLE:  Emacs Example File
#+AUTHOR: {your name here}
#+EMAIL:  {your email address here}
#+PROPERTY:    results silent
#+PROPERTY:    header-args:sh  :tangle no
#+PROPERTY:    tangle ~/.emacs.d/elisp/init-example.el
#+PROPERTY:    mkdirp yes
#+PROPERTY:    eval no-export
#+PROPERTY:    comments org

Now you can add the same types of headers and configuration values. You just need the following section at the end:

* Technical Artifacts

   Need to =provide= this file in order to require this package.

   #+BEGIN_SRC elisp
     (provide 'init-example)
   #+END_SRC

When you tangle this file, it writes it to the ~/.emacs.d/elisp directory, and since that is on the load-path, you can load it from your primary initialization script as Lisp with:

(require 'init-example)

Or do that interactively with: M-x load-library and type init-example.

Summary

With start, you are now ready to use the use-package to add and configure new packages, and keep notes by having them in an org-mode format.

Footnotes:

1

If you are using a Mac, transitioning to Emacs will be easier with Aquamacs. However, if you are a VI aficionado, then I suggest starting out with Spacemacs.