Skip to content
Easier Literate Programming using Org mode
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
img
LICENSE
README.md
README.org
org-tangle
org-tangle.md
org-tangle.org
org-weave
org-weave.md
org-weave.org

README.md

Humanity is The Big Story, which, in turn, is broken down into very many sub-Stories. We're Story-oriented. Code so far is not. Code is like networks of tunnels where, for all intents and purposes, most of the tunneling has already collapsed, the tunnel paths mostly unknowable.

What makes me so excited about org mode is that it's the first time I've seen literate programming move a tick up into the realm of actually creating a tellable Story.

Lawrence Bottorff, Feb 2014

What is it ?

org-noweb is a couple of programs who make literate programming with Org easier.

  • org-tangle takes one or several org files as arguments and produces programs
  • org-weave takes an org file as an argument and produces, on standard output, source code for typeset documentation.

Org already comes "batteries included" with (some) literate programming abilities, thanks to Eric Schulte and Dan Davison ; but these features are meant for interactive use, with a running Emacs instance.

org-noweb brings these features to the command line, allowing code and documentation to be generated non-interactively. If you care about build automation, that's just what you want.

org-tangle and org-weave themselves are written in literate Org documents, and this repository is managed using these GNU Makefile rules:

What is Literate Programming ? Why should I care ?

I'd personnaly recommend these two resources:

How does it work ?

Consider an Org document (source.org) containing source code interleaved with documentation:

Source code

Running org-tangle source.org will extract the source code blocks according to the :tangle directives within the source.org and generate, for instance:

Tangled code

Then, running org-weave -f gfm source.org > source.md will generate documentation in GitHub flavored Markdown.

Generated documentation

How to install it ?

  1. Clone this repository

    git clone https://github.com/ngirard/org-noweb
  2. Install org-tangle org-weave in a directory belonging to your $PATH

    cd org-noweb
    install -m 755 org-tangle org-weave /dest/dir

org-weave currently does nothing else than exporting to GitHub flavored Markdown ; it needs the ox-gfm package that was contributed by Lars Tveito. ox-gfm currently doesn't belong to the org / org-plus-contrib packages yet; so until then you'll need to

  • grab it from Gmane into a directory dir;

  • run org-weave using

    org-weave -f gfm -O '-Q --batch -L dir' file.org > file.md

The Makefile used

This is the Makefile file I'm using on my system to manage this repository.

PROGRAMS=org-tangle org-weave
TARGETS=$(PROGRAMS) README.md org-tangle.md org-weave.md

all: $(TARGETS)

%: %.org
	org-tangle -l emacs-lisp,org $<

%.md: %.org
	org-weave -f gfm -O '-Q --batch -L ~/.emacs.d/local-packages' $< > $@

DESTDIR=/home/soft/bin
install: all
	install -m 755 $(PROGRAMS) $(DESTDIR)
You can’t perform that action at this time.