assemb.el
is a little Emacs Lisp build system that simplifies the
process of building modular documents. It's particularly suited
towards programatically automating the process of assembling files to
be exported using org-mode
's suite of tools. It supports
hierarchical targets, "generic" targets, and incremental builds.
- I first started working on
assemb.el
to eliminate redundancy when I was writing personal statements for PhD applications.assemb.el
helped me reuse the parts that were common to most essays, and to easily compose documents from smaller parts. - I frequently use
org-mode
when writing notes as I run experiments and such. Sometimes I like to demonstrate some algorithms I'm working on by embedding source code in my notes, which is then executed every time I export my document so the results are displayed on the exported product. Sometimes these little programs take a noticeable time to run though, and it's annoying to wait for it every time I want to export my work.assemb.el
's incremental building capability saves me lots of time here.
To use assemb.el
, build targets are specified in a file called
assemb.el
in the root of your project.
Below is a simple Hello, World example.
(require 'assemble)
(defun default () (hello-world))
(assemble-target "hello-world" depending on '()
(message "Hello, Newman"))
To build your project, simply execute M-x assemble
. You'll be
prompted for a target name, but if you press Enter without giving one
it'll execute the target specified in your default
function.
Here we'll make a build target to export an org-mode file to LaTeX.
(require 'assemble)
(defun default () (foo.pdf))
(assemble-target "foo.pdf" depending on '(foo.org)
(defile "foo"
(insert "\\usepackage{custom-latex-style}\n")
(append-file-to-buffer "foo.org")
(assemble-latex-bibtex "foo")))
The defile
function is used to make a temporary buffer to export. We
use insert
and append-file-to-buffer
to edit the contents of the
buffer to be exported.
In the previous example, we made a build target that might be useful
for all .org
files, it is not exactly particular to foo.org
. Here
we'll show how to improve this to generate a website from several
.org
files.
(require 'assemble)
(defun default () (website))
(assemble-target "website" depending on '(foo.html bar.html))
(assemble-wildcard "html" depending on '(_org style.css)
(defile _filename
(insert-css "style.css")
(append-file-to-buffer _filename)
(assemble-html (concat _filename ".html"))))
Here we define a build target called "website"
that simply depends
on the files foo.html
and bar.html
. Since we wish to build all
HTML files the same way, we use assemble-wildcard
to define a
build-target for all .html
files (note that this can be overriden by
a build target for those .html
files that you want to treat
differently). The _org
dependency corresponds to the .org
file
with the same name as the .html
file being built. Likewise,
_filename
refers to the base name of the file.