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 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.
.org tangles to one or more files somewhere in my
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.
header-args otherwise each line would overwrite
the settings of the previous, and with the plus they are appended. See
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.
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.
mkdirp ensures the destination directory will be created.
In some cases, a single
.org file creates multiple output files,
git.org. In those cases I specify the output file at
** 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
make to update all dotfiles.
make publish will generate
the HTML for these dotfiles.
These are other people’s dotfiles managed with org-babel: