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"
20 title="And the Lord said, Behold, the people is one, and they have all one language; and this they begin to do; and now nothing will be restrained from them, which they have imagined to do. Genesis 11:1-9"/>
22 The "Little" Tower of Babel by Pieter Bruegel the Elder
23 <a href="http://www.flickr.com/photos/23379658@N05/" title=""><b>Martijn Streefkerk</b></a>
27 <img src="images/tower-of-babel.png" alt="images/tower-of-babel.png"
28 title="The Tower of Babel by Pieter Bruegel the Elder"/>
30 And the Lord said, Behold, the people is one, and they have all one
31 language; and this they begin to do; and now nothing will be
32 restrained from them, which they have imagined to do. Genesis 11:1-9
45 :CUSTOM_ID: introduction
47 Org-babel is an extension to the very excellent [[http://orgmode.org/][Org-mode]]; an [[http://www.gnu.org/software/emacs/][Emacs]]
48 major mode for doing almost anything with plain text. If you are
49 not familiar with Org-mode please take a moment to read [[http://orgmode.org/][the Org-mode
50 homepage]] before continuing.
52 Org-babel provides the following modifications to [[http://orgmode.org/manual/Literal-examples.html][the existing
53 support]] for blocks of source code examples in the org-mode core.
55 1. Interactive source code execution
56 2. Arguments to source code blocks
57 3. Exportation of source code blocks to files (literate programming)
61 :CUSTOM_ID: getting-started
64 1) Grab the latest code from the git repo at [[http://github.com/eschulte/org-babel/tree/master][github/org-babel]]
66 git clone git://github.com/eschulte/org-babel.git
69 2) Add the following lines to your .emacs, replacing the path as
70 appropriate. A good place to check that things are up and running
71 would the examples in [[* Basic org-babel functionality][Basic org-babel functionality]].
72 #+begin_src emacs-lisp
73 (add-to-list 'load-path "/path/to/org-babel/lisp")
74 (require 'org-babel-init)
77 3) Finally, activate the subset of supported Org-babel languages
78 which you want to be able to execute on your system. As an
79 example, the following activates python, ruby and R. For a full
80 list of languages, with notes on their dependencies see the
81 [[#reference-and-documentation][Reference / Documentation]] section below.
82 #+begin_src emacs-lisp
83 (require 'org-babel-python)
84 (require 'org-babel-ruby)
85 (require 'org-babel-R)
87 ;; Once you've activated languages, load the library of babel to
88 ;; make pre-built helper functions available in the languages you will be using.
89 (org-babel-load-library-of-babel)
92 * Basic org-babel functionality
94 :CUSTOM_ID: basic-functionality
96 *** Source code blocks
98 :CUSTOM_ID: source-code-blocks
101 Org-babel is all about *source code blocks* in org mode. These are
102 blocks of code (in whatever language), that can occur anywhere in
103 an org-mode file. For example, the following is a source block
104 containing [[http://www.ruby-lang.org/][ruby]] code:
107 : "This file was last evaluated on #{Date.today}"
110 If you are unfamiliar with the notion of a source code block in
111 org-mode, please have a look at the [[http://orgmode.org/manual/Literal-examples.html][relevant manual section]] before
114 Note that above is what the source block looks like in the org-mode
115 file. We had to take [[http://orgmode.org/manual/Literal-examples.html#Literal-examples][special steps]] to make it look that way in the
116 HTML output. Normally, when exported to HTML, source blocks are
117 fontified according to their language, and the begin_src...end_src
118 mark-up is omitted, like this:
121 "This file was last evaluated on #{Date.today}"
124 From now on, if you are viewing the HTML version, you will see the
125 HTML output only. However, much of this document consists of
126 interactive examples, and therefore in order to get a feeling for the
127 mechanics of Org-babel it might make most sense to grab the plain text
129 #+HTML: <a href="org-babel-worg.org">org-babel-worg.org</a>
130 and work through it in Emacs. Alternatively the htmlized
131 version of the plain text of this file at
132 #+HTML: <a href="org-babel-worg.org.html">org-babel-worg.html</a>
133 allows the plain text version to be viewed (non-interactively) in a web browser.
134 *** Source code execution
136 :CUSTOM_ID: source-code-execution
138 For interpreted languages such as shell, python, R, etc, org-babel
139 allows source blocks to be executed: the code is passed to the
140 interpreter and you have control over what is done with the results of
141 execution. Here are three examples of code blocks in three different
142 languages, followed by their output. If you are viewing the plain text
143 version of this document in emacs, place point anywhere inside the
144 blocks and use =C-c C-c= to run the code[fn:1] (and feel free to alter
149 "This file was last evaluated on #{Date.today}"
153 : This file was last evaluated on 2009-08-09
155 **** [[http://www.r-project.org/][R]]
156 #+begin_src R :results value
157 matrix(rnorm(6), nrow=2)
161 | -0.138279734486552 | -2.2476234005706 | -0.0839549402407832 |
162 | 0.0730510956002737 | 0.0634015508602321 | 0.174013159381603 |
164 **** [[http://ditaa.sourceforge.net/][ditaa]]
165 #+begin_src ditaa :file images/blue.png :cmdline -r
176 [[file:images/blue.png]]
178 *** Source code block syntax
180 The basic syntax of source-code blocks in Org-babel is as follows:
182 : #+srcname: name(arguments)
183 : #+begin_src language header-arguments
187 - name :: This name is associated with the source-code block. This is
188 similar to the =#+tblname= lines which can be used to name tables
189 in org-mode files. By referencing the srcname of a source-code
190 block it is possible to evaluate the block from other places,
191 files, or from inside tables.
192 - arguments :: Code blocks can have arguments (see [[#arguments-to-source-code-blocks][below]]) which are
193 provided using a familiar function-call syntax similar
194 to (e.g.) python or R.
195 - language :: The language of the code in the source-code block. Valid
196 values must be members of `org-babel-interpreters'.
197 - header-arguments :: Header arguments control many facets of the
198 evaluation and output of source-code blocks. See the [[* Header Arguments][Header
199 Arguments]] section for a complete review of available header
201 - body :: The actual source code which will be evaluated. An
202 important key-binding to become familiar with is =C-c
203 '=. This calls `org-edit-special' which brings up an edit
204 buffer containing the code using the emacs major mode
205 appropriate to the language.
207 *** What happens to the results?
211 Org-babel provides two fundamentally different modes for capturing
212 the results of code evaluation, specified by the =:results= header
214 **** =:results value= (functional mode)
215 This means that the 'result' of code evaluation is defined to be
216 the *value* of the last statement in the block. Thus with this
217 setting, one can view the code block as a function with a return
218 value. And not only can you view it that way, but you can
219 actually use the return value of one source block as input for
220 another (see [[meta-programming-language]]). This setting is the
223 As an example, consider the following block of python code and its
226 #+begin_src python :results value
228 print("Hello, today's date is %s" % time.ctime())
229 print('Two plus two is')
236 Notice that in functional mode, the output consists of the value of
237 the last statement, and nothing else.
239 **** =:results output= (scripting mode)
240 With this setting, org-babel captures all the text output of the
241 code block and places it in the org buffer. One can think of this
242 as a 'scripting' mode: the code block contains a series of
243 commands, and you get the output of all the commands. Unlike in
244 the 'functional' mode, the code block has no return value. (This
245 mode will be more familiar to Sweave users).
247 Now consider the result of evaluating the same source block as
248 before, but under scripting mode.
251 #+begin_src python :results output
253 print("Hello, today's date is %s" % time.ctime())
254 print('Two plus two is')
259 : Hello, today's date is Fri Sep 4 19:49:06 2009
262 Again, we got what we asked for: all the text output (stdout) from
263 python. Since we didn't print the last value (2 + 2), we didn't get it
266 *** Arguments to source code blocks
268 :CUSTOM_ID: arguments-to-source-code-blocks
270 In addition to evaluation of code blocks, org-babel allows them to
271 be parameterised (i.e. have arguments). Thus source code blocks
272 now have the status of *functions*. Arguments to code blocks can
273 be used in both functional and scripting mode.
275 **** Simple example of using a source block as a function
277 First let's look at a very simple example. The following source
278 block defines an org-babel function that will square its input.
285 In the org-mode file that looks like this:
286 : #+srcname: square(x)
292 Now we use the source block:
295 (/for information on the/ =lob= /syntax see [[library-of-babel]]/)
299 #+resname: square(x=6)
302 **** A more complex example: using an org-table as input
304 In this example we're going to define a function to compute a
305 Fibonacci sequence, and we're going to make it take its input
306 from a table in the org-mode buffer.
308 Here are the inputs for fibonacci-seq:
310 #+tblname: fibonacci-inputs
311 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
312 | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 |
314 in the Org-mode buffer this looks like
315 : #+tblname: fibonacci-inputs
316 : | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
317 : | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 |
319 [[http://www.gnu.org/software/emacs/manual/elisp.html][Emacs Lisp]] source code
320 #+srcname: fibonacci-seq(fib-inputs=fibonacci-inputs)
321 #+begin_src emacs-lisp
323 (if (or (= n 0) (= n 1))
325 (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))
327 (mapcar (lambda (row)
328 (mapcar #'fibonacci row)) fib-inputs)
331 in the Org-mode buffer this looks like
332 : #+srcname: fibonacci-seq(fib-inputs=fibonacci-inputs)
333 : #+begin_src emacs-lisp
334 : (defun fibonacci (n)
335 : (if (or (= n 0) (= n 1))
337 : (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))
339 : (mapcar (lambda (row)
340 : (mapcar #'fibonacci row)) fib-inputs)
343 Results of Emacs Lisp code evaluation
345 | 1 | 1 | 2 | 3 | 5 | 8 | 13 | 21 | 34 | 55 |
346 | 1 | 3 | 8 | 21 | 55 | 144 | 377 | 987 | 2584 | 6765 |
348 * A meta-programming language for org-mode
350 :CUSTOM_ID: meta-programming-language
353 Since information can pass freely between source-code blocks and
354 org-mode tables you can mix and match languages using each language
355 for those tasks to which it is suited. This makes Org-mode files with
356 Org-babel into a kind of meta-functional programming language in which
357 functions from many languages can work together.
359 As an example, lets take some system diagnostics in the shell, and
360 then graph them with R.
363 #+srcname: directories
364 #+begin_src bash :results replace
365 cd ~ && du -sc * |grep -v total
367 2. Results of the shell source code (on my system, grab this org-mode
368 files and try running it on your own)
369 #+resname: directories
371 | 12156104 | "Documents" |
372 | 3482440 | "Downloads" |
373 | 2901720 | "Library" |
375 | 16548024 | "Music" |
377 | 7649472 | "Pictures" |
385 3. R source code (which calls the previous shell source code)
386 #+srcname: directory-pie
387 #+begin_src R :var dirs = directories :session R-pie-example
388 pie(dirs[,1], labels = dirs[,2])
390 4. Results of R code [[file:images/dirs.png]]
392 * Spreadsheet plugins for org-mode in any language
394 :CUSTOM_ID: spreadsheet
397 *NOTE*: Maybe in-addition-to/in-stead-of this example we should do a
398 more traditional "spreadsheet" example with R [Eric]
400 Not only can Org-babel pass entire tables of data to source code
401 blocks (see [[arguments-to-source-code-blocks]]), Org-babel can also be
402 used to call source code blocks from *within* tables using the
403 Org-mode's [[http://orgmode.org/manual/The-spreadsheet.html#The-spreadsheet][existing spreadsheet functionality]].
405 In fact the functional test suite for Org-babel is implemented as a
406 large Org-mode table. To run the entire test suite you simple
407 evaluate the table =C-u C-c C-c=, and all of the tests are run
408 updating the table with pass/fail statistics.
410 Here's a sample of our test suite.
412 #+TBLNAME: org-babel-tests
413 | functionality | block | arg | expected | results | pass |
414 |------------------+--------------+-----+-------------+-------------+------|
415 | basic evaluation | | | | | pass |
416 |------------------+--------------+-----+-------------+-------------+------|
417 | emacs lisp | basic-elisp | 2 | 4 | 4 | pass |
418 | shell | basic-shell | | 6 | 6 | pass |
419 | ruby | basic-ruby | | org-babel | org-babel | pass |
420 | python | basic-python | | hello world | hello world | pass |
421 | R | basic-R | | 13 | 13 | pass |
422 #+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))
423 #+TBLFM: $5=""::$6=""
425 *** code blocks for tests
427 #+srcname: basic-elisp
428 #+begin_src emacs-lisp :var n=7
432 #+srcname: basic-shell
433 #+begin_src sh :results silent
437 #+srcname: date-simple
438 #+begin_src sh :results silent
442 #+srcname: basic-ruby
443 #+begin_src ruby :results silent
447 #+srcname: basic-python
448 #+begin_src python :results silent
453 #+begin_src R :results silent
460 :CUSTOM_ID: library-of-babel
462 What about those source code blocks which are so useful you want to
463 have them available in every org-mode buffer?
465 The [[file:library-of-babel.org][Library of Babel]] is an extensible collection of ready-made and
466 easily-shortcut-callable source-code blocks for handling common
467 tasks. Org-babel comes pre-populated with the source-code blocks
468 located in the [[file:library-of-babel.org][library-of-babel.org]] file. It is possible to add
469 source-code blocks from any org-mode file to the library by calling
471 #+srcname: add-file-to-lob
472 #+begin_src emacs-lisp
473 (org-babel-lob-ingest "path/to/file.org")
476 Once a function has been loaded into the Library of Babel it can be
477 called using the following short =lob= notation.
480 Note that it is also possible to pass table values or the output of
481 a source-code block to lob functions, and it is possible to
482 reference lob functions in source block arguments.
484 * Reproducible Research
486 :CUSTOM_ID: reproducable-research
489 An article about computational science in a scientific publication is
490 not the scholarship itself, it is merely advertising of the
491 scholarship. The actual scholarship is the complete software
492 development environment and the complete set of instructions which
493 generated the figures.
498 [[http://reproducibleresearch.net/index.php/Main_Page][Reproducible Research]] (RR) is the practice of distributing along with
499 an article of research all data, code, and tools required to reproduce
500 the results discussed in the paper. As such the paper becomes not
501 only a document describing the research but a complete laboratory in
502 which the research can be reproduced and extended.
504 Org-mode already has exceptional support for [[http://orgmode.org/manual/Exporting.html#Exporting][exporting to html and
505 LaTeX]]. Org-babel makes Org-mode a tool for RR by *activating* the
506 data and source code embedded into Org-mode documents making the
507 entire document executable. This makes it not only possible, but
508 natural to distribute research in a format that encourages readers to
509 recreate your results, and perform their own analysis.
511 One notable existing RR tool is [[http://en.wikipedia.org/wiki/Sweave][Sweave]] which provides for the
512 embedding of [[http://www.r-project.org/][R]] code into LaTeX documents. While Sweave is a mature
513 and very useful tool, we believe that Org-babel has several
515 - It supports multiple languages (we're not aware of other RR tools that do this)
516 - The [[http://orgmode.org/manual/Exporting.html#Exporting][export process]] is flexible and powerful, including HTML as a target in addition to LaTeX
517 - The document can make native use of all the features of Org-mode,
518 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]]
520 * Literate programming
522 :CUSTOM_ID: literate-programming
526 Let us change our traditional attitude to the construction of
527 programs: Instead of imagining that our main task is to instruct a
528 /computer/ what to do, let us concentrate rather on explaining to
529 /human beings/ what we want a computer to do.
531 The practitioner of literate programming can be regarded as an
532 essayist, whose main concern is with exposition and excellence of
533 style. Such an author, with thesaurus in hand, chooses the names of
534 variables carefully and explains what each variable means. He or she
535 strives for a program that is comprehensible because its concepts have
536 been introduced in an order that is best for human understanding,
537 using a mixture of formal and informal methods that reinforce each
543 Org-babel supports [[http://en.wikipedia.org/wiki/Literate_programming][Literate Programming]] (LP) by allowing the act of
544 programming to take place inside of Org-mode documents. The Org-mode
545 file can then be exported (*woven* in LP speak) to html or LaTeX for
546 consumption by a human, and the embedded source code can be extracted
547 (*tangled* in LP speak) into structured source code files for
548 consumption by a computer.
550 To support these operations Org-babel relies on Org-mode's [[http://orgmode.org/manual/Exporting.html#Exporting][existing
551 exporting functionality]] for *weaving* of documentation, and on the
552 =org-babel-tangle= function which makes use of [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] [[reference-expansion][reference syntax]]
553 for *tangling* of code files.
555 The [[literate-programming-example][following example]] demonstrates the process of *tangling* in
558 *** Simple Literate Programming Example (Noweb syntax)
560 :CUSTOM_ID: literate-programming-example
563 Tangling functionality is controlled by the =tangle= family of
564 [[header-arguments]]. These arguments can be used to turn tangling on or
565 off (the default) on the source code block, or the outline heading
568 The following demonstrates the combination of three source code blocks
569 into a single source code file using =org-babel-tangle=.
571 The following two blocks will not be tangled by default since they
572 have no =tangle= header arguments.
574 #+srcname: hello-world-prefix
575 #+begin_src sh :exports none
576 echo "/-----------------------------------------------------------\\"
579 : #+srcname: hello-world-prefix
580 : #+begin_src sh :exports none
581 : echo "/-----------------------------------------------------------\\"
584 #+srcname: hello-world-postfix
585 #+begin_src sh :exports none
586 echo "\-----------------------------------------------------------/"
589 : #+srcname: hello-world-postfix
590 : #+begin_src sh :exports none
591 : echo "\-----------------------------------------------------------/"
595 The third block does have a =tangle= header argument indicating the
596 name of the file to which it should be written. It also has [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]]
597 style references to the two previous source code blocks which will be
598 expanded during tangling to include them in the output file as well.
600 #+srcname: hello-world
601 #+begin_src sh :tangle hello :exports none
602 # <<hello-world-prefix>>
603 echo "| hello world |"
604 # <<hello-world-postfix>>
607 : #+srcname: hello-world
608 : #+begin_src sh :tangle hello :exports none
609 : # <<hello-world-prefix>>
610 : echo "| hello world |"
611 : # <<hello-world-postfix>>
614 Calling =org-babel-tangle= will result in the following being written
615 to the =hello.sh= file.
617 #+srcname: hello-world-output
620 # generated by org-babel-tangle
622 # [[file:~/src/org-babel/org-babel-worg.org::#literate-programming-example][block-16]]
623 # <<hello-world-prefix>>
624 echo "/-----------------------------------------------------------\\"
626 echo "| hello world |"
627 # <<hello-world-postfix>>
628 echo "\-----------------------------------------------------------/"
632 *** Emacs Initialization with Org-babel
633 Org-babel has special support for embedding your emacs initialization
634 into Org-mode files. The =org-babel-load-file= function can be used
635 to load the emacs lisp embedded in a literate Org-mode file in the
636 same way that you might load a regular elisp file.
638 This allows you to have all the niceness of Org-mode (folding, tags,
639 notes, html export, etc...) available in your emacs initialization.
641 To try this out either see the simple [[literate-emacs-init][Literate Emacs Initialization]]
642 example directly below, or check out the Org-babel Literate
643 Programming version of Phil Hagelberg's excellent [[http://github.com/technomancy/emacs-starter-kit/tree/master][emacs-starter-kit]]
644 available at [[http://github.com/eschulte/emacs-starter-kit/tree/master][Org-babel-emacs-starter-kit]].
646 ***** Literate Emacs Initialization
648 :CUSTOM_ID: literate-emacs-init
651 For a simple example of usage follow these 4 steps.
653 1) create a directory named =.emacs.d= in the base of your home
658 2) checkout the latest versions of Org-mode and Org-babel into the src
659 subdirectory of this new directory
664 git clone git://repo.or.cz/org-mode.git
665 git clone git://github.com/eschulte/org-babel.git
667 3) place the following in a file called =init.el= in your emacs
668 initialization directory (=~/.emacs.d=).
669 #+srcname: emacs-init
670 #+begin_src emacs-lisp
671 ;;; init.el --- Where all the magic begins
673 ;; This file loads both
674 ;; - Org-mode : http://orgmode.org/ and
675 ;; - Org-babel: http://eschulte.github.com/org-babel/
677 ;; It then loads the rest of our Emacs initialization from Emacs lisp
678 ;; embedded in literate Org-mode files.
680 ;; Load up Org Mode and Org Babel for elisp embedded in Org Mode files
681 (setq dotfiles-dir (file-name-directory (or (buffer-file-name) load-file-name)))
682 (add-to-list 'load-path (expand-file-name
683 "lisp" (expand-file-name
684 "org" (expand-file-name
685 "src" dotfiles-dir))))
686 (add-to-list 'load-path (expand-file-name
687 "lisp" (expand-file-name
688 "org-babel" (expand-file-name
689 "src" dotfiles-dir))))
690 (require 'org-babel-init)
692 ;; load up all literate org-mode files in this directory
693 (mapc #'org-babel-load-file (directory-files dotfiles-dir t "\\.org$"))
695 ;;; init.el ends here
697 4) Implement all of your emacs customizations inside of elisp
698 source-code blocks located in Org-mode files in this directory.
699 They will be loaded by emacs on startup.
701 * Reference / Documentation
703 :CUSTOM_ID: reference-and-documentation
706 The following can be added to your .emacs and used to activate
707 languages. It includes a brief list of the requirements for each
708 language. *Note*: this also serves as the list of languages
709 currently supported by Org-babel.
710 #+begin_src emacs-lisp
711 ;; Uncomment each of the following require lines if you want org-babel
712 ;; to support that language. Each language has a comment explaining
713 ;; it's dependencies. See the related files in lisp/langs for more
714 ;; detailed explanations of requirements.
715 ;; (require 'org-babel-R) ;; R and ess-mode
716 ;; (require 'org-babel-asymptote) ;; asymptote
717 ;; (require 'org-babel-css) ;; none
718 ;; (require 'org-babel-ditaa) ;; ditaa
719 ;; (require 'org-babel-dot) ;; dot
720 ;; (require 'org-babel-gnuplot) ;; gnuplot, and gnuplot-mode
721 ;; (require 'org-babel-haskell) ;; haskell, haskell-mode, inf-haskell
722 ;; (require 'org-babel-ocaml) ;; ocaml, and tuareg-mode
723 ;; (require 'org-babel-python) ;; python, and python-mode
724 ;; (require 'org-babel-ruby) ;; ruby, irb, ruby-mode, and inf-ruby
725 ;; (require 'org-babel-sass) ;; sass, sass-mode
726 ;; (require 'org-babel-sql) ;; none
731 :CUSTOM_ID: header-arguments
734 - results :: results arguments specify what should be done with the
735 output of source-code blocks
736 - The following options are mutually exclusive, and specify how the
737 results should be collected from the source-code block
740 - The following options are mutually exclusive and specify what type
741 of results the code block will return
742 - vector :: specifies that the results should be interpreted as a
743 multidimensional vector (even if the vector is
744 trivial), and will be inserted into the org-mode file
746 - scalar :: specifies that the results should be interpreted as a
747 scalar value, and will be inserted into the org-mode
749 - file :: specifies that the results should be interpreted as the
750 path to a file, and will be inserted into the org-mode
752 - The following options specify how the results should be inserted
753 into the org-mode file
754 - replace :: the current results replace any previously inserted
755 results from the code block
756 - silent :: rather than being inserted into the org-mode file the
757 results are echoed into the message bar
758 - exports :: exports arguments specify what should be included in html
759 or latex exports of the org-mode file
760 - code :: the body of code is included into the exported file
761 - results :: the results of evaluating the code is included in the
763 - both :: both the code and results are included in the exported
765 - none :: nothing is included in the exported file
766 - tangle :: tangle arguments specify whether or not the source-code
767 block should be included in tangled extraction of
769 - yes :: the source-code block is exported to a source-code file
770 named after the basename (name w/o extension) of the
772 - no :: (default) the source-code block is not exported to a
774 - other :: any other string passed to the =tangle= header argument
775 is interpreted as a file basename to which the block will
778 *** Noweb reference syntax
779 The [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] Literate Programming system allows named blocks of code to
780 be referenced by using a =<<code-block-name>>= syntax. When a
781 document is tangled these references are replaced with the named code.
782 An example is provided in the [[literate-programming-example]] in this
787 [fn:1] Calling =C-c C-o= on a source-code block will open the
788 block's results in a separate buffer.