1 #+OPTIONS: H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
2 #+STARTUP: align fold nodlcheck hidestars oddeven lognotestate hideblocks
3 #+SEQ_TODO: TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
4 #+TAGS: Write(w) Update(u) Fix(f) Check(c)
6 #+AUTHOR: Eric Schulte, Dan Davison
7 #+EMAIL: schulte.eric at gmail dot com, davison at stats dot ox dot ac dot uk
11 # #+INFOJS_OPT: view:content
15 <p>executable source code blocks in org-mode</p>
19 <img src="images/tower-of-babel.png" alt="images/tower-of-babel.png"/>
22 <a href="http://commons.wikimedia.org/wiki/Pieter_Brueghel_the_Elder" title="">
23 <b>Pieter Brueghel the Elder</b>
26 "And the Lord said, Behold, the people is one, and they have
27 all one language; and this they begin to do; and now nothing
28 will be restrained from them, which they have imagined to
43 :CUSTOM_ID: introduction
45 Org-babel is an extension to the very excellent [[http://orgmode.org/][Org-mode]], providing
46 the ability to execute source code in many different languages within
47 org-mode documents. Org-mode is an [[http://www.gnu.org/software/emacs/][Emacs]] major mode for doing almost
48 anything with plain text. If you are not familiar with Org-mode
49 please take a moment to read [[http://orgmode.org/][the Org-mode homepage]] before continuing.
51 Org-babel provides the following modifications to [[http://orgmode.org/manual/Literal-examples.html][the existing
52 support]] for blocks of source code examples in the org-mode core.
54 1. Interactive source code execution
55 2. Arguments to source code blocks
56 3. Exportation of source code blocks to files (literate programming)
60 :CUSTOM_ID: getting-started
63 1) Grab the latest code from the git repo at [[http://github.com/eschulte/org-babel/tree/master][github/org-babel]]
65 git clone git://github.com/eschulte/org-babel.git
68 2) Add the following lines to your .emacs, replacing the path as
69 appropriate. A good place to check that things are up and running
70 would the examples in [[* Basic org-babel functionality][Basic org-babel functionality]].
71 #+begin_src emacs-lisp
72 (add-to-list 'load-path "/path/to/org-babel/lisp")
73 (require 'org-babel-init)
76 3) Finally, activate the subset of supported Org-babel languages
77 which you want to be able to execute on your system. As an
78 example, the following activates python, ruby and R. For a full
79 list of languages, with notes on their dependencies see the
80 [[#reference-and-documentation][Reference / Documentation]] section below.
81 #+begin_src emacs-lisp
82 (require 'org-babel-python)
83 (require 'org-babel-ruby)
84 (require 'org-babel-R)
86 ;; Once you've activated languages, load the library of babel to
87 ;; make pre-built helper functions available in the languages you will be using.
88 (org-babel-load-library-of-babel)
91 * Basic org-babel functionality
93 :CUSTOM_ID: basic-functionality
95 *** Source code blocks
97 :CUSTOM_ID: source-code-blocks
100 Org-babel is all about *source code blocks* in org mode. These are
101 blocks of code (in whatever language), that can occur anywhere in
102 an org-mode file. For example, the following is a source block
103 containing [[http://www.ruby-lang.org/][ruby]] code:
106 : "This file was last evaluated on #{Date.today}"
109 If you are unfamiliar with the notion of a source code block in
110 org-mode, please have a look at the [[http://orgmode.org/manual/Literal-examples.html][relevant manual section]] before
113 Note that above is what the source block looks like in the org-mode
114 file. We had to take [[http://orgmode.org/manual/Literal-examples.html#Literal-examples][special steps]] to make it look that way in the
115 HTML output. Normally, when exported to HTML, source blocks are
116 fontified according to their language, and the begin_src...end_src
117 mark-up is omitted, like this:
120 "This file was last evaluated on #{Date.today}"
123 From now on, if you are viewing the HTML version, you will see the
124 HTML output only. However, much of this document consists of
125 interactive examples, and therefore in order to get a feeling for the
126 mechanics of Org-babel it might make most sense to grab the plain text
128 #+HTML: <a href="org-babel-worg.org">org-babel-worg.org</a>
129 and work through it in Emacs. Alternatively the htmlized
130 version of the plain text of this file at
131 #+HTML: <a href="org-babel-worg.org.html">org-babel-worg.html</a>
132 allows the plain text version to be viewed (non-interactively) in a web browser.
133 *** Source code execution
135 :CUSTOM_ID: source-code-execution
137 For interpreted languages such as shell, python, R, etc, org-babel
138 allows source blocks to be executed: the code is passed to the
139 interpreter and you have control over what is done with the results of
140 execution. Here are three examples of code blocks in three different
141 languages, followed by their output. If you are viewing the plain text
142 version of this document in emacs, place point anywhere inside the
143 blocks and use =C-c C-c= to run the code[fn:1] (and feel free to alter
148 "This file was last evaluated on #{Date.today}"
152 : This file was last evaluated on 2009-08-09
154 **** [[http://www.r-project.org/][R]]
155 #+begin_src R :results value
156 matrix(rnorm(6), nrow=2)
160 | -0.138279734486552 | -2.2476234005706 | -0.0839549402407832 |
161 | 0.0730510956002737 | 0.0634015508602321 | 0.174013159381603 |
163 **** [[http://ditaa.sourceforge.net/][ditaa]]
164 #+begin_src ditaa :file images/blue.png :cmdline -r
175 [[file:images/blue.png]]
177 *** Source code block syntax
179 The basic syntax of source-code blocks in Org-babel is as follows:
181 : #+srcname: name(arguments)
182 : #+begin_src language header-arguments
186 - name :: This name is associated with the source-code block. This is
187 similar to the =#+tblname= lines which can be used to name tables
188 in org-mode files. By referencing the srcname of a source-code
189 block it is possible to evaluate the block from other places,
190 files, or from inside tables.
191 - arguments :: Code blocks can have arguments (see [[#arguments-to-source-code-blocks][below]]) which are
192 provided using a familiar function-call syntax similar
193 to (e.g.) python or R.
194 - language :: The language of the code in the source-code block. Valid
195 values must be members of `org-babel-interpreters'.
196 - header-arguments :: Header arguments control many facets of the
197 evaluation and output of source-code blocks. See the [[* Header Arguments][Header
198 Arguments]] section for a complete review of available header
200 - body :: The actual source code which will be evaluated. An
201 important key-binding to become familiar with is =C-c
202 '=. This calls `org-edit-special' which brings up an edit
203 buffer containing the code using the emacs major mode
204 appropriate to the language.
206 *** What happens to the results?
210 Org-babel provides two fundamentally different modes for capturing
211 the results of code evaluation, specified by the =:results= header
213 **** =:results value= (functional mode)
214 This means that the 'result' of code evaluation is defined to be
215 the *value* of the last statement in the block. Thus with this
216 setting, one can view the code block as a function with a return
217 value. And not only can you view it that way, but you can
218 actually use the return value of one source block as input for
219 another (see [[meta-programming-language]]). This setting is the
222 As an example, consider the following block of python code and its
225 #+begin_src python :results value
227 print("Hello, today's date is %s" % time.ctime())
228 print('Two plus two is')
235 Notice that in functional mode, the output consists of the value of
236 the last statement, and nothing else.
238 **** =:results output= (scripting mode)
239 With this setting, org-babel captures all the text output of the
240 code block and places it in the org buffer. One can think of this
241 as a 'scripting' mode: the code block contains a series of
242 commands, and you get the output of all the commands. Unlike in
243 the 'functional' mode, the code block has no return value. (This
244 mode will be more familiar to Sweave users).
246 Now consider the result of evaluating the same source block as
247 before, but under scripting mode.
250 #+begin_src python :results output
252 print("Hello, today's date is %s" % time.ctime())
253 print('Two plus two is')
258 : Hello, today's date is Fri Sep 4 19:49:06 2009
261 Again, we got what we asked for: all the text output (stdout) from
262 python. Since we didn't print the last value (2 + 2), we didn't get it
265 *** Arguments to source code blocks
267 :CUSTOM_ID: arguments-to-source-code-blocks
269 In addition to evaluation of code blocks, org-babel allows them to
270 be parameterised (i.e. have arguments). Thus source code blocks
271 now have the status of *functions*. Arguments to code blocks can
272 be used in both functional and scripting mode.
274 **** Simple example of using a source block as a function
276 First let's look at a very simple example. The following source
277 block defines an org-babel function that will square its input.
284 In the org-mode file that looks like this:
285 : #+srcname: square(x)
291 Now we use the source block:
294 (/for information on the/ =lob= /syntax see [[library-of-babel]]/)
298 #+resname: square(x=6)
301 **** A more complex example: using an org-table as input
303 In this example we're going to define a function to compute a
304 Fibonacci sequence, and we're going to make it take its input
305 from a table in the org-mode buffer.
307 Here are the inputs for fibonacci-seq:
309 #+tblname: fibonacci-inputs
310 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
311 | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 |
313 in the Org-mode buffer this looks like
314 : #+tblname: fibonacci-inputs
315 : | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
316 : | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 |
318 [[http://www.gnu.org/software/emacs/manual/elisp.html][Emacs Lisp]] source code
319 #+srcname: fibonacci-seq(fib-inputs=fibonacci-inputs)
320 #+begin_src emacs-lisp
322 (if (or (= n 0) (= n 1))
324 (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))
326 (mapcar (lambda (row)
327 (mapcar #'fibonacci row)) fib-inputs)
330 in the Org-mode buffer this looks like
331 : #+srcname: fibonacci-seq(fib-inputs=fibonacci-inputs)
332 : #+begin_src emacs-lisp
333 : (defun fibonacci (n)
334 : (if (or (= n 0) (= n 1))
336 : (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))
338 : (mapcar (lambda (row)
339 : (mapcar #'fibonacci row)) fib-inputs)
342 Results of Emacs Lisp code evaluation
344 | 1 | 1 | 2 | 3 | 5 | 8 | 13 | 21 | 34 | 55 |
345 | 1 | 3 | 8 | 21 | 55 | 144 | 377 | 987 | 2584 | 6765 |
347 * A meta-programming language for org-mode
349 :CUSTOM_ID: meta-programming-language
352 Since information can pass freely between source-code blocks and
353 org-mode tables you can mix and match languages using each language
354 for those tasks to which it is suited. This makes Org-mode files with
355 Org-babel into a kind of meta-functional programming language in which
356 functions from many languages can work together.
358 As an example, lets take some system diagnostics in the shell, and
359 then graph them with R.
362 #+srcname: directories
363 #+begin_src bash :results replace
364 cd ~ && du -sc * |grep -v total
366 2. Results of the shell source code (on my system, grab this org-mode
367 files and try running it on your own)
368 #+resname: directories
370 | 12156104 | "Documents" |
371 | 3482440 | "Downloads" |
372 | 2901720 | "Library" |
374 | 16548024 | "Music" |
376 | 7649472 | "Pictures" |
384 3. R source code (which calls the previous shell source code)
385 #+srcname: directory-pie
386 #+begin_src R :var dirs = directories :session R-pie-example
387 pie(dirs[,1], labels = dirs[,2])
389 4. Results of R code [[file:images/dirs.png]]
391 * Spreadsheet plugins for org-mode in any language
393 :CUSTOM_ID: spreadsheet
396 *NOTE*: Maybe in-addition-to/in-stead-of this example we should do a
397 more traditional "spreadsheet" example with R [Eric]
399 Not only can Org-babel pass entire tables of data to source code
400 blocks (see [[arguments-to-source-code-blocks]]), Org-babel can also be
401 used to call source code blocks from *within* tables using the
402 Org-mode's [[http://orgmode.org/manual/The-spreadsheet.html#The-spreadsheet][existing spreadsheet functionality]].
404 In fact the functional test suite for Org-babel is implemented as a
405 large Org-mode table. To run the entire test suite you simple
406 evaluate the table =C-u C-c C-c=, and all of the tests are run
407 updating the table with pass/fail statistics.
409 Here's a sample of our test suite.
411 #+TBLNAME: org-babel-tests
412 | functionality | block | arg | expected | results | pass |
413 |------------------+--------------+-----+-------------+-------------+------|
414 | basic evaluation | | | | | pass |
415 |------------------+--------------+-----+-------------+-------------+------|
416 | emacs lisp | basic-elisp | 2 | 4 | 4 | pass |
417 | shell | basic-shell | | 6 | 6 | pass |
418 | ruby | basic-ruby | | org-babel | org-babel | pass |
419 | python | basic-python | | hello world | hello world | pass |
420 | R | basic-R | | 13 | 13 | pass |
421 #+TBLFM: $5='(if (= (length $3) 1) (progn (message (format "running %S" '(sbe $2 (n $3)))) (sbe $2 (n $3))) (sbe $2))::$6='(if (string= $4 $5) "pass" (format "expected %S but was %S" $4 $5))
422 #+TBLFM: $5=""::$6=""
424 *** code blocks for tests
426 #+srcname: basic-elisp
427 #+begin_src emacs-lisp :var n=7
431 #+srcname: basic-shell
432 #+begin_src sh :results silent
436 #+srcname: date-simple
437 #+begin_src sh :results silent
441 #+srcname: basic-ruby
442 #+begin_src ruby :results silent
446 #+srcname: basic-python
447 #+begin_src python :results silent
452 #+begin_src R :results silent
459 :CUSTOM_ID: library-of-babel
461 What about those source code blocks which are so useful you want to
462 have them available in every org-mode buffer?
464 The [[file:library-of-babel.org][Library of Babel]] is an extensible collection of ready-made and
465 easily-shortcut-callable source-code blocks for handling common
466 tasks. Org-babel comes pre-populated with the source-code blocks
467 located in the [[file:library-of-babel.org][library-of-babel.org]] file. It is possible to add
468 source-code blocks from any org-mode file to the library by calling
470 #+srcname: add-file-to-lob
471 #+begin_src emacs-lisp
472 (org-babel-lob-ingest "path/to/file.org")
475 Once a function has been loaded into the Library of Babel it can be
476 called using the following short =lob= notation.
479 Note that it is also possible to pass table values or the output of
480 a source-code block to lob functions, and it is possible to
481 reference lob functions in source block arguments.
483 * Reproducible Research
485 :CUSTOM_ID: reproducable-research
488 An article about computational science in a scientific publication is
489 not the scholarship itself, it is merely advertising of the
490 scholarship. The actual scholarship is the complete software
491 development environment and the complete set of instructions which
492 generated the figures.
497 [[http://reproducibleresearch.net/index.php/Main_Page][Reproducible Research]] (RR) is the practice of distributing along with
498 an article of research all data, code, and tools required to reproduce
499 the results discussed in the paper. As such the paper becomes not
500 only a document describing the research but a complete laboratory in
501 which the research can be reproduced and extended.
503 Org-mode already has exceptional support for [[http://orgmode.org/manual/Exporting.html#Exporting][exporting to html and
504 LaTeX]]. Org-babel makes Org-mode a tool for RR by *activating* the
505 data and source code embedded into Org-mode documents making the
506 entire document executable. This makes it not only possible, but
507 natural to distribute research in a format that encourages readers to
508 recreate your results, and perform their own analysis.
510 One notable existing RR tool is [[http://en.wikipedia.org/wiki/Sweave][Sweave]] which provides for the
511 embedding of [[http://www.r-project.org/][R]] code into LaTeX documents. While Sweave is a mature
512 and very useful tool, we believe that Org-babel has several
514 - It supports multiple languages (we're not aware of other RR tools that do this)
515 - The [[http://orgmode.org/manual/Exporting.html#Exporting][export process]] is flexible and powerful, including HTML as a target in addition to LaTeX
516 - The document can make native use of all the features of Org-mode,
517 such as those for [[http://orgmode.org/manual/Agenda-Views.html#Agenda-Views][project planning]] and [[http://orgmode.org/manual/TODO-Items.html#TODO-Items][task management]]
519 * Literate programming
521 :CUSTOM_ID: literate-programming
525 Let us change our traditional attitude to the construction of
526 programs: Instead of imagining that our main task is to instruct a
527 /computer/ what to do, let us concentrate rather on explaining to
528 /human beings/ what we want a computer to do.
530 The practitioner of literate programming can be regarded as an
531 essayist, whose main concern is with exposition and excellence of
532 style. Such an author, with thesaurus in hand, chooses the names of
533 variables carefully and explains what each variable means. He or she
534 strives for a program that is comprehensible because its concepts have
535 been introduced in an order that is best for human understanding,
536 using a mixture of formal and informal methods that reinforce each
542 Org-babel supports [[http://en.wikipedia.org/wiki/Literate_programming][Literate Programming]] (LP) by allowing the act of
543 programming to take place inside of Org-mode documents. The Org-mode
544 file can then be exported (*woven* in LP speak) to html or LaTeX for
545 consumption by a human, and the embedded source code can be extracted
546 (*tangled* in LP speak) into structured source code files for
547 consumption by a computer.
549 To support these operations Org-babel relies on Org-mode's [[http://orgmode.org/manual/Exporting.html#Exporting][existing
550 exporting functionality]] for *weaving* of documentation, and on the
551 =org-babel-tangle= function which makes use of [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] [[reference-expansion][reference syntax]]
552 for *tangling* of code files.
554 The [[literate-programming-example][following example]] demonstrates the process of *tangling* in
557 *** Simple Literate Programming Example (Noweb syntax)
559 :CUSTOM_ID: literate-programming-example
562 Tangling functionality is controlled by the =tangle= family of
563 [[header-arguments]]. These arguments can be used to turn tangling on or
564 off (the default) on the source code block, or the outline heading
567 The following demonstrates the combination of three source code blocks
568 into a single source code file using =org-babel-tangle=.
570 The following two blocks will not be tangled by default since they
571 have no =tangle= header arguments.
573 #+srcname: hello-world-prefix
574 #+begin_src sh :exports none
575 echo "/-----------------------------------------------------------\\"
578 : #+srcname: hello-world-prefix
579 : #+begin_src sh :exports none
580 : echo "/-----------------------------------------------------------\\"
583 #+srcname: hello-world-postfix
584 #+begin_src sh :exports none
585 echo "\-----------------------------------------------------------/"
588 : #+srcname: hello-world-postfix
589 : #+begin_src sh :exports none
590 : echo "\-----------------------------------------------------------/"
594 The third block does have a =tangle= header argument indicating the
595 name of the file to which it should be written. It also has [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]]
596 style references to the two previous source code blocks which will be
597 expanded during tangling to include them in the output file as well.
599 #+srcname: hello-world
600 #+begin_src sh :tangle hello :exports none
601 # <<hello-world-prefix>>
602 echo "| hello world |"
603 # <<hello-world-postfix>>
606 : #+srcname: hello-world
607 : #+begin_src sh :tangle hello :exports none
608 : # <<hello-world-prefix>>
609 : echo "| hello world |"
610 : # <<hello-world-postfix>>
613 Calling =org-babel-tangle= will result in the following being written
614 to the =hello.sh= file.
616 #+srcname: hello-world-output
619 # generated by org-babel-tangle
621 # [[file:~/src/org-babel/org-babel-worg.org::#literate-programming-example][block-16]]
622 # <<hello-world-prefix>>
623 echo "/-----------------------------------------------------------\\"
625 echo "| hello world |"
626 # <<hello-world-postfix>>
627 echo "\-----------------------------------------------------------/"
631 *** Emacs Initialization with Org-babel
632 Org-babel has special support for embedding your emacs initialization
633 into Org-mode files. The =org-babel-load-file= function can be used
634 to load the emacs lisp embedded in a literate Org-mode file in the
635 same way that you might load a regular elisp file.
637 This allows you to have all the niceness of Org-mode (folding, tags,
638 notes, html export, etc...) available in your emacs initialization.
640 To try this out either see the simple [[literate-emacs-init][Literate Emacs Initialization]]
641 example directly below, or check out the Org-babel Literate
642 Programming version of Phil Hagelberg's excellent [[http://github.com/technomancy/emacs-starter-kit/tree/master][emacs-starter-kit]]
643 available at [[http://github.com/eschulte/emacs-starter-kit/tree/master][Org-babel-emacs-starter-kit]].
645 ***** Literate Emacs Initialization
647 :CUSTOM_ID: literate-emacs-init
650 For a simple example of usage follow these 4 steps.
652 1) create a directory named =.emacs.d= in the base of your home
657 2) checkout the latest versions of Org-mode and Org-babel into the src
658 subdirectory of this new directory
663 git clone git://repo.or.cz/org-mode.git
664 git clone git://github.com/eschulte/org-babel.git
666 3) place the following in a file called =init.el= in your emacs
667 initialization directory (=~/.emacs.d=).
668 #+srcname: emacs-init
669 #+begin_src emacs-lisp
670 ;;; init.el --- Where all the magic begins
672 ;; This file loads both
673 ;; - Org-mode : http://orgmode.org/ and
674 ;; - Org-babel: http://eschulte.github.com/org-babel/
676 ;; It then loads the rest of our Emacs initialization from Emacs lisp
677 ;; embedded in literate Org-mode files.
679 ;; Load up Org Mode and Org Babel for elisp embedded in Org Mode files
680 (setq dotfiles-dir (file-name-directory (or (buffer-file-name) load-file-name)))
681 (add-to-list 'load-path (expand-file-name
682 "lisp" (expand-file-name
683 "org" (expand-file-name
684 "src" dotfiles-dir))))
685 (add-to-list 'load-path (expand-file-name
686 "lisp" (expand-file-name
687 "org-babel" (expand-file-name
688 "src" dotfiles-dir))))
689 (require 'org-babel-init)
691 ;; load up all literate org-mode files in this directory
692 (mapc #'org-babel-load-file (directory-files dotfiles-dir t "\\.org$"))
694 ;;; init.el ends here
696 4) Implement all of your emacs customizations inside of elisp
697 source-code blocks located in Org-mode files in this directory.
698 They will be loaded by emacs on startup.
700 * Reference / Documentation
702 :CUSTOM_ID: reference-and-documentation
705 The following can be added to your .emacs and used to activate
706 languages. It includes a brief list of the requirements for each
707 language. *Note*: this also serves as the list of languages
708 currently supported by Org-babel.
709 #+begin_src emacs-lisp
710 ;; Uncomment each of the following require lines if you want org-babel
711 ;; to support that language. Each language has a comment explaining
712 ;; it's dependencies. See the related files in lisp/langs for more
713 ;; detailed explanations of requirements.
714 ;; (require 'org-babel-R) ;; R and ess-mode
715 ;; (require 'org-babel-asymptote) ;; asymptote
716 ;; (require 'org-babel-css) ;; none
717 ;; (require 'org-babel-ditaa) ;; ditaa
718 ;; (require 'org-babel-dot) ;; dot
719 ;; (require 'org-babel-gnuplot) ;; gnuplot, and gnuplot-mode
720 ;; (require 'org-babel-haskell) ;; haskell, haskell-mode, inf-haskell
721 ;; (require 'org-babel-ocaml) ;; ocaml, and tuareg-mode
722 ;; (require 'org-babel-python) ;; python, and python-mode
723 ;; (require 'org-babel-ruby) ;; ruby, irb, ruby-mode, and inf-ruby
724 ;; (require 'org-babel-sass) ;; sass, sass-mode
725 ;; (require 'org-babel-sql) ;; none
730 :CUSTOM_ID: header-arguments
733 - results :: results arguments specify what should be done with the
734 output of source-code blocks
735 - The following options are mutually exclusive, and specify how the
736 results should be collected from the source-code block
739 - The following options are mutually exclusive and specify what type
740 of results the code block will return
741 - vector :: specifies that the results should be interpreted as a
742 multidimensional vector (even if the vector is
743 trivial), and will be inserted into the org-mode file
745 - scalar :: specifies that the results should be interpreted as a
746 scalar value, and will be inserted into the org-mode
748 - file :: specifies that the results should be interpreted as the
749 path to a file, and will be inserted into the org-mode
751 - The following options specify how the results should be inserted
752 into the org-mode file
753 - replace :: the current results replace any previously inserted
754 results from the code block
755 - silent :: rather than being inserted into the org-mode file the
756 results are echoed into the message bar
757 - exports :: exports arguments specify what should be included in html
758 or latex exports of the org-mode file
759 - code :: the body of code is included into the exported file
760 - results :: the results of evaluating the code is included in the
762 - both :: both the code and results are included in the exported
764 - none :: nothing is included in the exported file
765 - tangle :: tangle arguments specify whether or not the source-code
766 block should be included in tangled extraction of
768 - yes :: the source-code block is exported to a source-code file
769 named after the basename (name w/o extension) of the
771 - no :: (default) the source-code block is not exported to a
773 - other :: any other string passed to the =tangle= header argument
774 is interpreted as a file basename to which the block will
777 *** Noweb reference syntax
778 The [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] Literate Programming system allows named blocks of code to
779 be referenced by using a =<<code-block-name>>= syntax. When a
780 document is tangled these references are replaced with the named code.
781 An example is provided in the [[literate-programming-example]] in this
786 [fn:1] Calling =C-c C-o= on a source-code block will open the
787 block's results in a separate buffer.