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"/>
23 <a href="http://www.flickr.com/photos/23379658@N05/" title=""><b>Martijn Streefkerk</b></a>
36 :CUSTOM_ID: introduction
38 Org-babel is an extension to the very excellent [[http://orgmode.org/][Org-mode]]; an [[http://www.gnu.org/software/emacs/][Emacs]]
39 major mode for doing almost anything with plain text. If you are
40 not familiar with Org-mode please take a moment to read [[http://orgmode.org/][the Org-mode
41 homepage]] before continuing.
43 Org-babel provides the following modifications to [[http://orgmode.org/manual/Literal-examples.html][the existing
44 support]] for blocks of source code examples in the org-mode core.
46 1. Interactive source code execution
47 2. Arguments to source code blocks
48 3. Exportation of source code blocks to files (literate programming)
52 :CUSTOM_ID: getting-started
55 1) Grab the latest code from the git repo at [[http://github.com/eschulte/org-babel/tree/master][github/org-babel]]
57 git clone git://github.com/eschulte/org-babel.git
60 2) Add the following lines to your .emacs, replacing the path as
61 appropriate. A good place to check that things are up and running
62 would the examples in [[* Basic org-babel functionality][Basic org-babel functionality]].
63 #+begin_src emacs-lisp
64 (add-to-list 'load-path "/path/to/org-babel/lisp")
65 (require 'org-babel-init)
68 3) Finally, activate the subset of supported Org-babel languages
69 which you want to be able to execute on your system. As an
70 example, the following activates python, ruby and R. For a full
71 list of languages, with notes on their dependencies see the
72 [[#reference-and-documentation][Reference / Documentation]] section below.
73 #+begin_src emacs-lisp
74 (require 'org-babel-python)
75 (require 'org-babel-ruby)
76 (require 'org-babel-R)
78 ;; Once you've activated languages, load the library of babel to
79 ;; make pre-built helper functions available in the languages you will be using.
80 (org-babel-load-library-of-babel)
83 * Basic org-babel functionality
85 :CUSTOM_ID: basic-functionality
87 *** Source code blocks
89 :CUSTOM_ID: source-code-blocks
92 Org-babel is all about *source code blocks* in org mode. These are
93 blocks of code (in whatever language), that can occur anywhere in
94 an org-mode file. For example, the following is a source block
95 containing [[http://www.ruby-lang.org/][ruby]] code:
98 : "This file was last evaluated on #{Date.today}"
101 If you are unfamiliar with the notion of a source code block in
102 org-mode, please have a look at the [[http://orgmode.org/manual/Literal-examples.html][relevant manual section]] before
105 Note that above is what the source block looks like in the org-mode
106 file. We had to take [[http://orgmode.org/manual/Literal-examples.html#Literal-examples][special steps]] to make it look that way in the
107 HTML output. Normally, when exported to HTML, source blocks are
108 fontified according to their language, and the begin_src...end_src
109 mark-up is omitted, like this:
112 "This file was last evaluated on #{Date.today}"
115 From now on, if you are viewing the HTML version, you will see the
116 HTML output only. However, much of this document consists of
117 interactive examples, and therefore in order to get a feeling for the
118 mechanics of Org-babel it might make most sense to grab the plain text
120 #+HTML: <a href="org-babel-worg.org">org-babel-worg.org</a>
121 and work through it in Emacs. Alternatively the htmlized
122 version of the plain text of this file at
123 #+HTML: <a href="org-babel-worg.org.html">org-babel-worg.html</a>
124 allows the plain text version to be viewed (non-interactively) in a web browser.
125 *** Source code execution
127 :CUSTOM_ID: source-code-execution
129 For interpreted languages such as shell, python, R, etc, org-babel
130 allows source blocks to be executed: the code is passed to the
131 interpreter and you have control over what is done with the results of
132 execution. Here are three examples of code blocks in three different
133 languages, followed by their output. If you are viewing the plain text
134 version of this document in emacs, place point anywhere inside the
135 blocks and use =C-c C-c= to run the code[fn:1] (and feel free to alter
140 "This file was last evaluated on #{Date.today}"
144 : This file was last evaluated on 2009-08-09
146 **** [[http://www.r-project.org/][R]]
147 #+begin_src R :results value
148 matrix(rnorm(6), nrow=2)
152 | -0.138279734486552 | -2.2476234005706 | -0.0839549402407832 |
153 | 0.0730510956002737 | 0.0634015508602321 | 0.174013159381603 |
155 **** [[http://ditaa.sourceforge.net/][ditaa]]
156 #+begin_src ditaa :file images/blue.png :cmdline -r
167 [[file:images/blue.png]]
169 *** Source code block syntax
171 The basic syntax of source-code blocks in Org-babel is as follows:
173 : #+srcname: name(arguments)
174 : #+begin_src language header-arguments
178 - name :: This name is associated with the source-code block. This is
179 similar to the =#+tblname= lines which can be used to name tables
180 in org-mode files. By referencing the srcname of a source-code
181 block it is possible to evaluate the block from other places,
182 files, or from inside tables.
183 - arguments :: Code blocks can have arguments (see [[#arguments-to-source-code-blocks][below]]) which are
184 provided using a familiar function-call syntax similar
185 to (e.g.) python or R.
186 - language :: The language of the code in the source-code block. Valid
187 values must be members of `org-babel-interpreters'.
188 - header-arguments :: Header arguments control many facets of the
189 evaluation and output of source-code blocks. See the [[* Header Arguments][Header
190 Arguments]] section for a complete review of available header
192 - body :: The actual source code which will be evaluated. An
193 important key-binding to become familiar with is =C-c
194 '=. This calls `org-edit-special' which brings up an edit
195 buffer containing the code using the emacs major mode
196 appropriate to the language.
198 *** What happens to the results?
202 Org-babel provides two fundamentally different modes for capturing
203 the results of code evaluation, specified by the =:results= header
205 **** =:results value= (functional mode)
206 This means that the 'result' of code evaluation is defined to be
207 the *value* of the last statement in the block. Thus with this
208 setting, one can view the code block as a function with a return
209 value. And not only can you view it that way, but you can
210 actually use the return value of one source block as input for
211 another (see [[meta-programming-language]]). This setting is the
214 As an example, consider the following block of python code and its
217 #+begin_src python :results value
219 print("Hello, today's date is %s" % time.ctime())
220 print('Two plus two is')
227 Notice that in functional mode, the output consists of the value of
228 the last statement, and nothing else.
230 **** =:results output= (scripting mode)
231 With this setting, org-babel captures all the text output of the
232 code block and places it in the org buffer. One can think of this
233 as a 'scripting' mode: the code block contains a series of
234 commands, and you get the output of all the commands. Unlike in
235 the 'functional' mode, the code block has no return value. (This
236 mode will be more familiar to Sweave users).
238 Now consider the result of evaluating the same source block as
239 before, but under scripting mode.
242 #+begin_src python :results output
244 print("Hello, today's date is %s" % time.ctime())
245 print('Two plus two is')
250 : Hello, today's date is Fri Sep 4 19:49:06 2009
253 Again, we got what we asked for: all the text output (stdout) from
254 python. Since we didn't print the last value (2 + 2), we didn't get it
257 *** Arguments to source code blocks
259 :CUSTOM_ID: arguments-to-source-code-blocks
261 In addition to evaluation of code blocks, org-babel allows them to
262 be parameterised (i.e. have arguments). Thus source code blocks
263 now have the status of *functions*. Arguments to code blocks can
264 be used in both functional and scripting mode.
266 **** Simple example of using a source block as a function
268 First let's look at a very simple example. The following source
269 block defines an org-babel function that will square its input.
276 In the org-mode file that looks like this:
277 : #+srcname: square(x)
283 Now we use the source block:
286 (/for information on the/ =lob= /syntax see [[library-of-babel]]/)
290 #+resname: square(x=6)
293 **** A more complex example: using an org-table as input
295 In this example we're going to define a function to compute a
296 Fibonacci sequence, and we're going to make it take its input
297 from a table in the org-mode buffer.
299 Here are the inputs for fibonacci-seq:
301 #+tblname: fibonacci-inputs
302 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
303 | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 |
305 in the Org-mode buffer this looks like
306 : #+tblname: fibonacci-inputs
307 : | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
308 : | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 |
310 [[http://www.gnu.org/software/emacs/manual/elisp.html][Emacs Lisp]] source code
311 #+srcname: fibonacci-seq(fib-inputs=fibonacci-inputs)
312 #+begin_src emacs-lisp
314 (if (or (= n 0) (= n 1))
316 (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))
318 (mapcar (lambda (row)
319 (mapcar #'fibonacci row)) fib-inputs)
322 in the Org-mode buffer this looks like
323 : #+srcname: fibonacci-seq(fib-inputs=fibonacci-inputs)
324 : #+begin_src emacs-lisp
325 : (defun fibonacci (n)
326 : (if (or (= n 0) (= n 1))
328 : (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))
330 : (mapcar (lambda (row)
331 : (mapcar #'fibonacci row)) fib-inputs)
334 Results of Emacs Lisp code evaluation
336 | 1 | 1 | 2 | 3 | 5 | 8 | 13 | 21 | 34 | 55 |
337 | 1 | 3 | 8 | 21 | 55 | 144 | 377 | 987 | 2584 | 6765 |
339 * A meta-programming language for org-mode
341 :CUSTOM_ID: meta-programming-language
344 Since information can pass freely between source-code blocks and
345 org-mode tables you can mix and match languages using each language
346 for those tasks to which it is suited. This makes Org-mode files with
347 Org-babel into a kind of meta-functional programming language in which
348 functions from many languages can work together.
350 As an example, lets take some system diagnostics in the shell, and
351 then graph them with R.
354 #+srcname: directories
355 #+begin_src bash :results replace
356 cd ~ && du -sc * |grep -v total
358 2. Results of the shell source code (on my system, grab this org-mode
359 files and try running it on your own)
360 #+resname: directories
362 | 12156104 | "Documents" |
363 | 3482440 | "Downloads" |
364 | 2901720 | "Library" |
366 | 16548024 | "Music" |
368 | 7649472 | "Pictures" |
376 3. R source code (which calls the previous shell source code)
377 #+srcname: directory-pie
378 #+begin_src R :var dirs = directories :session R-pie-example
379 pie(dirs[,1], labels = dirs[,2])
381 4. Results of R code [[file:images/dirs.png]]
383 * Spreadsheet plugins for org-mode in any language
385 :CUSTOM_ID: spreadsheet
388 *NOTE*: Maybe in-addition-to/in-stead-of this example we should do a
389 more traditional "spreadsheet" example with R [Eric]
391 Not only can Org-babel pass entire tables of data to source code
392 blocks (see [[arguments-to-source-code-blocks]]), Org-babel can also be
393 used to call source code blocks from *within* tables using the
394 Org-mode's [[http://orgmode.org/manual/The-spreadsheet.html#The-spreadsheet][existing spreadsheet functionality]].
396 In fact the functional test suite for Org-babel is implemented as a
397 large Org-mode table. To run the entire test suite you simple
398 evaluate the table =C-u C-c C-c=, and all of the tests are run
399 updating the table with pass/fail statistics.
401 Here's a sample of our test suite.
403 #+TBLNAME: org-babel-tests
404 | functionality | block | arg | expected | results | pass |
405 |------------------+--------------+-----+-------------+-------------+------|
406 | basic evaluation | | | | | pass |
407 |------------------+--------------+-----+-------------+-------------+------|
408 | emacs lisp | basic-elisp | 2 | 4 | 4 | pass |
409 | shell | basic-shell | | 6 | 6 | pass |
410 | ruby | basic-ruby | | org-babel | org-babel | pass |
411 | python | basic-python | | hello world | hello world | pass |
412 | R | basic-R | | 13 | 13 | pass |
413 #+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))
414 #+TBLFM: $5=""::$6=""
416 *** code blocks for tests
418 #+srcname: basic-elisp
419 #+begin_src emacs-lisp :var n=7
423 #+srcname: basic-shell
424 #+begin_src sh :results silent
428 #+srcname: date-simple
429 #+begin_src sh :results silent
433 #+srcname: basic-ruby
434 #+begin_src ruby :results silent
438 #+srcname: basic-python
439 #+begin_src python :results silent
444 #+begin_src R :results silent
451 :CUSTOM_ID: library-of-babel
453 What about those source code blocks which are so useful you want to
454 have them available in every org-mode buffer?
456 The [[file:library-of-babel.org][Library of Babel]] is an extensible collection of ready-made and
457 easily-shortcut-callable source-code blocks for handling common
458 tasks. Org-babel comes pre-populated with the source-code blocks
459 located in the [[file:library-of-babel.org][library-of-babel.org]] file. It is possible to add
460 source-code blocks from any org-mode file to the library by calling
462 #+srcname: add-file-to-lob
463 #+begin_src emacs-lisp
464 (org-babel-lob-ingest "path/to/file.org")
467 Once a function has been loaded into the Library of Babel it can be
468 called using the following short =lob= notation.
471 Note that it is also possible to pass table values or the output of
472 a source-code block to lob functions, and it is possible to
473 reference lob functions in source block arguments.
475 * Reproducible Research
477 :CUSTOM_ID: reproducable-research
480 An article about computational science in a scientific publication is
481 not the scholarship itself, it is merely advertising of the
482 scholarship. The actual scholarship is the complete software
483 development environment and the complete set of instructions which
484 generated the figures.
489 [[http://reproducibleresearch.net/index.php/Main_Page][Reproducible Research]] (RR) is the practice of distributing along with
490 an article of research all data, code, and tools required to reproduce
491 the results discussed in the paper. As such the paper becomes not
492 only a document describing the research but a complete laboratory in
493 which the research can be reproduced and extended.
495 Org-mode already has exceptional support for [[http://orgmode.org/manual/Exporting.html#Exporting][exporting to html and
496 LaTeX]]. Org-babel makes Org-mode a tool for RR by *activating* the
497 data and source code embedded into Org-mode documents making the
498 entire document executable. This makes it not only possible, but
499 natural to distribute research in a format that encourages readers to
500 recreate your results, and perform their own analysis.
502 One notable existing RR tool is [[http://en.wikipedia.org/wiki/Sweave][Sweave]] which provides for the
503 embedding of [[http://www.r-project.org/][R]] code into LaTeX documents. While Sweave is a mature
504 and very useful tool, we believe that Org-babel has several
506 - It supports multiple languages (we're not aware of other RR tools that do this)
507 - The [[http://orgmode.org/manual/Exporting.html#Exporting][export process]] is flexible and powerful, including HTML as a target in addition to LaTeX
508 - The document can make native use of all the features of Org-mode,
509 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]]
511 * Literate programming
513 :CUSTOM_ID: literate-programming
517 Let us change our traditional attitude to the construction of
518 programs: Instead of imagining that our main task is to instruct a
519 /computer/ what to do, let us concentrate rather on explaining to
520 /human beings/ what we want a computer to do.
522 The practitioner of literate programming can be regarded as an
523 essayist, whose main concern is with exposition and excellence of
524 style. Such an author, with thesaurus in hand, chooses the names of
525 variables carefully and explains what each variable means. He or she
526 strives for a program that is comprehensible because its concepts have
527 been introduced in an order that is best for human understanding,
528 using a mixture of formal and informal methods that reinforce each
534 Org-babel supports [[http://en.wikipedia.org/wiki/Literate_programming][Literate Programming]] (LP) by allowing the act of
535 programming to take place inside of Org-mode documents. The Org-mode
536 file can then be exported (*woven* in LP speak) to html or LaTeX for
537 consumption by a human, and the embedded source code can be extracted
538 (*tangled* in LP speak) into structured source code files for
539 consumption by a computer.
541 To support these operations Org-babel relies on Org-mode's [[http://orgmode.org/manual/Exporting.html#Exporting][existing
542 exporting functionality]] for *weaving* of documentation, and on the
543 =org-babel-tangle= function which makes use of [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] [[reference-expansion][reference syntax]]
544 for *tangling* of code files.
546 The [[literate-programming-example][following example]] demonstrates the process of *tangling* in
549 *** Simple Literate Programming Example (Noweb syntax)
551 :CUSTOM_ID: literate-programming-example
554 Tangling functionality is controlled by the =tangle= family of
555 [[header-arguments]]. These arguments can be used to turn tangling on or
556 off (the default) on the source code block, or the outline heading
559 The following demonstrates the combination of three source code blocks
560 into a single source code file using =org-babel-tangle=.
562 The following two blocks will not be tangled by default since they
563 have no =tangle= header arguments.
565 #+srcname: hello-world-prefix
566 #+begin_src sh :exports none
567 echo "/-----------------------------------------------------------\\"
570 : #+srcname: hello-world-prefix
571 : #+begin_src sh :exports none
572 : echo "/-----------------------------------------------------------\\"
575 #+srcname: hello-world-postfix
576 #+begin_src sh :exports none
577 echo "\-----------------------------------------------------------/"
580 : #+srcname: hello-world-postfix
581 : #+begin_src sh :exports none
582 : echo "\-----------------------------------------------------------/"
586 The third block does have a =tangle= header argument indicating the
587 name of the file to which it should be written. It also has [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]]
588 style references to the two previous source code blocks which will be
589 expanded during tangling to include them in the output file as well.
591 #+srcname: hello-world
592 #+begin_src sh :tangle hello :exports none
593 # <<hello-world-prefix>>
594 echo "| hello world |"
595 # <<hello-world-postfix>>
598 : #+srcname: hello-world
599 : #+begin_src sh :tangle hello :exports none
600 : # <<hello-world-prefix>>
601 : echo "| hello world |"
602 : # <<hello-world-postfix>>
605 Calling =org-babel-tangle= will result in the following being written
606 to the =hello.sh= file.
608 #+srcname: hello-world-output
611 # generated by org-babel-tangle
613 # [[file:~/src/org-babel/org-babel-worg.org::#literate-programming-example][block-16]]
614 # <<hello-world-prefix>>
615 echo "/-----------------------------------------------------------\\"
617 echo "| hello world |"
618 # <<hello-world-postfix>>
619 echo "\-----------------------------------------------------------/"
623 *** Emacs Initialization with Org-babel
624 Org-babel has special support for embedding your emacs initialization
625 into Org-mode files. The =org-babel-load-file= function can be used
626 to load the emacs lisp embedded in a literate Org-mode file in the
627 same way that you might load a regular elisp file.
629 This allows you to have all the niceness of Org-mode (folding, tags,
630 notes, html export, etc...) available in your emacs initialization.
632 To try this out either see the simple [[literate-emacs-init][Literate Emacs Initialization]]
633 example directly below, or check out the Org-babel Literate
634 Programming version of Phil Hagelberg's excellent [[http://github.com/technomancy/emacs-starter-kit/tree/master][emacs-starter-kit]]
635 available at [[http://github.com/eschulte/emacs-starter-kit/tree/master][Org-babel-emacs-starter-kit]].
637 ***** Literate Emacs Initialization
639 :CUSTOM_ID: literate-emacs-init
642 For a simple example of usage follow these 4 steps.
644 1) create a directory named =.emacs.d= in the base of your home
649 2) checkout the latest versions of Org-mode and Org-babel into the src
650 subdirectory of this new directory
655 git clone git://repo.or.cz/org-mode.git
656 git clone git://github.com/eschulte/org-babel.git
658 3) place the following in a file called =init.el= in your emacs
659 initialization directory (=~/.emacs.d=).
660 #+srcname: emacs-init
661 #+begin_src emacs-lisp
662 ;;; init.el --- Where all the magic begins
664 ;; This file loads both
665 ;; - Org-mode : http://orgmode.org/ and
666 ;; - Org-babel: http://eschulte.github.com/org-babel/
668 ;; It then loads the rest of our Emacs initialization from Emacs lisp
669 ;; embedded in literate Org-mode files.
671 ;; Load up Org Mode and Org Babel for elisp embedded in Org Mode files
672 (setq dotfiles-dir (file-name-directory (or (buffer-file-name) load-file-name)))
673 (add-to-list 'load-path (expand-file-name
674 "lisp" (expand-file-name
675 "org" (expand-file-name
676 "src" dotfiles-dir))))
677 (add-to-list 'load-path (expand-file-name
678 "lisp" (expand-file-name
679 "org-babel" (expand-file-name
680 "src" dotfiles-dir))))
681 (require 'org-babel-init)
683 ;; load up all literate org-mode files in this directory
684 (mapc #'org-babel-load-file (directory-files dotfiles-dir t "\\.org$"))
686 ;;; init.el ends here
688 4) Implement all of your emacs customizations inside of elisp
689 source-code blocks located in Org-mode files in this directory.
690 They will be loaded by emacs on startup.
692 * Reference / Documentation
694 :CUSTOM_ID: reference-and-documentation
697 The following can be added to your .emacs and used to activate
698 languages. It includes a brief list of the requirements for each
699 language. *Note*: this also serves as the list of languages
700 currently supported by Org-babel.
701 #+begin_src emacs-lisp
702 ;; Uncomment each of the following require lines if you want org-babel
703 ;; to support that language. Each language has a comment explaining
704 ;; it's dependencies. See the related files in lisp/langs for more
705 ;; detailed explanations of requirements.
706 ;; (require 'org-babel-R) ;; R and ess-mode
707 ;; (require 'org-babel-asymptote) ;; asymptote
708 ;; (require 'org-babel-css) ;; none
709 ;; (require 'org-babel-ditaa) ;; ditaa
710 ;; (require 'org-babel-dot) ;; dot
711 ;; (require 'org-babel-gnuplot) ;; gnuplot, and gnuplot-mode
712 ;; (require 'org-babel-haskell) ;; haskell, haskell-mode, inf-haskell
713 ;; (require 'org-babel-ocaml) ;; ocaml, and tuareg-mode
714 ;; (require 'org-babel-python) ;; python, and python-mode
715 ;; (require 'org-babel-ruby) ;; ruby, irb, ruby-mode, and inf-ruby
716 ;; (require 'org-babel-sass) ;; sass, sass-mode
717 ;; (require 'org-babel-sql) ;; none
722 :CUSTOM_ID: header-arguments
725 - results :: results arguments specify what should be done with the
726 output of source-code blocks
727 - The following options are mutually exclusive, and specify how the
728 results should be collected from the source-code block
731 - The following options are mutually exclusive and specify what type
732 of results the code block will return
733 - vector :: specifies that the results should be interpreted as a
734 multidimensional vector (even if the vector is
735 trivial), and will be inserted into the org-mode file
737 - scalar :: specifies that the results should be interpreted as a
738 scalar value, and will be inserted into the org-mode
740 - file :: specifies that the results should be interpreted as the
741 path to a file, and will be inserted into the org-mode
743 - The following options specify how the results should be inserted
744 into the org-mode file
745 - replace :: the current results replace any previously inserted
746 results from the code block
747 - silent :: rather than being inserted into the org-mode file the
748 results are echoed into the message bar
749 - exports :: exports arguments specify what should be included in html
750 or latex exports of the org-mode file
751 - code :: the body of code is included into the exported file
752 - results :: the results of evaluating the code is included in the
754 - both :: both the code and results are included in the exported
756 - none :: nothing is included in the exported file
757 - tangle :: tangle arguments specify whether or not the source-code
758 block should be included in tangled extraction of
760 - yes :: the source-code block is exported to a source-code file
761 named after the basename (name w/o extension) of the
763 - no :: (default) the source-code block is not exported to a
765 - other :: any other string passed to the =tangle= header argument
766 is interpreted as a file basename to which the block will
769 *** Noweb reference syntax
770 The [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] Literate Programming system allows named blocks of code to
771 be referenced by using a =<<code-block-name>>= syntax. When a
772 document is tangled these references are replaced with the named code.
773 An example is provided in the [[literate-programming-example]] in this
778 [fn:1] Calling =C-c C-o= on a source-code block will open the
779 block's results in a separate buffer.