Merge branch 'master' of git://repo.or.cz/org-mode

UTILITIES/git-changelog

@@ -52,19 +52,42 @@ for commit in repo.iter_commits(ref, paths=path):
     diff = commit.diff(commit.parents[0])
     files = []
     for f in diff:
-        p = f.a_blob.path or f.b_blob.path
+        if not f.a_blob:
+            p = f.b_blob.path
+        elif not f.b_blob:
+            p = f.a_blob.path
+        else:
+            continue
+
         p2 = re.sub('^' + path + '/', '', p)
         if p != p2:
             files.append(p2)
 
     fp = Popen(["fmt", "-72"], shell = True, stdin = PIPE, stdout = PIPE)
-    fp.stdin.write("\t* %s: %s" % (string.join(files, ",\n\t"), log_text))
+    if files:
+        fp.stdin.write("\t* %s: %s" % (string.join(files, ",\n\t"), log_text))
+    else:
+        fp.stdin.write("\t* %s" % log_text)
     fp.stdin.close()
     log_text = fp.stdout.read()
     del fp
 
-    print "%s  %s  <%s>\n\n%s%s" % \
+    print "%s  %s  <%s>\n" % \
         (time.strftime("%Y-%m-%d", time.gmtime(date)),
-         author.name, author.email, log_text, log_text_remainder)
+         author.name, author.email)
+
+    if path:
+        log_text = re.sub(' ' + path + '/', ' ', log_text)
+        log_text_remainder = re.sub(' ' + path + '/', ' ', log_text_remainder)
+
+    # If the log_text_remainder already begins with a *, then use that as the
+    # changelog text.
+    if re.match('\s+\* ', log_text_remainder):
+        if log_text_remainder[0] == '\n':
+            print log_text_remainder[1:]
+        else:
+            print log_text_remainder
+    else:
+        print "%s%s" % (log_text, log_text_remainder)
 
 # git-changelog ends here

UTILITIES/make_emacs_changelog

@@ -0,0 +1,50 @@
+#!/usr/bin/perl
+
+$commitrange = shift @ARGV;
+if (!$commitrange) {
+  print STDERR "Enter commitrange: ";
+  $commitrange = <>;
+  $commitrange =~ s/\s*(.*?)\s+/$1/;
+}
+
+$syncdate = shift @ARGV;
+if (!$syncdate) {
+  print STDERR "Enter syncdate YYYY-MM-DD: ";
+  $syncdate = <>;
+  $syncdate =~ s/\s*(.*?)\s+/$1/;
+}
+
+# Run git log to get the commits the messages
+open IN,"git log $commitrange|";
+undef $/;
+$log = <IN>;
+@commits = split(/^(?=commit)/m,$log);
+
+for $i (0..$#commits) {
+  $entry = ""; $tiny = "";
+  $commit = $commits[$i];
+  $author = $1 if $commit=~/^Author: ([^\n]+)/m;
+  $date   = $1 if $commit=~/^Date: ([^\n]+)/m;
+  $entry  = $1 if $commit=~/^([ \t]*\* [^\f]*?)(\n[ \t]*\n|\Z)/m;
+  $tiny   = "  (tiny change)" if $commit =~ /TINYCHANGE/;
+
+  # split author into name and address
+  if ($author =~ /(.*?)\s+(<.*?>)/) {
+    $name = $1;
+    $address = $2;
+  } else {
+    warn "No name/address";
+    next;
+  }
+
+  if ($entry) {
+    # indent each line by 1 TAB
+    $entry =~ s/^[ \t]*/\t/gm;
+    # Add empty lines if there are several files in there
+    $entry =~ s/(\n[ \t]+\* )/\n$1/g;
+    # remove the lisp part of the path
+    $entry =~ s/^([ \t]+\* )lisp\//$1/mg;
+    print "$syncdate  $name  $address$tiny\n\n$entry\n\n";
+  }
+}
+ 

UTILITIES/pw

@@ -130,6 +130,7 @@ def usage():
                         by name
         search [str]  : Same as 'list'
         view <ID>     : View a patch
+        show <ID>     : Same as view
         update [-s state] [-c commit-ref] <ID>
                       : Update patch\n""")
     sys.stderr.write("""\nFilter options for 'list' and 'search':
@@ -586,7 +587,7 @@ def main():
 
         merge_with(patch_id, rpc, config.get('auth', 'username'))
 
-    elif action == 'view':
+    elif action == 'view' or action == 'show':
         try:
             patch_id = patch_id or int(args[0])
         except:

doc/org.texi

@@ -434,7 +434,7 @@ Using header arguments
 Specific header arguments
 
 * var::				Pass arguments to code blocks
-* results::			Specify the type of results and how they will be collectd and handled
+* results::			Specify the type of results and how they will be collected and handled
 * file::			Specify a path for file output
 * dir and remote execution::	Specify the default directory for code block execution
 * exports::			Export code and/or results
@@ -451,7 +451,7 @@ Specific header arguments
 Miscellaneous
 
 * Completion::			M-TAB knows what you need
-* Speed keys::			Electic commands at the beginning of a headline
+* Speed keys::			Electric commands at the beginning of a headline
 * Code evaluation security::	Org mode files evaluate inline code
 * Customization::		Adapting Org to your taste
 * In-buffer settings::		Overview of the #+KEYWORDS
@@ -1521,7 +1521,7 @@ LaTeX}).  Here are the valid references:
 @table @code
 @item [1]
 A plain numeric footnote marker.  Compatible with @file{footnote.el}, but not
-recommended because somthing like @samp{[1]} could easily be part of a code
+recommended because something like @samp{[1]} could easily be part of a code
 snippet.
 @item [fn:name]
 A named footnote reference, where @code{name} is a unique label word, or, for
@@ -2643,7 +2643,7 @@ functions.
 @node Org-Plot,  , The spreadsheet, Tables
 @section Org-Plot
 @cindex graph, in tables
-@cindex plot tables using gnuplot
+@cindex plot tables using Gnuplot
 @cindex #+PLOT
 
 Org-Plot can produce 2D and 3D graphs of information stored in org tables
@@ -3868,7 +3868,7 @@ If the task was going to be overdue the next day.
 If the task was overdue on that day.
 @end table
 
-In addition to coloring each day, the day is also marked with an asterix if
+In addition to coloring each day, the day is also marked with an asterisk if
 the task was actually done that day, and an exclamation mark to show where
 the current day falls in the graph.
 
@@ -5745,8 +5745,8 @@ use the shift key and press @kbd{S}.  Remember that using shift will always
 leave you clocked out, no matter which option you choose.
 @item C
 To cancel the clock altogether, use @kbd{C}.  Note that if instead of
-cancelling you subtract the away time, and the resulting clock amount is less
-than a minute, the clock will still be cancelled rather than clutter up the
+canceling you subtract the away time, and the resulting clock amount is less
+than a minute, the clock will still be canceled rather than clutter up the
 log with an empty entry.
 @end table
 
@@ -6026,7 +6026,7 @@ place where you started the capture process.
 @node Template elements, Template expansion, Capture templates, Capture templates
 @subsubsection Template elements
 
-Now lets look at the elements of a template defintion.  Each entry in
+Now lets look at the elements of a template definition.  Each entry in
 @code{org-capture-templates} is a list with the following items: 
 
 @table @var
@@ -6315,23 +6315,27 @@ same directory for attachments as the parent does.
 @node RSS Feeds, Protocols, Attachments, Capture - Refile - Archive
 @section RSS feeds
 @cindex RSS feeds
+@cindex Atom feeds
 
-Org can add and change entries based on information found in RSS feeds.  You
-could use this to make a task out of each new podcast in a podcast feed.  Or
-you could use a phone-based note-creating service on the web to import tasks
-into Org.  To access feeds, configure the variable @code{org-feed-alist}.
-The docstring of this variable has detailed information.  Here is just an
-example:
+Org can add and change entries based on information found in RSS feeds and
+Atom feeds.  You could use this to make a task out of each new podcast in a
+podcast feed.  Or you could use a phone-based note-creating service on the
+web to import tasks into Org.  To access feeds, configure the variable
+@code{org-feed-alist}.  The docstring of this variable has detailed
+information.  Here is just an example:
 
 @example
 (setq org-feed-alist
-      '(("ReQall" "http://www.reqall.com/user/feeds/rss/a1b2c3....."
-         "~/org/feeds.org" "ReQall Entries")
+     '(("Slashdot"
+	 "http://rss.slashdot.org/Slashdot/slashdot"
+	 "~/txt/org/feeds.org" "Slashdot Entries")))
 @end example
+
 @noindent
-will configure that new items from the feed provided by @file{reqall.com}
-will result in new entries in the file @file{~/org/feeds.org} under the
-heading @samp{ReQall Entries}, whenever the following command is used:
+will configure that new items from the feed provided by
+@code{rss.slashdot.org} will result in new entries in the file
+@file{~/org/feeds.org} under the heading @samp{Slashdot Entries}, whenever
+the following command is used:
 
 @table @kbd
 @kindex C-c C-x g
@@ -6352,8 +6356,8 @@ list of drawers in that file:
 #+DRAWERS: LOGBOOK PROPERTIES FEEDSTATUS
 @end example
 
-For more information, see @file{org-feed.el} and the docstring of
-@code{org-feed-alist}.
+For more information, including how to read atom feeds, see
+@file{org-feed.el} and the docstring of @code{org-feed-alist}.
 
 @node Protocols, Refiling notes, RSS Feeds, Capture - Refile - Archive
 @section Protocols for external access
@@ -9455,7 +9459,7 @@ and @code{style} attributes for a link:
 Org-mode tables are exported to HTML using the table tag defined in
 @code{org-export-html-table-tag}.  The default setting makes tables without
 cell borders and frame.  If you would like to change this for individual
-tables, place somthing like the following before the table:
+tables, place something like the following before the table:
 
 @cindex #+CAPTION
 @cindex #+ATTR_HTML
@@ -9486,7 +9490,7 @@ will link to a high resolution version of the image, you could use:
 [[file:highres.jpg][file:thumb.jpg]]
 @end example
 
