Initialise new source code chapter with reference.org from Worg

source-code-chapter.texi is just reference.org with level 1 headings
replaced with @section, and level 2 headings replaced with
@subsection, and with a top level @chapter node. This file is included
in org.texi with an @include line for now.

doc/org.texi

@@ -10595,6 +10595,8 @@ above, or by customizing the variable @code{org-publish-use-timestamps-flag}.
 This may be necessary in particular if files include other files via
 @code{#+SETUPFILE:} or @code{#+INCLUDE:}.
 
+@include source-code-chapter.texi
+
 @node Miscellaneous, Hacking, Publishing, Top
 @chapter Miscellaneous
 

doc/source-code-chapter.texi

@@ -0,0 +1,1006 @@
+@chapter Working with source code or Embedded Source Code
+
+@section Syntax
+  :PROPERTIES:
+  :CUSTOM_ID: syntax
+  :END:
+
+@subsection Source Code Block
+The basic syntax of source code blocks in Org-babel is as follows:
+
+: #+begin_src language header-arguments
+: body
+: #+end_src
+
+- language :: The language of the code in the source code block. Valid
+     values must be members of =org-babel-interpreters=.
+- header-arguments :: Header arguments control many facets of the
+     evaluation and output of source code blocks.  See the [[header-arguments][Header
+     Arguments]] section for a complete review of available header
+     arguments.
+- body :: The source code to be evaluated.  An important key-binding
+     is C-c '.  This calls =org-edit-src-code=, a function that brings
+     up an edit buffer containing the code using the Emacs major mode
+     appropriate to the language.  You can edit your source code block
+     as you regularly would in Emacs.
+
+This syntax can be expanded by naming the source code block.
+
+: #+source: name
+: #+begin_src language header-arguments
+:
+: #+end_src
+
+- name :: This name is associated with the source code block.  This is
+     similar to the =#+tblname= lines that can be used to name tables
+     in Org-mode files.  Referencing the name of a source code
+     block makes it possible to evaluate the block from other places in
+     the file, other files, or inside Org-mode tables.  It
+     is also possible to pass arguments to a source code block through
+     this =#+source:= line (see [[alternate-argument-syntax][Alternate argument syntax]]).
+
+@subsection Library of Babel
+[[file:library-of-babel.org][Library of Babel]] functions can be called using the following syntax.
+
+: #+lob: R-plot(data=R-plot-example-data)
+
+@subsection Aliases
+   Keyword aliases are intended to make Org-babel feel natural to
+   programmers fluent in a variety of languages.  For example,
+   #+begin_example
+     ,#+srcname: alias-example
+     ,#+begin_src emacs-lisp
+       '((call lob)
+         (source function srcname)
+         (results resname))
+     ,#+end_src
+
+     ,#+results: alias-example
+     | call    | lob      |         |
+     | source  | function | srcname |
+     | results | resname  |         |
+   #+end_example
+     - =#+srcname:= can be replaced with either of two aliases,  =#+source:= or =#+function:=.
+     - =#+results:= can be replaced with its alias, =#+resname:=.
+
+   When calling Library of Babel functions, as in the following
+   example, there are two acceptable keywords.  The =#+lob= call in
+   the example could be replaced with its alias, =#+call=.
+   #+begin_example
+     ,#+lob: R-plot(data=R-plot-example-data)
+   #+end_example
+
+@section Languages
+  :PROPERTIES:
+  :CUSTOM_ID: languages
+  :END:
+
+  Org-babel has support for the following languages.
+
+  | Language       | Documentation               | Identifier | Requirements                                |
+  |----------------+-----------------------------+------------+---------------------------------------------|
+  | Asymptote      | org-babel-doc-asymptote     | asymptote  | [[http://asymptote.sourceforge.net/][asymptote]], [[http://asymptote.sourceforge.net/doc/Editing-modes.html][asy-mode]]                         |
+  | C              | [[file:languages/org-babel-doc-C.org][org-babel-doc-C]]             | C          | none                                        |
+  | Clojure        | [[file:languages/org-babel-doc-clojure.org][org-babel-doc-clojure]]       | clojure    | [[http://clojure.org/][clojure]], [[http://www.emacswiki.org/emacs/clojure-mode.el][clojure-mode]], [[http://common-lisp.net/project/slime/][slime]], [[http://clojure.codestuffs.com/][swank-clojure]] |
+  | css            | org-babel-doc-css           | css        | none                                        |
+  | ditaa          | org-babel-doc-ditaa         | ditaa      | [[http://ditaa.org/ditaa/][ditaa]] (bundled with Org-mode)               |
+  | Graphviz       | org-babel-doc-dot           | dot        | [[http://www.graphviz.org/][dot]]                                         |
+  | Emacs Lisp     | org-babel-doc-emacs-lisp    | emacs-lisp | none                                        |
+  | gnuplot        | org-babel-doc-gnuplot       | gnuplot    | [[http://www.gnuplot.info/][gnuplot]], [[http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html][gnuplot-mode]]                       |
+  | Haskell        | org-babel-doc-haskell       | haskell    | [[http://www.haskell.org/][haskell]], [[http://projects.haskell.org/haskellmode-emacs/][haskell-mode]], [[http://www.haskell.org/haskellwiki/Haskell_mode_for_Emacs#inf-haskell.el:_the_best_thing_since_the_breadknife][inf-haskell]], [[http://people.cs.uu.nl/andres/lhs2tex/][lhs2tex]] |
+  | Matlab         | [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] | matlab     | matlab, [[http://sourceforge.net/projects/matlab-emacs/][matlab.el]]                           |
+  | LaTeX          | [[file:languages/org-babel-doc-LaTeX.org][org-babel-doc-latex]]         | latex      | [[http://www.latex-project.org/][latex]], [[http://www.gnu.org/software/auctex/][auctex]], [[http://www.gnu.org/software/auctex/reftex.html][reftex]]                       |
+  | Objective Caml | org-babel-doc-ocaml         | ocaml      | [[http://caml.inria.fr/][ocaml]], [[http://www-rocq.inria.fr/~acohen/tuareg/][tuareg-mode]]                          |
+  | Octave         | [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] | octave     | octave                                      |
+  | OZ             | [[file:languages/org-babel-doc-oz.org][org-babel-doc-oz]]            | oz         | [[http://www.mozart-oz.org/][Mozart]] which includes a major mode          |
+  | Perl           | org-babel-doc-perl          | perl       | [[http://www.perl.org/][perl]], [[http://www.emacswiki.org/emacs/CPerlMode][cperl-mode]] (optional)                 |
+  | Python         | org-babel-doc-python        | python     | [[http://www.python.org/][python]], [[https://launchpad.net/python-mode][python-mode]] (optional)              |
+  | R              | [[file:languages/org-babel-doc-R.org][org-babel-doc-R]]             | R          | [[http://www.r-project.org/][R]], [[http://ess.r-project.org/][ess-mode]]                                 |
+  | Ruby           | org-babel-doc-ruby          | ruby       | [[http://www.ruby-lang.org/][ruby]], [[http://www.ruby-lang.org/][irb]], [[http://github.com/eschulte/rinari/raw/master/util/ruby-mode.el][ruby-mode]], [[http://github.com/eschulte/rinari/raw/master/util/inf-ruby.el][inf-ruby mode]]         |
+  | Sass           | org-babel-doc-sass          | sass       | [[http://sass-lang.com/][sass]], [[http://github.com/nex3/haml/blob/master/extra/sass-mode.el][sass-mode]]                             |
+  | GNU Screen     | [[file:languages/org-babel-doc-screen.org][org-babel-doc-screen]]        | screen     | [[http://www.gnu.org/software/screen/][screen]], a terminal                          |
+  | shell          | org-babel-doc-sh            | sh[fn:1]   | a shell                                     |
+  | SQL            | org-babel-doc-sql           | sql        | none                                        |
+
+  To add support for a particular language to your Org-babel
+  installation first make sure that the requirements of the language
+  are met, then add a line like the following to your Emacs
+  configuration, (replace "identifier" with one of the
+  entries in the Identifier column of the table).
+  #+begin_src emacs-lisp
+    (require 'org-babel-identifier)
+  #+end_src
+
+@section Header Arguments
+    :PROPERTIES:
+    :CUSTOM_ID: header-arguments
+    :END:
+
+Definitions of all Org-babel header arguments are given [[header-argument-specific-documentation][below]].  In
+addition, some languages may add their own header arguments.  Please
+see the language-specific documentation for information on
+language-specific header arguments.
+
+@subsection Using Header Arguments
+
+The values of header arguments can be set in three different ways,
+each more specific than the last.
+
+*** System-wide
+    :PROPERTIES:
+    :CUSTOM_ID: system-wide-header-argument
+    :END:
+
+ System-wide values of header arguments can be specified by
+ customizing the =org-babel-default-header-args= variable:
+ #+begin_example
+   org-babel-default-header-args is a variable defined in `org-babel.el'.
+   Its value is
+   ((:session . "none")
+    (:results . "replace")
+    (:exports . "code")
+    (:cache . "no")
+    (:noweb . "no"))
+
+
+   Documentation:
+   Default arguments to use when evaluating a source block.
+ #+end_example
+ [[#default-noweb]]
+ For example, the following example could be used to set the default value
+ of =:noweb= header arguments to =yes=.  This would have the effect of
+ expanding =:noweb= references by default when evaluating source code blocks.
+ #+begin_src emacs-lisp :results silent :exports code
+   (setq org-babel-default-header-args
+         (cons '(:noweb . "yes")
+               (assq-delete-all :noweb org-babel-default-header-args)))
+ #+end_src
+
+*** Org-mode Properties
+
+ Header arguments are also read from [[http://orgmode.org/manual/Properties-and-Columns.html#Properties-and-Columns][Org-mode properties]], which
+ means they can be set on the outline header level.  For example, the
+ value of the =:cache= header argument will default to true in all
+ source code blocks under the following example of an Org-mode outline header:
+ #+begin_example
+   ,* outline header
+     :PROPERTIES:
+     :cache:    yes
+     :CUSTOM_ID: property-set-header-arguments
+     :END:
+ #+end_example
+ Properties defined in this way override the properties set in
+ =org-babel-default-header-args=.  It is convenient to use the
+ =org-set-property= function bound to =C-c C-x p= to set properties
+ in Org-mode documents.
+
+*** Source Code Block
+    :PROPERTIES:
+    :CUSTOM_ID: single-block-header-arguments
+    :END:
+ The most common way to assign values to header arguments is at the
+ source code block level.  This can be done by listing a sequence of
+ header arguments and their values as part of the =#+begin_src=
+ line.  Properties set in this way override both the values of
+ =org-babel-default-header-args= and header argument specified as
+ properties.  In the following example, the
+ =:results= header argument is set to =silent=, meaning the results
+ of execution will not be inserted in the buffer, and the =:exports=
+ header argument is set to =code=, meaning only the body of the
+ source code block
+ will be preserved on export to HTML or LaTeX.
+ #+begin_example
+   ,#+source: factorial
+   ,#+begin_src haskell :results silent :exports code
+     fac 0 = 1
+     fac n = n * fac (n-1)
+   ,#+end_src
+ #+end_example
+
+@subsection Specific Header Arguments
+    :PROPERTIES:
+    :CUSTOM_ID: header-argument-specific-documentation
+    :END:
+
+*** =:var=
+    :PROPERTIES:
+    :CUSTOM_ID: header-argument-var
+    :END:
+
+    The =:var= header argument is used to pass arguments to
+    source code blocks.  The specifics of how arguments are included
+    in a source code block are language specific and are
+    addressed in the language-specific documentation. However, the
+    syntax used to specify arguments is the same across all
+    languages.  The values passed to arguments can be or
+    - literal values
+    - values from org-mode tables
+    - the results of other source code blocks
+
+    These values can be indexed in a manner similar to arrays -- see
+    [[var-argument-indexing][argument indexing]].
+
+    The following syntax is used to pass arguments to source code
+    blocks using the =:var= header argument.
+
+    #+begin_example
+      :var name=assign
+    #+end_example
+
+    where =assign= can take one of the following forms
+
+    - literal value :: either a string ="string"= or a number =9=.
+    - reference :: a table name:
+
+         #+begin_example
+           ,#+tblname: example-table
+           | 1 |
+           | 2 |
+           | 3 |
+           | 4 |
+
+           ,#+source: table-length
+           ,#+begin_src emacs-lisp :var table=example-table
+             (length table)
+           ,#+end_src
+
+           ,#+results: table-length
+           : 4
+         #+end_example
+
+         a source code block name, as assigned by =#+srcname:=,
+         followed by parentheses:
+
+         #+begin_example
+           ,#+begin_src emacs-lisp :var length=table-length()
+             (* 2 length)
+           ,#+end_src
+
+           ,#+results:
+           : 8
+         #+end_example
+
+         In addition, an argument can be passed to the source code
+         block referenced by =:var=.  The argument is passed within
+         the parentheses following the source code block name:
+
+         #+begin_example
+           ,#+source: double
+           ,#+begin_src emacs-lisp :var input=8
+             (* 2 input)
+           ,#+end_src
+
+           ,#+results: double
+           : 16
+
+           ,#+source: squared
+           ,#+begin_src emacs-lisp :var input=double(input=1)
+             (* input input)
+           ,#+end_src
+
+           ,#+results: squared
+           : 4
+         #+end_example
+
+**** alternate argument syntax
+     :PROPERTIES:
+     :CUSTOM_ID: alternate-argument-syntax
+     :END:
+
+     It is also possible to specify arguments in a potentially more
+     natural way using the =#+source:= line of a source code block.
+     As in the following example arguments can be packed inside of
+     parenthesis following the source name.
+     #+begin_example
+       ,#+source: double(input=0)
+       ,#+begin_src emacs-lisp
+         (* 2 input)
+       ,#+end_src
+     #+end_example
+
+**** indexable variable values
+     :PROPERTIES:
+     :CUSTOM_ID: var-argument-indexing
+     :END:
+
+     It is possible to assign a portion of a value to a
+     variable in a source block.  The following example
+     assigns the second and third rows of the table
+     =example-table= to the variable =data=:
+
+     #+begin_example
+       :var data=example-table[1:2]
+     #+end_example
+
+     *Note:* ranges are indexed using the =:= operator.
+
+     *Note:* indices are 0 based.
+
+     The following example assigns the second column of the
+     first row of =example-table= to =data=:
+
+     #+begin_example
+       :var data=example-table[0,1]
+     #+end_example
+
+     It is possible to index into the results of source code blocks
+     as well as tables.  Any number of dimensions can be indexed.
+     Dimensions are separated from one another by commas.
+
+     For more information on indexing behavior see the documentation
+     for the =org-babel-ref-index-list= function -- provided below.
+
+     #+begin_example
+       org-babel-ref-index-list is a Lisp function in `org-babel-ref.el'.
+
+       (org-babel-ref-index-list INDEX LIS)
+
+       Return the subset of LIS indexed by INDEX.  If INDEX is
+       separated by ,s then each PORTION is assumed to index into the
+       next deepest nesting or dimension.  A valid PORTION can consist
+       of either an integer index, or two integers separated by a : in
+       which case the entire range is returned.
+     #+end_example
+
+     *Note:* In Emacs, the documentation for any function or variable
+     can be read using the =describe-function= (M-x describe
+     function) and =describe-variable= (M-x describe variable)
+     functions, respectively.
+
+*** =:results=
+    :PROPERTIES:
+    :CUSTOM_ID: header-argument-results
+    :END:
+
+    There are three types of results header argument:
+    - *collection* header arguments specify how the results should be collected from
+       the source code block;
+    - *type* header arguments specify what type of result the source code block
+       will return -- which has implications for how they will be
+       inserted into the Org-mode buffer; and
+    - *handling* header arguments specify how the results of
+       evaluating the source code block should be handled.
+
+     *Note:* only one option from each type may be supplied per source code
+       block.
+
+**** collection
+    :PROPERTIES:
+    :CUSTOM_ID: header-argument-results-collection
+    :END:
+     The following options are mutually exclusive, and specify how the
+     results should be collected from the source code block.
+
+     - value :: This is the default.  The result is the value
+                of the last statement in the source code block.
+                This header argument places Org-babel in functional
+                mode.  Note that in some languages, e.g., python,
+                use of this result type requires that a =return=
+                statement be included in the body of the source code
+                block. E.g., =:results value=.
+    - output :: The result is the collection of everything printed
+                to stdout during the execution of the source code
+                block.  This header argument places Org-babel in scripting
+                mode.  E.g., =:results output=.
+
+**** type
+     The following options are mutually exclusive and specify what
+     type of results the code block will return.  By default, results
+     are inserted as either a *table* or *scalar* depending on their
+     value.
+
+     - table, vector :: The results should be interpreted as an Org-mode table.
+                        If a single value is returned, Org-babel will convert it
+                        into a table with one row and one column.  E.g., =:results
+                        value table=.
+     - scalar, verbatim :: The results should be interpreted
+          literally -- meaning they will not be converted into a table.
+          The results will be inserted into the Org-mode buffer as
+          quoted text.  E.g., =:results value verbatim=.
+     - file :: The results will be interpreted as the path to a file,
+               and will be inserted into the Org-mode buffer as a file
+               link.  E.g., =:results value file=.
+     - raw, org :: The results are interpreted as raw Org-mode code and
+                   are inserted directly into the buffer.  If the results look
+                   like a table they will be aligned as such by Org-mode.
+                   E.g., =:results value raw=.
+     - html :: Results are assumed to be HTML and will be enclosed in
+               a =begin_html= block.  E.g., =:results value html=.
+     - latex :: Results assumed to be LaTeX and are enclosed in a
+                =begin_latex= block.  E.g., =:results value latex=.
+     - code :: Result are assumed to be parseable code and are
+               enclosed in a code block.  E.g., =:results value code=.
+     - pp :: The result is converted to pretty-printed code and is
+             enclosed in a code block.  This option currently supports
+             Emacs Lisp, python, and ruby.  E.g., =:results value pp=.
+
+**** handling
+     The following results options indicate what Org-babel should do
+     with the results once they are collected.
+
+     - silent :: The results will be echoed in the minibuffer but
+                 will not be inserted into the Org-mode buffer.  E.g.,
+                 =:results output silent=.
+     - replace :: The default value.  The results will be inserted
+                  into the Org-mode buffer.  E.g., =:results output
+                  replace=.
+
+*** =:file=
+    :PROPERTIES:
+    :CUSTOM_ID: header-argument-file
+    :END:
+
+    =:file= is used to specify a path for file output in which case an
+    [[http://orgmode.org/manual/Link-format.html#Link-format][org style]] =file:= link is inserted into the buffer as the
+    result. Common examples are graphical output from [[file:languages/org-babel-doc-R.org][R]], gnuplot,
+    ditaa and [[file:languages/org-babel-doc-LaTeX.org][latex]] blocks.
+
+    See the [[#header-argument-dir][=:dir= and remote execution]] section for examples.
+
+    Note that for some languages, including [[file:languages/org-babel-doc-R.org][R]], gnuplot, [[file:languages/org-babel-doc-LaTeX.org][latex]] and
+    ditaa, graphical output is sent to the specified file without the
+    file being referenced explicitly in the code block. See the
+    documentation for the individual languages for details. In
+    contrast, general purpose languages such as python and ruby
+    require that the code explicitly create output corresponding to
+    the path indicated by =:file=.
+
+    While the =:file= header argument can be used to specify the path
+    to the output file,
+
+*** =:dir= and remote execution
+    :PROPERTIES:
+    :CUSTOM_ID: header-argument-dir
+    :END:
+    =:dir= specifies the /default directory/ during code block
+    execution. If it is absent, then the directory associated with the
+    current buffer is used. In other words, supplying =:dir path=
+    temporarily has the same effect as changing the current directory
+    with =M-x cd path=, and then not supplying =:dir=. Under the
+    surface, =:dir= simply sets the value of the emacs variable
+    =default-directory=.
+
+    When using =:dir=, you should supply a relative path for [[#header-argument-file][file
+    output]] (e.g. =:file myfile.jpg= or =:file results/myfile.jpg=) in
+    which case that path will be interpreted relative to the default
+    directory.
+
+    In other words, if you want your plot to go into a folder called
+    Work in your home directory, you could use
+
+#+begin_example 
+  ,#+begin_src R :file myplot.png :dir ~/Work
+  matplot(matrix(rnorm(100), 10), type="l")
+  ,#+end_src
+#+end_example
+
+**** Remote execution
+     A directory on a remote machine can be specified using [[http://www.gnu.org/software/tramp/#Filename-Syntax][tramp
+     filename syntax]], in which case the code will be executed on the
+     remote machine[fn:2]. An example is
+
+#+begin_example 
+,#+begin_src R :file plot.png :dir /dand@yakuba.princeton.edu:
+  plot(1:10, main=system("hostname", intern=TRUE))
+,#+end_src
+#+end_example
+
+Text results will be returned to the local org buffer as normal, and
+file output will be created on the remote machine with relative paths
+interpreted relative to the remote directory. An org link to the
+remote file will be created.
+
+So in the above example a plot will be created on the remote machine,
+and a link of the following form will be inserted in the org buffer:
+
+#+begin_example 
+[[file:/scp:dand@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]
+#+end_example
+
+Most of this functionality follows immediately from the fact that
+=:dir= sets the value of the emacs variable =default-directory=,
+thanks to [[http://www.gnu.org/software/tramp/][tramp]]. Those using XEmacs, or GNU Emacs prior to
+version 23 may need to install tramp separately in order for the
+above features to work correctly.
+
+**** Further points
+     - If =:dir= is used in conjunction with =:session=, although it
+       will determine the starting directory for a new session as
+       expected, no attempt is currently made to alter the directory
+       associated with an existing session.
+     - =:dir= should typically not be used to create files during
+       export with =:exports results= or =:exports both=. The reason
+       is that, in order to retain portability of exported material
+       between machines, during export, links inserted into the buffer
+       will *not* be expanded against default directory. Therefore, if
+       default-directory is altered using =:dir=, it it probable that
+       the file will be created in a location to which the link does
+       not point.
+*** =:exports=
+    :PROPERTIES:
+    :CUSTOM_ID: header-argument-exports
+    :END:
+
+    Specify what should be included in HTML or LaTeX exports of the
+    Org-mode file.
+
+    - code :: the default.  The body of code is included
+              into the exported file.  E.g., =:exports code=.
+    - results :: the result of evaluating the code is included in the
+                  exported file. E.g., =:exports results=.
+    - both :: both the code and results are included in the exported
+               file. E.g., =:exports both=.
+    - none :: nothing is included in the exported file.  E.g.,
+               =:exports none=.
+
+*** =:tangle=
+    :PROPERTIES:
+    :CUSTOM_ID: tangle-header-arguments
+    :END:
+
+    Specify whether or not the source code block should be included
+    in tangled extraction of source code files.
+
+    - yes :: the source code block is exported to a source code file
+             named after the basename (name w/o extension) of the
+             Org-mode file.  E.g., =:tangle yes=.
+    - no :: the default.  The source code block is not
+          exported to a source code file.  E.g., =:tangle no=.
+    - other :: Any other string passed to the =:tangle= header argument
+                is interpreted as a file basename to which the block will
+                be exported.  E.g., =:tangle basename=.
+
+*** =:session=
+    :PROPERTIES:
+    :CUSTOM_ID: header-argument-session
+    :END:
+
+    Start a session for an interpreted language where state is
+    preserved.  This applies particularly to the supported languages
+    python, R and ruby.
+
+    By default, a session is not started.
+
+    A string passed to the =:session= header argument will give the
+    session a name.  This makes it possible to run concurrent
+    sessions for each interpreted language.
+
+*** =:noweb=
+    :PROPERTIES:
+    :CUSTOM_ID: header-argument-noweb
+    :END:
+
+    Controls the expansion of [[noweb-reference-syntax][noweb syntax]] references in a
+    source code block.  This header argument can have one of two
+    values: =yes= or =no=.
+    - =no= :: the default.  No [[noweb-reference-syntax][noweb syntax]] specific action is taken
+         on evaluating source code blocks/  However, noweb references
+         will still be expanded during tangling.
+    - =yes= :: all [[noweb-reference-syntax][noweb syntax]] references in the body of the source
+               code block will be expanded before the block is evaluated.
+
+**** Noweb Prefix Lines
+
+     Noweb insertions are now placed behind the line prefix of the
+     =<<reference>>=.
+
+     This behavior is illustrated in the following example.  Because
+     the =<<example>>= noweb reference appears behind the SQL
+     comment syntax, each line of the expanded noweb reference will
+     be commented.
+
+     This source code block:
+
+     #+begin_example
+       -- <<example>>
+     #+end_example
+
+
+     expands to:
+
+     #+begin_example
+       -- this is the
+       -- multi-line body of example
+     #+end_example
+
+     Note that noweb replacement text that does *not* contain any
+     newlines will not be affected by this change, so it is still
+     possible to use inline noweb references.
+
+     Thanks to Sébastien Vauban for this idea.
+
+*** =:cache=
+    :PROPERTIES:
+    :CUSTOM_ID: header-argument-cache
+    :END:
+
+    Controls the use of in-buffer caching of source code block
+    results to avoid re-running unchanged source code blocks.  This
+    header argument can have one of two values: =yes= or =no=.
+    - =no= :: The default.  No caching takes place and the source
+         code block will be run every time it is executed.
+    - =yes= :: every time the source code block is run a sha1 hash of
+         the code and arguments passed to the block will be
+         generated.  This hash is packed into the =#+results:= line
+         of the results and will be checked on subsequent executions
+         of the source code block.  If the source code block has not
+         changed since the last time it was evaluated, it will not be
+         re-evaluated.
+
+@section Results
+    :PROPERTIES:
+    :CUSTOM_ID: results-specification
+    :END:
+
+    The way in which results are handled depends on whether a [[header-argument-session][session]]
+    is invoked, as well as on whether
+    [[header-argument-results-collection][=:results value=] or
+    [[header-argument-results-collection][=:results output=]] is used. The following table shows the
+    possibilities:
+
+    |                   | non-session (default)    | =:session=                          |
+    |-------------------+--------------------------+-------------------------------------|
+    | =:results value=  | value of last expression | value of last expression            |
+    | =:results output= | contents of stdout       | concatenation of interpreter output |
+
+    *Note:*  With =:results value=, the result in both =:session= and
+    non-session is returned to Org-mode as a table (a one- or
+    two-dimensional vector of strings or numbers) when appropriate.
+
+**** Non-session
+***** =:results value=
+      This is the default. Internally, the value is obtained by
+      wrapping the code in a function definition in the external
+      language, and evaluating that function. Therefore, code should be
+      written as if it were the body of such a function. In particular,
+      note that python does not automatically return a value from a
+      function unless a =return= statement is present, and so a
+      'return' statement will usually be required in python.
+
+      This is the only one of the four evaluation contexts in which the
+      code is automatically wrapped in a function definition.
+
+***** =:results output=
+      The code is passed to the interpreter as an external process, and
+      the contents of the standard output stream are returned as
+      text. (In certain languages this also contains the error output
+      stream; this is an area for future work.)
+
+**** =:session=
+***** =:results value=
+      The code is passed to the interpreter running as an interactive
+      Emacs inferior process. The result returned is the result of the
+      last evaluation performed by the interpreter. (This is obtained in
+      a language-specific manner: the value of the variable =_= in
+      python and ruby, and the value of =.Last.value= in R).
+
+***** =:results output=
+       The code is passed to the interpreter running as an interactive
+       Emacs inferior process. The result returned is the concatenation
+       of the sequence of (text) output from the interactive
+       interpreter. Notice that this is not necessarily the same as what
+       would be sent to stdout if the same code were passed to a
+       non-interactive interpreter running as an external process. For
+       example, compare the following two blocks:
+
+#+begin_src python :results output
+       print "hello"
+       2
+       print "bye"
+#+end_src
+
+#+resname:
+       : hello
+       : bye
+
+       In non-session mode, the '2' is not printed and does not appear.
+
+#+begin_src python :results output :session
+       print "hello"
+       2
+       print "bye"
+#+end_src
+
+#+resname:
+       : hello
+       : 2
+       : bye
+
+       But in =:session= mode, the interactive interpreter receives input '2'
+       and prints out its value, '2'. (Indeed, the other print statements are
+       unnecessary here).
+
+@section Noweb Reference Syntax
+  :PROPERTIES:
+  :CUSTOM_ID: noweb-reference-syntax
+  :END:
+
+  The [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] Literate Programming system allows named blocks of code to
+  be referenced by using the familiar Noweb syntax:
+  : <<code-block-name>>
+
+  Noweb references are handled differently during evaluation and
+  tangling.
+
+  When a document is tangled, Noweb references are replaced with the
+  named source code block.
+
+  When a source code block is evaluated, the action depends upon the
+  value of the =:noweb= header argument.  If =:noweb yes=, then a
+  Noweb reference is expanded before evaluation.  If =:noweb no=,
+  the default, then the reference is not expanded before
+  evaluation.
+
+  *Note:* the default value, =:noweb no=, was chosen to ensure that
+  Org-babel does not break correct code in a language, such as Ruby,
+  where =<<arg>>= is a syntactically valid construct.  If =<<arg>>= is
+  not syntactically valid in languages that you use, then please
+  consider [[*System%20wide][setting the default value]].
+
+  An example that uses the Noweb reference syntax is provided in the
+  [[literate programming example]].
+
+@section Key Bindings & Useful Functions
+
+  Org-babel re-binds many common Org-mode key sequences depending on
+  the context.  Within a source-code block the following sequences
+  are rebound:
+  | =C-c C-c= | [[function-org-babel-execute][org-babel-execute-src-block]]     |
+  | =C-c C-o= | [[function-org-babel-open-src-block-result][org-babel-open-src-block-result]] |
+  | =C-up=    | [[function-org-babel-load-in-session][org-babel-load-in-session]]       |
+  | =M-down=  | [[function-org-babel-pop-to-session][org-babel-pop-to-session]]        |
+
+  Org-babel also exposes a number of functions behind the common
+  =org-babel-key-prefix= of =C-c M-b=:
+  #+begin_src emacs-lisp :exports none
+     (lambda (binding
+       (list (format "\\C-c \\M-b %s"
+                     (car binding))
+             (format "[[function-%s][%s]]"
+                     (cdr binding) (cdr binding))))
+     org-babel-key-bindings)
+  #+end_src
+  | =C-c M-b t= | [[function-org-babel-tangle][org-babel-tangle]]                  |
+  | =C-c M-b T= | [[function-org-babel-tangle-file][org-babel-tangle-file]]             |
+  | =C-c M-b e= | [[function-org-babel-execute-src-block][org-babel-execute-src-block]]       |
+  | =C-c M-b s= | [[function-org-babel-execute-subtree][org-babel-execute-subtree]]         |
+  | =C-c M-b b= | [[function-org-babel-execute-buffer][org-babel-execute-buffer]]          |
+  | =C-c M-b h= | [[function-org-babel-sha1-hash][org-babel-sha1-hash]]               |
+  | =C-c M-b g= | [[function-org-babel-goto-named-source-block][org-babel-goto-named-source-block]] |
+  | =C-c M-b l= | [[function-org-babel-lob-ingest][org-babel-lob-ingest]]              |
+
+
+@subsection Functions
+*** org-babel-execute-src-block
+    :PROPERTIES:
+    :CUSTOM_ID: function-org-babel-execute-src-block
+    :END:
+
+#+begin_example
+  org-babel-execute-src-block is an interactive Lisp function in
+  `org-babel.el'.
+
+  (org-babel-execute-src-block &optional ARG INFO PARAMS)
+
+  Execute the current source code block, and insert the results
+  into the buffer.  Source code execution and the collection and
+  formatting of results can be controlled through a variety of
+  header arguments.
+
+  Optionally supply a value for INFO in the form returned by
+  `org-babel-get-src-block-info'.
+
+  Optionally supply a value for PARAMS which will be merged with
+  the header arguments specified at the front of the source code
+  block.
+#+end_example
+
+*** org-babel-open-src-block-result
+    :PROPERTIES:
+    :CUSTOM_ID: function-org-babel-open-src-block-result
+    :END:
+
+#+begin_example
+  org-babel-open-src-block-result is an interactive Lisp function in
+  `org-babel.el'.
+
+  (org-babel-open-src-block-result &optional RE-RUN)
+
+  If `point' is on a src block then open the results of the
+  source code block, otherwise return nil.  With optional prefix
+  argument RE-RUN the source-code block is evaluated even if
+  results already exist.
+#+end_example
+
+*** org-babel-load-in-session
+    :PROPERTIES:
+    :CUSTOM_ID: function-org-babel-load-in-session
+    :END:
+
+#+begin_example
+  org-babel-load-in-session is an interactive Lisp function in
+  `org-babel.el'.
+
+  (org-babel-load-in-session &optional ARG INFO)
+
+  Load the body of the current source-code block.  Evaluate the
+  header arguments for the source block before entering the
+  session.  After loading the body this pops open the session.
+
+  [back]
+#+end_example
+
+*** org-babel-pop-to-session
+    :PROPERTIES:
+    :CUSTOM_ID: function-org-babel-pop-to-session
+    :END:
+
+#+begin_example
+  org-babel-pop-to-session is an interactive Lisp function in
+  `org-babel.el'.
+
+  (org-babel-pop-to-session &optional ARG INFO)
+
+  Pop to the session of the current source-code block.  If
+  called with a prefix argument then evaluate the header arguments
+  for the source block before entering the session.  Copy the body
+  of the source block to the kill ring.
+
+  [back]
+#+end_example
+
+*** org-babel-tangle
+    :PROPERTIES:
+    :CUSTOM_ID: function-org-babel-tangle
+    :END:
+
+#+begin_example
+  org-babel-tangle is an interactive Lisp function in
+  `org-babel-tangle.el'.
+
+  It is bound to C-c M-b t.
+
+  (org-babel-tangle &optional TARGET-FILE LANG)
+
+  Extract the bodies of all source code blocks from the current
+  file into their own source-specific files.  Optional argument
+  TARGET-FILE can be used to specify a default export file for all
+  source blocks.  Optional argument LANG can be used to limit the
+  exported source code blocks by language.
+#+end_example
+
+*** org-babel-execute-subtree
+    :PROPERTIES:
+    :CUSTOM_ID: function-org-babel-execute-subtree
+    :END:
+
+#+begin_example
+  org-babel-execute-subtree is an interactive Lisp function in
+  `org-babel.el'.
+
+  It is bound to C-c M-b s.
+
+  (org-babel-execute-subtree &optional ARG)
+
+  Replace EVAL snippets in the entire subtree.
+#+end_example
+
+*** org-babel-execute-buffer
+    :PROPERTIES:
+    :CUSTOM_ID: function-org-babel-execute-buffer
+    :END:
+
+#+begin_example
+  org-babel-execute-buffer is an interactive Lisp function in
+  `org-babel.el'.
+
+  It is bound to C-c M-b b.
+
+  (org-babel-execute-buffer &optional ARG)
+
+  Replace EVAL snippets in the entire buffer.
+#+end_example
+
+*** org-babel-sha1-hash
+    :PROPERTIES:
+    :CUSTOM_ID: function-org-babel-sha1-hash
+    :END:
+
+#+begin_example
+  org-babel-sha1-hash is an interactive Lisp function in `org-babel.el'.
+
+  It is bound to C-c M-b h.
+
+  (org-babel-sha1-hash &optional INFO)
+
+  Not documented.
+#+end_example
+
+*** org-babel-goto-named-source-block
+    :PROPERTIES:
+    :CUSTOM_ID: function-org-babel-goto-named-source-block
+    :END:
+
+#+begin_example
+  org-babel-goto-named-source-block is an interactive Lisp function in
+  `org-babel.el'.
+
+  It is bound to C-c M-b g.
+
+  (org-babel-goto-named-source-block &optional NAME)
+
+  Go to a named source-code block.
+#+end_example
+
+*** org-babel-lob-ingest
+    :PROPERTIES:
+    :CUSTOM_ID: function-org-babel-lob-ingest
+    :END:
+
+#+begin_example
+  org-babel-lob-ingest is an interactive Lisp function in
+  `org-babel-lob.el'.
+
+  It is bound to C-c M-b l.
+
+  (org-babel-lob-ingest &optional FILE)
+
+  Add all source-blocks defined in FILE to `org-babel-library-of-babel'.
+#+end_example
+
+@section Batch Execution
+It is possible to call Org-babel functions from the command line.
+This shell script calls [[function-org-babel-tangle][org-babel-tangle]] on every one of its
+arguments.
+
+Be sure to adjust the paths to fit your system.
+#+begin_src sh
+  #!/bin/sh
+  # -*- mode: shell-script -*-
+  #
+  # tangle a file with org-babel
+  #
+  DIR=`pwd`
+  FILES=""
+
+  # wrap each argument in the code required to call tangle on it
+  for i in $@; do
+  FILES="$FILES \"$i\""
+  done
+
+  emacsclient \
+  --eval "(progn
+  (add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\"))
+  (add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\"))
+  (require 'org)(require 'org-exp)(require 'org-babel)
+  (mapc (lambda (file)
+         (find-file (expand-file-name file \"$DIR\"))
+         (org-babel-tangle)
+         (kill-buffer)) '($FILES)))"
+#+end_src
+
+@section Footnotes
+
+[fn:1] The former use of the =shell= identifier is now deprecated.
+
+[fn:2] As long as the interpreter executable is found on the remote
+machine: see the variable =tramp-remote-path=
+
+
+@section HTML 1                                                           :noexport:
+
+#+begin_html
+  <style type="text/css">
+   <!--/*--><![CDATA[/*><!--*/
+  #table-of-contents {
+    max-width: 100%;
+    margin: 0;
+  }
+    /*]]>*/-->
+  </style>
+#+end_html
+
+@subsection Note
+   - HTML 1 was keeping the babelfish code from exporting.  Not sure
+     why or if the code itself is necessary, but moving it here gets
+     the fish on the page.