Customizing Emacs

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.

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.

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.

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

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.

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.

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.