# Introduction to Literate Programming

Welcome to a brief tutorial on literate programming in org-mode.

The following began as the basis for a workshop for the PDX Emacs Hackers meetup, but since everyone couldn't attend, I decided to expand it into a tutorial. I assume that you understand the basics of Emacs and I assume you have familiarity with org-mode for creating exported documents.

Warning: The examples are pretty lame.

## Requirements

During my workshop, I mentioned the following requirements to follow along. You may not need all the versions I mention here, but…

• Emacs, v23 or better (I really suggest v24.4 or better)

Type: C-h v and emacs-version

• org-mode, v8.2.10

Type: C-h v and org-version

Install: M-x package-refresh-contents M-x package-install and org

• Python and Ruby (or can translate silly examples into your favorite language)

## Background

Before we dive into how org-mode does literate programming, perhaps I should briefly describe literate programming.

### Why Literate Programming

Literate Programming first invented by Donald Knuth in 1980’s in an attempt to emphasize communication to other members on your team. As Donald Knuth once wrote:

“Let us change our traditional attitude to the construction of programs. Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.”

Wanting programs to be written for human understanding, with the order based on logic of the problem, ant not constrained to deficiencies in the programming language, we create a literate programming document that generates a document for people and and the source code files:

The idea is to invert code peppered with comments to prose interjected with the code.

While the resulting source code tangled from a literate programming document, may look the same to one coded directly, this idea did not result in an industry changer. Although it is used (to various degrees) in niche circles.

### Why Org?

Knuth's original literate programming approach was "text with minimal support, as only he wrote a program noweb to create (weave) the documentation and write (tangle) the source code.

For literate programming to be truly useful, one needs help from an editor, for instance the iPython's notebook. In the end, you still want text, as Carsten Dominik wrote:

“In the third millennium, does it still make sense to work with text files? Text files are the only truly portable format for files. The data will never get lost.”

So if you buy into literate programming, org-mode is fookin' brilliant, especially since we already use org-mode for everything else, right?

• Better documentation for your source code
• Great for team communication over issues and problems
• Clarify your own thoughts for complicated situations
• Note-oriented REPL for investigating new libraries
• Inter-language facility
• Org's organizational features, like Agendas

### A Warning

The software world of the 1980s is quite different than the current landscape, as engineers are more connected and work in teams, but they don't often use the same tools. If your team doesn't use Emacs, you may still find org-mode's approach useful.

First, it is a good way to work through complicated algorithms, and once you have something good, commit the resulting source code (as the prose you write become comments in the code).

Second, org-mode files can be a thoughtful repl as each block can be evaluated separately, and the results can be fed back to other blocks… but I'm getting a head of myself.

## Exporting Documents

The goal of using an org-mode file, with the methods I present here, is exporting to some document, either HTML, mail messages, Wiki, etc. While Org is really good for technical papers, my focus here is code and programming.

I'll just mention that you can use the LaTeX support to write things like the following:

