Merge branch 'master' into tangle

org-babel.org

@@ -114,6 +114,45 @@ table, allowing the test suite to be run be evaluation of the table
 and the results to be collected in the same table.
 
 
+** features
+
+*** code evaluation (comint buffer sessions and external processes)
+There are two main ways to evaluate source blocks with org-babel.
+
+- external :: By default (if the =:session= header argument is not
+              present) all source code blocks are evaluated in
+              external processes.  In these cases an external process
+              is used to evaluate the source-code blocks.
+- session :: Session based evaluation uses persistent sessions in
+             comint buffers.  Sessions can be used across multiple
+             source blocks setting and accessing variables in the
+             global environment.
+
+             Evaluating source blocks in sessions also allows for
+             interaction with the code.  To jump to the session of a
+             source block use the `org-babel-pop-to-session' command
+             or press =M-[down]= while inside of a source code block.
+             When called with a prefix argument
+             `org-babel-pop-to-session' will evaluate all header
+             arguments before jumping to the source-code block.
+
+*** results (values and outputs)
+Either the *value* or the *output* of source code blocks can be
+collected after evaluation.
+
+- value :: The default way to collect results from a source-code block
+           is to return the value of the last statement in the block.
+           This can be thought of as the return value of the block.
+           In this case any printed output of the block is ignored.
+           This can be though of a similar to a "functional" value of
+           evaluation.
+- output :: Another way of generating results from a source-code block
+            is to collect the output generated by the execution of the
+            block.  In this case all printed output is collected
+            throughout the execution of the block.  This can be
+            thought of as similar to a "script" style of evaluation.
+
+
 * Tasks [27/42]
 ** TODO support for working with =*Org Edit Src Example*= buffers [1/4]
 *** TODO set buffer-local-process variables appropriately [DED]