-If you need to add attributes to an inlines image, use a @code{#+ATTR_HTML}.
+If you need to add attributes to an inlined image, use a @code{#+ATTR_HTML}.
 In the example below we specify the @code{alt} and @code{title} attributes to
 support text viewers and accessibility, and align it to the right.
 
@@ -10329,7 +10333,7 @@ For more information and examples see the Org-taskjuggler tutorial at
 @cindex Freemind export
 @cindex mind map
 
-The freemind exporter was written by Lennart Borgman.
+The Freemind exporter was written by Lennart Borgman.
 
 @table @kbd
 @kindex C-c C-e m
@@ -11005,7 +11009,7 @@ formulas (see @ref{The spreadsheet}).
 @item <language>
 The language of the code in the block.
 @item <switches>
-Switches controling exportation of the code block (see switches discussion in
+Switches controlling exportation of the code block (see switches discussion in
 @ref{Literal examples})
 @item <header arguments>
 Optional header arguments control many aspects of evaluation, export and
@@ -11086,6 +11090,13 @@ Both the code block and its results will be exported.
 Neither the code block nor its results will be exported.
 @end table
 
+It is possible to inhibit the evaluation of code blocks during export.
+Setting the the @code{org-export-babel-evaluate} variable to @code{nil} will
+ensure that no code blocks are evaluated as part of the export process.  This
+can be useful in situations where potentially untrusted Org-mode files are
+exported in an automated fashion, for example when Org-mode is used as the
+markup language for a wiki.
+
 @comment  node-name,  next,  previous,  up
 @comment  Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code
 @node Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code
@@ -11120,37 +11131,36 @@ Tangle the current file.
 Choose a file to tangle.
 @end table
 
-@comment  node-name,  next,  previous,  up
-@comment  Evaluating code blocks,  , Extracting source code, Working With Source Code
+@subsubheading Hooks
+@table @code
+@item org-babel-post-tangle-hook
+This hook is run from within code files tangled by @code{org-babel-tangle}.
+Example applications could include post-processing, compilation or evaluation
+of tangled code files.
+@end table
 
 @node Evaluating code blocks, Library of Babel, Extracting source code, Working With Source Code
 @section Evaluating code blocks
 @cindex code block, evaluating
 @cindex source code, evaluating
 
-@quotation
-Whenever code is evaluated there is a potential for that code to do harm.
-Org-mode provides a number of safeguards to ensure that it only evaluates
-code with explicit confirmation from the user.  For information on these
-safeguards (and on how to disable them) see @ref{Code evaluation security}.
-@end quotation
-
-Code blocks can be evaluated and the results placed in the Org-mode buffer.
-By default, evaluation is only turned on for @code{emacs-lisp} code blocks,
-however support exists for evaluating blocks in many languages.  See
+Code blocks can be evaluated@footnote{Whenever code is evaluated there is a
+potential for that code to do harm.  Org-mode provides a number of safeguards
+to ensure that it only evaluates code with explicit confirmation from the
+user.  For information on these safeguards (and on how to disable them) see
+@ref{Code evaluation security}.} and the results placed in the Org-mode
+buffer.  By default, evaluation is only turned on for @code{emacs-lisp} code
+blocks, however support exists for evaluating blocks in many languages.  See
 @ref{Languages} for a list of supported languages.  See @ref{Structure of
 code blocks} for information on the syntax used to define a code block.
 
 @kindex C-c C-c
-There are a number of ways to evaluate code blocks.  The simplest is to
-press @kbd{C-c C-c} or @kbd{C-c C-v e} with the point on a code block.  This
-will call the @code{org-babel-execute-src-block} function to evaluate the
-block and insert its results into the Org-mode buffer.
-
-@quotation
-The @code{org-babel-no-eval-on-ctrl-c-ctrl-c} variable can be used to remove
-code evaluation from the @kbd{C-c C-c} key binding.
-@end quotation
+There are a number of ways to evaluate code blocks.  The simplest is to press
+@kbd{C-c C-c} or @kbd{C-c C-v e} with the point on a code block@footnote{The
+@code{org-babel-no-eval-on-ctrl-c-ctrl-c} variable can be used to remove code
+evaluation from the @kbd{C-c C-c} key binding.}.  This will call the
+@code{org-babel-execute-src-block} function to evaluate the block and insert
+its results into the Org-mode buffer.
 
 It is also possible to evaluate named code blocks from anywhere in an
 Org-mode buffer or an Org-mode table.  @code{#+call} (or synonymously
@@ -11413,7 +11423,7 @@ The following header arguments are defined:
 @menu
 * var::				Pass arguments to code blocks
 * results::			Specify the type of results and how they will
-                                be collectd and handled
+                                be collected and handled
 * file::			Specify a path for file output
 * dir and remote execution::	Specify the default directory for code block
                                 execution
@@ -11435,19 +11445,14 @@ The following header arguments are defined:
 
 @node var, results, Specific header arguments, Specific header arguments
 @subsubsection @code{:var}
-The @code{:var} header argument is used to pass arguments to
-code blocks.  The specifics of how arguments are included
-in a code block vary by language; these 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
-@itemize @bullet
-@item literal values
-@item values from org-mode tables
-@item the results of other code blocks
-@end itemize
-
-These values can be indexed in a manner similar to arrays---see the argument
+The @code{:var} header argument is used to pass arguments to code blocks.
+The specifics of how arguments are included in a code block vary by language;
+these 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 literal values, values from org-mode
+tables, or the results of other code blocks.
+
+These values can be indexed in a manner similar to arrays---see the
 ``indexable variable values'' heading below.
 
 The following syntax is used to pass arguments to code blocks using the
@@ -11530,43 +11535,90 @@ following the source name.
 @end example
 
 @subsubheading Indexable variable values
-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
+It is possible to reference portions of variable values by ``indexing'' into
+the variables.  Indexes are 0 based with negative values counting back from
+the end.  If an index is separated by @code{,}s then each subsequent section
+will index into the next deepest nesting or dimension of the value.  The
+following example assigns the last cell of the first row the table
 @code{example-table} to the variable @code{data}:
 
 @example
-:var data=example-table[1:2]
-@end example
+#+results: example-table
+| 1 | a |
+| 2 | b |
+| 3 | c |
+| 4 | d |
 
-Note: ranges are indexed using the @code{:} operator.
+#+begin_src emacs-lisp :var data=example-table[0,-1]
+  data
+#+end_src
 
-Note: indices are 0 based.
+#+results:
+: a
+@end example
 
-The following example assigns the second column of the first row of
-@code{example-table} to @code{data}:
+Ranges of variable values can be referenced using two integer separated by a
+@code{:}, in which case the entire inclusive range is referenced.  For
+example the following assigns the middle three rows of @code{example-table}
+to @code{data}.
 
 @example
-:var data=example-table[0,1]
+#+results: example-table
+| 1 | a |
+| 2 | b |
+| 3 | c |
+| 4 | d |
+| 5 | 3 |
+
+#+begin_src emacs-lisp :var data=example-table[1:3]
+  data
+#+end_src
+
+#+results:
+| 2 | b |
+| 3 | c |
+| 4 | d |
 @end example
 
-It is possible to index into the results of code blocks as well as
-tables.  Any number of dimensions can be indexed.  Dimensions are separated
-from one another by commas.
+Additionally an empty index, or the single character @code{*} are both
+interpreted to mean the entire range and as such are equivalent to
+@code{0:-1}, as shown in the following example in which the entire first
+column is referenced.
 
-For more information on indexing behavior see the documentation for the
-@code{org-babel-ref-index-list} function, provided below.
+@example
+#+results: example-table
+| 1 | a |
+| 2 | b |
+| 3 | c |
+| 4 | d |
 
-@deffn
-org-babel-ref-index-list is a Lisp function in `org-babel-ref.el'.
+#+begin_src emacs-lisp :var data=example-table[,0]
+  data
+#+end_src
 
-(org-babel-ref-index-list index lis)
+#+results:
+| 1 | 2 | 3 | 4 |
+@end example
 
-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 deffn
+It is possible to index into the results of code blocks as well as tables.
+Any number of dimensions can be indexed.  Dimensions are separated from one
+another by commas, as shown in the following example.
+
+@example
+#+source: 3D
+#+begin_src emacs-lisp
+  '(((1  2  3)  (4  5  6)  (7  8  9))
+    ((10 11 12) (13 14 15) (16 17 18))
+    ((19 20 21) (22 23 24) (25 26 27)))
+#+end_src
+
+#+begin_src emacs-lisp :var data=3D[1,,1]
+  data
+#+end_src
+
+#+results:
+| 11 | 14 | 17 |
+@end example
 
 @node results, file, var, Specific header arguments
 @subsubsection @code{:results}
@@ -12244,7 +12296,7 @@ emacsclient \
 
 @menu
 * Completion::			M-TAB knows what you need
-* Speed keys::			Electic commands at the beginning of a headline
+* Speed keys::			Electric commands at the beginning of a headline
 * Code evaluation security::	Org mode files evaluate inline code
 * Customization::		Adapting Org to your taste
 * In-buffer settings::		Overview of the #+KEYWORDS
@@ -13259,7 +13311,6 @@ hard to do in a general way, would lead to a customization nightmare,
 and would take away much of the simplicity of the Orgtbl-mode table
 editor.
 
-
 This appendix describes a different approach.  We keep the Orgtbl mode
 table in its native format (the @i{source table}), and use a custom
 function to @i{translate} the table to the correct syntax, and to
@@ -13267,10 +13318,10 @@ function to @i{translate} the table to the correct syntax, and to
 the burden of writing conversion functions on the user, but it allows
 for a very flexible system.
 
-Bastien added the ability to do the same with lists.  You can use Org's
-facilities to edit and structure lists by turning @code{orgstruct-mode}
-on, then locally exporting such lists in another format (HTML, La@TeX{}
-or Texinfo.)
+Bastien added the ability to do the same with lists, in Orgstruct mode.  You
+can use Org's facilities to edit and structure lists by turning
+@code{orgstruct-mode} on, then locally exporting such lists in another format
+(HTML, La@TeX{} or Texinfo.)
 
 
 @menu
@@ -13531,7 +13582,7 @@ containing the formatted table.  If you write a generally useful
 translator, please post it on @email{emacs-orgmode@@gnu.org} so that
 others can benefit from your work.
 
-@node  Radio lists,  , Translator functions, Tables in arbitrary syntax
+@node Radio lists,  , Translator functions, Tables in arbitrary syntax
 @subsection Radio lists
 @cindex radio lists
 @cindex org-list-insert-radio-list
@@ -13545,7 +13596,9 @@ Here are the differences with radio tables:
 
 @itemize @minus
 @item
-Use @code{ORGLST} instead of @code{ORGTBL}.
+Orgstruct mode must be active.
+@item
+Use the @code{ORGLST} keyword instead of @code{ORGTBL}.
 @item
 The available translation functions for radio lists don't take
 parameters.
@@ -13556,12 +13609,12 @@ parameters.
 Here is a La@TeX{} example.  Let's say that you have this in your
 La@TeX{} file:
 
-@cindex #+ORGLIST
+@cindex #+ORGLST
 @example
 % BEGIN RECEIVE ORGLST to-buy
 % END RECEIVE ORGLST to-buy
 \begin@{comment@}
-#+ORGLIST: SEND to-buy orgtbl-to-latex
+#+ORGLST: SEND to-buy org-list-to-latex
 - a new house
 - a new computer
   + a new keyboard
@@ -14153,7 +14206,7 @@ the view, only the current agenda files will be searched.
 
 @node History and Acknowledgments, Main Index, MobileOrg, Top
 @appendix History and acknowledgments
-@cindex acknowledgements
+@cindex acknowledgments
 @cindex history
 @cindex thanks
 

doc/orgcard.tex

@@ -477,8 +477,11 @@ formula, \kbd{:=} a field formula.
 
 \key{execute code block at point}{C-c C-c}
 \key{open results of code block at point}{C-c C-o}
-\key{preview body of code block at point}{C-c C-v p}
+\key{view expanded body of code block at point}{C-c C-v v}
 \key{go to named code block}{C-c C-v g}
+\key{go to named result}{C-c C-v r}
+\key{go to the next code block}{C-c C-v n}
+\key{go to the previous code block}{C-c C-v p}
 \key{execute all code blocks in current buffer}{C-c C-v b}
 \key{execute all code blocks in current subtree}{C-c C-v s}
 \key{tangle code blocks in current file}{C-c C-v t}

lisp/ob-C.el

@@ -83,7 +83,6 @@ header arguments (calls `org-babel-C-expand')."
 (defun org-babel-C-execute (body params)
   "This function should only be called by `org-babel-execute:C'
 or `org-babel-execute:c++'."
-  (message "executing C source code block")
   (let* ((processed-params (org-babel-process-params params))
          (tmp-src-file (make-temp-file "org-babel-C-src" nil
                                        (cond

lisp/ob-R.el

@@ -81,9 +81,8 @@
        (list body))) "\n")))
 
 (defun org-babel-execute:R (body params)
-  "Execute a block of R code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
-  (message "executing R source code block...")
+  "Execute a block of R code.
+This function is called by `org-babel-execute-src-block'."
   (save-excursion
     (let* ((processed-params (org-babel-process-params params))
            (result-type (nth 3 processed-params))
@@ -212,10 +211,10 @@ write.table(main(), file=\"%s\", sep=\"\\t\", na=\"nil\",row.names=%s, col.names
 
 (defun org-babel-R-evaluate
   (session body result-type column-names-p row-names-p)
-  "Pass BODY to the R process in SESSION.  If RESULT-TYPE equals
-'output then return a list of the outputs of the statements in
-BODY, if RESULT-TYPE equals 'value then return the value of the
-last statement in BODY, as elisp."
+  "Pass BODY to the R process in SESSION.
+If RESULT-TYPE equals 'output then return a list of the outputs
+of the statements in BODY, if RESULT-TYPE equals 'value then
+return the value of the last statement in BODY, as elisp."
   (if (not session)
       ;; external process evaluation
       (case result-type
@@ -267,13 +266,11 @@ last statement in BODY, as elisp."
 		  (inferior-ess-send-input)))) 2) "\n")))))
 
 (defun org-babel-R-process-value-result (result column-names-p)
-  "R-specific processing of return value prior to return to
-org-babel.  Insert hline if column names in output have been
-requested."
+  "R-specific processing of return value.
+Insert hline if column names in output have been requested."
   (if column-names-p
       (cons (car result) (cons 'hline (cdr result)))
     result))
-  
 
 (provide 'ob-R)
 

lisp/ob-asymptote.el

@@ -53,7 +53,7 @@
 
 (defvar org-babel-default-header-args:asymptote
   '((:results . "file") (:exports . "results"))
-  "Default arguments to use when evaluating a asymptote source block.")
+  "Default arguments when evaluating an Asymptote source block.")
 
 (defun org-babel-expand-body:asymptote (body params &optional processed-params)
   "Expand BODY according to PARAMS, return the expanded body."
@@ -63,9 +63,8 @@
 	    "\n" body "\n")))
 
 (defun org-babel-execute:asymptote (body params)
-  "Execute a block of Asymptote code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
-  (message "executing Asymptote source code block")
+  "Execute a block of Asymptote code.
+This function is called by `org-babel-execute-src-block'."
   (let* ((processed-params (org-babel-process-params params))
          (result-params (split-string (or (cdr (assoc :results params)) "")))
          (out-file (cdr (assoc :file params)))
@@ -86,12 +85,14 @@ called by `org-babel-execute-src-block'."
     out-file))
 
 (defun org-babel-prep-session:asymptote (session params)
-  "Prepare a session named SESSION according to PARAMS."
+  "Return an error if the :session header argument is set.
+Asymptote does not support sessions"
   (error "Asymptote does not support sessions"))
 
 (defun org-babel-asymptote-var-to-asymptote (pair)
-  "Convert an elisp val into a string of asymptote code specifying a var
-of the same value."
+  "Convert an elisp value into an Asymptote variable.
+The elisp value PAIR is converted into Asymptote code specifying
+a variable of the same value."
   (let ((var (car pair))
         (val (if (symbolp (cdr pair))
                  (symbol-name (cdr pair))
@@ -135,10 +136,10 @@ Empty cells are ignored."
      (org-combine-plists '(:hline nil :sep "," :tstart "{" :tend "}") params))))
 
 (defun org-babel-asymptote-define-type (data)
-  "Determine type of DATA. DATA is a list. Type symbol is
-returned as 'symbol. The type is usually the type of the first
-atom encountered, except for arrays of int where every cell must
-be of int type."
+  "Determine type of DATA.
+DATA is a list. Type symbol is returned as 'symbol. The type is
+usually the type of the first atom encountered, except for arrays
+of int, where every cell must be of int type."
   (labels ((anything-but-int (el)
                              (cond
                               ((null el) nil)

lisp/ob-clojure.el

@@ -116,8 +116,9 @@
          "clojure.main"))))))
 
 (defun org-babel-clojure-table-or-string (results)
-  "If RESULTS looks like a table, then convert them into an
-Emacs-lisp table, otherwise return the results as a string."
+  "Convert RESULTS to an elisp value.
+If RESULTS looks like a table, then convert to an Emacs-lisp
+table, otherwise return the results as a string."
   (org-babel-read
    (if (string-match "^\\[.+\\]$" results)
        (org-babel-read
@@ -130,14 +131,15 @@ Emacs-lisp table, otherwise return the results as a string."
      results)))
 
 (defun org-babel-clojure-var-to-clojure (var)
-  "Convert an elisp var into a string of clojure source code
-specifying a var of the same value."
+  "Convert an elisp value into a clojure variable.
+The elisp value VAR is converted into a string of clojure source
+code specifying a variable of the same value."
   (if (listp var)
       (format "'%s" var)
     (format "%S" var)))
 
 (defun org-babel-clojure-build-full-form (body vars)
-  "Construct a clojure let form with vars as the let vars."
+  "Construct a clojure let form with VARS as the let variables."
   (let ((vars-forms
 	 (mapconcat ;; define any variables
 	  (lambda (pair)
@@ -179,7 +181,8 @@ specifying a var of the same value."
   (cdr (assoc session org-babel-clojure-buffers)))
 
 (defun org-babel-clojure-initiate-session-by-key (&optional session)
-  "If there is not a current inferior-process-buffer in SESSION
+  "Initiate a clojure session in an inferior-process-buffer.
+If there is not a current inferior-process-buffer in SESSION
 then create one.  Return the initialized session."
   (save-window-excursion
     (let* ((session (if session
@@ -209,15 +212,15 @@ then create one.  Return the initialized session."
       session)))
 
 (defun org-babel-clojure-initiate-session (&optional session params)
-  "Return the slime-clojure repl buffer bound to this session
-or nil if \"none\" is specified."
+  "Return the slime-clojure repl buffer bound to SESSION.
+Returns nil if \"none\" is specified."
   (require 'slime) (require 'swank-clojure)
   (unless (and (stringp session) (string= session "none"))
     (org-babel-clojure-session-buffer
      (org-babel-clojure-initiate-session-by-key session))))
 
 (defun org-babel-clojure-session-connected-hook ()
-  "Finish setting up the bindings of org-babel session to a slime-clojure repl."
+  "Finish  binding an org-babel session to a slime-clojure repl."
   (let ((pending-session (pop org-babel-clojure-pending-sessions)))
     (when pending-session
       (save-excursion
@@ -279,10 +282,10 @@ repl buffer."
 	(org-babel-clojure-table-or-string (car results)))))))
 
 (defun org-babel-clojure-evaluate (buffer body &optional result-type)
-  "Pass BODY to the Clojure process in BUFFER.  If RESULT-TYPE equals
-'output then return a list of the outputs of the statements in
-BODY, if RESULT-TYPE equals 'value then return the value of the
-last statement in BODY, as elisp."
+  "Pass BODY to the Clojure process in BUFFER.
+If RESULT-TYPE equals 'output then return a list of the outputs
+of the statements in BODY, if RESULT-TYPE equals 'value then
+return the value of the last statement in BODY as elisp."
   (if buffer
       (org-babel-clojure-evaluate-session buffer body result-type)
     (org-babel-clojure-evaluate-external-process buffer body result-type)))
@@ -293,7 +296,7 @@ last statement in BODY, as elisp."
    body (nth 1 (or processed-params (org-babel-process-params params)))))
 
 (defun org-babel-execute:clojure (body params)
-  "Execute a block of Clojure code with org-babel."
+  "Execute a block of Clojure code."
   (require 'slime) (require 'swank-clojure)
   (let* ((processed-params (org-babel-process-params params))
          (body (org-babel-expand-body:clojure body params processed-params))

lisp/ob-comint.el

@@ -41,8 +41,9 @@
     (and buffer (buffer-live-p buffer) (get-buffer-process buffer) buffer)))
 
 (defmacro org-babel-comint-in-buffer (buffer &rest body)
-  "Check BUFFER with `org-babel-comint-buffer-livep' then execute
-body inside the protection of `save-window-excursion' and
+  "Check BUFFER and execute BODY.
+BUFFER is checked with `org-babel-comint-buffer-livep'.  BODY is
+executed inside the protection of `save-window-excursion' and
 `save-match-data'."
   (declare (indent 1))
   `(save-excursion
@@ -53,11 +54,12 @@ body inside the protection of `save-window-excursion' and
        ,@body)))
 
 (defmacro org-babel-comint-with-output (meta &rest body)
-  "Evaluate BODY in BUFFER, wait until EOE-INDICATOR appears in
-output, then return all process output.  If REMOVE-ECHO and
-FULL-BODY are present and non-nil, then strip echo'd body from
-the returned output.  META should be a list containing the
-following where the last two elements are optional.
+  "Evaluate BODY in BUFFER and return process output.
+Will wait until EOE-INDICATOR appears in the output, then return
+all process output.  If REMOVE-ECHO and FULL-BODY are present and
+non-nil, then strip echo'd body from the returned output.  META
+should be a list containing the following where the last two
+elements are optional.
 
  (BUFFER EOE-INDICATOR REMOVE-ECHO FULL-BODY)
 
@@ -113,7 +115,8 @@ or user `keyboard-quit' during execution of body."
 	 (split-string string-buffer comint-prompt-regexp)))))
 
 (defun org-babel-comint-input-command (buffer cmd)
-  "Pass CMD to BUFFER  The input will not be echoed."
+  "Pass CMD to BUFFER.
+The input will not be echoed."
   (org-babel-comint-in-buffer buffer
     (goto-char (process-mark (get-buffer-process buffer)))
     (insert cmd)
@@ -121,9 +124,9 @@ or user `keyboard-quit' during execution of body."
     (org-babel-comint-wait-for-output buffer)))
 
 (defun org-babel-comint-wait-for-output (buffer)
-  "Wait until output arrives from BUFFER.  Note: this is only
-safe when waiting for the result of a single statement (not large
-blocks of code)."
+  "Wait until output arrives from BUFFER.
+Note: this is only safe when waiting for the result of a single
+statement (not large blocks of code)."
   (org-babel-comint-in-buffer buffer
     (while (progn
              (goto-char comint-last-input-end)

lisp/ob-css.el

@@ -36,13 +36,13 @@
   "Expand BODY according to PARAMS, return the expanded body." body)
 
 (defun org-babel-execute:css (body params)
-  "Execute a block of CSS code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
-  (message "executing CSS source code block")
-  body)
+  "Execute a block of CSS code.
+This function is called by `org-babel-execute-src-block'."
+ body)
 
 (defun org-babel-prep-session:css (session params)
-  "Prepare SESSION according to the header arguments specified in PARAMS."
+  "Return an error if the :session header argument is set.
+CSS does not support sessions."
   (error "CSS sessions are nonsensical"))
 
 (provide 'ob-css)

lisp/ob-ditaa.el

@@ -41,16 +41,15 @@
 
 (defvar org-babel-default-header-args:ditaa
   '((:results . "file") (:exports . "results"))
-  "Default arguments to use when evaluating a ditaa source block.")
+  "Default arguments for evaluating a ditaa source block.")
 
 (defun org-babel-expand-body:ditaa (body params &optional processed-params)
   "Expand BODY according to PARAMS, return the expanded body." body)
 
 (defvar org-ditaa-jar-path)
 (defun org-babel-execute:ditaa (body params)
-  "Execute a block of Ditaa code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
-  (message "executing Ditaa source code block")
+  "Execute a block of Ditaa code with org-babel.
+This function is called by `org-babel-execute-src-block'."
   (let ((result-params (split-string (or (cdr (assoc :results params)) "")))
         (out-file (cdr (assoc :file params)))
         (cmdline (cdr (assoc :cmdline params)))
@@ -63,8 +62,7 @@ called by `org-babel-execute-src-block'."
     out-file))
 
 (defun org-babel-prep-session:ditaa (session params)
-  "This function does nothing as ditaa does not support
-sessions."
+  "Return an error because ditaa does not support sessions."
   (error "Ditaa does not support sessions"))
 
 (provide 'ob-ditaa)

lisp/ob-dot.el

@@ -50,9 +50,8 @@
   "Expand BODY according to PARAMS, return the expanded body." body)
 
 (defun org-babel-execute:dot (body params)
-  "Execute a block of Dot code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
-  (message "executing Dot source code block")
+  "Execute a block of Dot code with org-babel.
+This function is called by `org-babel-execute-src-block'."
   (let ((result-params (split-string (or (cdr (assoc :results params)) "")))
         (out-file (cdr (assoc :file params)))
         (cmdline (cdr (assoc :cmdline params)))
@@ -63,7 +62,7 @@ called by `org-babel-execute-src-block'."
     out-file))
 
 (defun org-babel-prep-session:dot (session params)
-  "Prepare SESSION according to the contents of PARAMS."
+  "Return an error because Dot does not support sessions."
   (error "Dot does not support sessions"))
 
 (provide 'ob-dot)

lisp/ob-emacs-lisp.el

@@ -31,7 +31,7 @@
 
 (defvar org-babel-default-header-args:emacs-lisp
   '((:hlines . "yes") (:colnames . "no"))
-  "Default arguments to use when evaluating an emacs-lisp source block.")
+  "Default arguments for evaluating an emacs-lisp source block.")
 
 (declare-function org-babel-comint-with-output "ob-comint" (&rest body))
 (declare-function org-babel-comint-buffer-livep "ob-comint" (buffer))
@@ -57,8 +57,7 @@
 	(concat "(pp " body ")") body)))
 
 (defun org-babel-execute:emacs-lisp (body params)
-  "Execute a block of emacs-lisp code with org-babel."
-  (message "executing emacs-lisp code block...")
+  "Execute a block of emacs-lisp code with Babel."
   (save-window-excursion
     (let ((processed-params (org-babel-process-params params)))
       (org-babel-reassemble-table

lisp/ob-eval.el

@@ -32,18 +32,18 @@
 (eval-when-compile (require 'cl))
 
 (defun org-babel-eval-error-notify (exit-code stderr)
-  "Open a buffer containing information from STDERR with a
-message about the value of EXIT-CODE."
+  "Open a buffer to display STDERR and a message with the value of EXIT-CODE."
   (let ((buf (get-buffer-create "*Org-Babel Error Output*")))
     (with-current-buffer buf
       (goto-char (point-max))
       (save-excursion (insert stderr)))
     (display-buffer buf))
-  (message "Babel evaluation exited with code %d" exit-code))
+  (message "Babel evaluation exited with code %S" exit-code))
 
 (defun org-babel-eval (cmd body)
-  "Run CMD on BODY, if CMD succeeds then return it's results,
-otherwise display STDERR with `org-babel-eval-error-notify'."
+  "Run CMD on BODY.
+If CMD succeeds then return it's results, otherwise display
+STDERR with `org-babel-eval-error-notify'."
   (let ((err-buff (get-buffer-create "*Org-Babel Error*")) exit-code)
     (with-current-buffer err-buff (erase-buffer))
     (with-temp-buffer
@@ -51,7 +51,7 @@ otherwise display STDERR with `org-babel-eval-error-notify'."
       (setq exit-code
 	    (org-babel-shell-command-on-region
 	     (point-min) (point-max) cmd t 'replace err-buff))
-      (if (> exit-code 0)
+      (if (or (not (numberp exit-code)) (> exit-code 0))
 	  (progn
 	    (with-current-buffer err-buff
 	      (org-babel-eval-error-notify exit-code (buffer-string)))
@@ -67,7 +67,7 @@ otherwise display STDERR with `org-babel-eval-error-notify'."
 (defun org-babel-shell-command-on-region (start end command
 				      &optional output-buffer replace
 				      error-buffer display-error-buffer)
-  "Execute string COMMAND in inferior shell with region as input.
+  "Execute COMMAND in an inferior shell with region as input.
 
 Fixes bugs in the emacs 23.1.1 version of `shell-command-on-region'
 

lisp/ob-exp.el

@@ -47,8 +47,17 @@
 
 (org-export-blocks-add-block '(src org-babel-exp-src-blocks nil))
 
+(defcustom org-export-babel-evaluate t
+  "Switch controlling code evaluation during export.
+When set to nil no code will be exported as part of the export
+process."
+  :group 'org-babel
+  :type 'boolean)
+(put 'org-export-babel-evaluate 'safe-local-variable (lambda (x) (eq x nil)))
+
 (defvar org-babel-function-def-export-keyword "function"
-  "When exporting a source block function, this keyword will
+  "The keyword to substitute for the source name line on export.
+When exporting a source block function, this keyword will
 appear in the exported version in the place of source name
 line. A source block is considered to be a source block function
 if the source name is present and is followed by a parenthesized
@@ -62,14 +71,16 @@ whitespace. An example is the following which generates n random
 #+end_src")
 
 (defvar org-babel-function-def-export-indent 4
-  "When exporting a source block function, the block contents
-will be indented by this many characters. See
+  "Number of characters to indent a source block on export.
+When exporting a source block function, the block contents will
+be indented by this many characters. See
 `org-babel-function-def-export-name' for the definition of a
 source block function.")
 
 (defun org-babel-exp-src-blocks (body &rest headers)
-  "Process src block for export.  Depending on the 'export'
-headers argument in replace the source code block with...
+  "Process source block for export.
+Depending on the 'export' headers argument in replace the source
+code block with...
 
 both ---- display the code and the results
 
@@ -96,7 +107,7 @@ none ----- do not display either code or results upon export"
       (org-babel-exp-do-export info 'block))))
 
 (defun org-babel-exp-inline-src-blocks (start end)
-  "Process inline src blocks between START and END for export.
+  "Process inline source blocks between START and END for export.
 See `org-babel-exp-src-blocks' for export options, currently the
 options and are taken from `org-babel-default-inline-header-args'."
   (interactive)
@@ -122,23 +133,24 @@ options and are taken from `org-babel-default-inline-header-args'."
 	(replace-match replacement t t nil 1)))))
 
 (defun org-exp-res/src-name-cleanup ()
-  "Cleanup leftover #+results and #+srcname lines as part of the
-org export cycle.  This should only be called after all block
-processing has taken place."
+  "Clean up #+results and #+srcname lines for export.
+This function should only be called after all block processing
+has taken place."
   (interactive)
   (save-excursion
     (goto-char (point-min))
     (while (org-re-search-forward-unprotected
 	    (concat
-	     "\\("org-babel-source-name-regexp"\\|"org-babel-result-regexp"\\)")
+	     "\\("org-babel-src-name-regexp"\\|"org-babel-result-regexp"\\)")
 	    nil t)
       (delete-region
        (progn (beginning-of-line) (point))
        (progn (end-of-line) (+ 1 (point)))))))
 
 (defun org-babel-in-example-or-verbatim ()
-  "Return true if the point is currently in an escaped portion of
-an org-mode buffer code which should be treated as normal
+  "Return true if point is in example or verbatim code.
+Example and verbatim code include escaped portions of
+an org-mode buffer code that should be treated as normal
 org-mode text."
   (or (org-in-indented-comment-line) 
       (save-excursion
@@ -148,7 +160,7 @@ org-mode text."
       (org-in-regexps-block-p "^[ \t]*#\\+begin_src" "^[ \t]*#\\+end_src")))
 
 (defun org-babel-exp-lob-one-liners (start end)
-  "Process #+lob (Library of Babel) calls between START and END for export.
+  "Process Library of Babel calls between START and END for export.
 See `org-babel-exp-src-blocks' for export options. Currently the
 options are taken from `org-babel-default-header-args'."
   (interactive)
@@ -175,8 +187,8 @@ options are taken from `org-babel-default-header-args'."
 	(replace-match replacement t t)))))
 
 (defun org-babel-exp-do-export (info type)
-  "Return a string containing the exported content of the current
-code block respecting the value of the :exports header argument."
+  "Return a string with the exported content of a code block.
+The function respects the value of the :exports header argument."
   (flet ((silently () (let ((session (cdr (assoc :session (nth 2 info)))))
 			(when (and session
 				   (not (equal "none" session))
@@ -193,10 +205,10 @@ code block respecting the value of the :exports header argument."
 
 (defvar backend)
 (defun org-babel-exp-code (info type)
-  "Return the code the current code block in a manner suitable
-for exportation by org-mode.  This function is called by
-`org-babel-exp-do-export'.  The code block will not be
-evaluated."
+  "Prepare and return code in the current code block for export.
+Code is prepared in a manner suitable for exportat by
+org-mode.  This function is called by `org-babel-exp-do-export'.
+The code block is not evaluated."
   (let ((lang (nth 0 info))
         (body (nth 1 info))
         (switches (nth 3 info))
@@ -230,59 +242,67 @@ evaluated."
 	  ((format ": %s\n" call-line))))))))
 
 (defun org-babel-exp-results (info type &optional silent)
-  "Return the results of the current code block in a manner
-suitable for exportation by org-mode.  This function is called by
-`org-babel-exp-do-export'.  The code block will be evaluated.
-Optional argument SILENT can be used to inhibit insertion of
-results into the buffer."
-  (let ((lang (nth 0 info))
-	(body (nth 1 info))
-	(params
-	 ;; lets ensure that we lookup references in the original file
-	 (mapcar
-	  (lambda (pair)
-	    (if (and org-current-export-file
-		     (eq (car pair) :var)
-		     (string-match org-babel-ref-split-regexp (cdr pair))
-		     (equal :ob-must-be-reference
-			    (org-babel-ref-literal (match-string 2 (cdr pair)))))
-		`(:var . ,(concat (match-string 1 (cdr pair))
-				  "=" org-current-export-file
-				  ":" (match-string 2 (cdr pair))))
-	      pair))
-	  (nth 2 info))))
-    ;; skip code blocks which we can't evaluate
-    (when (fboundp (intern (concat "org-babel-execute:" lang)))
-      (case type
-	('inline
-	  (let ((raw (org-babel-execute-src-block
-		      nil info '((:results . "silent"))))
-		(result-params (split-string (cdr (assoc :results params)))))
-	    (unless silent
-	      (cond ;; respect the value of the :results header argument
-	       ((member "file" result-params)
-		(org-babel-result-to-file raw))
-	       ((or (member "raw" result-params) (member "org" result-params))
-		(format "%s" raw))
-	       ((member "code" result-params)
-		(format "src_%s{%s}" lang raw))
-	       (t
-		(if (stringp raw)
-		    (if (= 0 (length raw)) "=(no results)="
+  "Evaluate and return the results of the current code block for export.
+Results are prepared in a manner suitable for export by org-mode.
+This function is called by `org-babel-exp-do-export'.  The code
+block will be evaluated.  Optional argument SILENT can be used to
+inhibit insertion of results into the buffer."
+  (if org-export-babel-evaluate
+      (let ((lang (nth 0 info))
+	    (body (nth 1 info))
+	    (params
+	     ;; lets ensure that we lookup references in the original file
+	     (mapcar
+	      (lambda (pair)
+		(if (and org-current-export-file
+			 (eq (car pair) :var)
+			 (string-match org-babel-ref-split-regexp (cdr pair))
+			 (equal :ob-must-be-reference
+				(org-babel-ref-literal
+				 (match-string 2 (cdr pair)))))
+		    `(:var . ,(concat (match-string 1 (cdr pair))
+				      "=" org-current-export-file
+				      ":" (match-string 2 (cdr pair))))
+		  pair))
+	      (nth 2 info))))
+	;; skip code blocks which we can't evaluate
+	(if (fboundp (intern (concat "org-babel-execute:" lang)))
+	    (case type
+	      ('inline
+		(let ((raw (org-babel-execute-src-block
+			    nil info '((:results . "silent"))))
+		      (result-params (split-string
+				      (cdr (assoc :results params)))))
+		  (unless silent
+		    (cond ;; respect the value of the :results header argument
+		     ((member "file" result-params)
+		      (org-babel-result-to-file raw))
+		     ((or (member "raw" result-params)
+			  (member "org" result-params))
 		      (format "%s" raw))
-		  (format "%S" raw)))))))
-	('block
-	    (org-babel-execute-src-block
-	     nil info (org-babel-merge-params
-		       params `((:results . ,(if silent "silent" "replace")))))
-	  "")
-	('lob
-	 (save-excursion
-	   (re-search-backward org-babel-lob-one-liner-regexp nil t)
-	   (org-babel-execute-src-block
-	    nil info (org-babel-merge-params
-		      params `((:results . ,(if silent "silent" "replace")))))
-	   ""))))))
+		     ((member "code" result-params)
+		      (format "src_%s{%s}" lang raw))
+		     (t
+		      (if (stringp raw)
+			  (if (= 0 (length raw)) "=(no results)="
+			    (format "%s" raw))
+			(format "%S" raw)))))))
+	      ('block
+		  (org-babel-execute-src-block
+		   nil info (org-babel-merge-params
+			     params
+			     `((:results . ,(if silent "silent" "replace")))))
+		"")
+	      ('lob
+	       (save-excursion
+		 (re-search-backward org-babel-lob-one-liner-regexp nil t)
+		 (org-babel-execute-src-block
+		  nil info (org-babel-merge-params
+			    params
+			    `((:results . ,(if silent "silent" "replace")))))
+		 "")))
+	  ""))
+    ""))
 
 (provide 'ob-exp)
 

lisp/ob-gnuplot.el

@@ -58,8 +58,8 @@
 (defvar org-babel-gnuplot-timestamp-fmt nil)
 
 (defun org-babel-gnuplot-process-vars (params)
-  "Extract variables from PARAMS and process the variables
-dumping all vectors into files and returning an association list
+  "Extract variables from PARAMS and process the variables.
+Dumps all vectors into files and returns an association list
 of variable names and the related value to be used in the gnuplot
 code."
   (mapcar
@@ -130,9 +130,8 @@ code."
       body)))
 
 (defun org-babel-execute:gnuplot (body params)
-  "Execute a block of Gnuplot code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
-  (message "executing Gnuplot source code block")
+  "Execute a block of Gnuplot code.
+This function is called by `org-babel-execute-src-block'."
   (require 'gnuplot)
   (let ((session (cdr (assoc :session params)))
         (result-type (cdr (assoc :results params)))
@@ -158,7 +157,7 @@ called by `org-babel-execute-src-block'."
         out-file))))
 
 (defun org-babel-prep-session:gnuplot (session params)
-  "Prepare SESSION according to the header arguments specified in PARAMS."
+  "Prepare SESSION according to the header arguments in PARAMS."
   (let* ((session (org-babel-gnuplot-initiate-session session))
          (vars (org-babel-ref-variables params))
          (var-lines (mapcar
@@ -183,7 +182,8 @@ called by `org-babel-execute-src-block'."
 
 (defvar gnuplot-buffer)
 (defun org-babel-gnuplot-initiate-session (&optional session params)
-  "If there is not a current inferior-process-buffer in SESSION
+  "Initiate a gnuplot session.
+If there is not a current inferior-process-buffer in SESSION
 then create one.  Return the initialized session.  The current
 `gnuplot-mode' doesn't provide support for multiple sessions."
   (require 'gnuplot)
@@ -193,13 +193,13 @@ then create one.  Return the initialized session.  The current
       gnuplot-buffer)))
 
 (defun org-babel-gnuplot-quote-timestamp-field (s)
-  "Convert field S from timestamp to Unix time and export to gnuplot."
+  "Convert S from timestamp to Unix time and export to gnuplot."
   (format-time-string org-babel-gnuplot-timestamp-fmt (org-time-string-to-time s)))
 
 (defvar org-table-number-regexp)
 (defvar org-ts-regexp3)
 (defun org-babel-gnuplot-quote-tsv-field (s)
-  "Quote field S for export to gnuplot."
+  "Quote S for export to gnuplot."
   (unless (stringp s)
     (setq s (format "%s" s)))
   (if (string-match org-table-number-regexp s) s

lisp/ob-haskell.el

@@ -70,8 +70,7 @@
       vars "\n") "\n" body "\n")))
 
 (defun org-babel-execute:haskell (body params)
-  "Execute a block of Haskell code with org-babel."
-  (message "executing haskell source code block")
+  "Execute a block of Haskell code."
   (let* ((processed-params (org-babel-process-params params))
          (session (nth 0 processed-params))
          (vars (nth 1 processed-params))
@@ -104,7 +103,8 @@
     string))
 
 (defun org-babel-haskell-initiate-session (&optional session params)
-  "If there is not a current inferior-process-buffer in SESSION
+  "Initiate a haskell session.
+If there is not a current inferior-process-buffer in SESSION
 then create one.  Return the initialized session."
   (require 'inf-haskell)
   (or (get-buffer "*haskell*")
@@ -124,7 +124,7 @@ then create one.  Return the initialized session."
 
 (defun org-babel-prep-session:haskell
   (session params &optional processed-params)
-  "Prepare SESSION according to the header arguments specified in PARAMS."
+  "Prepare SESSION according to the header arguments in PARAMS."
   (save-window-excursion
     (let ((pp (or processed-params (org-babel-process-params params)))
 	  (buffer (org-babel-haskell-initiate-session session)))
@@ -139,7 +139,8 @@ then create one.  Return the initialized session."
       (current-buffer))))
 
 (defun org-babel-haskell-table-or-string (results)
-  "If the results look like a table, then convert them into an
+  "Convert RESULTS to an Emacs-lisp table or string.
+If RESULTS look like a table, then convert them into an
 Emacs-lisp table, otherwise return the results as a string."
   (org-babel-read
    (if (and (stringp results) (string-match "^\\[.+\\]$" results))
@@ -153,21 +154,22 @@ Emacs-lisp table, otherwise return the results as a string."
      results)))
 
 (defun org-babel-haskell-var-to-haskell (var)
-  "Convert an elisp var into a string of haskell source code
-specifying a var of the same value."
+  "Convert an elisp value VAR into a haskell variable.
+The elisp VAR is converted to a string of haskell source code
+specifying a variable of the same value."
   (if (listp var)
       (concat "[" (mapconcat #'org-babel-haskell-var-to-haskell var ", ") "]")
     (format "%S" var)))
 
 (defvar org-src-preserve-indentation)
 (defun org-babel-haskell-export-to-lhs (&optional arg)
-  "Export to a .lhs file with all haskell code blocks escaped
-appropriately.  When called with a prefix argument the resulting
+  "Export to a .lhs file with all haskell code blocks escaped.
+When called with a prefix argument the resulting
 .lhs file will be exported to a .tex file.  This function will
 create two new files, base-name.lhs and base-name.tex where
 base-name is the name of the current org-mode file.
 
-Note that all standard org-babel literate programming
+Note that all standard Babel literate programming
 constructs (header arguments, no-web syntax etc...) are ignored."
   (interactive "P")
   (let* ((contents (buffer-string))

lisp/ob-keys.el

@@ -33,31 +33,34 @@
 (require 'ob)
 
 (defvar org-babel-key-prefix "\C-c\C-v"
-  "The `org-babel-key-prefix' variable holds the key prefix
-behind which all org-babel interactive key-binding are placed.
+  "The key prefix for Babel interactive key-bindings.
 See `org-babel-key-bindings' for the list of interactive babel
 functions which are assigned key bindings, and see
 `org-babel-map' for the actual babel keymap.")
 
 (defvar org-babel-map (make-sparse-keymap)
-  "The keymap holding key bindings for interactive org-babel
-functions.")
+  "The keymap for interactive Babel functions.")
 
 ;;;###autoload
 (defun org-babel-describe-bindings ()
-  "Describe all key binding placed behind the
-`org-babel-key-prefix' prefix."
+  "Describe all keybindings behind `org-babel-key-prefix'."
   (interactive)
   (describe-bindings org-babel-key-prefix))
 
 (defvar org-babel-key-bindings
-  '(("e" . org-babel-execute-src-block)
+  '(("p" . org-babel-previous-src-block)
+    ("\C-p" . org-babel-previous-src-block)
+    ("n" . org-babel-next-src-block)
+    ("\C-n" . org-babel-next-src-block)
+    ("e" . org-babel-execute-src-block)
     ("\C-e" . org-babel-execute-src-block)
     ("o" . org-babel-open-src-block-result)
     ("\C-o" . org-babel-open-src-block-result)
-    ("\C-p" . org-babel-expand-src-block)
-    ("p" . org-babel-expand-src-block)
-    ("g" . org-babel-goto-named-source-block)
+    ("\C-v" . org-babel-expand-src-block)
+    ("v" . org-babel-expand-src-block)
+    ("g" . org-babel-goto-named-src-block)
+    ("r" . org-babel-goto-named-result)
+    ("\C-r" . org-babel-goto-named-result)
     ("\C-b" . org-babel-execute-buffer)
     ("b" . org-babel-execute-buffer)
     ("\C-s" . org-babel-execute-subtree)
@@ -73,8 +76,8 @@ functions.")
     ("\C-a" . org-babel-sha1-hash)
     ("a" . org-babel-sha1-hash)
     ("h" . org-babel-describe-bindings))
-  "Alist associating key bindings with interactive Org-babel
-functions.  This list associates interactive org-babel functions
+  "Alist of key bindings and interactive Babel functions.
+This list associates interactive Babel functions
 with keys.  Each element of this list will add an entry to the
 `org-babel-map' using the letter key which is the `car' of the
 a-list placed behind the generic `org-babel-key-prefix'.")

lisp/ob-latex.el

@@ -42,7 +42,7 @@
 
 (defvar org-babel-default-header-args:latex
   '((:results . "latex") (:exports . "results"))
-  "Default arguments to use when evaluating a latex source block.")
+  "Default arguments to use when evaluating a LaTeX source block.")
 
 (defun org-babel-expand-body:latex (body params &optional processed-params)
   "Expand BODY according to PARAMS, return the expanded body."
@@ -58,9 +58,8 @@
 (defvar org-format-latex-options)
 (defvar org-export-latex-packages-alist)
 (defun org-babel-execute:latex (body params)
-  "Execute a block of Latex code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
-  (message "executing Latex source code block")
+  "Execute a block of Latex code with Babel.
+This function is called by `org-babel-execute-src-block'."
   (setq body (org-babel-expand-body:latex body params))
   (if (cdr (assoc :file params))
       (let ((out-file (cdr (assoc :file params)))
@@ -90,8 +89,8 @@ called by `org-babel-execute-src-block'."
 (defvar org-export-latex-packages-alist)
 (defvar org-export-latex-default-packages-alist)
 (defun org-babel-latex-body-to-tex-file (tex-file body &optional height width)
-  "Place the contents of BODY into TEX-FILE. Extracted from
-`org-create-formula-image' in org.el."
+  "Place the contents of BODY into TEX-FILE.
+Extracted from `org-create-formula-image' in org.el."
   (with-temp-file tex-file
     (insert (org-splice-latex-header
 	       org-format-latex-header
@@ -115,8 +114,8 @@ called by `org-babel-execute-src-block'."
 (defvar org-latex-to-pdf-process)
 (defvar org-export-pdf-remove-logfiles)
 (defun org-babel-latex-tex-to-pdf (tex-file)
-  "Generate a pdf according to the contents TEX-FILE.  Extracted
-from `org-export-as-pdf' in org-latex.el."
+  "Generate a pdf file according to the contents TEX-FILE.
+Extracted from `org-export-as-pdf' in org-latex.el."
   (let* ((wconfig (current-window-configuration))
          (default-directory (file-name-directory tex-file))
          (base (file-name-sans-extension tex-file))
@@ -149,8 +148,8 @@ from `org-export-as-pdf' in org-latex.el."
       pdffile)))
 
 (defun org-babel-prep-session:latex (session params)
-  "Create a session named SESSION according to PARAMS."
-  (error "Latex does not support sessions"))
+  "Return an error because LaTeX doesn't support sesstions."
+  (error "LaTeX does not support sessions"))
 
 (provide 'ob-latex)
 

lisp/ob-lob.el

@@ -33,12 +33,13 @@
 (require 'ob-table)
 
 (defvar org-babel-library-of-babel nil
-  "Library of source-code blocks.  This is an association list.
-Populate the library by adding files to `org-babel-lob-files'.")
+  "Library of source-code blocks.
+This is an association list.  Populate the library by adding
+files to `org-babel-lob-files'.")
 
 (defcustom org-babel-lob-files '()
-  "Files used to populate the `org-babel-library-of-babel'.  To
-add files to this list use the `org-babel-lob-ingest' command."
+  "Files used to populate the `org-babel-library-of-babel'.
+To add files to this list use the `org-babel-lob-ingest' command."
   :group 'org-babel
   :type 'list)
 
@@ -46,7 +47,7 @@ add files to this list use the `org-babel-lob-ingest' command."
 (defun org-babel-lob-ingest (&optional file)
   "Add all source-blocks defined in FILE to `org-babel-library-of-babel'."
   (interactive "f")
-  (org-babel-map-source-blocks file
+  (org-babel-map-src-blocks file
     (let* ((info (org-babel-get-src-block-info))
 	   (source-name (intern (nth 4 info))))
       (when source-name
@@ -55,23 +56,22 @@ add files to this list use the `org-babel-lob-ingest' command."
                     (assq-delete-all source-name org-babel-library-of-babel)))))))
 
 (defconst org-babel-lob-call-aliases '("lob" "call")
-  "These can be used interchangeably to call a source block
-  function. If you change the value of this variable then your
-  files may become unusable by other org-babel users, and vice
-  versa.")
+  "Aliases to call a source block function.
+If you change the value of this variable then your files may
+  become unusable by other org-babel users, and vice versa.")
 
 (defconst org-babel-lob-one-liner-regexp
   (concat "^\\([ \t]*\\)#\\+\\(?:"
 	  (mapconcat #'regexp-quote org-babel-lob-call-aliases "\\|")
 	  "\\):[ \t]+\\([^\(\)\n]+\\)\(\\([^\n]*\\)\)[ \t]*\\([^\n]*\\)")
-  "Regexp to match calls to predefined source block functions")
+  "Regexp to match calls to predefined source block functions.")
 
 ;; functions for executing lob one-liners
 ;;;###autoload
 (defun org-babel-lob-execute-maybe ()
-  "Detect if this is context for a org-babel Library Of Babel
-src-block and if so then run the appropriate source block from
-the Library."
+  "Execute a Library of Babel source block, if appropriate.
+Detect if this is context for a Library Of Babel source block and
+if so then run the appropriate source block from the Library."
   (interactive)
   (let ((info (org-babel-lob-get-info)))
     (if (nth 0 info) (progn (org-babel-lob-execute info) t) nil)))
@@ -80,8 +80,7 @@ the Library."
 
 ;;;###autoload
 (defun org-babel-lob-get-info ()
-  "Return the function call supplied on the current Library of
-Babel line as a string.
+  "Return a Library of Babel function call as a string.
 
 This function is analogous to org-babel-get-src-block-name. For
 both functions, after they are called, (match-string 1) matches

lisp/ob-mscgen.el

@@ -66,11 +66,10 @@
   "Expand BODY according to PARAMS, return the expanded body." body)
 
 (defun org-babel-execute:mscgen (body params)
-  "Execute a block of Mscgen code with org-babel.  This function
-is called by `org-babel-execute-src-block'.  Default filetype is
-png. Modify by setting :filetype parameter to mscgen supported
-formats."
-  (message "executing Mscgen source code block")
+  "Execute a block of Mscgen code with Babel.
+This function is called by `org-babel-execute-src-block'.
+Default filetype is png. Modify by setting :filetype parameter to
+mscgen supported formats."
   (let* ((out-file (or (cdr (assoc :file params)) "output.png" ))
          (filetype (or (cdr (assoc :filetype params)) "png" )))
     (unless (cdr (assoc :file params))
@@ -80,7 +79,7 @@ ERROR: no output file specified. Add \":file name.png\" to the src header"))
     out-file))
 
 (defun org-babel-prep-session:mscgen (session params)
-  "Prepare SESSION according to PARAMS."
+  "Raise an error because Mscgen doesn't support sessions."
   (error "Mscgen does not support sessions"))
 
 (provide 'ob-mscgen)

lisp/ob-ocaml.el

@@ -59,8 +59,7 @@
       vars "\n") "\n" body "\n")))
 
 (defun org-babel-execute:ocaml (body params)
-  "Execute a block of Ocaml code with org-babel."
-  (message "executing ocaml source code block")
+  "Execute a block of Ocaml code with Babel."
   (let* ((processed-params (org-babel-process-params params))
          (vars (nth 1 processed-params))
          (full-body (org-babel-expand-body:ocaml body params processed-params))
@@ -79,7 +78,7 @@
 
 (defvar tuareg-interactive-buffer-name)
 (defun org-babel-prep-session:ocaml (session params)
-  "Prepare SESSION according to the header arguments specified in PARAMS."
+  "Prepare SESSION according to the header arguments in PARAMS."
   (require 'tuareg)
   (let ((tuareg-interactive-buffer-name (if (and (not (string= session "none"))
                                                  (not (string= session "default"))
@@ -90,8 +89,8 @@
                            (get-buffer tuareg-interactive-buffer-name))))
 
 (defun org-babel-ocaml-parse-output (output)
-  "Parse OUTPUT where OUTPUT is string output from an ocaml
-process."
+  "Parse OUTPUT.
+OUTPUT is string output from an ocaml process."
   (let ((regexp "%s = \\(.+\\)$"))
     (cond
      ((string-match (format regexp "string") output)
@@ -106,7 +105,8 @@ process."
      (t (message "don't recognize type of %s" output) output))))
 
 (defun org-babel-ocaml-read-list (results)
-  "If the results look like a table, then convert them into an
+  "Convert RESULTS into an elisp table or string.
+If the results look like a table, then convert them into an
 Emacs-lisp table, otherwise return the results as a string."
   (org-babel-read
    (if (and (stringp results) (string-match "^\\[.+\\]$" results))
@@ -119,7 +119,8 @@ Emacs-lisp table, otherwise return the results as a string."
      results)))
 
 (defun org-babel-ocaml-read-array (results)
-  "If the results look like a table, then convert them into an
+  "Convert RESULTS into an elisp table or string.
+If the results look like a table, then convert them into an
 Emacs-lisp table, otherwise return the results as a string."
   (org-babel-read
    (if (and (stringp results) (string-match "^\\[.+\\]$" results))

lisp/ob-octave.el

@@ -43,9 +43,9 @@
 (defvar org-babel-default-header-args:octave '())
 
 (defvar org-babel-matlab-shell-command "matlab -nosplash"
-  "Shell command to use to run matlab as an external process.")
+  "Shell command to run matlab as an external process.")
 (defvar org-babel-octave-shell-command "octave -q"
-  "Shell command to use to run octave as an external process.")
+  "Shell command to run octave as an external process.")
 
 (defun org-babel-expand-body:matlab (body params &optional processed-params)
   "Expand BODY according to PARAMS, return the expanded body."
@@ -62,9 +62,9 @@
       vars "\n") "\n" body "\n")))
 
 (defvar org-babel-matlab-with-emacs-link nil
-  "If non-nil use matlab-shell-run-region for session
-  evaluation. This will use EmacsLink if (matlab-with-emacs-link)
-  evaluates to a non-nil value.")
+  "If non-nil use matlab-shell-run-region for session evaluation.
+  This will use EmacsLink if (matlab-with-emacs-link) evaluates
+  to a non-nil value.")
 
 (defvar org-babel-matlab-emacs-link-wrapper-method
    "%s
@@ -84,12 +84,11 @@ end")
 (defvar org-babel-octave-eoe-output "ans = org_babel_eoe")
 
 (defun org-babel-execute:matlab (body params)
-  "Execute a block of matlab code with org-babel."
+  "Execute a block of matlab code with Babel."
   (require 'matlab)
   (org-babel-execute:octave body params 'matlab))
 (defun org-babel-execute:octave (body params &optional matlabp)
-  "Execute a block of octave code with org-babel."
-  (message "executing %s source code block" (if matlabp "matlab" "octave"))
+  "Execute a block of octave code with Babel."
   (let* ((processed-params (org-babel-process-params params))
          (session
 	  (funcall (intern (format "org-babel-%s-initiate-session"
@@ -116,7 +115,7 @@ end")
   (require 'matlab)
   (org-babel-prep-session:octave session params 'matlab))
 (defun org-babel-octave-var-to-octave (var)
-  "Convert an emacs-lisp variable into an octave variable.
+  "Convert an emacs-lisp value into an octave variable.
 Converts an emacs-lisp variable into a string of octave code
 specifying a variable of the same value."
   (if (listp var)
@@ -140,15 +139,15 @@ specifying a variable of the same value."
     session))
 
 (defun org-babel-matlab-initiate-session (&optional session params)
-  "Create a matlab inferior process buffer.  If there is not a
-current inferior-process-buffer in SESSION then create. Return
-the initialized session."
+  "Create a matlab inferior process buffer.
+If there is not a current inferior-process-buffer in SESSION then
+create. Return the initialized session."
   (require 'matlab)
   (org-babel-octave-initiate-session session params 'matlab))
 (defun org-babel-octave-initiate-session (&optional session params matlabp)
-  "Create an octave inferior process buffer.  If there is not a
-current inferior-process-buffer in SESSION then create. Return
-the initialized session."
+  "Create an octave inferior process buffer.
+If there is not a current inferior-process-buffer in SESSION then
+create. Return the initialized session."
   (require 'octave-inf)
   (unless (string= session "none")
     (let ((session (or session
@@ -163,10 +162,10 @@ the initialized session."
 
 (defun org-babel-octave-evaluate
   (session body result-type lang &optional matlabp)
-  "Pass BODY to the octave process in SESSION.  If RESULT-TYPE
-equals 'output then return the outputs of the statements in BODY,
-if RESULT-TYPE equals 'value then return the value of the last
-statement in BODY, as elisp."
+  "Pass BODY to the octave process in SESSION.
+If RESULT-TYPE equals 'output then return the outputs of the
+statements in BODY, if RESULT-TYPE equals 'value then return the
+value of the last statement in BODY, as elisp."
   (if session
       (org-babel-octave-evaluate-session session body result-type matlabp)
     (org-babel-octave-evaluate-external-process body result-type matlabp)))
@@ -242,8 +241,9 @@ statement in BODY, as elisp."
 	 (mapconcat #'identity (reverse results) "\n"))))))
 
 (defun org-babel-octave-import-elisp-from-file (file-name)
-  "Import data from FILE-NAME.  This removes initial blank and
-comment lines and then calls `org-babel-import-elisp-from-file'."
+  "Import data from FILE-NAME.
+This removes initial blank and comment lines and then calls
+`org-babel-import-elisp-from-file'."
   (let ((temp-file (make-temp-file "org-babel-results-")) beg end)
     (with-temp-file temp-file
       (insert-file-contents file-name)

lisp/ob-perl.el

@@ -50,9 +50,8 @@
       vars "\n") "\n" (org-babel-trim body) "\n")))
 
 (defun org-babel-execute:perl (body params)
-  "Execute a block of Perl code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
-  (message "executing Perl source code block")
+  "Execute a block of Perl code with Babel.
+This function is called by `org-babel-execute-src-block'."
   (let* ((processed-params (org-babel-process-params params))
          (session (nth 0 processed-params))
          (vars (nth 1 processed-params))
@@ -69,13 +68,14 @@ called by `org-babel-execute-src-block'."
       (nth 5 processed-params) (cdr (assoc :rownames params))))))
 
 (defun org-babel-prep-session:perl (session params)
-  "Prepare SESSION according to the header arguments specified in PARAMS."
+  "Prepare SESSION according to the header arguments in PARAMS."
   (error "Sessions are not supported for Perl."))
 
 ;; helper functions
 
 (defun org-babel-perl-var-to-perl (var)
-  "Convert an elisp var into a string of perl source code
+  "Convert an elisp value to a perl variable.
+The elisp value, VAR, is converted to a string of perl source code
 specifying a var of the same value."
   (if (listp var)
       (concat "[" (mapconcat #'org-babel-perl-var-to-perl var ", ") "]")
@@ -84,7 +84,7 @@ specifying a var of the same value."
 (defvar org-babel-perl-buffers '(:default . nil))
 
 (defun org-babel-perl-initiate-session (&optional session params)
-  "Simply return nil, as sessions are not supported by perl"
+  "Return nil because sessions are not supported by perl"
 nil)
 
 (defvar org-babel-perl-wrapper-method
@@ -100,10 +100,10 @@ print o join(\"\\n\", @r), \"\\n\"")
   nil)
 
 (defun org-babel-perl-evaluate (session body &optional result-type)
-  "Pass BODY to the Perl process in SESSION.  If RESULT-TYPE equals
-'output then return a list of the outputs of the statements in
-BODY, if RESULT-TYPE equals 'value then return the value of the
-last statement in BODY, as elisp."
+  "Pass BODY to the Perl process in SESSION.
+If RESULT-TYPE equals 'output then return a list of the outputs
+of the statements in BODY, if RESULT-TYPE equals 'value then
+return the value of the last statement in BODY, as elisp."
   (when session (error "Sessions are not supported for Perl."))
   (case result-type
     (output (org-babel-eval org-babel-perl-command body))

lisp/ob-python.el

@@ -31,17 +31,21 @@
 (require 'ob-ref)
 (require 'ob-comint)
 (require 'ob-eval)
-(require (if (featurep 'xemacs) 'python-mode 'python))
 (eval-when-compile (require 'cl))
 
 (declare-function org-remove-indentation "org" )
+(declare-function py-shell "ext:python-mode" (&optional argprompt))
+(declare-function run-python "ext:python" (&optional cmd noshow new))
 
 (add-to-list 'org-babel-tangle-lang-exts '("python" . "py"))
 
 (defvar org-babel-default-header-args:python '())
 
 (defvar org-babel-python-command "python"
-  "Name of command to use for executing python code.")
+  "Name of command for executing python code.")
+
+(defvar org-babel-python-mode (if (featurep 'xemacs) 'python-mode 'python)
+  "Preferred python mode for use in running python interactively.")
 
 (defun org-babel-expand-body:python (body params &optional processed-params)
   "Expand BODY according to PARAMS, return the expanded body."
@@ -55,9 +59,8 @@
    "\n" (org-babel-trim body) "\n"))
 
 (defun org-babel-execute:python (body params)
-  "Execute a block of Python code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
-  (message "executing Python source code block")
+  "Execute a block of Python code with Babel.
+This function is called by `org-babel-execute-src-block'."
   (let* ((processed-params (org-babel-process-params params))
          (session (org-babel-python-initiate-session (first processed-params)))
          (result-params (nth 2 processed-params))
@@ -75,7 +78,7 @@ called by `org-babel-execute-src-block'."
 			      (cdr (assoc :rownames params)))))))
 
 (defun org-babel-prep-session:python (session params)
-  "Prepare SESSION according to the header arguments specified in PARAMS."
+  "Prepare SESSION according to the header arguments in PARAMS."
   (let* ((session (org-babel-python-initiate-session session))
          (vars (org-babel-ref-variables params))
          (var-lines (mapcar ;; define any variables
@@ -102,14 +105,20 @@ called by `org-babel-execute-src-block'."
 ;; helper functions
 
 (defun org-babel-python-var-to-python (var)
-  "Convert an elisp var into a string of python source code
-specifying a var of the same value."
+  "Convert an elisp value to a python variable.
+Convert an elisp value, VAR, into a string of python source code
+specifying a variable of the same value."
   (if (listp var)
       (concat "[" (mapconcat #'org-babel-python-var-to-python var ", ") "]")
-    (if (equal var 'hline) "None" (format "%S" var))))
+    (if (equal var 'hline)
+	"None"
+      (format
+       (if (and (stringp var) (string-match "[\n\r]" var)) "\"\"%S\"\"" "%S")
+       var))))
 
 (defun org-babel-python-table-or-string (results)
-  "If the results look like a list or tuple, then convert them into an
+  "Convert RESULTS into an appropriate elisp value.
+If the results look like a list or tuple, then convert them into an
 Emacs-lisp table, otherwise return the results as a string."
   ((lambda (res)
      (if (listp res)
@@ -134,15 +143,19 @@ Emacs-lisp table, otherwise return the results as a string."
   (cdr (assoc session org-babel-python-buffers)))
 
 (defun org-babel-python-initiate-session-by-key (&optional session)
-  "If there is not a current inferior-process-buffer in SESSION
+  "Initiate a python session.
+If there is not a current inferior-process-buffer in SESSION
 then create.  Return the initialized session."
+  (require org-babel-python-mode)
   (save-window-excursion
     (let* ((session (if session (intern session) :default))
            (python-buffer (org-babel-python-session-buffer session)))
       (cond
-       ((fboundp 'run-python) ; python.el
+       ((and (equal 'python org-babel-python-mode)
+	     (fboundp 'run-python)) ; python.el
 	(run-python))
-       ((fboundp 'py-shell) ; python-mode.el
+       ((and (equal 'python-mode org-babel-python-mode)
+	     (fboundp 'py-shell)) ; python-mode.el
 	;; `py-shell' creates a buffer whose name is the value of
 	;; `py-which-bufname' with '*'s at the beginning and end
 	(let* ((bufname (if python-buffer
@@ -166,7 +179,7 @@ then create.  Return the initialized session."
      (org-babel-python-initiate-session-by-key session))))
 
 (defvar org-babel-python-eoe-indicator "'org_babel_python_eoe'"
-  "Used to indicate that evaluation is has completed.")
+  "A string to indicate that evaluation has completed.")
 (defvar org-babel-python-wrapper-method
   "
 def main():
@@ -183,10 +196,10 @@ open('%s', 'w').write( pprint.pformat(main()) )")
 
 (defun org-babel-python-evaluate
   (buffer body &optional result-type result-params)
-  "Pass BODY to the Python process in BUFFER.  If RESULT-TYPE equals
-'output then return a list of the outputs of the statements in
-BODY, if RESULT-TYPE equals 'value then return the value of the
-last statement in BODY, as elisp."
+  "Pass BODY to the Python process in BUFFER.
+If RESULT-TYPE equals 'output then return a list of the outputs
+of the statements in BODY, if RESULT-TYPE equals 'value then
+return the value of the last statement in BODY, as elisp."
   (if (not buffer)
       ;; external process evaluation
       (case result-type

lisp/ob-ref.el

@@ -57,8 +57,9 @@
 (declare-function org-at-table-p "org" (&optional table-type))
 
 (defun org-babel-ref-variables (params)
-  "Takes a parameter alist, and return an alist of variable
-names, and the emacs-lisp representation of the related value."
+  "Convert PARAMS to variable names and values.
+Takes a parameter alist, and return an alist of variable names,
+and the emacs-lisp representation of the related value."
   (let ((assignments
 	 (delq nil (mapcar (lambda (pair) (if (eq (car pair) :var) (cdr pair))) params)))
 	(others
@@ -69,13 +70,14 @@ names, and the emacs-lisp representation of the related value."
   "[ \f\t\n\r\v]*\\(.+?\\)[ \f\t\n\r\v]*=[ \f\t\n\r\v]*\\(.+\\)[ \f\t\n\r\v]*")
 
 (defun org-babel-ref-parse (assignment &optional params)
-  "Parse a variable ASSIGNMENT in a header argument.  If the
-right hand side of the assignment has a literal value return that
-value, otherwise interpret as a reference to an external resource
-and find it's value using `org-babel-ref-resolve-reference'.
-Return a list with two elements.  The first element of the list
-will be the name of the variable, and the second will be an
-emacs-lisp representation of the value of the variable."
+  "Parse a variable ASSIGNMENT in a header argument.
+If the right hand side of the assignment has a literal value
+return that value, otherwise interpret as a reference to an
+external resource and find it's value using
+`org-babel-ref-resolve-reference'.  Return a list with two
+elements.  The first element of the list will be the name of the
+variable, and the second will be an emacs-lisp representation of
+the value of the variable."
   (if (string-match org-babel-ref-split-regexp assignment)
       (let ((var (match-string 1 assignment))
             (ref (match-string 2 assignment)))
@@ -86,7 +88,8 @@ emacs-lisp representation of the value of the variable."
 		   val)) (org-babel-ref-literal ref))))))
 
 (defun org-babel-ref-literal (ref)
-  "Determine if the right side of a header argument variable
+  "Return the value of REF if it is a literal value.
+Determine if the right side of a header argument variable
 assignment is a literal value or is a reference to some external
 resource.  REF should be a string of the right hand side of the
 assignment.  If REF is literal then return it's value, otherwise
@@ -134,7 +137,7 @@ return nil."
 	(goto-char (point-min))
 	(if (let ((result_regexp (concat "^[ \t]*#\\+\\(TBLNAME\\|RESNAME\\|RESULTS\\):[ \t]*"
 					 (regexp-quote ref) "[ \t]*$"))
-		  (regexp (concat org-babel-source-name-regexp
+		  (regexp (concat org-babel-src-name-regexp
 				  (regexp-quote ref) "\\(\(.*\)\\)?" "[ \t]*$")))
 	      ;; goto ref in the current buffer
 	      (or (and (not args)
@@ -173,29 +176,37 @@ return nil."
 	    result))))))
 
 (defun 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."
-  (if (string-match "^,?\\([^,]+\\)" index)
-      (let ((length (length lis))
+  "Return the subset of LIS indexed by INDEX.
+
+Indices are 0 based and negative indices count from the end of
+LIS, so 0 references the first element of LIS and -1 references
+the last.  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, two
+integers separated by a \":\" in which case the entire range is
+returned, or an empty string or \"*\" both of which are
+interpreted to mean the entire range and as such are equivalent
+to \"0:-1\"."
+  (if (and (> (length index) 0) (string-match "^\\([^,]*\\),?" index))
+      (let ((ind-re "\\(\\([-[:digit:]]+\\):\\([-[:digit:]]+\\)\\|\*\\)")
+	    (length (length lis))
             (portion (match-string 1 index))
             (remainder (substring index (match-end 0))))
         (flet ((wrap (num) (if (< num 0) (+ length num) num))
-               (open (lis) (if (and (listp lis) (= (length lis) 1)) (car lis) lis)))
+               (open (ls) (if (and (listp ls) (= (length ls) 1)) (car ls) ls)))
           (open
            (mapcar
             (lambda (sub-lis) (org-babel-ref-index-list remainder sub-lis))
-            (if (string-match "\\(\\([-[:digit:]]+\\):\\([-[:digit:]]+\\)\\|\*\\)"
-                              portion)
-                (mapcar (lambda (n) (nth n lis))
-                        (apply 'number-sequence
-                               (if (match-string 2 portion)
-                                   (list
-                                    (wrap (string-to-number (match-string 2 portion)))
-                                    (wrap (string-to-number (match-string 3 portion))))
-                                 (list (wrap 0) (wrap -1)))))
+            (if (or (= 0 (length portion)) (string-match ind-re portion))
+                (mapcar
+		 (lambda (n) (nth n lis))
+		 (apply 'number-sequence
+			(if (and (> (length portion) 0) (match-string 2 portion))
+			    (list
+			     (wrap (string-to-number (match-string 2 portion)))
+			     (wrap (string-to-number (match-string 3 portion))))
+			  (list (wrap 0) (wrap -1)))))
               (list (nth (wrap (string-to-number portion)) lis)))))))
     lis))
 
@@ -218,9 +229,9 @@ which case the entire range is returned."
 
 (defvar org-bracket-link-regexp)
 (defun org-babel-ref-at-ref-p ()
-  "Return the type of reference located at point or nil if none
-of the supported reference types are found.  Supported reference
-types are tables and source blocks."
+  "Return the type of reference located at point.
+Return nil if none of the supported reference types are found.
+Supported reference types are tables and source blocks."
   (cond ((org-at-table-p) 'table)
         ((looking-at "^[ \t]*#\\+BEGIN_SRC") 'source-block)
         ((looking-at org-bracket-link-regexp) 'file)

lisp/ob-ruby.el

@@ -65,9 +65,8 @@
       vars "\n") "\n" body "\n")))
 
 (defun org-babel-execute:ruby (body params)
-  "Execute a block of Ruby code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
-  (message "executing Ruby source code block")
+  "Execute a block of Ruby code with Babel.
+This function is called by `org-babel-execute-src-block'."
   (let* ((processed-params (org-babel-process-params params))
          (session (org-babel-ruby-initiate-session (first processed-params)))
          (result-params (nth 2 processed-params))
@@ -115,14 +114,16 @@ called by `org-babel-execute-src-block'."
 ;; helper functions
 
 (defun org-babel-ruby-var-to-ruby (var)
-  "Convert an elisp var into a string of ruby source code
-specifying a var of the same value."
+  "Convert VAR into a ruby variable.
+Convert an elisp value into a string of ruby source code
+specifying a variable of the same value."
   (if (listp var)
       (concat "[" (mapconcat #'org-babel-ruby-var-to-ruby var ", ") "]")
     (format "%S" var)))
 
 (defun org-babel-ruby-table-or-string (results)
-  "If RESULTS look like a table, then convert them into an
+  "Convert RESULTS into an appropriate elisp value.
+If RESULTS look like a table, then convert them into an
 Emacs-lisp table, otherwise return the results as a string."
   (org-babel-read
    (if (and (stringp results) (string-match "^\\[.+\\]$" results))
@@ -136,7 +137,8 @@ Emacs-lisp table, otherwise return the results as a string."
      results)))
 
 (defun org-babel-ruby-initiate-session (&optional session params)
-  "If there is not a current inferior-process-buffer in SESSION
+  "Initiate a ruby session.
+If there is not a current inferior-process-buffer in SESSION
 then create one.  Return the initialized session."
   (require 'inf-ruby)
   (unless (string= session "none")
@@ -148,7 +150,7 @@ then create one.  Return the initialized session."
         (org-babel-ruby-initiate-session session)))))
 
 (defvar org-babel-ruby-eoe-indicator ":org_babel_ruby_eoe"
-  "Used to indicate that evaluation is has completed.")
+  "String to indicate that evaluation has completed.")
 (defvar org-babel-ruby-f-write
   "File.open('%s','w'){|f| f.write((_.class == String) ? _ : _.inspect)}")
 (defvar org-babel-ruby-pp-f-write
@@ -176,10 +178,10 @@ end
 
 (defun org-babel-ruby-evaluate
   (buffer body &optional result-type result-params)
-  "Pass BODY to the Ruby process in BUFFER.  If RESULT-TYPE equals
-'output then return a list of the outputs of the statements in
-BODY, if RESULT-TYPE equals 'value then return the value of the
-last statement in BODY, as elisp."
+  "Pass BODY to the Ruby process in BUFFER.
+If RESULT-TYPE equals 'output then return a list of the outputs
+of the statements in BODY, if RESULT-TYPE equals 'value then
+return the value of the last statement in BODY, as elisp."
   (if (not buffer)
       ;; external process evaluation
       (case result-type

lisp/ob-sass.el

@@ -47,9 +47,8 @@
   "Expand BODY according to PARAMS, return the expanded body." body)
 
 (defun org-babel-execute:sass (body params)
-  "Execute a block of Sass code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
-  (message "executing Sass source code block")
+  "Execute a block of Sass code with Babel.
+This function is called by `org-babel-execute-src-block'."
   (let* ((result-params (split-string (or (cdr (assoc :results params)) "")))
          (file (cdr (assoc :file params)))
          (out-file (or file (make-temp-file "org-babel-sass-out")))
@@ -61,7 +60,7 @@ called by `org-babel-execute-src-block'."
     (or file (with-temp-buffer (insert-file-contents out-file) (buffer-string)))))
 
 (defun org-babel-prep-session:sass (session params)
-  "This function does nothing as sass does not support sessions."
+  "Raise an error because sass does not support sessions."
   (error "Sass does not support sessions"))
 
 (provide 'ob-sass)

lisp/ob-screen.el

@@ -49,7 +49,7 @@ In case you want to use a different screen than one selected by your $PATH")
   "Expand BODY according to PARAMS, return the expanded body." body)
 
 (defun org-babel-execute:screen (body params)
-  "Send a block of code via screen to a terminal using org-babel.
+  "Send a block of code via screen to a terminal using Babel.
 \"default\" session is be used when none is specified."
   (message "Sending source code block to interactive terminal session...")
   (save-window-excursion
@@ -82,7 +82,7 @@ In case you want to use a different screen than one selected by your $PATH")
 ;; helper functions
 
 (defun org-babel-screen-session-execute-string (session body)
-  "If SESSION exist, send BODY to it."
+  "If SESSION exists, send BODY to it."
   (let ((socket (org-babel-screen-session-socketname session)))
     (when socket
       (let ((tmpfile (org-babel-screen-session-write-temp-file session body)))
@@ -93,7 +93,7 @@ In case you want to use a different screen than one selected by your $PATH")
                       "paste z"))))))
 
 (defun org-babel-screen-session-socketname (session)
-  "Check if SESSION exist by parsing output of \"screen -ls\"."
+  "Check if SESSION exists by parsing output of \"screen -ls\"."
   (let* ((screen-ls (shell-command-to-string "screen -ls"))
          (sockets (delq
 		   nil
@@ -125,8 +125,8 @@ In case you want to use a different screen than one selected by your $PATH")
     tmpfile))
 
 (defun org-babel-screen-test ()
-  "Test if the default setup works.  The terminal should shortly
-flicker."
+  "Test if the default setup works.
+The terminal should shortly flicker."
   (interactive)
   (let* ((session "org-babel-testing")
          (random-string (format "%s" (random 99999)))

lisp/ob-sh.el

@@ -43,8 +43,8 @@
 (defvar org-babel-default-header-args:sh '())
 
 (defvar org-babel-sh-command "sh"
-  "Command used to invoke a shell.  This will be passed to
-  `shell-command-on-region'")
+  "Command used to invoke a shell.
+This will be passed to  `shell-command-on-region'")
 
 (defun org-babel-expand-body:sh (body params &optional processed-params)
   "Expand BODY according to PARAMS, return the expanded body."
@@ -59,18 +59,19 @@
     vars "\n") "\n" body "\n\n")))
 
 (defun org-babel-execute:sh (body params)
-  "Execute a block of Shell commands with org-babel.  This
-function is called by `org-babel-execute-src-block'."
-  (message "executing Shell source code block")
+  "Execute a block of Shell commands with Babel.
+This function is called by `org-babel-execute-src-block'."
   (let* ((processed-params (org-babel-process-params params))
          (session (org-babel-sh-initiate-session (nth 0 processed-params)))
          (result-params (nth 2 processed-params)) 
          (full-body (org-babel-expand-body:sh
-                     body params processed-params))) ;; then the source block body
+                     body params processed-params)))
     (org-babel-reassemble-table
      (org-babel-sh-evaluate session full-body result-params)
-     (org-babel-pick-name (nth 4 processed-params) (cdr (assoc :colnames params)))
-     (org-babel-pick-name (nth 5 processed-params) (cdr (assoc :rownames params))))))
+     (org-babel-pick-name
+      (nth 4 processed-params) (cdr (assoc :colnames params)))
+     (org-babel-pick-name
+      (nth 5 processed-params) (cdr (assoc :rownames params))))))
 
 (defun org-babel-prep-session:sh (session params)
   "Prepare SESSION according to the header arguments specified in PARAMS."
@@ -101,19 +102,26 @@ function is called by `org-babel-execute-src-block'."
 ;; helper functions
 
 (defun org-babel-sh-var-to-sh (var &optional sep)
-  "Convert an elisp var into a string of shell commands
-specifying a var of the same value."
+  "Convert an elisp value to a shell variable.
+Convert an elisp var into a string of shell commands specifying a
+var of the same value."
   (if (listp var)
       (flet ((deep-string (el)
                           (if (listp el)
                               (mapcar #'deep-string el)
-                           (org-babel-sh-var-to-sh el sep))))
-       (format "$(cat <<BABEL_TABLE\n%s\nBABEL_TABLE\n)"
-                (orgtbl-to-generic (deep-string var) (list :sep (or sep "\t")))))
-    (if (stringp var) (format "%s" var) (format "%S" var))))
+			    (org-babel-sh-var-to-sh el sep))))
+	(format "$(cat <<BABEL_TABLE\n%s\nBABEL_TABLE\n)"
+		(orgtbl-to-generic
+		 (deep-string var) (list :sep (or sep "\t")))))
+    (if (stringp var)
+	(if (string-match "[\n\r]" var)
+	    (format "$(cat <<BABEL_STRING\n%s\nBABEL_STRING\n)" var)
+	  (format "%s" var))
+      (format "%S" var))))
 
 (defun org-babel-sh-table-or-results (results)
-  "If the results look like a table, then convert them into an
+  "Convert RESULTS to an appropriate elisp value.
+If the results look like a table, then convert them into an
 Emacs-lisp table, otherwise return the results as a string."
   (org-babel-read
    (if (string-match "^\\[.+\\]$" results)
@@ -134,19 +142,19 @@ Emacs-lisp table, otherwise return the results as a string."
           (progn (shell session) (get-buffer (current-buffer)))))))
 
 (defvar org-babel-sh-eoe-indicator "echo 'org_babel_sh_eoe'"
-  "Used to indicate that evaluation is has completed.")
+  "String to indicate that evaluation has completed.")
 (defvar org-babel-sh-eoe-output "org_babel_sh_eoe"
-  "Used to indicate that evaluation is has completed.")
+  "String to indicate that evaluation has completed.")
 
 (defun org-babel-sh-evaluate (session body &optional result-params)
-  "Pass BODY to the Shell process in BUFFER.  If RESULT-TYPE equals
-'output then return a list of the outputs of the statements in
-BODY, if RESULT-TYPE equals 'value then return the value of the
-last statement in BODY."
+  "Pass BODY to the Shell process in BUFFER.
+If RESULT-TYPE equals 'output then return a list of the outputs
+of the statements in BODY, if RESULT-TYPE equals 'value then
+return the value of the last statement in BODY."
   ((lambda (results)
      (if (or (member "scalar" result-params)
 	     (member "output" result-params))
-	 (buffer-string)
+	 results
        (let ((tmp-file (make-temp-file "org-babel-sh")))
 	 (with-temp-file tmp-file (insert results))
 	 (org-babel-import-elisp-from-file tmp-file))))

lisp/ob-sql.el

@@ -54,9 +54,8 @@
   "Expand BODY according to PARAMS, return the expanded body." body)
 
 (defun org-babel-execute:sql (body params)
-  "Execute a block of Sql code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
-  (message "executing Sql source code block")
+  "Execute a block of Sql code with Babel.
+This function is called by `org-babel-execute-src-block'."
   (let* ((result-params (split-string (or (cdr (assoc :results params)) "")))
 	 (processed-params (org-babel-process-params params))
          (cmdline (cdr (assoc :cmdline params)))
@@ -81,7 +80,7 @@ called by `org-babel-execute-src-block'."
 
 
 (defun org-babel-prep-session:sql (session params)
-  "Prepare SESSION according to the header arguments specified in PARAMS."
+  "Raise an error because Sql sessions aren't implemented."
   (error "sql sessions not yet implemented"))
 
 (provide 'ob-sql)

lisp/ob-sqlite.el

@@ -31,8 +31,9 @@
 (require 'ob-ref)
 
 (declare-function org-fill-template "org" (template alist))
-(declare-function org-table-convert-region
-		  "org-table" (beg0 end0 &optional separator))
+(declare-function org-table-convert-region "org-table"
+		  (beg0 end0 &optional separator))
+(declare-function orgtbl-to-csv "org-table" (TABLE PARAMS))
 
 (defvar org-babel-default-header-args:sqlite '())
 
@@ -40,15 +41,15 @@
   '(db header echo bail csv column html line list separator nullvalue)
   "Sqlite specific header args.")
 
-(defun org-babel-expand-body:sqlite
-  (body params &optional processed-params) body)
+(defun org-babel-expand-body:sqlite (body params &optional processed-params)
+  (org-babel-sqlite-expand-vars
+   body (or (nth 1 processed-params) (org-babel-ref-variables params))))
 
 (defvar org-babel-sqlite3-command "sqlite3")
 
 (defun org-babel-execute:sqlite (body params)
-  "Execute a block of Sqlite code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
-  (message "executing Sqlite source code block")
+  "Execute a block of Sqlite code with Babel.
+This function is called by `org-babel-execute-src-block'."
   (let ((result-params (split-string (or (cdr (assoc :results params)) "")))
 	(vars (org-babel-ref-variables params))
 	(db (cdr (assoc :db params)))
@@ -60,14 +61,19 @@ called by `org-babel-execute-src-block'."
 			   (list :header :echo :bail :column
 				 :csv :html :line :list))))
 	exit-code)
-    (message "others:%s" others)
     (unless db (error "ob-sqlite: can't evaluate without a database."))
     (with-temp-buffer
       (insert
        (shell-command-to-string
 	(org-fill-template
-	 "%cmd %header %separator %nullvalue %others %csv %db  %body"
+	 "%cmd -init %body %header %separator %nullvalue %others %csv %db "
 	 (list
+	  (cons "body" ((lambda (sql-file)
+			  (with-temp-file sql-file
+			    (insert (org-babel-expand-body:sqlite
+				     body nil (list nil vars))))
+			  sql-file)
+			(make-temp-file "ob-sqlite-sql")))
 	  (cons "cmd" org-babel-sqlite3-command)
 	  (cons "header" (if headers-p "-header" "-noheader"))
 	  (cons "separator"
@@ -84,12 +90,11 @@ called by `org-babel-execute-src-block'."
 			      (member :html others) separator)
 			  ""
 			"-csv"))
-	  (cons "db " db)
-	  (cons "body" (format "%S" (org-babel-sqlite-expand-vars
-				     body vars)))))))
+	  (cons "db " db)))))
       (if (or (member "scalar" result-params)
 	      (member "html" result-params)
-	      (member "code" result-params))
+	      (member "code" result-params)
+	      (equal (point-min) (point-max)))
 	  (buffer-string)
 	(org-table-convert-region (point-min) (point-max))
 	(org-babel-sqlite-table-or-scalar
@@ -100,10 +105,22 @@ called by `org-babel-execute-src-block'."
   "Expand the variables held in VARS in BODY."
   (mapc
    (lambda (pair)
-     (setq body (replace-regexp-in-string
-		 (format "\$%s" (car pair))
-		 (format "%S" (cdr pair))
-		 body)))
+     (setq body
+	   (replace-regexp-in-string
+	    (format "\$%s" (car pair))
+	    ((lambda (val)
+	       (if (listp val)
+		   ((lambda (data-file)
+		      (with-temp-file data-file
+			(insert (orgtbl-to-csv
+				 val '(:fmt (lambda (el) (if (stringp el)
+							el
+						      (format "%S" el)))))))
+		      data-file)
+		    (make-temp-file "ob-sqlite-data"))
+		 (format "%S" val)))
+	     (cdr pair))
+	    body)))
    vars)
   body)
 
@@ -124,7 +141,8 @@ called by `org-babel-execute-src-block'."
     table))
 
 (defun org-babel-prep-session:sqlite (session params)
-  "Prepare SESSION according to the header arguments specified in PARAMS."
+  "Raise an error because support for sqlite sessions isn't implemented.
+Prepare SESSION according to the header arguments specified in PARAMS."
   (error "sqlite sessions not yet implemented"))
 
 (provide 'ob-sqlite)

lisp/ob-table.el

@@ -54,15 +54,16 @@
 (require 'ob)
 
 (defun org-babel-table-truncate-at-newline (string)
-  "If STRING ends in a newline character, then remove the newline
+  "Replace newline character with ellipses.
+If STRING ends in a newline character, then remove the newline
 character and replace it with ellipses."
   (if (and (stringp string) (string-match "[\n\r]" string))
       (concat (substring string 0 (match-beginning 0)) "...")
     string))
 
 (defmacro sbe (source-block &rest variables)
-  "Return the results of calling SOURCE-BLOCK assigning every
-variable in VARIABLES.  Each element of VARIABLES should be a two
+  "Return the results of calling SOURCE-BLOCK with VARIABLES.
+Each element of VARIABLES should be a two
 element list, whose first element is the name of the variable and
 second element is a string of its value.  The following call to
 `sbe' would be equivalent to the following source code block.

lisp/ob-tangle.el

@@ -33,6 +33,8 @@
   (require 'cl))
 
 (declare-function org-link-escape "org" (text &optional table))
+(declare-function org-heading-components "org" ())
+(declare-function with-temp-filebuffer "org-interaction" (file &rest body))
 
 (defcustom org-babel-tangle-lang-exts
   '(("emacs-lisp" . "el"))
@@ -47,12 +49,17 @@ then the name of the language is used."
 	   (string "Language name")
 	   (string "File Extension"))))
 
+(defcustom org-babel-post-tangle-hook nil
+  "Hook run in code files tangled by `org-babel-tangle'."
+  :group 'org-babel
+  :type 'hook)
+
 ;;;###autoload
 (defun org-babel-load-file (file)
-  "Load the contents of the Emacs Lisp source code blocks in the
-org-mode formatted FILE.  This function will first export the
-source code using `org-babel-tangle' and then load the resulting
-file using `load-file'."
+  "Load Emacs Lisp source code blocks in the Org-mode FILE.
+This function exports the source code using
+`org-babel-tangle' and then loads the resulting file using
+`load-file'."
   (flet ((age (file)
               (float-time
                (time-subtract (current-time)
@@ -69,11 +76,11 @@ file using `load-file'."
 
 ;;;###autoload
 (defun org-babel-tangle-file (file &optional target-file lang)
-  "Extract the bodies of all source code blocks in FILE with
-`org-babel-tangle'.  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."
+  "Extract the bodies of source code blocks in FILE.
+Source code blocks are extracted with `org-babel-tangle'.
+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."
   (interactive "fFile to tangle: \nP")
   (let ((visited-p (get-file-buffer (expand-file-name file)))
 	to-be-removed)
@@ -90,7 +97,8 @@ blocks by language."
 
 ;;;###autoload
 (defun org-babel-tangle (&optional target-file lang)
-  "Extract the bodies of all source code blocks from the current
+  "Write code blocks to source-specific files.
+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
@@ -99,6 +107,11 @@ exported source code blocks by language."
   (save-buffer)
   (save-excursion
     (let ((block-counter 0)
+	  (org-babel-default-header-args
+	   (if target-file
+	       (org-babel-merge-params org-babel-default-header-args
+				       (list (cons :tangle target-file)))
+	     org-babel-default-header-args))
           path-collector)
       (mapc ;; map over all languages
        (lambda (by-lang)
@@ -120,13 +133,12 @@ exported source code blocks by language."
                 (let* ((tangle (get-spec :tangle))
                        (she-bang ((lambda (sheb) (when (> (length sheb) 0) sheb))
 				  (get-spec :shebang)))
-                       (base-name (or (cond
-                                       ((string= "yes" tangle)
-                                        (file-name-sans-extension
-					 (buffer-file-name)))
-                                       ((string= "no" tangle) nil)
-                                       ((> (length tangle) 0) tangle))
-                                      target-file))
+                       (base-name (cond
+				   ((string= "yes" tangle)
+				    (file-name-sans-extension
+				     (buffer-file-name)))
+				   ((string= "no" tangle) nil)
+				   ((> (length tangle) 0) tangle)))
                        (file-name (when base-name
                                     ;; decide if we want to add ext to base-name
                                     (if (and ext (string= "yes" tangle))
@@ -138,7 +150,7 @@ exported source code blocks by language."
                       (delete-file file-name))
                     ;; drop source-block to file
                     (with-temp-buffer
-                      (if (fboundp lang-f) (funcall lang-f))
+                      (when (fboundp lang-f) (funcall lang-f))
                       (when (and she-bang (not (member file-name she-banged)))
                         (insert (concat she-bang "\n"))
                         (setq she-banged (cons file-name she-banged)))
@@ -160,10 +172,18 @@ exported source code blocks by language."
        (org-babel-tangle-collect-blocks lang))
       (message "tangled %d code block%s" block-counter
                (if (= block-counter 1) "" "s"))
+      ;; run `org-babel-post-tangle-hook' in all tangled files
+      (when org-babel-post-tangle-hook
+	(mapc
+	 (lambda (file)
+	   (with-temp-filebuffer file
+	     (run-hooks 'org-babel-post-tangle-hook)))
+	 path-collector))
       path-collector)))
 
 (defun org-babel-tangle-clean ()
-  "Call this function inside of a source-code file generated by
+  "Remove comments inserted by `org-babel-tangle'.
+Call this function inside of a source-code file generated by
 `org-babel-tangle' to remove all comments inserted automatically
 by `org-babel-tangle'.  Warning, this comment removes any lines
 containing constructs which resemble org-mode file links or noweb
@@ -177,20 +197,28 @@ references."
 
 (defvar org-stored-links)
 (defun org-babel-tangle-collect-blocks (&optional lang)
-  "Collect all source blocks in the current org-mode file.
+  "Collect source blocks in the current Org-mode file.
 Return an association list of source-code block specifications of
 the form used by `org-babel-spec-to-string' grouped by language.
 Optional argument LANG can be used to limit the collected source
 code blocks by language."
-  (let ((block-counter 0) blocks)
-    (org-babel-map-source-blocks (buffer-file-name)
-      (setq block-counter (+ 1 block-counter))
+  (let ((block-counter 1) (current-heading "") blocks)
+    (org-babel-map-src-blocks (buffer-file-name)
+      ((lambda (new-heading)
+	 (if (not (string= new-heading current-heading))
+	     (progn
+	       (setq block-counter 1)
+	       (setq current-heading new-heading))
+	   (setq block-counter (+ 1 block-counter))))
+       (replace-regexp-in-string "[ \t]" "-"
+				 (nth 4 (org-heading-components))))
       (let* ((link (progn (call-interactively 'org-store-link)
                           (org-babel-clean-text-properties
 			   (car (pop org-stored-links)))))
              (info (org-babel-get-src-block-info))
              (source-name (intern (or (nth 4 info)
-                                      (format "block-%d" block-counter))))
+                                      (format "%s:%d"
+					      current-heading block-counter))))
              (src-lang (nth 0 info))
 	     (expand-cmd (intern (concat "org-babel-expand-body:" src-lang)))
              (params (nth 2 info))
@@ -229,7 +257,8 @@ code blocks by language."
     blocks))
 
 (defun org-babel-spec-to-string (spec)
-  "Insert the source-code specified by SPEC into the current
+  "Insert SPEC into the current file.
+Insert the source-code specified by SPEC into the current
 source code file.  This function uses `comment-region' which
 assumes that the appropriate major-mode is set.  SPEC has the
 form

lisp/ob.el

@@ -38,6 +38,7 @@
 (declare-function tramp-dissect-file-name "tramp" (name &optional nodefault))
 (declare-function tramp-file-name-user "tramp" (vec))
 (declare-function tramp-file-name-host "tramp" (vec))
+(declare-function org-icompleting-read "org" (&rest args))
 (declare-function org-edit-src-code "org" (context code edit-buffer-name))
 (declare-function org-open-at-point "org" (&optional in-emacs reference-buffer))
 (declare-function org-save-outline-visibility "org" (use-markers &rest body))
@@ -61,8 +62,14 @@
 (declare-function org-babel-ref-variables "ob-ref" (params))
 (declare-function org-babel-ref-resolve-reference "ob-ref" (ref &optional params))
 
+(defgroup org-babel nil
+  "Code block evaluation and management in `org-mode' documents."
+  :tag "Babel"
+  :group 'org)
+
 (defcustom org-confirm-babel-evaluate t
-    "Require confirmation before interactively evaluating code
+  "Confirm before evaluation.
+Require confirmation before interactively evaluating code
 blocks in Org-mode buffers.  The default value of this variable
 is t, meaning confirmation is required for any code block
 evaluation.  This variable can be set to nil to inhibit any
@@ -84,15 +91,19 @@ remove code block execution from the C-c C-c keybinding."
 (put 'org-confirm-babel-evaluate 'safe-local-variable (lambda (x) (eq x t)))
 
 (defcustom org-babel-no-eval-on-ctrl-c-ctrl-c nil
-  "This variable can be set to remove code block evaluation from
-the C-c C-c key binding."
+  "Remove code block evaluation from the C-c C-c key binding."
   :group 'org-babel
   :type 'boolean)
 
-(defvar org-babel-source-name-regexp
+(defvar org-babel-src-name-regexp
   "^[ \t]*#\\+\\(srcname\\|source\\|function\\):[ \t]*"
   "Regular expression used to match a source name line.")
 
+(defvar org-babel-src-name-w-name-regexp
+  (concat org-babel-src-name-regexp
+	  "\\([^ ()\f\t\n\r\v]+\\)\\(\(\\(.*\\)\)\\|\\)")
+  "Regular expression matching source name lines with a name.")
+
 (defvar org-babel-src-block-regexp
   (concat
    ;; (1) indentation                     (2) lang
@@ -116,7 +127,7 @@ the C-c C-c key binding."
   "Regexp used to identify inline src-blocks.")
 
 (defun org-babel-get-src-block-info (&optional header-vars-only)
-  "Get information of the current source block.
+  "Get information on the current source block.
 
 Returns a list
  (language body header-arguments-alist switches name function-args indent).
@@ -132,9 +143,8 @@ added to the header-arguments-alist."
 	  (setq indent (car (last info)))
 	  (setq info (butlast info))
 	  (forward-line -1)
-	  (if (looking-at
-	       (concat org-babel-source-name-regexp
-		       "\\([^ ()\f\t\n\r\v]+\\)\\(\(\\(.*\\)\)\\|\\)"))
+	  (if (and (looking-at org-babel-src-name-w-name-regexp)
+		   (match-string 2))
 	      (progn
 		(setq info (append info (list (org-babel-clean-text-properties
 					       (match-string 2)))))
@@ -163,11 +173,11 @@ added to the header-arguments-alist."
         nil))))
 
 (defun org-babel-confirm-evaluate (info)
-  "Confirm that the user wishes to evaluate the code block
-defined by INFO.  This behavior can be suppressed by setting the
-value of `org-confirm-babel-evaluate' to nil, in which case all
-future interactive code block evaluations will proceed without
-any confirmation from the user.
+  "Confirm evaluation of the code block INFO.
+This behavior can be suppressed by setting the value of
+`org-confirm-babel-evaluate' to nil, in which case all future
+interactive code block evaluations will proceed without any
+confirmation from the user.
 
 Note disabling confirmation may result in accidental evaluation
 of potentially harmful code."
@@ -186,7 +196,8 @@ of potentially harmful code."
 
 ;;;###autoload
 (defun org-babel-execute-src-block-maybe ()
-  "Detect if this is context for a org-babel src-block and if so
+  "Conditionally execute a source block.
+Detect if this is context for a Babel src-block and if so
 then run `org-babel-execute-src-block'."
   (interactive)
   (if (not org-babel-no-eval-on-ctrl-c-ctrl-c)
@@ -198,7 +209,8 @@ then run `org-babel-execute-src-block'."
 
 ;;;###autoload
 (defun org-babel-expand-src-block-maybe ()
-  "Detect if this is context for a org-babel src-block and if so
+  "Conditionally expand a source block.
+Detect if this is context for a org-babel src-block and if so
 then run `org-babel-expand-src-block'."
   (interactive)
   (let ((info (org-babel-get-src-block-info)))
@@ -208,7 +220,8 @@ then run `org-babel-expand-src-block'."
 
 ;;;###autoload
 (defun org-babel-load-in-session-maybe ()
-  "Detect if this is context for a org-babel src-block and if so
+  "Conditionally load a source block in a session.
+Detect if this is context for a org-babel src-block and if so
 then run `org-babel-load-in-session'."
   (interactive)
   (let ((info (org-babel-get-src-block-info)))
@@ -220,7 +233,8 @@ then run `org-babel-load-in-session'."
 
 ;;;###autoload
 (defun org-babel-pop-to-session-maybe ()
-  "Detect if this is context for a org-babel src-block and if so
+  "Conditionally pop to a session.
+Detect if this is context for a org-babel src-block and if so
 then run `org-babel-pop-to-session'."
   (interactive)
   (let ((info (org-babel-get-src-block-info)))
@@ -230,14 +244,14 @@ then run `org-babel-pop-to-session'."
 
 (defconst org-babel-header-arg-names
   '(cache cmdline colnames dir exports file noweb results
-	  session tangle var noeval)
-  "Common header arguments used by org-babel.  Note that
-individual languages may define their own language specific
-header arguments as well.")
+	  session tangle var noeval comments)
+  "Common header arguments used by org-babel.
+Note that individual languages may define their own language
+specific header arguments as well.")
 
 (defvar org-babel-default-header-args
   '((:session . "none") (:results . "replace") (:exports . "code")
-    (:cache . "no") (:noweb . "no") (:hlines . "no"))
+    (:cache . "no") (:noweb . "no") (:hlines . "no") (:tangle . "no"))
   "Default arguments to use when evaluating a source block.")
 
 (defvar org-babel-default-inline-header-args
@@ -248,20 +262,26 @@ header arguments as well.")
 (make-variable-buffer-local 'org-babel-current-buffer-properties)
 
 (defvar org-babel-result-regexp
-  "^[ \t]*#\\+res\\(ults\\|name\\)\\(\\[\\([[:alnum:]]+\\)\\]\\)?\\:"
-  "Regular expression used to match result lines.  If the
-results are associated with a hash key then the hash will be
-saved in the second match data.")
+  "^[ \t]*#\\+res\\(ults\\|name\\)\\(\\[\\([[:alnum:]]+\\)\\]\\)?\\:[ \t]*"
+  "Regular expression used to match result lines.
+If the results are associated with a hash key then the hash will
+be saved in the second match data.")
+
+(defvar org-babel-result-w-name-regexp
+  (concat org-babel-result-regexp
+	  "\\([^ ()\f\t\n\r\v]+\\)\\(\(\\(.*\\)\)\\|\\)"))
 
 (defvar org-babel-min-lines-for-block-output 10
-  "If number of lines of output is equal to or exceeds this
+  "The minimum number of lines for block output.
+If number of lines of output is equal to or exceeds this
 value, the output is placed in a #+begin_example...#+end_example
 block. Otherwise the output is marked as literal by inserting
 colons at the starts of the lines. This variable only takes
 effect if the :results output option is in effect.")
 
 (defvar org-babel-noweb-error-langs nil
-  "List of language for which errors should be raised when the
+  "Languages for which Babel will raise literate programming errors.
+List of languages for which errors should be raised when the
 source code block satisfying a noweb reference in this language
 can not be resolved.")
 
@@ -272,17 +292,17 @@ can not be resolved.")
   "Hook for functions to be called after `org-babel-execute-src-block'")
 (defun org-babel-named-src-block-regexp-for-name (name)
   "This generates a regexp used to match a src block named NAME."
-  (concat org-babel-source-name-regexp (regexp-quote name) "[ \t\n]*"
+  (concat org-babel-src-name-regexp (regexp-quote name) "[ \t\n]*"
 	  (substring org-babel-src-block-regexp 1)))
 
 ;;; functions
 (defvar call-process-region)
 ;;;###autoload
 (defun 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.
+  "Execute the current source code block.
+Insert the results of execution 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'.
@@ -336,7 +356,10 @@ block."
                 (setq result (org-babel-read-result))
                 (message (replace-regexp-in-string "%" "%%"
                                                    (format "%S" result))) result)
-            (setq result (funcall cmd body params))
+            (message "executing %s code block%s..."
+		     (capitalize lang)
+		     (if (nth 4 info) (format " (%s)" (nth 4 info)) ""))
+	    (setq result (funcall cmd body params))
             (if (eq result-type 'value)
                 (setq result (if (and (or (member "vector" result-params)
                                           (member "table" result-params))
@@ -350,15 +373,17 @@ block."
       (setq call-process-region 'org-babel-call-process-region-original))))
 
 (defun org-babel-expand-body:generic (body params &optional processed-params)
-  "Expand a block of code with org-babel according to it's header
+  "Expand BODY with PARAMS.
+Expand a block of code with org-babel according to it's header
 arguments.  This generic implementation of body expansion is
 called for languages which have not defined their own specific
 org-babel-expand-body:lang function." body)
 
 ;;;###autoload
 (defun org-babel-expand-src-block (&optional arg info params)
-  "Expand the current source code block according to it's header
-arguments, and pop open the results in a preview buffer."
+  "Expand the current source code block.
+Expand according to the source code block's header
+arguments and pop open the results in a preview buffer."
   (interactive)
   (let* ((info (or info (org-babel-get-src-block-info)))
          (lang (nth 0 info))
@@ -378,9 +403,10 @@ arguments, and pop open the results in a preview buffer."
 
 ;;;###autoload
 (defun 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."
+  "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."
   (interactive)
   (let* ((info (or info (org-babel-get-src-block-info)))
          (lang (nth 0 info))
@@ -459,7 +485,8 @@ results already exist."
 
 ;;;###autoload
 (defun org-babel-execute-buffer (&optional arg)
-  "Call `org-babel-execute-src-block' on every source block in
+  "Execute source code blocks in a buffer.
+Call `org-babel-execute-src-block' on every source block in
 the current buffer."
   (interactive "P")
   (save-excursion
@@ -474,7 +501,8 @@ the current buffer."
 
 ;;;###autoload
 (defun org-babel-execute-subtree (&optional arg)
-  "Call `org-babel-execute-src-block' on every source block in
+  "Execute source code blocks in a subtree.
+Call `org-babel-execute-src-block' on every source block in
 the current subtree."
   (interactive "P")
   (save-restriction
@@ -495,15 +523,14 @@ the current subtree."
     hash))
 
 (defun org-babel-result-hash (&optional info)
-  "Return the in-buffer hash associated with the results
-specified in INFO."
+  "Return the in-buffer hash associated with INFO."
   (org-babel-where-is-src-block-result nil info)
   (org-babel-clean-text-properties (match-string 3)))
 
 (defun org-babel-hide-hash ()
-  "Hide the hash in the current results line.  Only the initial
-`org-babel-hash-show' characters of the hash will remain
-visible."
+  "Hide the hash in the current results line.
+Only the initial `org-babel-hash-show' characters of the hash
+will remain visible."
   (add-to-invisibility-spec '(org-babel-hide-hash . t))
   (save-excursion
     (when (and (re-search-forward org-babel-result-regexp nil t)
@@ -519,10 +546,10 @@ visible."
         (overlay-put ov1 'babel-hash hash)))))
 
 (defun org-babel-hide-all-hashes ()
-  "Hide the hash in the current buffer.  Only the initial
-`org-babel-hash-show' characters of each hash will remain
-visible.  This function should be called as part of the
-`org-mode-hook'."
+  "Hide the hash in the current buffer.
+Only the initial `org-babel-hash-show' characters of each hash
+will remain visible.  This function should be called as part of
+the `org-mode-hook'."
   (save-excursion
     (while (re-search-forward org-babel-result-regexp nil t)
       (goto-char (match-beginning 0))
@@ -531,9 +558,9 @@ visible.  This function should be called as part of the
 (add-hook 'org-mode-hook 'org-babel-hide-all-hashes)
 
 (defun org-babel-hash-at-point (&optional point)
-  "Return the value of the hash at `point'.  The hash is also
-added as the last element of the kill ring.  This can be called
-with C-c C-c."
+  "Return the value of the hash at POINT.
+The hash is also added as the last element of the kill ring.
+This can be called with C-c C-c."
   (interactive)
   (let ((hash (car (delq nil (mapcar
 			      (lambda (ol) (overlay-get ol 'babel-hash))
@@ -542,7 +569,8 @@ with C-c C-c."
 (add-hook 'org-ctrl-c-ctrl-c-hook 'org-babel-hash-at-point)
 
 (defun org-babel-result-hide-spec ()
-  "Add `org-babel-hide-result' as an invisibility spec for hiding
+  "Hide portions of results lines.
+Add `org-babel-hide-result' as an invisibility spec for hiding
 portions of results lines."
   (add-to-invisibility-spec '(org-babel-hide-result . t)))
 (add-hook 'org-mode-hook 'org-babel-result-hide-spec)
@@ -620,7 +648,7 @@ portions of results lines."
 	  (lambda () (org-add-hook 'change-major-mode-hook
 			      'org-babel-show-result-all 'append 'local)))
 
-(defmacro org-babel-map-source-blocks (file &rest body)
+(defmacro org-babel-map-src-blocks (file &rest body)
   "Evaluate BODY forms on each source-block in FILE."
   (declare (indent 1))
   `(let ((visited-p (get-file-buffer (expand-file-name ,file)))
@@ -638,7 +666,8 @@ portions of results lines."
 
 (defvar org-file-properties)
 (defun org-babel-params-from-properties (&optional lang)
-  "Return an association list of any source block params which
+  "Retrieve parameters specified as properties.
+Return an association list of any source block params which
 may be specified in the properties of the current outline entry."
   (save-match-data
     (let (val sym)
@@ -660,7 +689,8 @@ may be specified in the properties of the current outline entry."
 		 (and (boundp sym) (eval sym))))))))))
 
 (defun org-babel-params-from-buffer ()
-  "Return an association list of any source block params which
+  "Retrieve per-buffer parameters.
+ Return an association list of any source block params which
 may be specified at the top of the current buffer."
   (or org-babel-current-buffer-properties
       (setq org-babel-current-buffer-properties
@@ -676,8 +706,7 @@ may be specified at the top of the current buffer."
 
 (defvar org-src-preserve-indentation)
 (defun org-babel-parse-src-block-match ()
-  "Parse the match data resulting from a match of the
-`org-babel-src-block-regexp'."
+  "Parse the results from a match of the `org-babel-src-block-regexp'."
   (let* ((block-indentation (length (match-string 1)))
 	 (lang (org-babel-clean-text-properties (match-string 2)))
          (lang-headers (intern (concat "org-babel-default-header-args:" lang)))
@@ -703,8 +732,7 @@ may be specified at the top of the current buffer."
 	  block-indentation)))
 
 (defun org-babel-parse-inline-src-block-match ()
-  "Parse the match data resulting from a match of the
-`org-babel-inline-src-block-regexp'."
+  "Parse the results from a match of the `org-babel-inline-src-block-regexp'."
   (let* ((lang (org-babel-clean-text-properties (match-string 2)))
          (lang-headers (intern (concat "org-babel-default-header-args:" lang))))
     (list lang
@@ -759,7 +787,8 @@ Return a list (session vars result-params result-type colnames rownames)."
   (remove 'hline table))
 
 (defun org-babel-get-colnames (table)
-  "Return a cons cell, the `car' of which contains the TABLE less
+  "Return the column names of TABLE.
+Return a cons cell, the `car' of which contains the TABLE less
 colnames, and the `cdr' of which contains a list of the column
 names."
   (if (equal 'hline (nth 1 table))
@@ -767,7 +796,8 @@ names."
     (cons (cdr table) (car table))))
 
 (defun org-babel-get-rownames (table)
-  "Return a cons cell, the `car' of which contains the TABLE less
+  "Return the row names of TABLE.
+Return a cons cell, the `car' of which contains the TABLE less
 colnames, and the `cdr' of which contains a list of the column
 names.  Note: this function removes any hlines in TABLE."
   (flet ((trans (table) (apply #'mapcar* #'list table)))
@@ -806,7 +836,8 @@ names.  Note: this function removes any hlines in TABLE."
         (cdr (car (last names)))))))
 
 (defun org-babel-disassemble-tables (vars hlines colnames rownames)
-  "Process the variables in VARS according to the HLINES,
+  "Parse tables for further processing.
+Process the variables in VARS according to the HLINES,
 ROWNAMES and COLNAMES header arguments.  Return a list consisting
 of the vars, cnames and rnames."
   (let (cnames rnames)
@@ -833,7 +864,8 @@ of the vars, cnames and rnames."
      cnames rnames)))
 
 (defun org-babel-reassemble-table (table colnames rownames)
-  "Given a TABLE and set of COLNAMES and ROWNAMES add the names
+  "Add column and row names to a table.
+Given a TABLE and set of COLNAMES and ROWNAMES add the names
 to the table for reinsertion to org-mode."
   (if (listp table)
       ((lambda (table)
@@ -845,14 +877,15 @@ to the table for reinsertion to org-mode."
     table))
 
 (defun org-babel-where-is-src-block-head ()
-  "Return the point at the beginning of the current source
+  "Find where the current source block begins.
+Return the point at the beginning of the current source
 block.  Specifically at the beginning of the #+BEGIN_SRC line.
 If the point is not on a source block then return nil."
   (let ((initial (point)) top bottom)
     (or
      (save-excursion ;; on a source name line
        (beginning-of-line 1)
-       (and (looking-at org-babel-source-name-regexp) (forward-line 1)
+       (and (looking-at org-babel-src-name-regexp) (forward-line 1)
             (looking-at org-babel-src-block-regexp)
             (point)))
      (save-excursion ;; on a #+begin_src line
@@ -869,9 +902,12 @@ If the point is not on a source block then return nil."
         (point))))))
 
 ;;;###autoload
-(defun org-babel-goto-named-source-block (&optional name)
+(defun org-babel-goto-named-src-block (name)
   "Go to a named source-code block."
-  (interactive "ssource-block name: ")
+  (interactive
+   (let ((completion-ignore-case t))
+     (list (org-icompleting-read "source-block name: "
+				 (org-babel-src-block-names) nil t))))
   (let ((point (org-babel-find-named-block name)))
     (if point
         ;; taken from `org-open-at-point'
@@ -891,8 +927,32 @@ org-babel-named-src-block-regexp."
                 (re-search-backward regexp nil t))
         (match-beginning 0)))))
 
+(defun org-babel-src-block-names (&optional file)
+  "Returns the names of source blocks in FILE or the current buffer."
+  (save-excursion
+    (when file (find-file file)) (goto-char (point-min))
+    (let (names)
+      (while (re-search-forward org-babel-src-name-w-name-regexp nil t)
+	(setq names (cons (org-babel-clean-text-properties (match-string 2))
+			  names)))
+      names)))
+
+;;;###autoload
+(defun org-babel-goto-named-result (name)
+  "Go to a named result."
+  (interactive
+   (let ((completion-ignore-case t))
+     (list (org-icompleting-read "source-block name: "
+				 (org-babel-result-names) nil t))))
+  (let ((point (org-babel-find-named-result name)))
+    (if point
+        ;; taken from `org-open-at-point'
+        (progn (goto-char point) (org-show-context))
+      (message "result '%s' not found in this buffer" name))))
+
 (defun org-babel-find-named-result (name)
-  "Return the location of the result named NAME in the current
+  "Find a named result.
+Return the location of the result named NAME in the current
 buffer or nil if no such result exists."
   (save-excursion
     (goto-char (point-min))
@@ -901,9 +961,37 @@ buffer or nil if no such result exists."
                    "[ \t]" (regexp-quote name) "[ \t\n\f\v\r]") nil t)
       (beginning-of-line 0) (point))))
 
+(defun org-babel-result-names (&optional file)
+  "Returns the names of results in FILE or the current buffer."
+  (save-excursion
+    (when file (find-file file)) (goto-char (point-min))
+    (let (names)
+      (while (re-search-forward org-babel-result-w-name-regexp nil t)
+	(setq names (cons (org-babel-clean-text-properties (match-string 4))
+			  names)))
+      names)))
+
+;;;###autoload
+(defun org-babel-next-src-block (&optional arg)
+  "Jump to the next source block.
+With optional prefix argument ARG, jump forward ARG many source blocks."
+  (interactive "P")
+  (when (looking-at org-babel-src-block-regexp) (forward-char 1))
+  (re-search-forward org-babel-src-block-regexp nil nil (or arg 1))
+  (goto-char (match-beginning 0)) (org-show-context))
+
+;;;###autoload
+(defun org-babel-previous-src-block (&optional arg)
+  "Jump to the previous source block.
+With optional prefix argument ARG, jump backward ARG many source blocks."
+  (interactive "P")
+  (re-search-backward org-babel-src-block-regexp nil nil (or arg 1))
+  (goto-char (match-beginning 0)) (org-show-context))
+
 (defvar org-babel-lob-one-liner-regexp)
 (defun org-babel-where-is-src-block-result (&optional insert info hash indent)
-  "Return the point at the beginning of the result of the current
+  "Find where the current source block results begin.
+Return the point at the beginning of the result of the current
 source block.  Specifically at the beginning of the results line.
 If no result exists for this block then create a results line
 following the source block."
@@ -913,39 +1001,65 @@ following the source block."
 	   (name (if on-lob-line
 		     (nth 0 (org-babel-lob-get-info))
 		   (nth 4 (or info (org-babel-get-src-block-info)))))
-	   (head (unless on-lob-line (org-babel-where-is-src-block-head))) end)
+	   (head (unless on-lob-line (org-babel-where-is-src-block-head)))
+	   found beg end)
       (when head (goto-char head))
-      (or (and name (org-babel-find-named-result name))
-          (and (or on-lob-line (re-search-forward "^[ \t]*#\\+end_src" nil t))
-               (progn (end-of-line 1)
-		      (if (eobp) (insert "\n") (forward-char 1))
-		      (setq end (point))
-                      (or (and (not name)
-			       (progn ;; unnamed results line already exists
-				 (re-search-forward "[^ \f\t\n\r\v]" nil t)
-				 (beginning-of-line 1)
-                                 (looking-at
-                                  (concat org-babel-result-regexp "\n"))))
-			  ;; or (with optional insert) back up and
-			  ;; make one ourselves
-                          (when insert
-                            (goto-char end)
-			    (if (looking-at "[\n\r]")
-                                (forward-char 1) (insert "\n"))
-                            (insert (concat
-				     (if indent
-					 (mapconcat
-					  (lambda (el) " ")
-					  (number-sequence 1 indent) "")
-				       "")
-				     "#+results"
-				     (when hash (concat "["hash"]"))
-				     ":"
-				     (when name (concat " " name)) "\n\n"))
-			    (backward-char)
-                            (beginning-of-line 0)
-                            (if hash (org-babel-hide-hash)) t)))
-               (point))))))
+      (setq
+       found ;; was there a result (before we potentially insert one)
+       (or
+	(and
+	 ;; named results:
+	 ;; - return t if it is found, else return nil
+	 ;; - if it does not need to be rebuilt, then don't set end
+	 ;; - if it does need to be rebuilt then do set end
+	 name (setq beg (org-babel-find-named-result name))
+	 (prog1 beg
+	   (when (and hash (not (string= hash (match-string 3))))
+	     (goto-char beg) (setq end beg) ;; beginning of result
+	     (forward-line 1)
+	     (delete-region end (org-babel-result-end)) nil)))
+	(and
+	 ;; unnamed results:
+	 ;; - return t if it is found, else return nil
+	 ;; - if it is found, and the hash doesn't match, delete and set end
+	 (or on-lob-line (re-search-forward "^[ \t]*#\\+end_src" nil t))
+	 (progn (end-of-line 1)
+		(if (eobp) (insert "\n") (forward-char 1))
+		(setq end (point))
+		(or (and (not name)
+			 (progn ;; unnamed results line already exists
+			   (re-search-forward "[^ \f\t\n\r\v]" nil t)
+			   (beginning-of-line 1)
+			   (looking-at
+			    (concat org-babel-result-regexp "\n")))
+			 (prog1 (point)
+			   ;; must remove and rebuild if hash!=old-hash
+			   (if (and hash (not (string= hash (match-string 3))))
+			       (prog1 nil
+				 (forward-line 1)
+				 (delete-region
+				  end (org-babel-result-end)))
+			     (setq end nil)))))))))
+      (if (and insert end)
+	  (progn
+	    (goto-char end)
+	    (unless beg
+	      (if (looking-at "[\n\r]") (forward-char 1) (insert "\n")))
+	    (insert (concat
+		     (if indent
+			 (mapconcat
+			  (lambda (el) " ")
+			  (number-sequence 1 indent) "")
+		       "")
+		     "#+results"
+		     (when hash (concat "["hash"]"))
+		     ":"
+		     (when name (concat " " name)) "\n"))
+	    (unless beg (insert "\n") (backward-char))
+	    (beginning-of-line 0)
+	    (if hash (org-babel-hide-hash))
+	    (point))
+	found))))
 
 (defvar org-block-regexp)
 (defun org-babel-read-result ()
@@ -980,8 +1094,9 @@ following the source block."
 
 (defvar org-link-types-re)
 (defun org-babel-read-link ()
-  "Read the link at `point' into emacs-lisp.  If the path of the
-link is a file path it is expanded using `expand-file-name'."
+  "Read the link at `point' into emacs-lisp.
+If the path of the link is a file path it is expanded using
+`expand-file-name'."
   (let* ((case-fold-search t)
          (raw (and (looking-at org-bracket-link-regexp)
                    (org-babel-clean-text-properties (match-string 1))))
@@ -996,7 +1111,8 @@ link is a file path it is expanded using `expand-file-name'."
 
 (defun org-babel-insert-result
   (result &optional result-params info hash indent lang)
-  "Insert RESULT into the current buffer after the end of the
+  "Insert RESULT into the current buffer.
+By default RESULT is inserted after the end of the
 current source block.  With optional argument RESULT-PARAMS
 controls insertion of results in the org-mode file.
 RESULT-PARAMS can take the following values...
@@ -1136,9 +1252,9 @@ code ---- the results are extracted in the syntax of the source
       (point))))
 
 (defun org-babel-result-to-file (result)
-  "Convert RESULT into an `org-mode' link.  If the
-`default-directory' is different from the containing file's
-directory then expand relative links."
+  "Convert RESULT into an `org-mode' link.
+If the `default-directory' is different from the containing
+file's directory then expand relative links."
   (format
    "[[file:%s]]"
    (if (and default-directory
@@ -1170,9 +1286,9 @@ directory then expand relative links."
 	     (insert "#+end_example\n"))))))
 
 (defun org-babel-merge-params (&rest plists)
-  "Combine all parameter association lists in PLISTS.  Later
-elements of PLISTS override the values of previous element.  This
-takes into account some special considerations for certain
+  "Combine all parameter association lists in PLISTS.
+Later elements of PLISTS override the values of previous element.
+This takes into account some special considerations for certain
 parameters when merging lists."
   (let ((results-exclusive-groups
 	 '(("file" "vector" "table" "scalar" "raw" "org"
@@ -1271,10 +1387,10 @@ parameters when merging lists."
                                          params)))))))))
 
 (defun org-babel-expand-noweb-references (&optional info parent-buffer)
-  "This function expands Noweb style references in the body of
-the current source-code block.  For example the following
-reference would be replaced with the body of the source-code
-block named 'example-block'.
+  "Expand Noweb references in the body of the current source code block.
+
+For example the following reference would be replaced with the
+body of the source-code block named 'example-block'.
 
 <<example-block>>
 
@@ -1388,8 +1504,8 @@ This is taken almost directly from `org-read-prop'."
       (string-to-number string)))
 
 (defun org-babel-import-elisp-from-file (file-name)
-  "Read the results located at FILE-NAME into an elisp table.  If
-the table is trivial, then return it as a scalar."
+  "Read the results located at FILE-NAME into an elisp table.
+If the table is trivial, then return it as a scalar."
   (let (result)
     (save-window-excursion
       (with-temp-buffer
@@ -1421,8 +1537,8 @@ the table is trivial, then return it as a scalar."
   (apply 'string (reverse (string-to-list string))))
 
 (defun org-babel-chomp (string &optional regexp)
-  "Remove any trailing space or carriage returns characters from
-STRING.  Default regexp used is \"[ \f\t\n\r\v]\" but can be
+  "Strip trailing spaces and carriage returns from STRING.
+Default regexp used is \"[ \f\t\n\r\v]\" but can be
 overwritten by specifying a regexp as a second argument."
   (let ((regexp (or regexp "[ \f\t\n\r\v]")))
     (while (and (> (length string) 0)
@@ -1431,7 +1547,8 @@ overwritten by specifying a regexp as a second argument."
     string))
 
 (defun org-babel-trim (string &optional regexp)
-  "Like `org-babel-chomp' only it runs on both the front and back
+  "Strip leading and trailing spaces and carriage returns from STRING.
+Like `org-babel-chomp' only it runs on both the front and back
 of the string."
   (org-babel-chomp (org-babel-reverse-string
                     (org-babel-chomp (org-babel-reverse-string string) regexp))
@@ -1440,8 +1557,8 @@ of the string."
 (defvar org-babel-org-babel-call-process-region-original nil)
 (defun org-babel-tramp-handle-call-process-region
   (start end program &optional delete buffer display &rest args)
-  "Use tramp to handle call-process-region.  Fixes a bug in
-`tramp-handle-call-process-region'."
+  "Use tramp to handle call-process-region.
+Fixes a bug in `tramp-handle-call-process-region'."
   (if (and (featurep 'tramp) (file-remote-p default-directory))
       (let ((tmpfile (tramp-compat-make-temp-file "")))
 	(write-region start end tmpfile)
@@ -1457,7 +1574,8 @@ of the string."
            start end program delete buffer display args)))
 
 (defun org-babel-maybe-remote-file (file)
-  "If FILE specifies a remove file, then parse the information on
+  "Conditionally parse information on a remote connnection.
+If FILE specifies a remove file, then parse the information on
 the remote connection."
   (if (file-remote-p default-directory)
       (let* ((vec (tramp-dissect-file-name default-directory))

lisp/org-agenda.el

@@ -6965,13 +6965,14 @@ m     Mark the entry at point for an agenda action
 s     Schedule the marked entry to the date at the cursor
 d     Set the deadline of the marked entry to the date at the cursor
 r     Call `org-remember' with cursor date as the default date
+c     Call `org-capture' with cursor date as the default date
 SPC   Show marked entry in other window
 TAB   Visit marked entry in other window
 
 The cursor may be at a date in the calendar, or in the Org agenda."
   (interactive)
   (let (ans)
-    (message "Select action: [m]ark | [s]chedule [d]eadline [r]emember [ ]show")
+    (message "Select action: [m]ark | [s]chedule [d]eadline [r]emember [c]apture [ ]show")
     (setq ans (read-char-exclusive))
     (cond
      ((equal ans ?m)

lisp/org-capture.el

@@ -97,14 +97,16 @@ keys         The keys that will select the template, as a string, characters
 description  A short string describing the template, will be shown during
              selection.
 
-type         The type of entry.  Valid are:
+type         The type of entry.  Valid types are:
                entry       an Org-mode node, with a headline. Will be
                            filed as the child of the target entry or as
                            a top-level entry.
-               item        a plain list item, placed in the first plain
-                           list a the target location.
-               checkitem   a checkbox item.  This only differs from the
-                           plain lis item by the default template.
+               item        a plain list item, will be placed in the
+                           first plain list at the target
+                           location.
+               checkitem   a checkbox item.  This differs from the
+                           plain list item only is so far as it uses a
+                           different default template.
                table-line  a new line in the first table at target location.
                plain       text to be inserted as it is.
 
@@ -119,7 +121,7 @@ target       Specification of where the captured item should be placed.
                  Text will be placed at the beginning or end of that file
 
              (id \"id of existing org entry\")
-                 Filing as child of this entry, or in the body of the entry
+                 File as child of this entry, or in the body of the entry
 
              (file+headline \"path/to/file\" \"node headline\")
                  Fast configuration if the target heading is unique in the file
@@ -128,20 +130,20 @@ target       Specification of where the captured item should be placed.
                  For non-unique headings, the full path is safer
 
              (file+regexp  \"path/to/file\" \"regexp to find location\")
+                 File to the entry matching regexp
 
              (file+datetree \"path/to/file\")
-                 Will create a heading in a date tree.
+                 Will create a heading in a date tree
 
              (file+function \"path/to/file\" function-finding-location)
-                 A function to find the right location in the file.
+                 A function to find the right location in the file
 
              (clock)
-                File to the entry that is currently being clocked.
+                File to the entry that is currently being clocked
 
              (function function-finding-location)
                 Most general way, write your own function to find both
-                file and location.
-
+                file and location
 
 template     The template for creating the capture item.  If you leave this
              empty, an appropriate default template will be used.  See below
@@ -156,7 +158,7 @@ template     The template for creating the capture item.  If you leave this
 The rest of the entry is a property list of additional options.  Recognized
 properties are:
 
- :prepend            Normally new captured information will be appended at
+ :prepend            Normally newly captured information will be appended at
                      the target location (last child, last table line,
                      last list item...).  Setting this property will
                      change that.
@@ -183,12 +185,12 @@ properties are:
                      which means that the new line should become the third
                      line before the second horizontal separaor line.
 
-The template defined the text to be inserted.  Often then this is an org-mode
+The template defines the text to be inserted.  Often this is an org-mode
 entry (so the first line should start with a star) that will be filed as a
 child of the target headline.  It can also be freely formatted text.
 Furthermore, the following %-escapes will be replaced with content:
 
-  %^{prompt}  Prompt the user for a string and replace this sequence with it.
+  %^{prompt}  prompt the user for a string and replace this sequence with it.
               A default value and a completion table ca be specified like this:
               %^{prompt|default|completion2|completion3|...}
   %t          time stamp, date only
@@ -202,13 +204,13 @@ Furthermore, the following %-escapes will be replaced with content:
               indented, the entire inserted text will be indented as well.
   %c          current kill ring head
   %x          content of the X clipboard
-  %^C         Interactive selection of which kill or clip to use
-  %^L         Like %^C, but insert as link
+  %^C         interactive selection of which kill or clip to use
+  %^L         like %^C, but insert as link
   %k          title of currently clocked task
   %K          link to currently clocked task
   %^g         prompt for tags, with completion on tags in target file
-  %^G         prompt for tags, with completion all tags in all agenda files
-  %^{prop}p   Prompt the user for a value for property `prop'
+  %^G         prompt for tags, with completion on all tags in all agenda files
+  %^{prop}p   prompt the user for a value for property `prop'
   %:keyword   specific information for certain link types, see below
   %[pathname] insert the contents of the file given by `pathname'
   %(sexp)     evaluate elisp `(sexp)' and replace with the result
@@ -283,7 +285,7 @@ calendar           |  %:type %:date"
 	   (choice :tag "Template"
 		   (string)
 		   (list :tag "File"
-			 (const :format "" file-contents)
+			 (const :format "" file)
 			 (file :tag "Template file"))
 		   (list :tag "Function"
 			 (const :format "" function)
@@ -372,7 +374,8 @@ bypassed."
    (t
     ;; FIXME: Are these needed?
     (let* ((orig-buf (current-buffer))
-	   (annotation (if org-capture-link-is-already-stored
+	   (annotation (if (and (boundp 'org-capture-link-is-already-stored)
+				org-capture-link-is-already-stored)
 			   (plist-get org-store-link-plist :annotation)
 			 (org-store-link nil)))
 	   (initial (and (org-region-active-p)
@@ -544,16 +547,7 @@ already gone."
 	  (save-restriction
 	    (widen)
 	    (goto-char pos)
-	    (call-interactively 'org-refile)
-	    (when (and (boundp 'bookmark-alist)
-		       (assoc "org-capture-last-stored" bookmark-alist))
-	      (if (assoc "org-refile-last-stored" bookmark-alist)
-		  (setcdr (assoc "org-refile-last-stored" bookmark-alist)
-			  (cdr (assoc "org-refile-last-stored" bookmark-alist)))
-		(push (cons "org-capture-last-stored"
-			    (cdr (assoc "org-refile-last-stored"
-					bookmark-alist)))
-		      bookmark-alist)))))))))
+	    (call-interactively 'org-refile)))))))
 
 (defun org-capture-kill ()
   "Abort the current capture process."
@@ -987,7 +981,7 @@ Point will remain at the first line after the inserted text."
   (org-capture-put :key (car entry) :description (nth 1 entry)
 		   :target (nth 3 entry))
   (let ((txt (nth 4 entry)) (type (or (nth 2 entry) 'entry)))
-    (when (or (not txt) (not (string-match "\\S-" txt)))
+    (when (or (not (stringp txt)) (not (string-match "\\S-" txt)))
       ;; The template may be empty or omitted for special types.
       ;; Here we insert the default templates for such cases.
       (cond

lisp/org-entities.el

@@ -525,7 +525,9 @@ Kind can be any of `latex', `html', `ascii', `latin1', or `utf8'."
   (interactive)
   (with-output-to-temp-buffer "*Org Entity Help*"
     (princ "Org-mode entities\n=================\n\n")
-    (let ((ll (append org-entities-user org-entities))
+    (let ((ll (append '("* User-defined additions (variable org-entities-user)")
+		      org-entities-user
+		      org-entities))
 	  e latex mathp html latin utf8 name ascii
 	  (lastwasstring t)
 	  (head (concat

lisp/org-exp.el

@@ -234,7 +234,7 @@ This option can also be set with the +OPTIONS line, e.g. \"num:t\"."
   "Format of section numbers for export.
 The variable has two components.
 1. A list of lists, each indicating a counter type and a separator.
-   The counter type can be any of \"1\", \"A\", \"a\", \"I\", or \"a\".
+   The counter type can be any of \"1\", \"A\", \"a\", \"I\", or \"i\".
    It causes causes numeric, alphabetic, or roman counters, respectively.
    The separator is only used if another counter for a subsection is being
    added.
@@ -2107,19 +2107,29 @@ in the list) and remove property and value from the list in LISTVAR."
 	lang code trans opts indent caption)
     (goto-char (point-min))
     (while (re-search-forward
-	    "\\(^\\([ \t]*\\)#\\+BEGIN_SRC:?[ \t]+\\([^ \t\n]+\\)\\(.*\\)\n\\([^\000]+?\n\\)[ \t]*#\\+END_SRC.*\n?\\)\\|\\(^\\([ \t]*\\)#\\+BEGIN_EXAMPLE:?\\(?:[ \t]+\\(.*\\)\\)?\n\\([^\000]+?\n\\)[ \t]*#\\+END_EXAMPLE.*\n?\\)"
+	    "\\(^\\([ \t]*\\)#\\+BEGIN_SRC:?\\([ \t]+\\([^ \t\n]+\\)\\)?\\(.*\\)\n\\([^\000]+?\n\\)[ \t]*#\\+END_SRC.*\n?\\)\\|\\(^\\([ \t]*\\)#\\+BEGIN_EXAMPLE:?\\(?:[ \t]+\\(.*\\)\\)?\n\\([^\000]+?\n\\)[ \t]*#\\+END_EXAMPLE.*\n?\\)"
 	    nil t)
       (if (match-end 1)
-	  ;; src segments
-	  (setq lang (match-string 3)
-		opts (match-string 4)
-		code (match-string 5)
-		indent (length (match-string 2))
-                caption (get-text-property 0 'org-caption (match-string 0)))
+	  (if (not (match-string 4))
+	      (error "source block missing language specification: %s"
+		     (let* ((body (match-string 6))
+			    (nothing (message "body:%s" body))
+			    (preview (or (and (string-match
+					       "^[ \t]*\\([^\n\r]*\\)" body)
+					      (match-string 1 body)) body)))
+		       (if (> (length preview) 35)
+			   (concat (substring preview 0 32) "...")
+			 preview)))
+	    ;; src segments
+	    (setq lang (match-string 4)
+		  opts (match-string 5)
+		  code (match-string 6)
+		  indent (length (match-string 2))
+		  caption (get-text-property 0 'org-caption (match-string 0))))
 	(setq lang nil
-	      opts (match-string 8)
-	      code (match-string 9)
-	      indent (length (match-string 7))
+	      opts (match-string 9)
+	      code (match-string 10)
+	      indent (length (match-string 8))
               caption (get-text-property 0 'org-caption (match-string 0))))
 
       (setq trans (org-export-format-source-code-or-example

lisp/org-feed.el

@@ -166,10 +166,11 @@ Here are the keyword-value pair allows in `org-feed-alist'.
      When the handler is called, point will be at the feed headline.
 
 :parse-feed function
-     This function gets passed a buffer, and should return a list of entries,
-     each being a property list containing the `:guid' and `:item-full-text'
-     keys.  The default is `org-feed-parse-rss-feed'; `org-feed-parse-atom-feed'
-     is an alternative.
+     This function gets passed a buffer, and should return a list
+     of entries, each being a property list containing the
+     `:guid' and `:item-full-text' keys.  The default is
+     `org-feed-parse-rss-feed'; `org-feed-parse-atom-feed' is an
+     alternative.
 
 :parse-entry function
      This function gets passed an entry as returned by the parse-feed
@@ -200,12 +201,12 @@ Here are the keyword-value pair allows in `org-feed-alist'.
 		    (list :inline t :tag "Changed items"
 			  (const :changed-handler)
 			  (symbol :tag "Handler Function"))
-                    (list :inline t :tag "Parse Feed"
-                          (const :parse-feed)
-                          (symbol :tag "Parse Feed Function"))
-                    (list :inline t :tag "Parse Entry"
-                          (const :parse-entry)
-                          (symbol :tag "Parse Entry Function"))
+		    (list :inline t :tag "Parse Feed"
+			  (const :parse-feed)
+			  (symbol :tag "Parse Feed Function"))
+		    (list :inline t :tag "Parse Entry"
+			  (const :parse-entry)
+			  (symbol :tag "Parse Entry Function"))
 		    )))))
 
 (defcustom org-feed-drawer "FEEDSTATUS"
@@ -270,6 +271,7 @@ have been saved."
 
 (defun org-feed-unescape (s)
   "Unescape protected entities in S."
+  (require 'xml)
   (let ((re (concat "&\\("
 		    (mapconcat 'car xml-entity-alist "\\|")
 		    "\\);")))
@@ -313,10 +315,10 @@ it can be a list structured like an entry in `org-feed-alist'."
 			org-feed-default-template))
 	  (drawer (or (nth 1 (memq :drawer feed))
 		      org-feed-drawer))
-          (parse-feed (or (nth 1 (memq :parse-feed feed))
-                          'org-feed-parse-rss-feed))
-          (parse-entry (or (nth 1 (memq :parse-entry feed))
-                           'org-feed-parse-rss-entry))
+	  (parse-feed (or (nth 1 (memq :parse-feed feed))
+			  'org-feed-parse-rss-feed))
+	  (parse-entry (or (nth 1 (memq :parse-entry feed))
+			   'org-feed-parse-rss-entry))
 	  feed-buffer inbox-pos new-formatted
 	  entries old-status status new changed guid-alist e guid olds)
       (setq feed-buffer (org-feed-get-feed url))
@@ -332,10 +334,11 @@ it can be a list structured like an entry in `org-feed-alist'."
 	  (setq old-status (org-feed-read-previous-status inbox-pos drawer))
 	  ;; Add the "handled" status to the appropriate entries
 	  (setq entries (mapcar (lambda (e)
-				  (setq e (plist-put e :handled
-						     (nth 1 (assoc
-							     (plist-get e :guid)
-							     old-status)))))
+				  (setq e
+					(plist-put e :handled
+						   (nth 1 (assoc
+							   (plist-get e :guid)
+							   old-status)))))
 				entries))
 	  ;; Find out which entries are new and which are changed
 	  (dolist (e entries)
@@ -630,14 +633,15 @@ containing the properties `:guid' and `:item-full-text'.
 
 The `:item-full-text' property actually contains the sexp
 formatted as a string, not the original XML data."
+  (require 'xml)
   (with-current-buffer buffer
     (widen)
     (let ((feed (car (xml-parse-region (point-min) (point-max)))))
       (mapcar
        (lambda (entry)
-         (list
-          :guid (car (xml-node-children (car (xml-get-children entry 'id))))
-          :item-full-text (prin1-to-string entry)))
+	 (list
+	  :guid (car (xml-node-children (car (xml-get-children entry 'id))))
+	  :item-full-text (prin1-to-string entry)))
        (xml-get-children feed 'entry)))))
 
 (defun org-feed-parse-atom-entry (entry)
@@ -645,28 +649,36 @@ formatted as a string, not the original XML data."
   (let ((xml (car (read-from-string (plist-get entry :item-full-text)))))
     ;; Get first <link href='foo'/>.
     (setq entry (plist-put entry :link
-                           (xml-get-attribute
-                            (car (xml-get-children xml 'link))
-                            'href)))
+			   (xml-get-attribute
+			    (car (xml-get-children xml 'link))
+			    'href)))
     ;; Add <title/> as :title.
     (setq entry (plist-put entry :title
-			   (org-feed-unescape (car (xml-node-children
-						    (car (xml-get-children xml 'title)))))))
+			   (org-feed-unescape
+			    (car (xml-node-children
+				  (car (xml-get-children xml 'title)))))))
     (let* ((content (car (xml-get-children xml 'content)))
-           (type (xml-get-attribute-or-nil content 'type)))
+	   (type (xml-get-attribute-or-nil content 'type)))
       (when content
-        (cond
-         ((string= type "text")
-          ;; We like plain text.
-	  (setq entry (plist-put entry :description (org-feed-unescape (car (xml-node-children content))))))
-         ((string= type "html")
-          ;; TODO: convert HTML to Org markup.
-	  (setq entry (plist-put entry :description (org-feed-unescape (car (xml-node-children content))))))
-         ((string= type "xhtml")
-          ;; TODO: convert XHTML to Org markup.
-          (setq entry (plist-put entry :description (prin1-to-string (xml-node-children content)))))
-         (t
-          (setq entry (plist-put entry :description (format "Unknown '%s' content." type)))))))
+	(cond
+	 ((string= type "text")
+	  ;; We like plain text.
+	  (setq entry (plist-put entry :description
+				 (org-feed-unescape
+				  (car (xml-node-children content))))))
+	 ((string= type "html")
+	  ;; TODO: convert HTML to Org markup.
+	  (setq entry (plist-put entry :description
+				 (org-feed-unescape
+				  (car (xml-node-children content))))))
+	 ((string= type "xhtml")
+	  ;; TODO: convert XHTML to Org markup.
+	  (setq entry (plist-put entry :description
+				 (prin1-to-string
+				  (xml-node-children content)))))
+	 (t
+	  (setq entry (plist-put entry :description
+				 (format "Unknown '%s' content." type)))))))
     entry))
 
 (provide 'org-feed)

lisp/org-latex.el

@@ -385,7 +385,7 @@ for example using customize, or with something like
     (shell-script "bash")
     (gnuplot "Gnuplot")
     (ocaml "Caml") (caml "Caml")
-    (sql "SQL"))
+    (sql "SQL") (sqlite "sql"))
   "Alist mapping languages to their listing language counterpart.
 The key is a symbol, the major mode symbol without the \"-mode\".
 The value is the string that should be inserted as the language parameter
@@ -1221,9 +1221,16 @@ If END is non-nil, it is the end of the region."
 	    :timestamps (plist-get opt-plist :timestamps)
 	    :footnotes (plist-get opt-plist :footnotes)))
 	(org-unmodified
-	 (let ((inhibit-read-only t))
-	   (add-text-properties pt (max pt (1- end))
-				'(:org-license-to-kill t))))))))
+	 (let ((inhibit-read-only t)
+	       (limit (max pt (1- end))))
+	   (add-text-properties pt limit
+				'(:org-license-to-kill t))
+	   (save-excursion
+	     (goto-char pt)
+	     (while (re-search-forward "^[ \t]*#+.*\n?" limit t)
+	       (remove-text-properties (match-beginning 0) (match-end 0)
+				'(:org-license-to-kill t))))))))))
+	       
 
 (defvar org-export-latex-header-defs nil
   "The header definitions that might be used in the LaTeX body.")
@@ -1987,7 +1994,6 @@ The conversion is made depending of STRING-BEFORE and STRING-AFTER."
     s))
 (defvar org-latex-entities)   ; defined below
 (defvar org-latex-entities-regexp)   ; defined below
-(defvar org-latex-entities-exceptions)   ; defined below
 
 (defun org-export-latex-preprocess (parameters)
   "Clean stuff in the LaTeX export."
@@ -2101,15 +2107,18 @@ The conversion is made depending of STRING-BEFORE and STRING-AFTER."
 	(add-text-properties (match-beginning 0) (match-end 0)
 			     '(org-protected t)))))
 
+  ;; Special case for \nbsp
+  (goto-char (point-min))
+  (while (re-search-forward "\\\\nbsp\\({}\\|\\>\\)" nil t)
+    (org-if-unprotected
+     (replace-match (org-export-latex-protect-string "~"))))
+
   ;; Protect LaTeX entities
   (goto-char (point-min))
-  (let (a)
-    (while (re-search-forward org-latex-entities-regexp nil t)
-      (if (setq a (assoc (match-string 0) org-latex-entities-exceptions))
-	  (replace-match (org-add-props (nth 1 a) nil 'org-protected t)
-			 t t)
-	(add-text-properties (match-beginning 0) (match-end 0)
-			     '(org-protected t)))))
+  (while (re-search-forward org-latex-entities-regexp nil t)
+    (org-if-unprotected
+     (add-text-properties (match-beginning 0) (match-end 0)
+			  '(org-protected t))))
 
   ;; Replace radio links
   (goto-char (point-min))
@@ -2324,7 +2333,6 @@ The conversion is made depending of STRING-BEFORE and STRING-AFTER."
    "\\medskip"
    "\\multicolumn"
    "\\multiput"
-   ("\\nbsp" "~")
    "\\newcommand"
    "\\newcounter"
    "\\newenvironment"
@@ -2396,14 +2404,9 @@ The conversion is made depending of STRING-BEFORE and STRING-AFTER."
    "\\vspace")
  "A list of LaTeX commands to be protected when performing conversion.")
 
-(defvar org-latex-entities-exceptions nil)
-
 (defconst org-latex-entities-regexp
   (let (names rest)
     (dolist (x org-latex-entities)
-      (when (consp x)
-	(add-to-list 'org-latex-entities-exceptions x)
-	(setq x (car x)))
       (if (string-match "[a-zA-Z]$" x)
 	  (push x names)
 	(push x rest)))

lisp/org-list.el

@@ -195,19 +195,19 @@ When the indentation would be larger than this, it will become
 % END RECEIVE ORGLST %n
 \\begin{comment}
 #+ORGLST: SEND %n org-list-to-latex
-| | |
+-
 \\end{comment}\n")
     (texinfo-mode "@c BEGIN RECEIVE ORGLST %n
 @c END RECEIVE ORGLST %n
 @ignore
 #+ORGLST: SEND %n org-list-to-texinfo
-| | |
+-
 @end ignore\n")
     (html-mode "<!-- BEGIN RECEIVE ORGLST %n -->
 <!-- END RECEIVE ORGLST %n -->
 <!--
 #+ORGLST: SEND %n org-list-to-html
-| | |
+-
 -->\n"))
   "Templates for radio lists in different major modes.
 All occurrences of %n in a template will be replaced with the name of the
@@ -1277,17 +1277,15 @@ this list."
     (save-excursion
       (org-list-goto-true-beginning)
       (beginning-of-line 0)
-      (unless (looking-at "#\\+ORGLST: *SEND +\\([a-zA-Z0-9_]+\\) +\\([^ \t\r\n]+\\)\\( +.*\\)?")
+      (unless (looking-at "[ \t]*#\\+ORGLST[: \t][ \t]*SEND[ \t]+\\([^ \t\r\n]+\\)[ \t]+\\([^ \t\r\n]+\\)\\([ \t]+.*\\)?")
 	(if maybe
 	    (throw 'exit nil)
 	  (error "Don't know how to transform this list"))))
     (let* ((name (match-string 1))
 	   (transform (intern (match-string 2)))
 	   (item-beginning (org-list-item-beginning))
-	   (txt (buffer-substring-no-properties
-		 (car item-beginning)
-		 (org-list-end (cdr item-beginning))))
-	   (list (org-list-parse-list))
+	   (list (save-excursion (org-list-goto-true-beginning)
+				 (org-list-parse-list)))
 	   beg)
       (unless (fboundp transform)
 	(error "No such transformation function %s" transform))

lisp/org-src.el

@@ -146,7 +146,7 @@ but which mess up the display of a snippet in Org exported files.")
 
 (defcustom org-src-lang-modes
   '(("ocaml" . tuareg) ("elisp" . emacs-lisp) ("ditaa" . artist)
-    ("asymptote" . asy) ("dot" . fundamental))
+    ("asymptote" . asy) ("dot" . fundamental) ("sqlite" . sql))
   "Alist mapping languages to their major mode.
 The key is the language name, the value is the string that should
 be inserted as the name of the major mode.  For many languages this is

lisp/org.el

@@ -76,14 +76,15 @@
 
 (require 'calendar)
 ;; Emacs 22 calendar compatibility:  Make sure the new variables are available
-(unless (boundp 'calendar-view-holidays-initially-flag)
-  (defvaralias 'calendar-view-holidays-initially-flag
-    'view-calendar-holidays-initially))
-(unless (boundp 'calendar-view-diary-initially-flag)
-  (defvaralias 'calendar-view-diary-initially-flag
-    'view-diary-entries-initially))
-(unless (boundp 'diary-fancy-buffer)
-  (defvaralias 'diary-fancy-buffer 'fancy-diary-buffer))
+(when (fboundp 'defvaralias)
+  (unless (boundp 'calendar-view-holidays-initially-flag)
+    (defvaralias 'calendar-view-holidays-initially-flag
+      'view-calendar-holidays-initially))
+  (unless (boundp 'calendar-view-diary-initially-flag)
+    (defvaralias 'calendar-view-diary-initially-flag
+      'view-diary-entries-initially))
+  (unless (boundp 'diary-fancy-buffer)
+    (defvaralias 'diary-fancy-buffer 'fancy-diary-buffer)))
 
 ;; For XEmacs, noutline is not yet provided by outline.el, so arrange for
 ;; the file noutline.el being loaded.
@@ -105,13 +106,6 @@
 (require 'org-footnote)
 
 ;; babel
-(let* ((babel-path (expand-file-name
-		    "babel"
-		    (file-name-directory (or (buffer-file-name)
-					     load-file-name))))
-       (babel-langs-path (expand-file-name "langs" babel-path)))
-  (add-to-list 'load-path babel-path)
-  (add-to-list 'load-path babel-langs-path))
 (require 'ob)
 (require 'ob-table)
 (require 'ob-lob)
@@ -122,6 +116,7 @@
 
 ;; load languages based on value of `org-babel-load-languages'
 (defvar org-babel-load-languages)
+;;;###autoload
 (defun org-babel-do-load-languages (sym value)
   "Load the languages defined in `org-babel-load-languages'."
   (set-default sym value)
@@ -448,7 +443,8 @@ This option can also be set with the +OPTIONS line, e.g. \"^:nil\"."
 	  (const :tag "Only with braces" {})
 	  (const :tag "Never interpret" nil)))
 
-(defvaralias 'org-export-with-sub-superscripts 'org-use-sub-superscripts)
+(if (fboundp 'defvaralias)
+    (defvaralias 'org-export-with-sub-superscripts 'org-use-sub-superscripts))
 
 
 (defcustom org-startup-with-beamer-mode nil
@@ -8708,8 +8704,9 @@ Use TAB to complete link prefixes, then RET for type-specific completion support
 	 (t
 	  (save-match-data
 	    (if (string-match (concat "^" (regexp-quote
-					   (file-name-as-directory
-					    default-directory)))
+					   (expand-file-name
+					    (file-name-as-directory
+					     default-directory))))
 			      (expand-file-name path))
 		;; We are linking a file with relative path name.
 		(setq path (substring (expand-file-name path)
@@ -10146,7 +10143,7 @@ This can be done with a 0 prefix: `C-0 C-c C-w'"
 		  ;; If we are refiling for capture, make sure that the
 		  ;; last-capture pointers point here
 		  (when (org-bound-and-true-p org-refile-for-capture)
-		    (bookmark-set "org-refile-last-stored")
+		    (bookmark-set "org-capture-last-stored-marker")
 		    (move-marker org-capture-last-stored-marker (point)))
 		  (if (fboundp 'deactivate-mark) (deactivate-mark))
 		  (run-hooks 'org-after-refile-insert-hook))))
@@ -17125,11 +17122,13 @@ This command does many different things, depending on context:
 	  (org-footnote-at-definition-p))
       (call-interactively 'org-footnote-action))
      ((org-at-item-checkbox-p)
-      (call-interactively 'org-toggle-checkbox))
+      (call-interactively 'org-toggle-checkbox)
+      (org-list-send-list 'maybe))
      ((org-at-item-p)
       (if arg
 	  (call-interactively 'org-toggle-checkbox)
-	(call-interactively 'org-maybe-renumber-ordered-list)))
+	(call-interactively 'org-maybe-renumber-ordered-list))
+      (org-list-send-list 'maybe))
      ((save-excursion (beginning-of-line 1) (looking-at org-dblock-start-re))
       ;; Dynamic block
       (beginning-of-line 1)