- Unicode References :: for instance, \alpha, \beta and \gamma.
- Subscripts :: like Hydrogen atoms, H_2, and Water, H_{2}O.
- Superscripts :: The mass of the sun is 1.989 x 10^30 kg.
- Embedded Equations :: Surrounded with either single =$=, like$a^2=b$, or escaped parenthesis, like: $$b=\frac{1}{2}$$ - Separated equations :: Either in double =$$= or escaped brackets, like this:$$ a=\frac{1}{2}\sqrt{2} $$or this: $a=-\sqrt{2}$ or this: $$x=\sqrt{b}$$ #+OPTIONS: tex:t  Into this pretty HTML: Unicode References for instance, α, β and γ. Subscripts like Hydrogen atoms, H2, and Water, H2O. Superscripts The mass of the sun is 1.989 x 1030 kg. Embedded Equations Surrounded with either single , like $$a^2=b$$, or escaped parenthesis, like: $$b=\frac{1}{2}$$ Separated equations Either in double $$ or escaped brackets, like this: $$a=\frac{1}{2}\sqrt{2}$$ or this: $a=-\sqrt{2}$ or this: $$x=\sqrt{b}$$ ## Basics This tutorial is really a workshop, so fire up Emacs, and create an org-mode file, and let's get cracking. Create the following source code block (no, case doesn't matter): #+BEGIN_SRC emacs-lisp (directory-files ".") #+END_SRC  • Type C-c C-c to execute the command and note the results, are inserted back into your file… we'll use that to our advantage later. • Type C-c ’ (apostrophe) to edit the block in the language's mode. This allows you to gain benefit of paredit and whatnot. ### Shortcuts If you are using a newer version of Emacs (not v22) or a later version of org-mode (installed from ELPA), use Org Templates: • Create a block quickly by typing: <s and hit TAB • If not, you can try yasnippets • You can hit C-c C-c anywhere from BEGIN to END • Jump to next block in your file with C-c M-f and back C-c M-b ### Good Configuration To syntax highlight your code, set the following in your .emacs init file: (setq org-confirm-babel-evaluate nil org-src-fontify-natively t org-src-tab-acts-natively t)  The last variable removes the annoying "Do you want to execute" your code when you type: C-c C-c ## Language Support While many programming languages are supported, not everything is (not too difficult to add your own, tho). Let me go through a few popular ones and note a few differences. ### Ruby Example Let's try re-creating our Lisp example in Ruby: #+BEGIN_SRC ruby Dir.entries('.') #+END_SRC  If C-c C-c doesn't work, you may have to pre-load the support: M-x load-library and then ob-ruby You can load yer language beforehand by adding the following to .emacs): (require 'ob-ruby)  ### Python Example Notice that Ruby, like Lisp, uses the results of the last expression. Python, on the other hand, expects the results to come from an explicit return: #+BEGIN_SRC python from os import listdir return listdir(".") #+END_SRC  ### Shell Example Most languages take the resulting values as the results. The shell, on the other hand, uses the results that are printed to standout out: #+BEGIN_SRC sh ls -1 #+END_SRC  If C-c C-c doesn't work, you may have to pre-load the support: M-x load-library and then ob-sh ### All Favorite Languages If, like me, you are a polyglot programmer, you may want to add something like following to your .emacs file: (org-babel-do-load-languages 'org-babel-load-languages '((sh . t) (js . t) (emacs-lisp . t) (perl . t) (scala . t) (clojure . t) (python . t) (ruby . t) (dot . t) (css . t) (plantuml . t)))  ## Block Settings Most of the interesting stuff happens by setting various block parameters (also called header parameters). Code blocks can have zero or more header parameters. First let's dive into the various ways they can be defined, and then discuss most of the specific parameters after, but I need a parameter we can use. ### Example: dir As an example of how to set a parameter, let's look at the dir parameter, which sets the directory/folder for where a code block executes: #+BEGIN_SRC sh :dir /etc ls #+END_SRC  Type C-c C-c to execute this, and you'll notice a lot more entries in that directory… assuming, of course, you have a /etc directory. An interesting aspect of this parameter is when you use Tramp references to have code block remotely executed: #+BEGIN_SRC sh hostname -f #+END_SRC #+RESULTS: : blobfish #+BEGIN_SRC sh :dir /howardabrams.com: hostname -f #+END_SRC #+RESULTS: : goblin.howardabrams.com  ### Setting Parameter Locations Parameters can be set in different locations. Here is the list from most specific to most general: • Inline with Header Block, or above Header Block • Defaults for Blocks in a Section • Defaults for Blocks in entire Document • Defaults for Every Document Having a particular parameter set for all documents isn't very useful to me, but this can be done by setting either of these list variables: • org-babel-default-header-args • org-babel-default-header-args:<lang> Note: You can set parameters when a block is called, but we'll talk about this later. ### Too Many Parameters? Setting parameters inline with Header Block is fine with few parameters, but org-mode supplies lots of parameters, and if you have too many, you can bring one or more up above block. For instance, the following are equivalent: #+BEGIN_SRC sh :dir /etc :var USER=howard grep$USER passwd
#+END_SRC

#+BEGIN_SRC sh :var USER=howard
grep $USER passwd #+END_SRC #+HEADER: :dir /etc #+HEADER: :var USER=howard #+BEGIN_SRC sh grep$USER passwd
#+END_SRC


### Section Default Parameters

Parameters that should be the same for all source blocks in a section can be placed in a property drawer. Perhaps, you should just run through this on your own by following these steps:

• Type: C-c C-x p
• For Property enter: dir
• For Value enter: /etc

Jump to the :PROPERTIES: drawer, and hit TAB to see the contents, but it should look something like:

* A New Section
:PROPERTIES:
:dir: /etc
:END:

#+BEGIN_SRC ruby
File.absolute_path(".")
#+END_SRC

