Toon’s Literate Dotfiles

Literate dotfiles

These are my dotfiles. I’m using Emacs Org mode, and more specifically org-babel to build these dotfiles using literate programming.

Literate programming

Literate programming is a way of writing programs where the documentation is mixed with the source code. It was first introduced by Donald Knuth.

Instead of being written for computers, literate programs are intended for programmers first. So the order follows the human logic, and not that of computers. The source files are compiled so computers also can read them.

You can read all about it Knuth’s paper.

Org-babel

Org-babel gives Org mode the ability to mix human natural language with computer source code. It can be used to mix different languages together. A piece of data may pass from a table to a Python code block, and eventually go through a gnuplot code block to end up as a plot embedded in the document.

Output files

Each .org tangles to one or more files somewhere in my $HOME directory. Many dotfiles management tools use symbolic links to place files at their correct location, but with this approach output files are written directly to the correct location.

There are several ways to configure the output files, but in most cases I’m using a 1-to-1 configuration by specifying document-wide properties. 

#+PROPERTY:   header-args+ :comments both
#+PROPERTY:   header-args+ :mkdirp yes
#+PROPERTY:   header-args+ :tangle "<filename>"
-----

I’m appending + to header-args otherwise each line would overwrite the settings of the previous, and with the plus they are appended. See Property syntax.

Comments

comments is set to “both”. With this setting, the text from the org file is inserted as comment in the file, and also a link to the source file is added.

For example, pryrc.org gets tangled to: 

#-*- mode: ruby -*-
# Stepping code

# Enable short commands for stepping around while debugging.

# [[file:literate-dotfiles/pryrc.org::*Stepping%20code][Stepping code:1]]
if defined?(PryByebug)
  Pry.commands.alias_command 'c', 'continue'
  Pry.commands.alias_command 's', 'step'
  Pry.commands.alias_command 'n', 'next'
  Pry.commands.alias_command 'f', 'finish'
end
# Stepping code:1 ends here

# ...

The headlines are included in the comments, but also Org mode links to the source blocks are included. If you’d install and enable org-link-minor-mode those links become clickable.

Mkdir

And mkdirp ensures the destination directory will be created.

Multiple files

In some cases, a single .org file creates multiple output files, like git.org. In those cases I specify the output file at headline level: 

** My script
:PROPERTIES:
:header-args: :tangle ~/path/to/destination
:header-args+: :comments both :mkdirp yes :shebang "#!/bin/bash -e"
:END:

or sometimes at code block level: 

#+BEGIN_SRC my-lang :tangle ~/path/to/destination
... source of the script here ...
#+END_SRC

Index [16/16]

These are the things I manage with this project:

Deprecated [6/6]

These files are no longer actively maintained because tools were replaces by other:

Usage

Just run make to update all dotfiles. make publish will generate the HTML for these dotfiles.

Other examples

These are other people’s dotfiles managed with org-babel: