Working with emacs

or just working with org mode

I use emacs as a specialized tool for org mode. I would prefer org mode to be a standalone tool, to integrate with any other editors, but …

From the website: "Org mode is for keeping notes, maintaining TODO lists, planning projects, and authoring documents with a fast and effective plain-text system."

As for many things emacs, it's difficult to describe consicely what org mode can do. I'll just share what I do with it.

1 Usage

1.1 DOING Write prose

Org mode syntax is not that different from markdown and other lightweight markup languages. It is definitely more "outliner oriented" As such it supports various typographic features (rare ones too), even footnotes1

What makes org mode special is actually the editing experience within emacs, with all the helpers to:

  • inserting dates, links, tables, etc
  • moving sections around
  • folding
  • managing table in a simple way (just TAB'ing thought the cells)
  • etc

Editing text is however a real chore with emacs, so I use the evil-mode, to emulate vi modal style on top.

The org mode author mentions "authoring" as one of the goals for org mode and indeed, one can easily export documents in various formats thanks to the built-in exporters and many third party extensions, my favourite being pandoc.

Org mode allows to add metadata (called properties) at the document or a heading level. This metata can be as generic as "author" or custom as "whatwouldbobthinkofthat".

1.2 TODO Manage todolists and projects

Org mode was primarily an outlining mode for emacs. As such, org mode features a powerful system to organize tasks:

  1. in a hierarchy, by nesting subtasks within tasks, without limits
  2. with a task status and tags (TODO, DOING, …)
  3. with custom properties for each task (time estimated, spent, value, $$$, etc)
  4. with timers to track time
  5. with features to generate spreadsheet like table computing information from the outline metadata (sum of time spent, etc)

I use this feature extensively with my customers.

I usually start a project by creating an initial org document in a new git repository, where I start to collect my notes about the customers needs, then I follow with my propositions and estimations, then I track my tasks in this same document and even generate invoices from there, based on the tasks delivered, the time spent or whatever the contract says.

I find org mode encourages creating large files instead of multiple small dedicated documents. It is however possible to "include" external files in an org document, as to produce a "master document". I don't bother with that approach, but I am not writing books.

1.3 DONE Write technical documents

Org mode can be extended with babel to lend itself to literate programming or even interactive programming, like jupyter notebook:

  1. integrate code blocks in your document (python, javascript, lua, golang …)
  2. execute the code blocks in place
  3. have data structures flow from one block to another
  4. integrate code output back it the document, in the form of text or graphics

For instance, we could create a small go program for the go docs, give it the name abs, pass it a value, execute the program, display the results:

package main

import (
	"fmt"
	"math"
)

var (
out []float64
)

func main() {
    for i:=1; i<seed; i++ {
	out = append(out, math.Sqrt(float64(i)))
    }
	fmt.Printf("%#v", out)
}

I use this feature for different purposes:

  1. integrating live information in documentation, computed when updating the documents (version, git info, etc).
  2. generating charts and diagrams, from actual code, by integrating the graphviz or plantuml code in the document
  3. generate student evaluation, based on data tables

1.4 Publishing notes as a blog

Write notes and eventually publish them. See the dedicated article.

2 Setup and configuration

Emacs is designed to be customized, using its emacs-lisp

2.1 Computing org files from the command line (batch mode)

See batch execution doc page

#!/bin/sh
# Tangle files with Org mode
#
emacs -Q --batch --eval "
    (progn
      (require 'ob-tangle)
      (dolist (file command-line-args-left)
        (with-current-buffer (find-file-noselect file)
          (org-babel-tangle))))
  " "$@"

Footnotes:

1

though the way they are displayed varies…