#+RESULTS:
: /etc


### Language-Specific Default Values

You can specify language-specific header arguments. Try the following:

• Type: C-c C-x p
• For Property enter: header-args:sh
• For Value enter: ~:dir /etc
• Type: C-c C-x p
• For Property enter: header-args:ruby
• For Value enter: :dir /

You should have something that looks like:

* Another Section
:PROPERTIES:
:END:

#+BEGIN_SRC sh
#+END_SRC

#+BEGIN_SRC sh
echo $NUM_USERS #+END_SRC #+RESULTS: : 2 This doesn't return... why? #+BEGIN_SRC ruby 21 * 2 #+END_SRC  Warning: A :session setting for a section is shared for each block… regardless of language! Probably not what you want. ### Writing Results to a File Create and evaluate this block: #+BEGIN_SRC ruby :results output :file primes.txt require 'prime' Prime.each(5000) do |prime| p prime end #+END_SRC  Notice that the results of evaluation is a link to a file. Click on the link to load the file in a buffer. Note: The :file parameter needs :results output As it doesn't know how to format internal values ## Exporting Hit C-c C-e h o to display your file in a browser. The :exports header argument specifies what to export: • code for just the block • results for just the results to evaluating block • both for both code and results • none to ignore the block Note: The :exports is good to set as a document property. To get syntax highlight for HTML exports, simply include the htmlize library: (require 'htmlize)  Should come with recent versions of org-mode. Doesn't load? Install it from ELPA. ## Literate Programming Some programming is useful in creating source code files from an org-mode file (called tangling). ### Tangling The :tangle parameter takes all blocks of the same language, and writes them into the source file specified. #+BEGIN_SRC ruby :tangle double-space.rb while s = gets print s ; puts end #+END_SRC  Type: C-c C-v t to render double-space.rb Multiple code blocks with the same value are all included in the same file in order. With a :tangle parameter value of yes, writes the block(s) to a file with same name as org file. Use PROPERTY to specify values for the entire file: #+PROPERTY: tangle ~/.emacs.d/elisp/bling-mode.el  ### Comments If sharing source with others, have prose turned into comments: Precede each line in the text from standard in (or file) with the current line number. See [[http://benoithamelin.tumblr.com/ruby1line][one liners]]. #+BEGIN_SRC ruby while s = gets puts "#{$<.file.lineno}: #{s}"
end
#+END_SRC

#+PROPERTY: tangle lineno.rb


Gets turned into this Ruby script:

# Precede each line in the text from standard in (or file) with the
# current line number.
# See [[http://benoithamelin.tumblr.com/ruby1line][one liners]].

while s = gets
puts "#{$<.file.lineno}: #{s}" end  Note: Only prose above a block is written out as a comment. ### Shebang When creating scripts, we often need to give it the initial interpreter to use. Here is specify the :shebang parameter (either as a block header or a document property): Precede each line in the text from standard in (or file) with the current line number. See [[http://benoithamelin.tumblr.com/ruby1line][one liners]]. #+BEGIN_SRC ruby :shebang "#!/usr/local/bin/ruby" while s = gets puts "#{$<.file.lineno}: #{s}"
end
#+END_SRC

#+PROPERTY: shebang #!/bin/ruby
#+PROPERTY: tangle lineno


Works as expected:

#!/usr/local/bin/ruby
# Precede each line in the text from standard in (or file) with the
# current line number.
# See [[http://benoithamelin.tumblr.com/ruby1line][one liners]].

while s = gets
puts "#{$<.file.lineno}: #{s}" end  ### Noweb If you name a block, you can include that block inside another block… as text, using :noweb1. Consider this org-mode file: Print the last field of each line. #+NAME: the-script #+BEGIN_SRC ruby puts$F.last
#+END_SRC

#+BEGIN_SRC sh :noweb yes :tangle last-col.sh
ruby -ane '<<the-script>>'
#+END_SRC


Creates last-col.sh source code that contains:

ruby -ane 'puts $F.last'  How useful is this? Older languages that Donald Knuth used, required all variables and functions to be defined before used. This meant, you always wrote code, bottom-up. However, some code may be better explained from a top-down approach. The web and tangling approach could work well for some algorithms. #### Warning about Noweb Suppose we had a block with multiple lines, as in: #+NAME: prime #+BEGIN_SRC ruby require "prime" Prime.prime?(ARG[0]) #+END_SRC #+BEGIN_SRC ruby :noweb yes :tangle primes.sh cat$* | xargs ruby -ne '<<prime>>'
#+END_SRC


