Working with emacs

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 footnotes¹

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".

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.

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

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

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))))
  " "$@"

[BROKEN LINK: 26A1A9F8-E245-4AC3-9150-CC10A719EEE6]