Org-mode for Literate Programming and Reproducible Research
===========================================================

This presentation introduces the use of Org-mode [1] as a platform for
Reproducible Research and Literate Programming.  It closely follows
the related JSS paper [2] in both content and form.  Examples are
included demonstrating the interactive use of code blocks from within
Org-mode documents.

Familiarity with Emacs is assumed.

Footnotes:
[1] http://orgmode.org
[2] http://www.jstatsoft.org/v46/i03

Instructions
============

The intent is to first introduce the concepts and syntax of Code
Blocks in Org-mode documents, and then to work through some
illustrative examples.  Follow these steps to work through this
presentation:

1. Ensure that either a recent version of Emacs (24 or greater) or the
   latest version of Org-mode is installed.

2. Evaluate the following Emacs Lisp snippet to configure your Emacs
   to allow code block execution.
   #+begin_src emacs-lisp
     (org-babel-do-load-languages
      'org-babel-load-languages
      '((sh         . t)
        (emacs-lisp . t)
        (lisp       . t)
        (gnuplot    . t)
        (R          . t)
        (dot        . t)
        (python     . t)))
     (setq org-confirm-babel-evaluate nil)
   #+end_src

3. Open the babel.org file in Emacs, and step through the top level
   headings.  The follow headings require special instructions:

   "Export -- supporting reproducible research" This heading will be
   exported to pdf in order to demonstrate the automatic code
   evaluation RR features of Org-mode.  First narrow to only this
   heading with "C-x n S", then export to pdf with "C-c C-e d".  After
   viewing the resulting pdf, widen with "C-x n w".

   "Tangling -- supporting literate programming" This heading will be
   tangled to produce two shell scripts in this directory.  Tangle
   with "C-c C-v t", then run the resulting "./run" shell script.  Be
   careful on slower or older hardware as this script is *very* CPU
   intensive -- like many gnuplot "movies" it relies on processing
   time to control frame rate.

   "Example -- Pascal's Triangle with Lisp and Dot" To run the
   examples in this heading simply interactively execute the code
   blocks with "C-c C-c" in order and view the results.

For more information and trouble shooting the "Working With Source
Code" portion of the Org-mode manual, available with "M-x info" and
online at http://orgmode.org/manual/Working-With-Source-Code.html.