Treats the preceding text before the noweb reference like initial comment characters, as it will generate the following:

cat $* | xargs ruby -ne 'require "prime" cat$* | xargs ruby -ne 'Prime.prime?(ARG[0])'


This requires either here docs or single quotes in a shell, or triple quotes in Python:

cat $* | xargs ruby -ne ' '  ## Variables Org can pass in one or move values into your source block as variables. This begin with an example where the variable is statically set: #+BEGIN_SRC python :var interest=13 return 313 * (interest / 100.0) #+END_SRC #+RESULTS: : 40.69  Of course, you can specify multiple variables, in one or more places, as in this example: #+HEADER: :var a=42 d=56 :var f=23 #+HEADERS: :var b=79 e=79 #+BEGIN_SRC ruby :var c=3 g=2 [ a, b, c, d, e, f, g ] #+END_SRC #+RESULTS: | 42 | 79 | 3 | 56 | 79 | 23 | 2 |  But how useful is there in setting static values for a variable? ### Block-to-Block Value Passing Following along by creating a source block with a name, as in: #+NAME: twelve-primes #+BEGIN_SRC ruby require 'prime' Prime.first 12 #+END_SRC #+RESULTS: twelve-primes | 2 | 3 | 5 | 7 | 11 | 13 | 17 | 19 | 23 | 29 | 31 | 37 |  Notice the RESULTS: section has the same name as the block. We can pass this result into another code block as an array variable: #+BEGIN_SRC python :var primes=twelve-primes return primes[-1] #+END_SRC #+RESULTS: : 37  Perhaps this is the first time Ruby and Python have worked together. ### Tabular Variable Data For this next example, I need a table of interesting numbers. A wee bit of Lisp will do handy, but feel free to re-write in your favorite language. #+NAME: cool-numbers #+BEGIN_SRC emacs-lisp (mapcar (lambda (i) (list i (random 10) (expt i 2) (random 100) (expt i 3) (random 1000))) (number-sequence 1 10)) #+END_SRC #+RESULTS: cool-numbers | 1 | 1 | 1 | 14 | 1 | 74 | | 2 | 7 | 4 | 25 | 8 | 823 | | 3 | 2 | 9 | 68 | 27 | 402 | | 4 | 4 | 16 | 17 | 64 | 229 | | 5 | 6 | 25 | 4 | 125 | 208 | | 6 | 7 | 36 | 67 | 216 | 203 | | 7 | 0 | 49 | 96 | 343 | 445 | | 8 | 0 | 64 | 58 | 512 | 908 | | 9 | 2 | 81 | 15 | 729 | 465 | | 10 | 0 | 100 | 61 | 1000 | 798 |  The cool-numbers table becomes an array or arrays for our block, so let's use a Python comprehension to spit out the values into one long array. And just to make it interesting, let's increment each number: #+BEGIN_SRC python :var nums=cool-numbers :results list return [ cell + 1 for row in nums for cell in row ] #+END_SRC #+RESULTS: - 2 - 4 - 2 - 23 - 2 - 955 - 3 - 7 - 5 - 43 - 9 ...  #### Slicing and Dicing Tables We can get just a single row from a table, but giving an indexed number to the cool-numbers table reference. Check out this short Ruby block: #+BEGIN_SRC ruby :var fifth=cool-numbers[4] fifth #+END_SRC #+RESULTS: | 5 | 9 | 25 | 93 | 125 | 524 |  We can also get just a single column in a similar way. In this case, the comma specifies that we want any row, but the 4 limits it to just the fifth column that contains our numbers raised to the third power: #+NAME: cubes #+BEGIN_SRC elisp :var cubes=cool-numbers[,4] cubes #+END_SRC #+RESULTS: cubes | 1 | 8 | 27 | 64 | 125 | 216 | 343 | 512 | 729 | 1000 |  #### Reprocessing The cool-numbers was used in the cubes block (that we named), and we can use the results from that block in another block: #+NAME: roots_of_list #+BEGIN_SRC python :var lst=cubes :results list import math return [ math.sqrt(n) for n in lst ] #+END_SRC #+RESULTS: roots_of_list - 1.0 - 2.8284271247461903 - 5.196152422706632 - 8.0 - 11.180339887498949 - 14.696938456699069 - 18.520259177452136 - 22.627416997969522 - 27.0 - 31.622776601683793  Once again, Ruby and Python being the close siblings that they are. ## Keeping your Blocks Clean A block of code does something, but A block of code also communicates something, so try to remove necessary code that doesn't help communicate out of the block. Here are two examples of how that can be done. ### Cleaning Results Sometimes the results from an evaluation aren't exactly what we want exported to our document. While we could probably change the code, perhaps our point is the code as written. You can change the output from a code block using the :post parameter, this allows us to have the code block we wish, as well as the resulting output. For example, the shell command, ls -l, pre-pends an initial Total line. To remove it, we first create a /processor code block to return all lines except the first. Notice, my variable, data: #+NAME: skip_first #+BEGIN_SRC elisp :var data="" (cdr data) #+END_SRC  Now our code block can contain just the ls -l, but we sent the output to the skip_first block. We assign its data variable to *this* (which refers to our output), and now we only have files: #+BEGIN_SRC sh :post skip_first(data=*this*) ls -l #+END_SRC #+RESULTS: -rw-rw-r-- 1 howard howard 6075 Sep 2 2015 emacs-init.org -rw-rw-r-- 1 howard howard 21676 Jul 5 2015 eshell-fun.org -rw-rw-r-- 1 howard howard 3014 Jul 5 2015 eshell.org -rw-rw-r-- 1 howard howard 4362 Sep 2 2015 getting-started2.org -rw-rw-r-- 1 howard howard 5125 Mar 30 2015 getting-started.org -rw-r----- 1 howard howard 110690 Mar 11 2015 gnu-shaving.png ....  Typically, we may only want an example of a long set of results, Processing blocks like this are often something we don't want exported. ls -l  ### Environment Setup I often query OpenStack instances with its nova command. This command reads connection credentials from environment variables, and we often set these in resource files. A typical session would go like: $ source openrc
\$ nova list


The code in a block that I want to communicate is the nova list part, however, the source command, is necessary, but is not something I want exported, so I put that unsightly code in :prologue sections:

#+HEADER: :prologue "source openrc"
#+BEGIN_SRC sh
nova list
#+END_SRC


Code in the :prologue will not be exported, and my team mates who receive my illustrious prose, will only see the nova list and possibly the results of executing it.

### Using RVM

Languages like Python and Ruby often want a virtual machine to specify how something should be processed. You can use :prologue with two backslashes to pre-pend it (for shell calls anyway):

#+BEGIN_SRC sh :prologue "~/.rvm/bin/rvm 1.9.3@msw exec \\"
gem list
#+END_SRC


Note: Execution of Ruby or Python code is based on the rvm, or pyvenv or ELPY.

## Miscellaneous Features

The following are some parameters and other features that didn't seem to fit before.

### Calling Blocks

So far, our code blocks have pulled values into their code blocks with the :var parameter, however, we can also push values into blocks by calling it elsewhere in our document.

Remember our roots_of_list block we created above? It took a variable, lst, but here we re-call it with a different value for its variable:

#+CALL: roots_of_list( lst='(16 144 81 61) )

#+Results:
| 4.0 | 12.0 | 9.0 | 7.810249675906654 |


We can also call it with values from the output of another code block. Here we pass in a column from our cool-numbers table:

#+CALL: roots_of_list( lst=cool-numbers[,2] )

#+RESULTS:
| 1.0 | 2.0 | 3.0 | 4.0 | 5.0 | 6.0 | 7.0 | 8.0 | 9.0 | 10.0 |


Note: You can set additional parameters for the block inside brackets. See org#Evaluating code blocks for details.

How does this look when exported? Depends on the results. If the block returned a single value, for instance, something like:

#+NAME: cube
#+BEGIN_SRC elisp :var n=0 :exports none
(* n n n)
#+END_SRC


Calling it with a table does what you expect:

#+CALL: cube[:results table](n=3)


But calling it with a list, seems to export it inside a <pre> block. YMMV, I suppose.

### Embedded Results

If you want a quickly evaluated result from a language, you can embed code in curlies. For instance, add the following to your org file, and type C-c C-c at the beginning of the line:

src_ruby{ 5+6 } =11=


The answer, 11, was appended to the line. When exported, only the results are shown (not the source).

I suppose these would be most useful within the prose, as in:

We will be bringing src_ruby{ 5+6 } children.


Note: The answer will be wrapped in HTML <code> tags.

You can insert the results of a shell script:

Why do I have src_sh{ ls /tmp | wc -l } files?


Or even the insert the results from an Emacs Lisp function:

src_elisp{ org-agenda-files }


Also supports calling blocks too. For instance, we defined a block of code earlier and named it roots_of_list, and this can be called:

call_roots_of_list( lst=cool-numbers[,2] )
| 1.0 | 2.0 | 3.0 | 4.0 | 5.0 | 6.0 | 7.0 | 8.0 | 9.0 | 10.0 |


Warning: During my workshop, when I was demonstrating this feature, we noticed that if you C-c C-c the src_XYZ feature to embed the answer, when you export it, you will have two answers. The one you embedded and the results of evaluating the code during the exporting.

### Library of Babel

The Library of Babel is a collection of code blocks accessible to any org-mode file. Like the Gem resources for Ruby, you specify the files containing named blocks that should be accessible.

Do this by following these steps:

• Create a new org-mode file with at least one named block
• Once in your Emacs session: C-c C-v i
• Select your new file to specify that this should be added to babel collection.

Try it out with a code block that might be nice to use:

#+NAME: take
#+BEGIN_SRC elisp :var data='() only=5
(require 'cl)
(flet ((take (remaining lst)
(if (> remaining 0)
(cons (car lst) (take (1- remaining) (cdr lst)))
'("..."))))
(take only data))
#+END_SRC


After you have saved this new file, and loaded it as a babel addition, let's use it with a :post parameter:

#+BEGIN_SRC python :post take(data=*this*, only=3)
return [x * x for x in range(1, 20)]
#+END_SRC

#+RESULTS:
| 1 | 4 | 9 | ... |


This feature is really helpful with:

• :post processing output
• #+CALL where you want just the results on line
• call_XYZ() where you want results embedded inline

For a more permanent addition to your tower, add a call to org-babel-lob-ingest with each file to your Emacs init file.

## Specialized Languages

I've found a few programming languages that really add to an org-mode way of writing documents.

### Graphviz

If you have Graphviz installed, we can create an diagram directly from your document:

#+BEGIN_SRC dot :file some-illustration.png
digraph {
a -> b;
b -> c:
d -> a;
}
#+END_SRC


For these, I often set :exports results so that the code to generate the image isn't exported.

Warning: If you wish to execute the code block to generate an image, the language needs to be set to dot, but if you want to edit the code in a side buffer (with the C-c ’ … apostrophe), you need to change the language to graphviz-dot.

### PlantUML

If you have PlantUML installed, you can do something like:

#+BEGIN_SRC plantuml :file sequence.png :exports results
@startuml sequence-diagram.png

Alice -> Bob: synchronous call
Alice ->> Bob: asynchronous call

@enduml
#+END_SRC


Hrm… have descriptive illustrations associated with your source code?

### Calc

We have access the impressive Emacs Calculator as well to use a more normal mathematical syntax.

#+BEGIN_SRC calc :var a=2 b=9 c=64 x=5
((a+b)^3 + sqrt(c)) / (2x+1)
#+END_SRC

#+RESULTS:
: 121.727272727


Let's simplify a formula by leaving out some of the values for a variable:

#+BEGIN_SRC calc :var a=4 b=2
((a+b)^3 + sqrt(c)) / (2x+1)
#+END_SRC

#+RESULTS:
: (sqrt(c) + 216) / (2 x + 1)


You may need to load it: M-x load-library and type: ob-calc

Keep in mind that each line of each calc block is placed on the stack in the Calc mode buffer (see it with C-x * *).

## Summary

Here is a summary listing of the header arguments, separated based on your goal or needs:

• Code Evaluation?
dir
specify directory the code should run … Tramp?
session
re-use interpreter between code blocks
file
write results to the file system
eval
limit evaluation of specific code blocks
cache
cache eval results to avoid re-evaluation of blocks
var
setting variables for a block (ignore with no-expand)
• Exporting?
results
either output or value and the formatting
exports
how the code and results should be exported
• Literate Programming?
tangle
how the source written to a script file … this is literate programming.
mkdirp
create parent directory of tangled source file
shebang
the initial line written to tangled files
noweb
toggle expansion of noweb references
noweb-ref
resolution target for noweb references
• Special Input?
prologue
text to prepend to code block body
epilogue
text to append to code block body
• Special Output and Formatting?