From df2252b87ff9c289ae7692b78c71fc8f61b7efb2 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 11:48:07 -0400 Subject: [PATCH 001/138] Initialise new source code chapter with reference.org from Worg source-code-chapter.texi is just reference.org with level 1 headings replaced with @section, and level 2 headings replaced with @subsection, and with a top level @chapter node. This file is included in org.texi with an @include line for now. --- doc/org.texi | 2 + doc/source-code-chapter.texi | 1006 ++++++++++++++++++++++++++++++++++ 2 files changed, 1008 insertions(+) create mode 100644 doc/source-code-chapter.texi diff --git a/doc/org.texi b/doc/org.texi index 17615e0fa..1b3e078c2 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10842,6 +10842,8 @@ above, or by customizing the variable @code{org-publish-use-timestamps-flag}. This may be necessary in particular if files include other files via @code{#+SETUPFILE:} or @code{#+INCLUDE:}. +@include source-code-chapter.texi + @node Miscellaneous, Hacking, Publishing, Top @chapter Miscellaneous diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi new file mode 100644 index 000000000..eafe02d7f --- /dev/null +++ b/doc/source-code-chapter.texi @@ -0,0 +1,1006 @@ +@chapter Working with source code or Embedded Source Code + +@section Syntax + :PROPERTIES: + :CUSTOM_ID: syntax + :END: + +@subsection Source Code Block +The basic syntax of source code blocks in Org-babel is as follows: + +: #+begin_src language header-arguments +: body +: #+end_src + +- language :: The language of the code in the source code block. Valid + values must be members of =org-babel-interpreters=. +- header-arguments :: Header arguments control many facets of the + evaluation and output of source code blocks. See the [[header-arguments][Header + Arguments]] section for a complete review of available header + arguments. +- body :: The source code to be evaluated. An important key-binding + is C-c '. This calls =org-edit-src-code=, a function that brings + up an edit buffer containing the code using the Emacs major mode + appropriate to the language. You can edit your source code block + as you regularly would in Emacs. + +This syntax can be expanded by naming the source code block. + +: #+source: name +: #+begin_src language header-arguments +: +: #+end_src + +- name :: This name is associated with the source code block. This is + similar to the =#+tblname= lines that can be used to name tables + in Org-mode files. Referencing the name of a source code + block makes it possible to evaluate the block from other places in + the file, other files, or inside Org-mode tables. It + is also possible to pass arguments to a source code block through + this =#+source:= line (see [[alternate-argument-syntax][Alternate argument syntax]]). + +@subsection Library of Babel +[[file:library-of-babel.org][Library of Babel]] functions can be called using the following syntax. + +: #+lob: R-plot(data=R-plot-example-data) + +@subsection Aliases + Keyword aliases are intended to make Org-babel feel natural to + programmers fluent in a variety of languages. For example, + #+begin_example + ,#+srcname: alias-example + ,#+begin_src emacs-lisp + '((call lob) + (source function srcname) + (results resname)) + ,#+end_src + + ,#+results: alias-example + | call | lob | | + | source | function | srcname | + | results | resname | | + #+end_example + - =#+srcname:= can be replaced with either of two aliases, =#+source:= or =#+function:=. + - =#+results:= can be replaced with its alias, =#+resname:=. + + When calling Library of Babel functions, as in the following + example, there are two acceptable keywords. The =#+lob= call in + the example could be replaced with its alias, =#+call=. + #+begin_example + ,#+lob: R-plot(data=R-plot-example-data) + #+end_example + +@section Languages + :PROPERTIES: + :CUSTOM_ID: languages + :END: + + Org-babel has support for the following languages. + + | Language | Documentation | Identifier | Requirements | + |----------------+-----------------------------+------------+---------------------------------------------| + | Asymptote | org-babel-doc-asymptote | asymptote | [[http://asymptote.sourceforge.net/][asymptote]], [[http://asymptote.sourceforge.net/doc/Editing-modes.html][asy-mode]] | + | C | [[file:languages/org-babel-doc-C.org][org-babel-doc-C]] | C | none | + | Clojure | [[file:languages/org-babel-doc-clojure.org][org-babel-doc-clojure]] | clojure | [[http://clojure.org/][clojure]], [[http://www.emacswiki.org/emacs/clojure-mode.el][clojure-mode]], [[http://common-lisp.net/project/slime/][slime]], [[http://clojure.codestuffs.com/][swank-clojure]] | + | css | org-babel-doc-css | css | none | + | ditaa | org-babel-doc-ditaa | ditaa | [[http://ditaa.org/ditaa/][ditaa]] (bundled with Org-mode) | + | Graphviz | org-babel-doc-dot | dot | [[http://www.graphviz.org/][dot]] | + | Emacs Lisp | org-babel-doc-emacs-lisp | emacs-lisp | none | + | gnuplot | org-babel-doc-gnuplot | gnuplot | [[http://www.gnuplot.info/][gnuplot]], [[http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html][gnuplot-mode]] | + | Haskell | org-babel-doc-haskell | haskell | [[http://www.haskell.org/][haskell]], [[http://projects.haskell.org/haskellmode-emacs/][haskell-mode]], [[http://www.haskell.org/haskellwiki/Haskell_mode_for_Emacs#inf-haskell.el:_the_best_thing_since_the_breadknife][inf-haskell]], [[http://people.cs.uu.nl/andres/lhs2tex/][lhs2tex]] | + | Matlab | [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] | matlab | matlab, [[http://sourceforge.net/projects/matlab-emacs/][matlab.el]] | + | LaTeX | [[file:languages/org-babel-doc-LaTeX.org][org-babel-doc-latex]] | latex | [[http://www.latex-project.org/][latex]], [[http://www.gnu.org/software/auctex/][auctex]], [[http://www.gnu.org/software/auctex/reftex.html][reftex]] | + | Objective Caml | org-babel-doc-ocaml | ocaml | [[http://caml.inria.fr/][ocaml]], [[http://www-rocq.inria.fr/~acohen/tuareg/][tuareg-mode]] | + | Octave | [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] | octave | octave | + | OZ | [[file:languages/org-babel-doc-oz.org][org-babel-doc-oz]] | oz | [[http://www.mozart-oz.org/][Mozart]] which includes a major mode | + | Perl | org-babel-doc-perl | perl | [[http://www.perl.org/][perl]], [[http://www.emacswiki.org/emacs/CPerlMode][cperl-mode]] (optional) | + | Python | org-babel-doc-python | python | [[http://www.python.org/][python]], [[https://launchpad.net/python-mode][python-mode]] (optional) | + | R | [[file:languages/org-babel-doc-R.org][org-babel-doc-R]] | R | [[http://www.r-project.org/][R]], [[http://ess.r-project.org/][ess-mode]] | + | Ruby | org-babel-doc-ruby | ruby | [[http://www.ruby-lang.org/][ruby]], [[http://www.ruby-lang.org/][irb]], [[http://github.com/eschulte/rinari/raw/master/util/ruby-mode.el][ruby-mode]], [[http://github.com/eschulte/rinari/raw/master/util/inf-ruby.el][inf-ruby mode]] | + | Sass | org-babel-doc-sass | sass | [[http://sass-lang.com/][sass]], [[http://github.com/nex3/haml/blob/master/extra/sass-mode.el][sass-mode]] | + | GNU Screen | [[file:languages/org-babel-doc-screen.org][org-babel-doc-screen]] | screen | [[http://www.gnu.org/software/screen/][screen]], a terminal | + | shell | org-babel-doc-sh | sh[fn:1] | a shell | + | SQL | org-babel-doc-sql | sql | none | + + To add support for a particular language to your Org-babel + installation first make sure that the requirements of the language + are met, then add a line like the following to your Emacs + configuration, (replace "identifier" with one of the + entries in the Identifier column of the table). + #+begin_src emacs-lisp + (require 'org-babel-identifier) + #+end_src + +@section Header Arguments + :PROPERTIES: + :CUSTOM_ID: header-arguments + :END: + +Definitions of all Org-babel header arguments are given [[header-argument-specific-documentation][below]]. In +addition, some languages may add their own header arguments. Please +see the language-specific documentation for information on +language-specific header arguments. + +@subsection Using Header Arguments + +The values of header arguments can be set in three different ways, +each more specific than the last. + +*** System-wide + :PROPERTIES: + :CUSTOM_ID: system-wide-header-argument + :END: + + System-wide values of header arguments can be specified by + customizing the =org-babel-default-header-args= variable: + #+begin_example + org-babel-default-header-args is a variable defined in `org-babel.el'. + Its value is + ((:session . "none") + (:results . "replace") + (:exports . "code") + (:cache . "no") + (:noweb . "no")) + + + Documentation: + Default arguments to use when evaluating a source block. + #+end_example + [[#default-noweb]] + For example, the following example could be used to set the default value + of =:noweb= header arguments to =yes=. This would have the effect of + expanding =:noweb= references by default when evaluating source code blocks. + #+begin_src emacs-lisp :results silent :exports code + (setq org-babel-default-header-args + (cons '(:noweb . "yes") + (assq-delete-all :noweb org-babel-default-header-args))) + #+end_src + +*** Org-mode Properties + + Header arguments are also read from [[http://orgmode.org/manual/Properties-and-Columns.html#Properties-and-Columns][Org-mode properties]], which + means they can be set on the outline header level. For example, the + value of the =:cache= header argument will default to true in all + source code blocks under the following example of an Org-mode outline header: + #+begin_example + ,* outline header + :PROPERTIES: + :cache: yes + :CUSTOM_ID: property-set-header-arguments + :END: + #+end_example + Properties defined in this way override the properties set in + =org-babel-default-header-args=. It is convenient to use the + =org-set-property= function bound to =C-c C-x p= to set properties + in Org-mode documents. + +*** Source Code Block + :PROPERTIES: + :CUSTOM_ID: single-block-header-arguments + :END: + The most common way to assign values to header arguments is at the + source code block level. This can be done by listing a sequence of + header arguments and their values as part of the =#+begin_src= + line. Properties set in this way override both the values of + =org-babel-default-header-args= and header argument specified as + properties. In the following example, the + =:results= header argument is set to =silent=, meaning the results + of execution will not be inserted in the buffer, and the =:exports= + header argument is set to =code=, meaning only the body of the + source code block + will be preserved on export to HTML or LaTeX. + #+begin_example + ,#+source: factorial + ,#+begin_src haskell :results silent :exports code + fac 0 = 1 + fac n = n * fac (n-1) + ,#+end_src + #+end_example + +@subsection Specific Header Arguments + :PROPERTIES: + :CUSTOM_ID: header-argument-specific-documentation + :END: + +*** =:var= + :PROPERTIES: + :CUSTOM_ID: header-argument-var + :END: + + The =:var= header argument is used to pass arguments to + source code blocks. The specifics of how arguments are included + in a source code block are language specific and are + addressed in the language-specific documentation. However, the + syntax used to specify arguments is the same across all + languages. The values passed to arguments can be or + - literal values + - values from org-mode tables + - the results of other source code blocks + + These values can be indexed in a manner similar to arrays -- see + [[var-argument-indexing][argument indexing]]. + + The following syntax is used to pass arguments to source code + blocks using the =:var= header argument. + + #+begin_example + :var name=assign + #+end_example + + where =assign= can take one of the following forms + + - literal value :: either a string ="string"= or a number =9=. + - reference :: a table name: + + #+begin_example + ,#+tblname: example-table + | 1 | + | 2 | + | 3 | + | 4 | + + ,#+source: table-length + ,#+begin_src emacs-lisp :var table=example-table + (length table) + ,#+end_src + + ,#+results: table-length + : 4 + #+end_example + + a source code block name, as assigned by =#+srcname:=, + followed by parentheses: + + #+begin_example + ,#+begin_src emacs-lisp :var length=table-length() + (* 2 length) + ,#+end_src + + ,#+results: + : 8 + #+end_example + + In addition, an argument can be passed to the source code + block referenced by =:var=. The argument is passed within + the parentheses following the source code block name: + + #+begin_example + ,#+source: double + ,#+begin_src emacs-lisp :var input=8 + (* 2 input) + ,#+end_src + + ,#+results: double + : 16 + + ,#+source: squared + ,#+begin_src emacs-lisp :var input=double(input=1) + (* input input) + ,#+end_src + + ,#+results: squared + : 4 + #+end_example + +**** alternate argument syntax + :PROPERTIES: + :CUSTOM_ID: alternate-argument-syntax + :END: + + It is also possible to specify arguments in a potentially more + natural way using the =#+source:= line of a source code block. + As in the following example arguments can be packed inside of + parenthesis following the source name. + #+begin_example + ,#+source: double(input=0) + ,#+begin_src emacs-lisp + (* 2 input) + ,#+end_src + #+end_example + +**** indexable variable values + :PROPERTIES: + :CUSTOM_ID: var-argument-indexing + :END: + + It is possible to assign a portion of a value to a + variable in a source block. The following example + assigns the second and third rows of the table + =example-table= to the variable =data=: + + #+begin_example + :var data=example-table[1:2] + #+end_example + + *Note:* ranges are indexed using the =:= operator. + + *Note:* indices are 0 based. + + The following example assigns the second column of the + first row of =example-table= to =data=: + + #+begin_example + :var data=example-table[0,1] + #+end_example + + It is possible to index into the results of source code blocks + as well as tables. Any number of dimensions can be indexed. + Dimensions are separated from one another by commas. + + For more information on indexing behavior see the documentation + for the =org-babel-ref-index-list= function -- provided below. + + #+begin_example + org-babel-ref-index-list is a Lisp function in `org-babel-ref.el'. + + (org-babel-ref-index-list INDEX LIS) + + Return the subset of LIS indexed by INDEX. If INDEX is + separated by ,s then each PORTION is assumed to index into the + next deepest nesting or dimension. A valid PORTION can consist + of either an integer index, or two integers separated by a : in + which case the entire range is returned. + #+end_example + + *Note:* In Emacs, the documentation for any function or variable + can be read using the =describe-function= (M-x describe + function) and =describe-variable= (M-x describe variable) + functions, respectively. + +*** =:results= + :PROPERTIES: + :CUSTOM_ID: header-argument-results + :END: + + There are three types of results header argument: + - *collection* header arguments specify how the results should be collected from + the source code block; + - *type* header arguments specify what type of result the source code block + will return -- which has implications for how they will be + inserted into the Org-mode buffer; and + - *handling* header arguments specify how the results of + evaluating the source code block should be handled. + + *Note:* only one option from each type may be supplied per source code + block. + +**** collection + :PROPERTIES: + :CUSTOM_ID: header-argument-results-collection + :END: + The following options are mutually exclusive, and specify how the + results should be collected from the source code block. + + - value :: This is the default. The result is the value + of the last statement in the source code block. + This header argument places Org-babel in functional + mode. Note that in some languages, e.g., python, + use of this result type requires that a =return= + statement be included in the body of the source code + block. E.g., =:results value=. + - output :: The result is the collection of everything printed + to stdout during the execution of the source code + block. This header argument places Org-babel in scripting + mode. E.g., =:results output=. + +**** type + The following options are mutually exclusive and specify what + type of results the code block will return. By default, results + are inserted as either a *table* or *scalar* depending on their + value. + + - table, vector :: The results should be interpreted as an Org-mode table. + If a single value is returned, Org-babel will convert it + into a table with one row and one column. E.g., =:results + value table=. + - scalar, verbatim :: The results should be interpreted + literally -- meaning they will not be converted into a table. + The results will be inserted into the Org-mode buffer as + quoted text. E.g., =:results value verbatim=. + - file :: The results will be interpreted as the path to a file, + and will be inserted into the Org-mode buffer as a file + link. E.g., =:results value file=. + - raw, org :: The results are interpreted as raw Org-mode code and + are inserted directly into the buffer. If the results look + like a table they will be aligned as such by Org-mode. + E.g., =:results value raw=. + - html :: Results are assumed to be HTML and will be enclosed in + a =begin_html= block. E.g., =:results value html=. + - latex :: Results assumed to be LaTeX and are enclosed in a + =begin_latex= block. E.g., =:results value latex=. + - code :: Result are assumed to be parseable code and are + enclosed in a code block. E.g., =:results value code=. + - pp :: The result is converted to pretty-printed code and is + enclosed in a code block. This option currently supports + Emacs Lisp, python, and ruby. E.g., =:results value pp=. + +**** handling + The following results options indicate what Org-babel should do + with the results once they are collected. + + - silent :: The results will be echoed in the minibuffer but + will not be inserted into the Org-mode buffer. E.g., + =:results output silent=. + - replace :: The default value. The results will be inserted + into the Org-mode buffer. E.g., =:results output + replace=. + +*** =:file= + :PROPERTIES: + :CUSTOM_ID: header-argument-file + :END: + + =:file= is used to specify a path for file output in which case an + [[http://orgmode.org/manual/Link-format.html#Link-format][org style]] =file:= link is inserted into the buffer as the + result. Common examples are graphical output from [[file:languages/org-babel-doc-R.org][R]], gnuplot, + ditaa and [[file:languages/org-babel-doc-LaTeX.org][latex]] blocks. + + See the [[#header-argument-dir][=:dir= and remote execution]] section for examples. + + Note that for some languages, including [[file:languages/org-babel-doc-R.org][R]], gnuplot, [[file:languages/org-babel-doc-LaTeX.org][latex]] and + ditaa, graphical output is sent to the specified file without the + file being referenced explicitly in the code block. See the + documentation for the individual languages for details. In + contrast, general purpose languages such as python and ruby + require that the code explicitly create output corresponding to + the path indicated by =:file=. + + While the =:file= header argument can be used to specify the path + to the output file, + +*** =:dir= and remote execution + :PROPERTIES: + :CUSTOM_ID: header-argument-dir + :END: + =:dir= specifies the /default directory/ during code block + execution. If it is absent, then the directory associated with the + current buffer is used. In other words, supplying =:dir path= + temporarily has the same effect as changing the current directory + with =M-x cd path=, and then not supplying =:dir=. Under the + surface, =:dir= simply sets the value of the emacs variable + =default-directory=. + + When using =:dir=, you should supply a relative path for [[#header-argument-file][file + output]] (e.g. =:file myfile.jpg= or =:file results/myfile.jpg=) in + which case that path will be interpreted relative to the default + directory. + + In other words, if you want your plot to go into a folder called + Work in your home directory, you could use + +#+begin_example + ,#+begin_src R :file myplot.png :dir ~/Work + matplot(matrix(rnorm(100), 10), type="l") + ,#+end_src +#+end_example + +**** Remote execution + A directory on a remote machine can be specified using [[http://www.gnu.org/software/tramp/#Filename-Syntax][tramp + filename syntax]], in which case the code will be executed on the + remote machine[fn:2]. An example is + +#+begin_example +,#+begin_src R :file plot.png :dir /dand@yakuba.princeton.edu: + plot(1:10, main=system("hostname", intern=TRUE)) +,#+end_src +#+end_example + +Text results will be returned to the local org buffer as normal, and +file output will be created on the remote machine with relative paths +interpreted relative to the remote directory. An org link to the +remote file will be created. + +So in the above example a plot will be created on the remote machine, +and a link of the following form will be inserted in the org buffer: + +#+begin_example +[[file:/scp:dand@yakuba.princeton.edu:/home/dand/plot.png][plot.png]] +#+end_example + +Most of this functionality follows immediately from the fact that +=:dir= sets the value of the emacs variable =default-directory=, +thanks to [[http://www.gnu.org/software/tramp/][tramp]]. Those using XEmacs, or GNU Emacs prior to +version 23 may need to install tramp separately in order for the +above features to work correctly. + +**** Further points + - If =:dir= is used in conjunction with =:session=, although it + will determine the starting directory for a new session as + expected, no attempt is currently made to alter the directory + associated with an existing session. + - =:dir= should typically not be used to create files during + export with =:exports results= or =:exports both=. The reason + is that, in order to retain portability of exported material + between machines, during export, links inserted into the buffer + will *not* be expanded against default directory. Therefore, if + default-directory is altered using =:dir=, it it probable that + the file will be created in a location to which the link does + not point. +*** =:exports= + :PROPERTIES: + :CUSTOM_ID: header-argument-exports + :END: + + Specify what should be included in HTML or LaTeX exports of the + Org-mode file. + + - code :: the default. The body of code is included + into the exported file. E.g., =:exports code=. + - results :: the result of evaluating the code is included in the + exported file. E.g., =:exports results=. + - both :: both the code and results are included in the exported + file. E.g., =:exports both=. + - none :: nothing is included in the exported file. E.g., + =:exports none=. + +*** =:tangle= + :PROPERTIES: + :CUSTOM_ID: tangle-header-arguments + :END: + + Specify whether or not the source code block should be included + in tangled extraction of source code files. + + - yes :: the source code block is exported to a source code file + named after the basename (name w/o extension) of the + Org-mode file. E.g., =:tangle yes=. + - no :: the default. The source code block is not + exported to a source code file. E.g., =:tangle no=. + - other :: Any other string passed to the =:tangle= header argument + is interpreted as a file basename to which the block will + be exported. E.g., =:tangle basename=. + +*** =:session= + :PROPERTIES: + :CUSTOM_ID: header-argument-session + :END: + + Start a session for an interpreted language where state is + preserved. This applies particularly to the supported languages + python, R and ruby. + + By default, a session is not started. + + A string passed to the =:session= header argument will give the + session a name. This makes it possible to run concurrent + sessions for each interpreted language. + +*** =:noweb= + :PROPERTIES: + :CUSTOM_ID: header-argument-noweb + :END: + + Controls the expansion of [[noweb-reference-syntax][noweb syntax]] references in a + source code block. This header argument can have one of two + values: =yes= or =no=. + - =no= :: the default. No [[noweb-reference-syntax][noweb syntax]] specific action is taken + on evaluating source code blocks/ However, noweb references + will still be expanded during tangling. + - =yes= :: all [[noweb-reference-syntax][noweb syntax]] references in the body of the source + code block will be expanded before the block is evaluated. + +**** Noweb Prefix Lines + + Noweb insertions are now placed behind the line prefix of the + =<>=. + + This behavior is illustrated in the following example. Because + the =<>= noweb reference appears behind the SQL + comment syntax, each line of the expanded noweb reference will + be commented. + + This source code block: + + #+begin_example + -- <> + #+end_example + + + expands to: + + #+begin_example + -- this is the + -- multi-line body of example + #+end_example + + Note that noweb replacement text that does *not* contain any + newlines will not be affected by this change, so it is still + possible to use inline noweb references. + + Thanks to Sébastien Vauban for this idea. + +*** =:cache= + :PROPERTIES: + :CUSTOM_ID: header-argument-cache + :END: + + Controls the use of in-buffer caching of source code block + results to avoid re-running unchanged source code blocks. This + header argument can have one of two values: =yes= or =no=. + - =no= :: The default. No caching takes place and the source + code block will be run every time it is executed. + - =yes= :: every time the source code block is run a sha1 hash of + the code and arguments passed to the block will be + generated. This hash is packed into the =#+results:= line + of the results and will be checked on subsequent executions + of the source code block. If the source code block has not + changed since the last time it was evaluated, it will not be + re-evaluated. + +@section Results + :PROPERTIES: + :CUSTOM_ID: results-specification + :END: + + The way in which results are handled depends on whether a [[header-argument-session][session]] + is invoked, as well as on whether + [[header-argument-results-collection][=:results value=] or + [[header-argument-results-collection][=:results output=]] is used. The following table shows the + possibilities: + + | | non-session (default) | =:session= | + |-------------------+--------------------------+-------------------------------------| + | =:results value= | value of last expression | value of last expression | + | =:results output= | contents of stdout | concatenation of interpreter output | + + *Note:* With =:results value=, the result in both =:session= and + non-session is returned to Org-mode as a table (a one- or + two-dimensional vector of strings or numbers) when appropriate. + +**** Non-session +***** =:results value= + This is the default. Internally, the value is obtained by + wrapping the code in a function definition in the external + language, and evaluating that function. Therefore, code should be + written as if it were the body of such a function. In particular, + note that python does not automatically return a value from a + function unless a =return= statement is present, and so a + 'return' statement will usually be required in python. + + This is the only one of the four evaluation contexts in which the + code is automatically wrapped in a function definition. + +***** =:results output= + The code is passed to the interpreter as an external process, and + the contents of the standard output stream are returned as + text. (In certain languages this also contains the error output + stream; this is an area for future work.) + +**** =:session= +***** =:results value= + The code is passed to the interpreter running as an interactive + Emacs inferior process. The result returned is the result of the + last evaluation performed by the interpreter. (This is obtained in + a language-specific manner: the value of the variable =_= in + python and ruby, and the value of =.Last.value= in R). + +***** =:results output= + The code is passed to the interpreter running as an interactive + Emacs inferior process. The result returned is the concatenation + of the sequence of (text) output from the interactive + interpreter. Notice that this is not necessarily the same as what + would be sent to stdout if the same code were passed to a + non-interactive interpreter running as an external process. For + example, compare the following two blocks: + +#+begin_src python :results output + print "hello" + 2 + print "bye" +#+end_src + +#+resname: + : hello + : bye + + In non-session mode, the '2' is not printed and does not appear. + +#+begin_src python :results output :session + print "hello" + 2 + print "bye" +#+end_src + +#+resname: + : hello + : 2 + : bye + + But in =:session= mode, the interactive interpreter receives input '2' + and prints out its value, '2'. (Indeed, the other print statements are + unnecessary here). + +@section Noweb Reference Syntax + :PROPERTIES: + :CUSTOM_ID: noweb-reference-syntax + :END: + + The [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] Literate Programming system allows named blocks of code to + be referenced by using the familiar Noweb syntax: + : <> + + Noweb references are handled differently during evaluation and + tangling. + + When a document is tangled, Noweb references are replaced with the + named source code block. + + When a source code block is evaluated, the action depends upon the + value of the =:noweb= header argument. If =:noweb yes=, then a + Noweb reference is expanded before evaluation. If =:noweb no=, + the default, then the reference is not expanded before + evaluation. + + *Note:* the default value, =:noweb no=, was chosen to ensure that + Org-babel does not break correct code in a language, such as Ruby, + where =<>= is a syntactically valid construct. If =<>= is + not syntactically valid in languages that you use, then please + consider [[*System%20wide][setting the default value]]. + + An example that uses the Noweb reference syntax is provided in the + [[literate programming example]]. + +@section Key Bindings & Useful Functions + + Org-babel re-binds many common Org-mode key sequences depending on + the context. Within a source-code block the following sequences + are rebound: + | =C-c C-c= | [[function-org-babel-execute][org-babel-execute-src-block]] | + | =C-c C-o= | [[function-org-babel-open-src-block-result][org-babel-open-src-block-result]] | + | =C-up= | [[function-org-babel-load-in-session][org-babel-load-in-session]] | + | =M-down= | [[function-org-babel-pop-to-session][org-babel-pop-to-session]] | + + Org-babel also exposes a number of functions behind the common + =org-babel-key-prefix= of =C-c M-b=: + #+begin_src emacs-lisp :exports none + (lambda (binding + (list (format "\\C-c \\M-b %s" + (car binding)) + (format "[[function-%s][%s]]" + (cdr binding) (cdr binding)))) + org-babel-key-bindings) + #+end_src + | =C-c M-b t= | [[function-org-babel-tangle][org-babel-tangle]] | + | =C-c M-b T= | [[function-org-babel-tangle-file][org-babel-tangle-file]] | + | =C-c M-b e= | [[function-org-babel-execute-src-block][org-babel-execute-src-block]] | + | =C-c M-b s= | [[function-org-babel-execute-subtree][org-babel-execute-subtree]] | + | =C-c M-b b= | [[function-org-babel-execute-buffer][org-babel-execute-buffer]] | + | =C-c M-b h= | [[function-org-babel-sha1-hash][org-babel-sha1-hash]] | + | =C-c M-b g= | [[function-org-babel-goto-named-source-block][org-babel-goto-named-source-block]] | + | =C-c M-b l= | [[function-org-babel-lob-ingest][org-babel-lob-ingest]] | + + +@subsection Functions +*** org-babel-execute-src-block + :PROPERTIES: + :CUSTOM_ID: function-org-babel-execute-src-block + :END: + +#+begin_example + org-babel-execute-src-block is an interactive Lisp function in + `org-babel.el'. + + (org-babel-execute-src-block &optional ARG INFO PARAMS) + + Execute the current source code block, and insert the results + into the buffer. Source code execution and the collection and + formatting of results can be controlled through a variety of + header arguments. + + Optionally supply a value for INFO in the form returned by + `org-babel-get-src-block-info'. + + Optionally supply a value for PARAMS which will be merged with + the header arguments specified at the front of the source code + block. +#+end_example + +*** org-babel-open-src-block-result + :PROPERTIES: + :CUSTOM_ID: function-org-babel-open-src-block-result + :END: + +#+begin_example + org-babel-open-src-block-result is an interactive Lisp function in + `org-babel.el'. + + (org-babel-open-src-block-result &optional RE-RUN) + + If `point' is on a src block then open the results of the + source code block, otherwise return nil. With optional prefix + argument RE-RUN the source-code block is evaluated even if + results already exist. +#+end_example + +*** org-babel-load-in-session + :PROPERTIES: + :CUSTOM_ID: function-org-babel-load-in-session + :END: + +#+begin_example + org-babel-load-in-session is an interactive Lisp function in + `org-babel.el'. + + (org-babel-load-in-session &optional ARG INFO) + + Load the body of the current source-code block. Evaluate the + header arguments for the source block before entering the + session. After loading the body this pops open the session. + + [back] +#+end_example + +*** org-babel-pop-to-session + :PROPERTIES: + :CUSTOM_ID: function-org-babel-pop-to-session + :END: + +#+begin_example + org-babel-pop-to-session is an interactive Lisp function in + `org-babel.el'. + + (org-babel-pop-to-session &optional ARG INFO) + + Pop to the session of the current source-code block. If + called with a prefix argument then evaluate the header arguments + for the source block before entering the session. Copy the body + of the source block to the kill ring. + + [back] +#+end_example + +*** org-babel-tangle + :PROPERTIES: + :CUSTOM_ID: function-org-babel-tangle + :END: + +#+begin_example + org-babel-tangle is an interactive Lisp function in + `org-babel-tangle.el'. + + It is bound to C-c M-b t. + + (org-babel-tangle &optional TARGET-FILE LANG) + + Extract the bodies of all source code blocks from the current + file into their own source-specific files. Optional argument + TARGET-FILE can be used to specify a default export file for all + source blocks. Optional argument LANG can be used to limit the + exported source code blocks by language. +#+end_example + +*** org-babel-execute-subtree + :PROPERTIES: + :CUSTOM_ID: function-org-babel-execute-subtree + :END: + +#+begin_example + org-babel-execute-subtree is an interactive Lisp function in + `org-babel.el'. + + It is bound to C-c M-b s. + + (org-babel-execute-subtree &optional ARG) + + Replace EVAL snippets in the entire subtree. +#+end_example + +*** org-babel-execute-buffer + :PROPERTIES: + :CUSTOM_ID: function-org-babel-execute-buffer + :END: + +#+begin_example + org-babel-execute-buffer is an interactive Lisp function in + `org-babel.el'. + + It is bound to C-c M-b b. + + (org-babel-execute-buffer &optional ARG) + + Replace EVAL snippets in the entire buffer. +#+end_example + +*** org-babel-sha1-hash + :PROPERTIES: + :CUSTOM_ID: function-org-babel-sha1-hash + :END: + +#+begin_example + org-babel-sha1-hash is an interactive Lisp function in `org-babel.el'. + + It is bound to C-c M-b h. + + (org-babel-sha1-hash &optional INFO) + + Not documented. +#+end_example + +*** org-babel-goto-named-source-block + :PROPERTIES: + :CUSTOM_ID: function-org-babel-goto-named-source-block + :END: + +#+begin_example + org-babel-goto-named-source-block is an interactive Lisp function in + `org-babel.el'. + + It is bound to C-c M-b g. + + (org-babel-goto-named-source-block &optional NAME) + + Go to a named source-code block. +#+end_example + +*** org-babel-lob-ingest + :PROPERTIES: + :CUSTOM_ID: function-org-babel-lob-ingest + :END: + +#+begin_example + org-babel-lob-ingest is an interactive Lisp function in + `org-babel-lob.el'. + + It is bound to C-c M-b l. + + (org-babel-lob-ingest &optional FILE) + + Add all source-blocks defined in FILE to `org-babel-library-of-babel'. +#+end_example + +@section Batch Execution +It is possible to call Org-babel functions from the command line. +This shell script calls [[function-org-babel-tangle][org-babel-tangle]] on every one of its +arguments. + +Be sure to adjust the paths to fit your system. +#+begin_src sh + #!/bin/sh + # -*- mode: shell-script -*- + # + # tangle a file with org-babel + # + DIR=`pwd` + FILES="" + + # wrap each argument in the code required to call tangle on it + for i in $@; do + FILES="$FILES \"$i\"" + done + + emacsclient \ + --eval "(progn + (add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\")) + (add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\")) + (require 'org)(require 'org-exp)(require 'org-babel) + (mapc (lambda (file) + (find-file (expand-file-name file \"$DIR\")) + (org-babel-tangle) + (kill-buffer)) '($FILES)))" +#+end_src + +@section Footnotes + +[fn:1] The former use of the =shell= identifier is now deprecated. + +[fn:2] As long as the interpreter executable is found on the remote +machine: see the variable =tramp-remote-path= + + +@section HTML 1 :noexport: + +#+begin_html + +#+end_html + +@subsection Note + - HTML 1 was keeping the babelfish code from exporting. Not sure + why or if the code itself is necessary, but moving it here gets + the fish on the page. From 12e9b0a567e5eb8cc6ccd3b972d958fb544fde99 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 12:00:44 -0400 Subject: [PATCH 002/138] Quote some @ symbols and clean up. make info and make pdf work now. --- doc/source-code-chapter.texi | 25 +++---------------------- 1 file changed, 3 insertions(+), 22 deletions(-) diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi index eafe02d7f..b0d7ccc0a 100644 --- a/doc/source-code-chapter.texi +++ b/doc/source-code-chapter.texi @@ -480,7 +480,7 @@ each more specific than the last. remote machine[fn:2]. An example is #+begin_example -,#+begin_src R :file plot.png :dir /dand@yakuba.princeton.edu: +,#+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu: plot(1:10, main=system("hostname", intern=TRUE)) ,#+end_src #+end_example @@ -494,7 +494,7 @@ So in the above example a plot will be created on the remote machine, and a link of the following form will be inserted in the org buffer: #+begin_example -[[file:/scp:dand@yakuba.princeton.edu:/home/dand/plot.png][plot.png]] +[[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]] #+end_example Most of this functionality follows immediately from the fact that @@ -964,7 +964,7 @@ Be sure to adjust the paths to fit your system. FILES="" # wrap each argument in the code required to call tangle on it - for i in $@; do + for i in $@@; do FILES="$FILES \"$i\"" done @@ -985,22 +985,3 @@ Be sure to adjust the paths to fit your system. [fn:2] As long as the interpreter executable is found on the remote machine: see the variable =tramp-remote-path= - - -@section HTML 1 :noexport: - -#+begin_html - -#+end_html - -@subsection Note - - HTML 1 was keeping the babelfish code from exporting. Not sure - why or if the code itself is necessary, but moving it here gets - the fish on the page. From a465cff872fc1329f7106cdbb404e322bc62243d Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 12:21:57 -0400 Subject: [PATCH 003/138] Wrap verbatim examples in @example ... @end example Note that there are some cases where the #+begin_src itself is part of the example, and others where only the body of the source block is the example. --- doc/source-code-chapter.texi | 216 ++++++++++++++++++----------------- 1 file changed, 112 insertions(+), 104 deletions(-) diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi index b0d7ccc0a..c2e93d742 100644 --- a/doc/source-code-chapter.texi +++ b/doc/source-code-chapter.texi @@ -8,10 +8,11 @@ @subsection Source Code Block The basic syntax of source code blocks in Org-babel is as follows: -: #+begin_src language header-arguments -: body -: #+end_src - +@example +#+begin_src language header-arguments +body +#+end_src +@end example - language :: The language of the code in the source code block. Valid values must be members of =org-babel-interpreters=. - header-arguments :: Header arguments control many facets of the @@ -26,10 +27,12 @@ The basic syntax of source code blocks in Org-babel is as follows: This syntax can be expanded by naming the source code block. -: #+source: name -: #+begin_src language header-arguments -: -: #+end_src +@example +#+sourcename +#+begin_src language header-arguments +body +#+end_src +@end example - name :: This name is associated with the source code block. This is similar to the =#+tblname= lines that can be used to name tables @@ -42,33 +45,35 @@ This syntax can be expanded by naming the source code block. @subsection Library of Babel [[file:library-of-babel.org][Library of Babel]] functions can be called using the following syntax. -: #+lob: R-plot(data=R-plot-example-data) +@example +#+lob: R-plot(data=R-plot-example-data) +@end example @subsection Aliases Keyword aliases are intended to make Org-babel feel natural to programmers fluent in a variety of languages. For example, - #+begin_example - ,#+srcname: alias-example - ,#+begin_src emacs-lisp + @example + #+srcname: alias-example + #+begin_src emacs-lisp '((call lob) (source function srcname) (results resname)) - ,#+end_src + #+end_src - ,#+results: alias-example + #+results: alias-example | call | lob | | | source | function | srcname | | results | resname | | - #+end_example + @end example - =#+srcname:= can be replaced with either of two aliases, =#+source:= or =#+function:=. - =#+results:= can be replaced with its alias, =#+resname:=. When calling Library of Babel functions, as in the following example, there are two acceptable keywords. The =#+lob= call in the example could be replaced with its alias, =#+call=. - #+begin_example - ,#+lob: R-plot(data=R-plot-example-data) - #+end_example + @example + #+lob: R-plot(data=R-plot-example-data) + @end example @section Languages :PROPERTIES: @@ -107,9 +112,9 @@ This syntax can be expanded by naming the source code block. are met, then add a line like the following to your Emacs configuration, (replace "identifier" with one of the entries in the Identifier column of the table). - #+begin_src emacs-lisp + @example (require 'org-babel-identifier) - #+end_src + @end example @section Header Arguments :PROPERTIES: @@ -133,7 +138,7 @@ each more specific than the last. System-wide values of header arguments can be specified by customizing the =org-babel-default-header-args= variable: - #+begin_example + @example org-babel-default-header-args is a variable defined in `org-babel.el'. Its value is ((:session . "none") @@ -145,16 +150,16 @@ each more specific than the last. Documentation: Default arguments to use when evaluating a source block. - #+end_example + @end example [[#default-noweb]] For example, the following example could be used to set the default value of =:noweb= header arguments to =yes=. This would have the effect of expanding =:noweb= references by default when evaluating source code blocks. - #+begin_src emacs-lisp :results silent :exports code + @example (setq org-babel-default-header-args (cons '(:noweb . "yes") (assq-delete-all :noweb org-babel-default-header-args))) - #+end_src + @end example *** Org-mode Properties @@ -162,13 +167,13 @@ each more specific than the last. means they can be set on the outline header level. For example, the value of the =:cache= header argument will default to true in all source code blocks under the following example of an Org-mode outline header: - #+begin_example - ,* outline header + @example + * outline header :PROPERTIES: :cache: yes :CUSTOM_ID: property-set-header-arguments :END: - #+end_example + @end example Properties defined in this way override the properties set in =org-babel-default-header-args=. It is convenient to use the =org-set-property= function bound to =C-c C-x p= to set properties @@ -189,13 +194,13 @@ each more specific than the last. header argument is set to =code=, meaning only the body of the source code block will be preserved on export to HTML or LaTeX. - #+begin_example - ,#+source: factorial - ,#+begin_src haskell :results silent :exports code + @example + #+source: factorial + #+begin_src haskell :results silent :exports code fac 0 = 1 fac n = n * fac (n-1) - ,#+end_src - #+end_example + #+end_src + @end example @subsection Specific Header Arguments :PROPERTIES: @@ -223,64 +228,64 @@ each more specific than the last. The following syntax is used to pass arguments to source code blocks using the =:var= header argument. - #+begin_example + @example :var name=assign - #+end_example + @end example where =assign= can take one of the following forms - literal value :: either a string ="string"= or a number =9=. - reference :: a table name: - #+begin_example - ,#+tblname: example-table + @example + #+tblname: example-table | 1 | | 2 | | 3 | | 4 | - ,#+source: table-length - ,#+begin_src emacs-lisp :var table=example-table + #+source: table-length + #+begin_src emacs-lisp :var table=example-table (length table) - ,#+end_src + #+end_src - ,#+results: table-length + #+results: table-length : 4 - #+end_example + @end example a source code block name, as assigned by =#+srcname:=, followed by parentheses: - #+begin_example - ,#+begin_src emacs-lisp :var length=table-length() + @example + #+begin_src emacs-lisp :var length=table-length() (* 2 length) - ,#+end_src + #+end_src - ,#+results: + #+results: : 8 - #+end_example + @end example In addition, an argument can be passed to the source code block referenced by =:var=. The argument is passed within the parentheses following the source code block name: - #+begin_example - ,#+source: double - ,#+begin_src emacs-lisp :var input=8 + @example + #+source: double + #+begin_src emacs-lisp :var input=8 (* 2 input) - ,#+end_src + #+end_src - ,#+results: double + #+results: double : 16 - ,#+source: squared - ,#+begin_src emacs-lisp :var input=double(input=1) + #+source: squared + #+begin_src emacs-lisp :var input=double(input=1) (* input input) - ,#+end_src + #+end_src - ,#+results: squared + #+results: squared : 4 - #+end_example + @end example **** alternate argument syntax :PROPERTIES: @@ -291,12 +296,12 @@ each more specific than the last. natural way using the =#+source:= line of a source code block. As in the following example arguments can be packed inside of parenthesis following the source name. - #+begin_example - ,#+source: double(input=0) - ,#+begin_src emacs-lisp + @example + #+source: double(input=0) + #+begin_src emacs-lisp (* 2 input) - ,#+end_src - #+end_example + #+end_src + @end example **** indexable variable values :PROPERTIES: @@ -308,9 +313,9 @@ each more specific than the last. assigns the second and third rows of the table =example-table= to the variable =data=: - #+begin_example + @example :var data=example-table[1:2] - #+end_example + @end example *Note:* ranges are indexed using the =:= operator. @@ -319,9 +324,9 @@ each more specific than the last. The following example assigns the second column of the first row of =example-table= to =data=: - #+begin_example + @example :var data=example-table[0,1] - #+end_example + @end example It is possible to index into the results of source code blocks as well as tables. Any number of dimensions can be indexed. @@ -330,7 +335,7 @@ each more specific than the last. For more information on indexing behavior see the documentation for the =org-babel-ref-index-list= function -- provided below. - #+begin_example + @example org-babel-ref-index-list is a Lisp function in `org-babel-ref.el'. (org-babel-ref-index-list INDEX LIS) @@ -340,7 +345,7 @@ each more specific than the last. next deepest nesting or dimension. A valid PORTION can consist of either an integer index, or two integers separated by a : in which case the entire range is returned. - #+end_example + @end example *Note:* In Emacs, the documentation for any function or variable can be read using the =describe-function= (M-x describe @@ -468,22 +473,22 @@ each more specific than the last. In other words, if you want your plot to go into a folder called Work in your home directory, you could use -#+begin_example - ,#+begin_src R :file myplot.png :dir ~/Work +@example + #+begin_src R :file myplot.png :dir ~/Work matplot(matrix(rnorm(100), 10), type="l") - ,#+end_src -#+end_example + #+end_src +@end example **** Remote execution A directory on a remote machine can be specified using [[http://www.gnu.org/software/tramp/#Filename-Syntax][tramp filename syntax]], in which case the code will be executed on the remote machine[fn:2]. An example is -#+begin_example -,#+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu: +@example +#+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu: plot(1:10, main=system("hostname", intern=TRUE)) -,#+end_src -#+end_example +#+end_src +@end example Text results will be returned to the local org buffer as normal, and file output will be created on the remote machine with relative paths @@ -493,9 +498,9 @@ remote file will be created. So in the above example a plot will be created on the remote machine, and a link of the following form will be inserted in the org buffer: -#+begin_example +@example [[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]] -#+end_example +@end example Most of this functionality follows immediately from the fact that =:dir= sets the value of the emacs variable =default-directory=, @@ -591,17 +596,17 @@ above features to work correctly. This source code block: - #+begin_example + @example -- <> - #+end_example + @end example expands to: - #+begin_example + @example -- this is the -- multi-line body of example - #+end_example + @end example Note that noweb replacement text that does *not* contain any newlines will not be affected by this change, so it is still @@ -683,6 +688,7 @@ above features to work correctly. non-interactive interpreter running as an external process. For example, compare the following two blocks: +@example #+begin_src python :results output print "hello" 2 @@ -692,9 +698,10 @@ above features to work correctly. #+resname: : hello : bye +@end example In non-session mode, the '2' is not printed and does not appear. - +@example #+begin_src python :results output :session print "hello" 2 @@ -705,6 +712,7 @@ above features to work correctly. : hello : 2 : bye +@end example But in =:session= mode, the interactive interpreter receives input '2' and prints out its value, '2'. (Indeed, the other print statements are @@ -776,7 +784,7 @@ above features to work correctly. :CUSTOM_ID: function-org-babel-execute-src-block :END: -#+begin_example +@example org-babel-execute-src-block is an interactive Lisp function in `org-babel.el'. @@ -793,14 +801,14 @@ above features to work correctly. Optionally supply a value for PARAMS which will be merged with the header arguments specified at the front of the source code block. -#+end_example +@end example *** org-babel-open-src-block-result :PROPERTIES: :CUSTOM_ID: function-org-babel-open-src-block-result :END: -#+begin_example +@example org-babel-open-src-block-result is an interactive Lisp function in `org-babel.el'. @@ -810,14 +818,14 @@ above features to work correctly. source code block, otherwise return nil. With optional prefix argument RE-RUN the source-code block is evaluated even if results already exist. -#+end_example +@end example *** org-babel-load-in-session :PROPERTIES: :CUSTOM_ID: function-org-babel-load-in-session :END: -#+begin_example +@example org-babel-load-in-session is an interactive Lisp function in `org-babel.el'. @@ -828,14 +836,14 @@ above features to work correctly. session. After loading the body this pops open the session. [back] -#+end_example +@end example *** org-babel-pop-to-session :PROPERTIES: :CUSTOM_ID: function-org-babel-pop-to-session :END: -#+begin_example +@example org-babel-pop-to-session is an interactive Lisp function in `org-babel.el'. @@ -847,14 +855,14 @@ above features to work correctly. of the source block to the kill ring. [back] -#+end_example +@end example *** org-babel-tangle :PROPERTIES: :CUSTOM_ID: function-org-babel-tangle :END: -#+begin_example +@example org-babel-tangle is an interactive Lisp function in `org-babel-tangle.el'. @@ -867,14 +875,14 @@ above features to work correctly. TARGET-FILE can be used to specify a default export file for all source blocks. Optional argument LANG can be used to limit the exported source code blocks by language. -#+end_example +@end example *** org-babel-execute-subtree :PROPERTIES: :CUSTOM_ID: function-org-babel-execute-subtree :END: -#+begin_example +@example org-babel-execute-subtree is an interactive Lisp function in `org-babel.el'. @@ -883,14 +891,14 @@ above features to work correctly. (org-babel-execute-subtree &optional ARG) Replace EVAL snippets in the entire subtree. -#+end_example +@end example *** org-babel-execute-buffer :PROPERTIES: :CUSTOM_ID: function-org-babel-execute-buffer :END: -#+begin_example +@example org-babel-execute-buffer is an interactive Lisp function in `org-babel.el'. @@ -899,14 +907,14 @@ above features to work correctly. (org-babel-execute-buffer &optional ARG) Replace EVAL snippets in the entire buffer. -#+end_example +@end example *** org-babel-sha1-hash :PROPERTIES: :CUSTOM_ID: function-org-babel-sha1-hash :END: -#+begin_example +@example org-babel-sha1-hash is an interactive Lisp function in `org-babel.el'. It is bound to C-c M-b h. @@ -914,14 +922,14 @@ above features to work correctly. (org-babel-sha1-hash &optional INFO) Not documented. -#+end_example +@end example *** org-babel-goto-named-source-block :PROPERTIES: :CUSTOM_ID: function-org-babel-goto-named-source-block :END: -#+begin_example +@example org-babel-goto-named-source-block is an interactive Lisp function in `org-babel.el'. @@ -930,14 +938,14 @@ above features to work correctly. (org-babel-goto-named-source-block &optional NAME) Go to a named source-code block. -#+end_example +@end example *** org-babel-lob-ingest :PROPERTIES: :CUSTOM_ID: function-org-babel-lob-ingest :END: -#+begin_example +@example org-babel-lob-ingest is an interactive Lisp function in `org-babel-lob.el'. @@ -946,7 +954,7 @@ above features to work correctly. (org-babel-lob-ingest &optional FILE) Add all source-blocks defined in FILE to `org-babel-library-of-babel'. -#+end_example +@end example @section Batch Execution It is possible to call Org-babel functions from the command line. @@ -954,7 +962,7 @@ This shell script calls [[function-org-babel-tangle][org-babel-tangle]] on every arguments. Be sure to adjust the paths to fit your system. -#+begin_src sh +@example #!/bin/sh # -*- mode: shell-script -*- # @@ -977,7 +985,7 @@ Be sure to adjust the paths to fit your system. (find-file (expand-file-name file \"$DIR\")) (org-babel-tangle) (kill-buffer)) '($FILES)))" -#+end_src +@end example @section Footnotes From 50716ee1e73bdc92340c82c5dd49afd982187077 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 12:28:25 -0400 Subject: [PATCH 004/138] Convert level 3 headings to @subsubsections --- doc/source-code-chapter.texi | 44 ++++++++++++++++++------------------ 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi index c2e93d742..9b2be2c05 100644 --- a/doc/source-code-chapter.texi +++ b/doc/source-code-chapter.texi @@ -131,7 +131,7 @@ language-specific header arguments. The values of header arguments can be set in three different ways, each more specific than the last. -*** System-wide +@subsubsection System-wide :PROPERTIES: :CUSTOM_ID: system-wide-header-argument :END: @@ -161,7 +161,7 @@ each more specific than the last. (assq-delete-all :noweb org-babel-default-header-args))) @end example -*** Org-mode Properties +@subsubsection Org-mode Properties Header arguments are also read from [[http://orgmode.org/manual/Properties-and-Columns.html#Properties-and-Columns][Org-mode properties]], which means they can be set on the outline header level. For example, the @@ -179,7 +179,7 @@ each more specific than the last. =org-set-property= function bound to =C-c C-x p= to set properties in Org-mode documents. -*** Source Code Block +@subsubsection Source Code Block :PROPERTIES: :CUSTOM_ID: single-block-header-arguments :END: @@ -207,7 +207,7 @@ each more specific than the last. :CUSTOM_ID: header-argument-specific-documentation :END: -*** =:var= +@subsubsection =:var= :PROPERTIES: :CUSTOM_ID: header-argument-var :END: @@ -352,7 +352,7 @@ each more specific than the last. function) and =describe-variable= (M-x describe variable) functions, respectively. -*** =:results= +@subsubsection =:results= :PROPERTIES: :CUSTOM_ID: header-argument-results :END: @@ -430,7 +430,7 @@ each more specific than the last. into the Org-mode buffer. E.g., =:results output replace=. -*** =:file= +@subsubsection =:file= :PROPERTIES: :CUSTOM_ID: header-argument-file :END: @@ -453,7 +453,7 @@ each more specific than the last. While the =:file= header argument can be used to specify the path to the output file, -*** =:dir= and remote execution +@subsubsection =:dir= and remote execution :PROPERTIES: :CUSTOM_ID: header-argument-dir :END: @@ -521,7 +521,7 @@ above features to work correctly. default-directory is altered using =:dir=, it it probable that the file will be created in a location to which the link does not point. -*** =:exports= +@subsubsection =:exports= :PROPERTIES: :CUSTOM_ID: header-argument-exports :END: @@ -538,7 +538,7 @@ above features to work correctly. - none :: nothing is included in the exported file. E.g., =:exports none=. -*** =:tangle= +@subsubsection =:tangle= :PROPERTIES: :CUSTOM_ID: tangle-header-arguments :END: @@ -555,7 +555,7 @@ above features to work correctly. is interpreted as a file basename to which the block will be exported. E.g., =:tangle basename=. -*** =:session= +@subsubsection =:session= :PROPERTIES: :CUSTOM_ID: header-argument-session :END: @@ -570,7 +570,7 @@ above features to work correctly. session a name. This makes it possible to run concurrent sessions for each interpreted language. -*** =:noweb= +@subsubsection =:noweb= :PROPERTIES: :CUSTOM_ID: header-argument-noweb :END: @@ -614,7 +614,7 @@ above features to work correctly. Thanks to Sébastien Vauban for this idea. -*** =:cache= +@subsubsection =:cache= :PROPERTIES: :CUSTOM_ID: header-argument-cache :END: @@ -779,7 +779,7 @@ above features to work correctly. @subsection Functions -*** org-babel-execute-src-block +@subsubsection org-babel-execute-src-block :PROPERTIES: :CUSTOM_ID: function-org-babel-execute-src-block :END: @@ -803,7 +803,7 @@ above features to work correctly. block. @end example -*** org-babel-open-src-block-result +@subsubsection org-babel-open-src-block-result :PROPERTIES: :CUSTOM_ID: function-org-babel-open-src-block-result :END: @@ -820,7 +820,7 @@ above features to work correctly. results already exist. @end example -*** org-babel-load-in-session +@subsubsection org-babel-load-in-session :PROPERTIES: :CUSTOM_ID: function-org-babel-load-in-session :END: @@ -838,7 +838,7 @@ above features to work correctly. [back] @end example -*** org-babel-pop-to-session +@subsubsection org-babel-pop-to-session :PROPERTIES: :CUSTOM_ID: function-org-babel-pop-to-session :END: @@ -857,7 +857,7 @@ above features to work correctly. [back] @end example -*** org-babel-tangle +@subsubsection org-babel-tangle :PROPERTIES: :CUSTOM_ID: function-org-babel-tangle :END: @@ -877,7 +877,7 @@ above features to work correctly. exported source code blocks by language. @end example -*** org-babel-execute-subtree +@subsubsection org-babel-execute-subtree :PROPERTIES: :CUSTOM_ID: function-org-babel-execute-subtree :END: @@ -893,7 +893,7 @@ above features to work correctly. Replace EVAL snippets in the entire subtree. @end example -*** org-babel-execute-buffer +@subsubsection org-babel-execute-buffer :PROPERTIES: :CUSTOM_ID: function-org-babel-execute-buffer :END: @@ -909,7 +909,7 @@ above features to work correctly. Replace EVAL snippets in the entire buffer. @end example -*** org-babel-sha1-hash +@subsubsection org-babel-sha1-hash :PROPERTIES: :CUSTOM_ID: function-org-babel-sha1-hash :END: @@ -924,7 +924,7 @@ above features to work correctly. Not documented. @end example -*** org-babel-goto-named-source-block +@subsubsection org-babel-goto-named-source-block :PROPERTIES: :CUSTOM_ID: function-org-babel-goto-named-source-block :END: @@ -940,7 +940,7 @@ above features to work correctly. Go to a named source-code block. @end example -*** org-babel-lob-ingest +@subsubsection org-babel-lob-ingest :PROPERTIES: :CUSTOM_ID: function-org-babel-lob-ingest :END: From 59193e2e2c10ae33823a84e329e832e8a1a179dd Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 12:35:17 -0400 Subject: [PATCH 005/138] Add an example block that was missed --- doc/source-code-chapter.texi | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi index 9b2be2c05..aeee0f545 100644 --- a/doc/source-code-chapter.texi +++ b/doc/source-code-chapter.texi @@ -760,6 +760,7 @@ above features to work correctly. Org-babel also exposes a number of functions behind the common =org-babel-key-prefix= of =C-c M-b=: +@example #+begin_src emacs-lisp :exports none (lambda (binding (list (format "\\C-c \\M-b %s" @@ -768,6 +769,8 @@ above features to work correctly. (cdr binding) (cdr binding)))) org-babel-key-bindings) #+end_src +@end example + | =C-c M-b t= | [[function-org-babel-tangle][org-babel-tangle]] | | =C-c M-b T= | [[function-org-babel-tangle-file][org-babel-tangle-file]] | | =C-c M-b e= | [[function-org-babel-execute-src-block][org-babel-execute-src-block]] | @@ -777,7 +780,6 @@ above features to work correctly. | =C-c M-b g= | [[function-org-babel-goto-named-source-block][org-babel-goto-named-source-block]] | | =C-c M-b l= | [[function-org-babel-lob-ingest][org-babel-lob-ingest]] | - @subsection Functions @subsubsection org-babel-execute-src-block :PROPERTIES: From 787e2746a55a8506c3cd27466d5709cae1b78441 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 12:42:43 -0400 Subject: [PATCH 006/138] Convert level 4 headings to subsubheadings. Also some promotion of some of the most deeply nested headings. --- doc/source-code-chapter.texi | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi index aeee0f545..90851c0aa 100644 --- a/doc/source-code-chapter.texi +++ b/doc/source-code-chapter.texi @@ -287,7 +287,7 @@ each more specific than the last. : 4 @end example -**** alternate argument syntax +@subsubheading alternate argument syntax :PROPERTIES: :CUSTOM_ID: alternate-argument-syntax :END: @@ -369,7 +369,7 @@ each more specific than the last. *Note:* only one option from each type may be supplied per source code block. -**** collection +@subsubheading collection :PROPERTIES: :CUSTOM_ID: header-argument-results-collection :END: @@ -388,7 +388,7 @@ each more specific than the last. block. This header argument places Org-babel in scripting mode. E.g., =:results output=. -**** type +@subsubheading type The following options are mutually exclusive and specify what type of results the code block will return. By default, results are inserted as either a *table* or *scalar* depending on their @@ -419,7 +419,7 @@ each more specific than the last. enclosed in a code block. This option currently supports Emacs Lisp, python, and ruby. E.g., =:results value pp=. -**** handling +@subsubheading handling The following results options indicate what Org-babel should do with the results once they are collected. @@ -479,7 +479,7 @@ each more specific than the last. #+end_src @end example -**** Remote execution +@subsubheading Remote execution A directory on a remote machine can be specified using [[http://www.gnu.org/software/tramp/#Filename-Syntax][tramp filename syntax]], in which case the code will be executed on the remote machine[fn:2]. An example is @@ -508,7 +508,7 @@ thanks to [[http://www.gnu.org/software/tramp/][tramp]]. Those using XEmacs, or version 23 may need to install tramp separately in order for the above features to work correctly. -**** Further points +@subsubheading Further points - If =:dir= is used in conjunction with =:session=, although it will determine the starting directory for a new session as expected, no attempt is currently made to alter the directory @@ -584,7 +584,7 @@ above features to work correctly. - =yes= :: all [[noweb-reference-syntax][noweb syntax]] references in the body of the source code block will be expanded before the block is evaluated. -**** Noweb Prefix Lines +@subsubheading Noweb Prefix Lines Noweb insertions are now placed behind the line prefix of the =<>=. @@ -652,8 +652,8 @@ above features to work correctly. non-session is returned to Org-mode as a table (a one- or two-dimensional vector of strings or numbers) when appropriate. -**** Non-session -***** =:results value= +@subsection Non-session +@subsubsection =:results value= This is the default. Internally, the value is obtained by wrapping the code in a function definition in the external language, and evaluating that function. Therefore, code should be @@ -665,21 +665,21 @@ above features to work correctly. This is the only one of the four evaluation contexts in which the code is automatically wrapped in a function definition. -***** =:results output= +@subsubsection =:results output= The code is passed to the interpreter as an external process, and the contents of the standard output stream are returned as text. (In certain languages this also contains the error output stream; this is an area for future work.) -**** =:session= -***** =:results value= +@subsection =:session= +@subsubsection =:results value= The code is passed to the interpreter running as an interactive Emacs inferior process. The result returned is the result of the last evaluation performed by the interpreter. (This is obtained in a language-specific manner: the value of the variable =_= in python and ruby, and the value of =.Last.value= in R). -***** =:results output= +@subsubsection =:results output= The code is passed to the interpreter running as an interactive Emacs inferior process. The result returned is the concatenation of the sequence of (text) output from the interactive @@ -688,6 +688,7 @@ above features to work correctly. non-interactive interpreter running as an external process. For example, compare the following two blocks: + @example #+begin_src python :results output print "hello" From a8616afcaca2293f6a84046303e9c4d72c4c0f49 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 14:57:09 -0400 Subject: [PATCH 007/138] Add material to introduction of source code chapter --- doc/source-code-chapter.texi | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi index 90851c0aa..d0ad56092 100644 --- a/doc/source-code-chapter.texi +++ b/doc/source-code-chapter.texi @@ -1,4 +1,31 @@ -@chapter Working with source code or Embedded Source Code +@chapter Working With Source Code or Embedded Source Code + +Source code can be included in Org-mode documents using a @samp{src} block: + +FIXME: This example is also in the Literal Examples section. +@example +#+BEGIN_SRC emacs-lisp +(defun org-xor (a b) + "Exclusive or." + (if a (not b) b)) +#+END_SRC +@end example + +Org supports the following ways of working with such code blocks: + +@itemize @bullet +@item +Editing in the appropriate Emacs major-mode (@kbd{C-c '}) +@item +Export with appropriate markup +@item +Extraction (``tangling'') into pure code files. +@item +Execution, with results captured in the Org buffer +@item +Using code blocks in table formulas +@end itemize + @section Syntax :PROPERTIES: From 36767ff4b659ebc937b560eb8c881686e3f81713 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 15:54:14 -0400 Subject: [PATCH 008/138] Working on syntax section --- doc/source-code-chapter.texi | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi index d0ad56092..b21fd7c02 100644 --- a/doc/source-code-chapter.texi +++ b/doc/source-code-chapter.texi @@ -36,27 +36,32 @@ Using code blocks in table formulas The basic syntax of source code blocks in Org-babel is as follows: @example -#+begin_src language header-arguments +#+begin_src language header-arguments switches body #+end_src @end example -- language :: The language of the code in the source code block. Valid - values must be members of =org-babel-interpreters=. -- header-arguments :: Header arguments control many facets of the - evaluation and output of source code blocks. See the [[header-arguments][Header - Arguments]] section for a complete review of available header - arguments. -- body :: The source code to be evaluated. An important key-binding - is C-c '. This calls =org-edit-src-code=, a function that brings - up an edit buffer containing the code using the Emacs major mode - appropriate to the language. You can edit your source code block - as you regularly would in Emacs. - +@table +@item language +The language of the code in the source code block. Valid values must +be members of =org-babel-interpreters=. +@item header-arguments +Header arguments control many facets of the evaluation and output of +source code blocks. See the [[header-arguments][Header Arguments]] +section for a complete review of available header arguments. +@item switches +FIXME link/relocate switches discussion in ``Literal examples'' section +@item body +The source code to be evaluated. An important key-binding is C-c '. +This calls =org-edit-src-code=, a function that brings up an edit +buffer containing the code using the Emacs major mode appropriate to +the language. You can edit your source code block as you regularly +would in Emacs. +@end table This syntax can be expanded by naming the source code block. @example #+sourcename -#+begin_src language header-arguments +#+begin_src language header-arguments switches body #+end_src @end example From 98957ed30038bbd8018190fb0695f01123c952df Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 22:09:36 -0400 Subject: [PATCH 009/138] Edits to initial sections --- doc/source-code-chapter.texi | 79 ++++++++++++++++++++++++------------ 1 file changed, 54 insertions(+), 25 deletions(-) diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi index b21fd7c02..9cce3ccc3 100644 --- a/doc/source-code-chapter.texi +++ b/doc/source-code-chapter.texi @@ -1,8 +1,7 @@ -@chapter Working With Source Code or Embedded Source Code +@chapter ``Working With Source Code'' or ``Embedded Source Code'' Source code can be included in Org-mode documents using a @samp{src} block: -FIXME: This example is also in the Literal Examples section. @example #+BEGIN_SRC emacs-lisp (defun org-xor (a b) @@ -11,52 +10,82 @@ FIXME: This example is also in the Literal Examples section. #+END_SRC @end example -Org supports the following ways of working with such code blocks: +Org provides the following features for working with such code blocks: @itemize @bullet @item -Editing in the appropriate Emacs major-mode (@kbd{C-c '}) +Editing in the appropriate Emacs major-mode (@ref{Editing Source Code}) @item -Export with appropriate markup +Export with appropriate markup (@ref{Exporting Code Blocks}) @item -Extraction (``tangling'') into pure code files. +Extraction (``tangling'') into pure code files. (@ref{Extracting Source Code}) @item -Execution, with results captured in the Org buffer +Code execution, with results captured in the Org buffer (@ref{Evaluating Code Blocks}) @item Using code blocks in table formulas @end itemize -@section Syntax - :PROPERTIES: - :CUSTOM_ID: syntax - :END: -@subsection Source Code Block -The basic syntax of source code blocks in Org-babel is as follows: +@section Structure of Code Blocks + +The basic structure of code blocks is as follows: @example +#+srcname: name #+begin_src language header-arguments switches body #+end_src @end example -@table + +@table @code +@item name +The initial name line is optional. If present it is used during code evaluation. @item language -The language of the code in the source code block. Valid values must -be members of =org-babel-interpreters=. +The language of the code in the block. @item header-arguments -Header arguments control many facets of the evaluation and output of -source code blocks. See the [[header-arguments][Header Arguments]] -section for a complete review of available header arguments. +Header arguments control evaluation, export and tangling of source +code blocks. See the [[header-arguments][Header Arguments]] section. @item switches FIXME link/relocate switches discussion in ``Literal examples'' section @item body -The source code to be evaluated. An important key-binding is C-c '. -This calls =org-edit-src-code=, a function that brings up an edit -buffer containing the code using the Emacs major mode appropriate to -the language. You can edit your source code block as you regularly -would in Emacs. +The code @end table + +@section Editing Source Code + +Use @kbd{C-c '} to edit the code block at point. This brings up a +language major-mode buffer containing the body of the code +block. Saving this buffer will write the new contents back to the Org +buffer. Use @kbd{C-c '} again to exit. + +The edit buffer has a minor mode active called +@code{org-src-mode}. The following variables can be used to configure +the behavior of the edit buffer. See also the customization group +@code{org-edit-structure} for futher configuration options. + +@table @code +@item org-src-lang-modes +If an emacs major-mode named @code{-mode} exists, where +@code{} is the language named in header line of the code block, +then the edit buffer will be placed in that major-mode. This variable +can be used to map arbitrary language names to existing major modes. +@item org-src-window-setup +Controls the way Emacs windows are rearranged when the edit buffer is created. +@item org-src-preserve-indentation +This variable is expecially useful for tangling languages such as +python, where whitespace the indentation in the output is critical. +@item org-src-ask-before-returning-to-edit-buffer +By default, Org will ask before returning to an open edit buffer. Set +to a non-nil value to switch without asking. +@end table + +@section Exporting Code Blocks + +@section Extracting Source Code + +@section Evaluating Code Blocks + This syntax can be expanded by naming the source code block. @example @@ -107,7 +136,7 @@ body #+lob: R-plot(data=R-plot-example-data) @end example -@section Languages +@subsection Languages :PROPERTIES: :CUSTOM_ID: languages :END: From 10010aa3260ed8a8893361ed44449fcb6ed1e7c5 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 22:10:17 -0400 Subject: [PATCH 010/138] Create texinfo node structures for new chapter --- doc/org.texi | 5 +++-- doc/source-code-chapter.texi | 25 +++++++++++++++++++++++++ 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 1b3e078c2..c5b55957a 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -108,6 +108,7 @@ license to the document, as described in section 6 of the license. * Markup:: Prepare text for rich export * Exporting:: Sharing and publishing of notes * Publishing:: Create a web site of linked Org files +* Working With Source Code:: Using Org for literate programming, reproducible research and code evaluation. * Miscellaneous:: All the rest which did not fit elsewhere * Hacking:: How to hack your way around * MobileOrg:: Viewing and capture on a mobile device @@ -10330,7 +10331,7 @@ and the description from the body (limited to How this calendar is best read and updated, depends on the application you are using. The FAQ covers this issue. -@node Publishing, Miscellaneous, Exporting, Top +@node Publishing, Working With Source Code, Exporting, Top @chapter Publishing @cindex publishing @cindex O'Toole, David @@ -10844,7 +10845,7 @@ This may be necessary in particular if files include other files via @include source-code-chapter.texi -@node Miscellaneous, Hacking, Publishing, Top +@node Miscellaneous, Hacking, Working With Source Code, Top @chapter Miscellaneous @menu diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi index 9cce3ccc3..dafe4365c 100644 --- a/doc/source-code-chapter.texi +++ b/doc/source-code-chapter.texi @@ -1,3 +1,6 @@ +@node Working With Source Code, Miscellaneous, Publishing, Top +@comment node-name, next, previous, up +@comment Working With Source Code, Miscellaneous, Publishing, Top @chapter ``Working With Source Code'' or ``Embedded Source Code'' Source code can be included in Org-mode documents using a @samp{src} block: @@ -25,8 +28,18 @@ Code execution, with results captured in the Org buffer (@ref{Evaluating Code Bl Using code blocks in table formulas @end itemize +@menu +* Structure of Code Blocks:: +* Editing Source Code:: +* Exporting Code Blocks:: +* Extracting Source Code:: +* Evaluating Code Blocks:: +@end menu +@node Structure of Code Blocks, Editing Source Code, Working With Source Code, Working With Source Code +@comment node-name, next, previous, up +@comment Structure of Code Blocks, Editing Source Code, Working With Source Code, Working With Source Code @section Structure of Code Blocks The basic structure of code blocks is as follows: @@ -52,6 +65,9 @@ FIXME link/relocate switches discussion in ``Literal examples'' section The code @end table +@node Editing Source Code, Exporting Code Blocks, Structure of Code Blocks, Working With Source Code +@comment node-name, next, previous, up +@comment Editing Source Code, Exporting Code Blocks, Structure of Code Blocks, Working With Source Code @section Editing Source Code Use @kbd{C-c '} to edit the code block at point. This brings up a @@ -80,10 +96,19 @@ By default, Org will ask before returning to an open edit buffer. Set to a non-nil value to switch without asking. @end table +@node Exporting Code Blocks, Extracting Source Code, Editing Source Code, Working With Source Code +@comment node-name, next, previous, up +@comment Exporting Code Blocks, Extracting Source Code, Editing Source Code, Working With Source Code @section Exporting Code Blocks +@node Extracting Source Code, Evaluating Code Blocks, Exporting Code Blocks, Working With Source Code +@comment node-name, next, previous, up +@comment Extracting Source Code, Evaluating Code Blocks, Exporting Code Blocks, Working With Source Code @section Extracting Source Code +@node Evaluating Code Blocks, , Extracting Source Code, Working With Source Code +@comment node-name, next, previous, up +@comment Evaluating Code Blocks, , Extracting Source Code, Working With Source Code @section Evaluating Code Blocks This syntax can be expanded by naming the source code block. From e25035855fbe576121df558c8ca00d658b392e00 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 22:12:41 -0400 Subject: [PATCH 011/138] Move new chapter into main org.texi file It is currently impractical to work with it as an @included file, because the automatic node pointer updates do not work by default. --- doc/org.texi | 1085 +++++++++++++++++++++++++++++++++- doc/source-code-chapter.texi | 1084 --------------------------------- 2 files changed, 1084 insertions(+), 1085 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index c5b55957a..22d5b9fdd 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10843,7 +10843,1090 @@ above, or by customizing the variable @code{org-publish-use-timestamps-flag}. This may be necessary in particular if files include other files via @code{#+SETUPFILE:} or @code{#+INCLUDE:}. -@include source-code-chapter.texi +@node Working With Source Code, Miscellaneous, Publishing, Top +@comment node-name, next, previous, up +@comment Working With Source Code, Miscellaneous, Publishing, Top +@chapter ``Working With Source Code'' or ``Embedded Source Code'' + +Source code can be included in Org-mode documents using a @samp{src} block: + +@example +#+BEGIN_SRC emacs-lisp +(defun org-xor (a b) + "Exclusive or." + (if a (not b) b)) +#+END_SRC +@end example + +Org provides the following features for working with such code blocks: + +@itemize @bullet +@item +Editing in the appropriate Emacs major-mode (@ref{Editing Source Code}) +@item +Export with appropriate markup (@ref{Exporting Code Blocks}) +@item +Extraction (``tangling'') into pure code files. (@ref{Extracting Source Code}) +@item +Code execution, with results captured in the Org buffer (@ref{Evaluating Code Blocks}) +@item +Using code blocks in table formulas +@end itemize + +@menu +* Structure of Code Blocks:: +* Editing Source Code:: +* Exporting Code Blocks:: +* Extracting Source Code:: +* Evaluating Code Blocks:: +@end menu + + +@node Structure of Code Blocks, Editing Source Code, Working With Source Code, Working With Source Code +@comment node-name, next, previous, up +@comment Structure of Code Blocks, Editing Source Code, Working With Source Code, Working With Source Code +@section Structure of Code Blocks + +The basic structure of code blocks is as follows: + +@example +#+srcname: name +#+begin_src language header-arguments switches +body +#+end_src +@end example + +@table @code +@item name +The initial name line is optional. If present it is used during code evaluation. +@item language +The language of the code in the block. +@item header-arguments +Header arguments control evaluation, export and tangling of source +code blocks. See the [[header-arguments][Header Arguments]] section. +@item switches +FIXME link/relocate switches discussion in ``Literal examples'' section +@item body +The code +@end table + +@node Editing Source Code, Exporting Code Blocks, Structure of Code Blocks, Working With Source Code +@comment node-name, next, previous, up +@comment Editing Source Code, Exporting Code Blocks, Structure of Code Blocks, Working With Source Code +@section Editing Source Code + +Use @kbd{C-c '} to edit the code block at point. This brings up a +language major-mode buffer containing the body of the code +block. Saving this buffer will write the new contents back to the Org +buffer. Use @kbd{C-c '} again to exit. + +The edit buffer has a minor mode active called +@code{org-src-mode}. The following variables can be used to configure +the behavior of the edit buffer. See also the customization group +@code{org-edit-structure} for futher configuration options. + +@table @code +@item org-src-lang-modes +If an emacs major-mode named @code{-mode} exists, where +@code{} is the language named in header line of the code block, +then the edit buffer will be placed in that major-mode. This variable +can be used to map arbitrary language names to existing major modes. +@item org-src-window-setup +Controls the way Emacs windows are rearranged when the edit buffer is created. +@item org-src-preserve-indentation +This variable is expecially useful for tangling languages such as +python, where whitespace the indentation in the output is critical. +@item org-src-ask-before-returning-to-edit-buffer +By default, Org will ask before returning to an open edit buffer. Set +to a non-nil value to switch without asking. +@end table + +@node Exporting Code Blocks, Extracting Source Code, Editing Source Code, Working With Source Code +@comment node-name, next, previous, up +@comment Exporting Code Blocks, Extracting Source Code, Editing Source Code, Working With Source Code +@section Exporting Code Blocks + +@node Extracting Source Code, Evaluating Code Blocks, Exporting Code Blocks, Working With Source Code +@comment node-name, next, previous, up +@comment Extracting Source Code, Evaluating Code Blocks, Exporting Code Blocks, Working With Source Code +@section Extracting Source Code + +@node Evaluating Code Blocks, , Extracting Source Code, Working With Source Code +@comment node-name, next, previous, up +@comment Evaluating Code Blocks, , Extracting Source Code, Working With Source Code +@section Evaluating Code Blocks + +This syntax can be expanded by naming the source code block. + +@example +#+sourcename +#+begin_src language header-arguments switches +body +#+end_src +@end example + +- name :: This name is associated with the source code block. This is + similar to the =#+tblname= lines that can be used to name tables + in Org-mode files. Referencing the name of a source code + block makes it possible to evaluate the block from other places in + the file, other files, or inside Org-mode tables. It + is also possible to pass arguments to a source code block through + this =#+source:= line (see [[alternate-argument-syntax][Alternate argument syntax]]). + +@subsection Library of Babel +[[file:library-of-babel.org][Library of Babel]] functions can be called using the following syntax. + +@example +#+lob: R-plot(data=R-plot-example-data) +@end example + +@subsection Aliases + Keyword aliases are intended to make Org-babel feel natural to + programmers fluent in a variety of languages. For example, + @example + #+srcname: alias-example + #+begin_src emacs-lisp + '((call lob) + (source function srcname) + (results resname)) + #+end_src + + #+results: alias-example + | call | lob | | + | source | function | srcname | + | results | resname | | + @end example + - =#+srcname:= can be replaced with either of two aliases, =#+source:= or =#+function:=. + - =#+results:= can be replaced with its alias, =#+resname:=. + + When calling Library of Babel functions, as in the following + example, there are two acceptable keywords. The =#+lob= call in + the example could be replaced with its alias, =#+call=. + @example + #+lob: R-plot(data=R-plot-example-data) + @end example + +@subsection Languages + :PROPERTIES: + :CUSTOM_ID: languages + :END: + + Org-babel has support for the following languages. + + | Language | Documentation | Identifier | Requirements | + |----------------+-----------------------------+------------+---------------------------------------------| + | Asymptote | org-babel-doc-asymptote | asymptote | [[http://asymptote.sourceforge.net/][asymptote]], [[http://asymptote.sourceforge.net/doc/Editing-modes.html][asy-mode]] | + | C | [[file:languages/org-babel-doc-C.org][org-babel-doc-C]] | C | none | + | Clojure | [[file:languages/org-babel-doc-clojure.org][org-babel-doc-clojure]] | clojure | [[http://clojure.org/][clojure]], [[http://www.emacswiki.org/emacs/clojure-mode.el][clojure-mode]], [[http://common-lisp.net/project/slime/][slime]], [[http://clojure.codestuffs.com/][swank-clojure]] | + | css | org-babel-doc-css | css | none | + | ditaa | org-babel-doc-ditaa | ditaa | [[http://ditaa.org/ditaa/][ditaa]] (bundled with Org-mode) | + | Graphviz | org-babel-doc-dot | dot | [[http://www.graphviz.org/][dot]] | + | Emacs Lisp | org-babel-doc-emacs-lisp | emacs-lisp | none | + | gnuplot | org-babel-doc-gnuplot | gnuplot | [[http://www.gnuplot.info/][gnuplot]], [[http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html][gnuplot-mode]] | + | Haskell | org-babel-doc-haskell | haskell | [[http://www.haskell.org/][haskell]], [[http://projects.haskell.org/haskellmode-emacs/][haskell-mode]], [[http://www.haskell.org/haskellwiki/Haskell_mode_for_Emacs#inf-haskell.el:_the_best_thing_since_the_breadknife][inf-haskell]], [[http://people.cs.uu.nl/andres/lhs2tex/][lhs2tex]] | + | Matlab | [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] | matlab | matlab, [[http://sourceforge.net/projects/matlab-emacs/][matlab.el]] | + | LaTeX | [[file:languages/org-babel-doc-LaTeX.org][org-babel-doc-latex]] | latex | [[http://www.latex-project.org/][latex]], [[http://www.gnu.org/software/auctex/][auctex]], [[http://www.gnu.org/software/auctex/reftex.html][reftex]] | + | Objective Caml | org-babel-doc-ocaml | ocaml | [[http://caml.inria.fr/][ocaml]], [[http://www-rocq.inria.fr/~acohen/tuareg/][tuareg-mode]] | + | Octave | [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] | octave | octave | + | OZ | [[file:languages/org-babel-doc-oz.org][org-babel-doc-oz]] | oz | [[http://www.mozart-oz.org/][Mozart]] which includes a major mode | + | Perl | org-babel-doc-perl | perl | [[http://www.perl.org/][perl]], [[http://www.emacswiki.org/emacs/CPerlMode][cperl-mode]] (optional) | + | Python | org-babel-doc-python | python | [[http://www.python.org/][python]], [[https://launchpad.net/python-mode][python-mode]] (optional) | + | R | [[file:languages/org-babel-doc-R.org][org-babel-doc-R]] | R | [[http://www.r-project.org/][R]], [[http://ess.r-project.org/][ess-mode]] | + | Ruby | org-babel-doc-ruby | ruby | [[http://www.ruby-lang.org/][ruby]], [[http://www.ruby-lang.org/][irb]], [[http://github.com/eschulte/rinari/raw/master/util/ruby-mode.el][ruby-mode]], [[http://github.com/eschulte/rinari/raw/master/util/inf-ruby.el][inf-ruby mode]] | + | Sass | org-babel-doc-sass | sass | [[http://sass-lang.com/][sass]], [[http://github.com/nex3/haml/blob/master/extra/sass-mode.el][sass-mode]] | + | GNU Screen | [[file:languages/org-babel-doc-screen.org][org-babel-doc-screen]] | screen | [[http://www.gnu.org/software/screen/][screen]], a terminal | + | shell | org-babel-doc-sh | sh[fn:1] | a shell | + | SQL | org-babel-doc-sql | sql | none | + + To add support for a particular language to your Org-babel + installation first make sure that the requirements of the language + are met, then add a line like the following to your Emacs + configuration, (replace "identifier" with one of the + entries in the Identifier column of the table). + @example + (require 'org-babel-identifier) + @end example + +@section Header Arguments + :PROPERTIES: + :CUSTOM_ID: header-arguments + :END: + +Definitions of all Org-babel header arguments are given [[header-argument-specific-documentation][below]]. In +addition, some languages may add their own header arguments. Please +see the language-specific documentation for information on +language-specific header arguments. + +@subsection Using Header Arguments + +The values of header arguments can be set in three different ways, +each more specific than the last. + +@subsubsection System-wide + :PROPERTIES: + :CUSTOM_ID: system-wide-header-argument + :END: + + System-wide values of header arguments can be specified by + customizing the =org-babel-default-header-args= variable: + @example + org-babel-default-header-args is a variable defined in `org-babel.el'. + Its value is + ((:session . "none") + (:results . "replace") + (:exports . "code") + (:cache . "no") + (:noweb . "no")) + + + Documentation: + Default arguments to use when evaluating a source block. + @end example + [[#default-noweb]] + For example, the following example could be used to set the default value + of =:noweb= header arguments to =yes=. This would have the effect of + expanding =:noweb= references by default when evaluating source code blocks. + @example + (setq org-babel-default-header-args + (cons '(:noweb . "yes") + (assq-delete-all :noweb org-babel-default-header-args))) + @end example + +@subsubsection Org-mode Properties + + Header arguments are also read from [[http://orgmode.org/manual/Properties-and-Columns.html#Properties-and-Columns][Org-mode properties]], which + means they can be set on the outline header level. For example, the + value of the =:cache= header argument will default to true in all + source code blocks under the following example of an Org-mode outline header: + @example + * outline header + :PROPERTIES: + :cache: yes + :CUSTOM_ID: property-set-header-arguments + :END: + @end example + Properties defined in this way override the properties set in + =org-babel-default-header-args=. It is convenient to use the + =org-set-property= function bound to =C-c C-x p= to set properties + in Org-mode documents. + +@subsubsection Source Code Block + :PROPERTIES: + :CUSTOM_ID: single-block-header-arguments + :END: + The most common way to assign values to header arguments is at the + source code block level. This can be done by listing a sequence of + header arguments and their values as part of the =#+begin_src= + line. Properties set in this way override both the values of + =org-babel-default-header-args= and header argument specified as + properties. In the following example, the + =:results= header argument is set to =silent=, meaning the results + of execution will not be inserted in the buffer, and the =:exports= + header argument is set to =code=, meaning only the body of the + source code block + will be preserved on export to HTML or LaTeX. + @example + #+source: factorial + #+begin_src haskell :results silent :exports code + fac 0 = 1 + fac n = n * fac (n-1) + #+end_src + @end example + +@subsection Specific Header Arguments + :PROPERTIES: + :CUSTOM_ID: header-argument-specific-documentation + :END: + +@subsubsection =:var= + :PROPERTIES: + :CUSTOM_ID: header-argument-var + :END: + + The =:var= header argument is used to pass arguments to + source code blocks. The specifics of how arguments are included + in a source code block are language specific and are + addressed in the language-specific documentation. However, the + syntax used to specify arguments is the same across all + languages. The values passed to arguments can be or + - literal values + - values from org-mode tables + - the results of other source code blocks + + These values can be indexed in a manner similar to arrays -- see + [[var-argument-indexing][argument indexing]]. + + The following syntax is used to pass arguments to source code + blocks using the =:var= header argument. + + @example + :var name=assign + @end example + + where =assign= can take one of the following forms + + - literal value :: either a string ="string"= or a number =9=. + - reference :: a table name: + + @example + #+tblname: example-table + | 1 | + | 2 | + | 3 | + | 4 | + + #+source: table-length + #+begin_src emacs-lisp :var table=example-table + (length table) + #+end_src + + #+results: table-length + : 4 + @end example + + a source code block name, as assigned by =#+srcname:=, + followed by parentheses: + + @example + #+begin_src emacs-lisp :var length=table-length() + (* 2 length) + #+end_src + + #+results: + : 8 + @end example + + In addition, an argument can be passed to the source code + block referenced by =:var=. The argument is passed within + the parentheses following the source code block name: + + @example + #+source: double + #+begin_src emacs-lisp :var input=8 + (* 2 input) + #+end_src + + #+results: double + : 16 + + #+source: squared + #+begin_src emacs-lisp :var input=double(input=1) + (* input input) + #+end_src + + #+results: squared + : 4 + @end example + +@subsubheading alternate argument syntax + :PROPERTIES: + :CUSTOM_ID: alternate-argument-syntax + :END: + + It is also possible to specify arguments in a potentially more + natural way using the =#+source:= line of a source code block. + As in the following example arguments can be packed inside of + parenthesis following the source name. + @example + #+source: double(input=0) + #+begin_src emacs-lisp + (* 2 input) + #+end_src + @end example + +**** indexable variable values + :PROPERTIES: + :CUSTOM_ID: var-argument-indexing + :END: + + It is possible to assign a portion of a value to a + variable in a source block. The following example + assigns the second and third rows of the table + =example-table= to the variable =data=: + + @example + :var data=example-table[1:2] + @end example + + *Note:* ranges are indexed using the =:= operator. + + *Note:* indices are 0 based. + + The following example assigns the second column of the + first row of =example-table= to =data=: + + @example + :var data=example-table[0,1] + @end example + + It is possible to index into the results of source code blocks + as well as tables. Any number of dimensions can be indexed. + Dimensions are separated from one another by commas. + + For more information on indexing behavior see the documentation + for the =org-babel-ref-index-list= function -- provided below. + + @example + org-babel-ref-index-list is a Lisp function in `org-babel-ref.el'. + + (org-babel-ref-index-list INDEX LIS) + + Return the subset of LIS indexed by INDEX. If INDEX is + separated by ,s then each PORTION is assumed to index into the + next deepest nesting or dimension. A valid PORTION can consist + of either an integer index, or two integers separated by a : in + which case the entire range is returned. + @end example + + *Note:* In Emacs, the documentation for any function or variable + can be read using the =describe-function= (M-x describe + function) and =describe-variable= (M-x describe variable) + functions, respectively. + +@subsubsection =:results= + :PROPERTIES: + :CUSTOM_ID: header-argument-results + :END: + + There are three types of results header argument: + - *collection* header arguments specify how the results should be collected from + the source code block; + - *type* header arguments specify what type of result the source code block + will return -- which has implications for how they will be + inserted into the Org-mode buffer; and + - *handling* header arguments specify how the results of + evaluating the source code block should be handled. + + *Note:* only one option from each type may be supplied per source code + block. + +@subsubheading collection + :PROPERTIES: + :CUSTOM_ID: header-argument-results-collection + :END: + The following options are mutually exclusive, and specify how the + results should be collected from the source code block. + + - value :: This is the default. The result is the value + of the last statement in the source code block. + This header argument places Org-babel in functional + mode. Note that in some languages, e.g., python, + use of this result type requires that a =return= + statement be included in the body of the source code + block. E.g., =:results value=. + - output :: The result is the collection of everything printed + to stdout during the execution of the source code + block. This header argument places Org-babel in scripting + mode. E.g., =:results output=. + +@subsubheading type + The following options are mutually exclusive and specify what + type of results the code block will return. By default, results + are inserted as either a *table* or *scalar* depending on their + value. + + - table, vector :: The results should be interpreted as an Org-mode table. + If a single value is returned, Org-babel will convert it + into a table with one row and one column. E.g., =:results + value table=. + - scalar, verbatim :: The results should be interpreted + literally -- meaning they will not be converted into a table. + The results will be inserted into the Org-mode buffer as + quoted text. E.g., =:results value verbatim=. + - file :: The results will be interpreted as the path to a file, + and will be inserted into the Org-mode buffer as a file + link. E.g., =:results value file=. + - raw, org :: The results are interpreted as raw Org-mode code and + are inserted directly into the buffer. If the results look + like a table they will be aligned as such by Org-mode. + E.g., =:results value raw=. + - html :: Results are assumed to be HTML and will be enclosed in + a =begin_html= block. E.g., =:results value html=. + - latex :: Results assumed to be LaTeX and are enclosed in a + =begin_latex= block. E.g., =:results value latex=. + - code :: Result are assumed to be parseable code and are + enclosed in a code block. E.g., =:results value code=. + - pp :: The result is converted to pretty-printed code and is + enclosed in a code block. This option currently supports + Emacs Lisp, python, and ruby. E.g., =:results value pp=. + +@subsubheading handling + The following results options indicate what Org-babel should do + with the results once they are collected. + + - silent :: The results will be echoed in the minibuffer but + will not be inserted into the Org-mode buffer. E.g., + =:results output silent=. + - replace :: The default value. The results will be inserted + into the Org-mode buffer. E.g., =:results output + replace=. + +@subsubsection =:file= + :PROPERTIES: + :CUSTOM_ID: header-argument-file + :END: + + =:file= is used to specify a path for file output in which case an + [[http://orgmode.org/manual/Link-format.html#Link-format][org style]] =file:= link is inserted into the buffer as the + result. Common examples are graphical output from [[file:languages/org-babel-doc-R.org][R]], gnuplot, + ditaa and [[file:languages/org-babel-doc-LaTeX.org][latex]] blocks. + + See the [[#header-argument-dir][=:dir= and remote execution]] section for examples. + + Note that for some languages, including [[file:languages/org-babel-doc-R.org][R]], gnuplot, [[file:languages/org-babel-doc-LaTeX.org][latex]] and + ditaa, graphical output is sent to the specified file without the + file being referenced explicitly in the code block. See the + documentation for the individual languages for details. In + contrast, general purpose languages such as python and ruby + require that the code explicitly create output corresponding to + the path indicated by =:file=. + + While the =:file= header argument can be used to specify the path + to the output file, + +@subsubsection =:dir= and remote execution + :PROPERTIES: + :CUSTOM_ID: header-argument-dir + :END: + =:dir= specifies the /default directory/ during code block + execution. If it is absent, then the directory associated with the + current buffer is used. In other words, supplying =:dir path= + temporarily has the same effect as changing the current directory + with =M-x cd path=, and then not supplying =:dir=. Under the + surface, =:dir= simply sets the value of the emacs variable + =default-directory=. + + When using =:dir=, you should supply a relative path for [[#header-argument-file][file + output]] (e.g. =:file myfile.jpg= or =:file results/myfile.jpg=) in + which case that path will be interpreted relative to the default + directory. + + In other words, if you want your plot to go into a folder called + Work in your home directory, you could use + +@example + #+begin_src R :file myplot.png :dir ~/Work + matplot(matrix(rnorm(100), 10), type="l") + #+end_src +@end example + +@subsubheading Remote execution + A directory on a remote machine can be specified using [[http://www.gnu.org/software/tramp/#Filename-Syntax][tramp + filename syntax]], in which case the code will be executed on the + remote machine[fn:2]. An example is + +@example +#+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu: + plot(1:10, main=system("hostname", intern=TRUE)) +#+end_src +@end example + +Text results will be returned to the local org buffer as normal, and +file output will be created on the remote machine with relative paths +interpreted relative to the remote directory. An org link to the +remote file will be created. + +So in the above example a plot will be created on the remote machine, +and a link of the following form will be inserted in the org buffer: + +@example +[[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]] +@end example + +Most of this functionality follows immediately from the fact that +=:dir= sets the value of the emacs variable =default-directory=, +thanks to [[http://www.gnu.org/software/tramp/][tramp]]. Those using XEmacs, or GNU Emacs prior to +version 23 may need to install tramp separately in order for the +above features to work correctly. + +@subsubheading Further points + - If =:dir= is used in conjunction with =:session=, although it + will determine the starting directory for a new session as + expected, no attempt is currently made to alter the directory + associated with an existing session. + - =:dir= should typically not be used to create files during + export with =:exports results= or =:exports both=. The reason + is that, in order to retain portability of exported material + between machines, during export, links inserted into the buffer + will *not* be expanded against default directory. Therefore, if + default-directory is altered using =:dir=, it it probable that + the file will be created in a location to which the link does + not point. +@subsubsection =:exports= + :PROPERTIES: + :CUSTOM_ID: header-argument-exports + :END: + + Specify what should be included in HTML or LaTeX exports of the + Org-mode file. + + - code :: the default. The body of code is included + into the exported file. E.g., =:exports code=. + - results :: the result of evaluating the code is included in the + exported file. E.g., =:exports results=. + - both :: both the code and results are included in the exported + file. E.g., =:exports both=. + - none :: nothing is included in the exported file. E.g., + =:exports none=. + +@subsubsection =:tangle= + :PROPERTIES: + :CUSTOM_ID: tangle-header-arguments + :END: + + Specify whether or not the source code block should be included + in tangled extraction of source code files. + + - yes :: the source code block is exported to a source code file + named after the basename (name w/o extension) of the + Org-mode file. E.g., =:tangle yes=. + - no :: the default. The source code block is not + exported to a source code file. E.g., =:tangle no=. + - other :: Any other string passed to the =:tangle= header argument + is interpreted as a file basename to which the block will + be exported. E.g., =:tangle basename=. + +@subsubsection =:session= + :PROPERTIES: + :CUSTOM_ID: header-argument-session + :END: + + Start a session for an interpreted language where state is + preserved. This applies particularly to the supported languages + python, R and ruby. + + By default, a session is not started. + + A string passed to the =:session= header argument will give the + session a name. This makes it possible to run concurrent + sessions for each interpreted language. + +@subsubsection =:noweb= + :PROPERTIES: + :CUSTOM_ID: header-argument-noweb + :END: + + Controls the expansion of [[noweb-reference-syntax][noweb syntax]] references in a + source code block. This header argument can have one of two + values: =yes= or =no=. + - =no= :: the default. No [[noweb-reference-syntax][noweb syntax]] specific action is taken + on evaluating source code blocks/ However, noweb references + will still be expanded during tangling. + - =yes= :: all [[noweb-reference-syntax][noweb syntax]] references in the body of the source + code block will be expanded before the block is evaluated. + +@subsubheading Noweb Prefix Lines + + Noweb insertions are now placed behind the line prefix of the + =<>=. + + This behavior is illustrated in the following example. Because + the =<>= noweb reference appears behind the SQL + comment syntax, each line of the expanded noweb reference will + be commented. + + This source code block: + + @example + -- <> + @end example + + + expands to: + + @example + -- this is the + -- multi-line body of example + @end example + + Note that noweb replacement text that does *not* contain any + newlines will not be affected by this change, so it is still + possible to use inline noweb references. + + Thanks to Sébastien Vauban for this idea. + +@subsubsection =:cache= + :PROPERTIES: + :CUSTOM_ID: header-argument-cache + :END: + + Controls the use of in-buffer caching of source code block + results to avoid re-running unchanged source code blocks. This + header argument can have one of two values: =yes= or =no=. + - =no= :: The default. No caching takes place and the source + code block will be run every time it is executed. + - =yes= :: every time the source code block is run a sha1 hash of + the code and arguments passed to the block will be + generated. This hash is packed into the =#+results:= line + of the results and will be checked on subsequent executions + of the source code block. If the source code block has not + changed since the last time it was evaluated, it will not be + re-evaluated. + +@section Results + :PROPERTIES: + :CUSTOM_ID: results-specification + :END: + + The way in which results are handled depends on whether a [[header-argument-session][session]] + is invoked, as well as on whether + [[header-argument-results-collection][=:results value=] or + [[header-argument-results-collection][=:results output=]] is used. The following table shows the + possibilities: + + | | non-session (default) | =:session= | + |-------------------+--------------------------+-------------------------------------| + | =:results value= | value of last expression | value of last expression | + | =:results output= | contents of stdout | concatenation of interpreter output | + + *Note:* With =:results value=, the result in both =:session= and + non-session is returned to Org-mode as a table (a one- or + two-dimensional vector of strings or numbers) when appropriate. + +@subsection Non-session +@subsubsection =:results value= + This is the default. Internally, the value is obtained by + wrapping the code in a function definition in the external + language, and evaluating that function. Therefore, code should be + written as if it were the body of such a function. In particular, + note that python does not automatically return a value from a + function unless a =return= statement is present, and so a + 'return' statement will usually be required in python. + + This is the only one of the four evaluation contexts in which the + code is automatically wrapped in a function definition. + +@subsubsection =:results output= + The code is passed to the interpreter as an external process, and + the contents of the standard output stream are returned as + text. (In certain languages this also contains the error output + stream; this is an area for future work.) + +@subsection =:session= +@subsubsection =:results value= + The code is passed to the interpreter running as an interactive + Emacs inferior process. The result returned is the result of the + last evaluation performed by the interpreter. (This is obtained in + a language-specific manner: the value of the variable =_= in + python and ruby, and the value of =.Last.value= in R). + +@subsubsection =:results output= + The code is passed to the interpreter running as an interactive + Emacs inferior process. The result returned is the concatenation + of the sequence of (text) output from the interactive + interpreter. Notice that this is not necessarily the same as what + would be sent to stdout if the same code were passed to a + non-interactive interpreter running as an external process. For + example, compare the following two blocks: + + +@example +#+begin_src python :results output + print "hello" + 2 + print "bye" +#+end_src + +#+resname: + : hello + : bye +@end example + + In non-session mode, the '2' is not printed and does not appear. +@example +#+begin_src python :results output :session + print "hello" + 2 + print "bye" +#+end_src + +#+resname: + : hello + : 2 + : bye +@end example + + But in =:session= mode, the interactive interpreter receives input '2' + and prints out its value, '2'. (Indeed, the other print statements are + unnecessary here). + +@section Noweb Reference Syntax + :PROPERTIES: + :CUSTOM_ID: noweb-reference-syntax + :END: + + The [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] Literate Programming system allows named blocks of code to + be referenced by using the familiar Noweb syntax: + : <> + + Noweb references are handled differently during evaluation and + tangling. + + When a document is tangled, Noweb references are replaced with the + named source code block. + + When a source code block is evaluated, the action depends upon the + value of the =:noweb= header argument. If =:noweb yes=, then a + Noweb reference is expanded before evaluation. If =:noweb no=, + the default, then the reference is not expanded before + evaluation. + + *Note:* the default value, =:noweb no=, was chosen to ensure that + Org-babel does not break correct code in a language, such as Ruby, + where =<>= is a syntactically valid construct. If =<>= is + not syntactically valid in languages that you use, then please + consider [[*System%20wide][setting the default value]]. + + An example that uses the Noweb reference syntax is provided in the + [[literate programming example]]. + +@section Key Bindings & Useful Functions + + Org-babel re-binds many common Org-mode key sequences depending on + the context. Within a source-code block the following sequences + are rebound: + | =C-c C-c= | [[function-org-babel-execute][org-babel-execute-src-block]] | + | =C-c C-o= | [[function-org-babel-open-src-block-result][org-babel-open-src-block-result]] | + | =C-up= | [[function-org-babel-load-in-session][org-babel-load-in-session]] | + | =M-down= | [[function-org-babel-pop-to-session][org-babel-pop-to-session]] | + + Org-babel also exposes a number of functions behind the common + =org-babel-key-prefix= of =C-c M-b=: +@example + #+begin_src emacs-lisp :exports none + (lambda (binding + (list (format "\\C-c \\M-b %s" + (car binding)) + (format "[[function-%s][%s]]" + (cdr binding) (cdr binding)))) + org-babel-key-bindings) + #+end_src +@end example + + | =C-c M-b t= | [[function-org-babel-tangle][org-babel-tangle]] | + | =C-c M-b T= | [[function-org-babel-tangle-file][org-babel-tangle-file]] | + | =C-c M-b e= | [[function-org-babel-execute-src-block][org-babel-execute-src-block]] | + | =C-c M-b s= | [[function-org-babel-execute-subtree][org-babel-execute-subtree]] | + | =C-c M-b b= | [[function-org-babel-execute-buffer][org-babel-execute-buffer]] | + | =C-c M-b h= | [[function-org-babel-sha1-hash][org-babel-sha1-hash]] | + | =C-c M-b g= | [[function-org-babel-goto-named-source-block][org-babel-goto-named-source-block]] | + | =C-c M-b l= | [[function-org-babel-lob-ingest][org-babel-lob-ingest]] | + +@subsection Functions +@subsubsection org-babel-execute-src-block + :PROPERTIES: + :CUSTOM_ID: function-org-babel-execute-src-block + :END: + +@example + org-babel-execute-src-block is an interactive Lisp function in + `org-babel.el'. + + (org-babel-execute-src-block &optional ARG INFO PARAMS) + + Execute the current source code block, and insert the results + into the buffer. Source code execution and the collection and + formatting of results can be controlled through a variety of + header arguments. + + Optionally supply a value for INFO in the form returned by + `org-babel-get-src-block-info'. + + Optionally supply a value for PARAMS which will be merged with + the header arguments specified at the front of the source code + block. +@end example + +@subsubsection org-babel-open-src-block-result + :PROPERTIES: + :CUSTOM_ID: function-org-babel-open-src-block-result + :END: + +@example + org-babel-open-src-block-result is an interactive Lisp function in + `org-babel.el'. + + (org-babel-open-src-block-result &optional RE-RUN) + + If `point' is on a src block then open the results of the + source code block, otherwise return nil. With optional prefix + argument RE-RUN the source-code block is evaluated even if + results already exist. +@end example + +@subsubsection org-babel-load-in-session + :PROPERTIES: + :CUSTOM_ID: function-org-babel-load-in-session + :END: + +@example + org-babel-load-in-session is an interactive Lisp function in + `org-babel.el'. + + (org-babel-load-in-session &optional ARG INFO) + + Load the body of the current source-code block. Evaluate the + header arguments for the source block before entering the + session. After loading the body this pops open the session. + + [back] +@end example + +@subsubsection org-babel-pop-to-session + :PROPERTIES: + :CUSTOM_ID: function-org-babel-pop-to-session + :END: + +@example + org-babel-pop-to-session is an interactive Lisp function in + `org-babel.el'. + + (org-babel-pop-to-session &optional ARG INFO) + + Pop to the session of the current source-code block. If + called with a prefix argument then evaluate the header arguments + for the source block before entering the session. Copy the body + of the source block to the kill ring. + + [back] +@end example + +@subsubsection org-babel-tangle + :PROPERTIES: + :CUSTOM_ID: function-org-babel-tangle + :END: + +@example + org-babel-tangle is an interactive Lisp function in + `org-babel-tangle.el'. + + It is bound to C-c M-b t. + + (org-babel-tangle &optional TARGET-FILE LANG) + + Extract the bodies of all source code blocks from the current + file into their own source-specific files. Optional argument + TARGET-FILE can be used to specify a default export file for all + source blocks. Optional argument LANG can be used to limit the + exported source code blocks by language. +@end example + +@subsubsection org-babel-execute-subtree + :PROPERTIES: + :CUSTOM_ID: function-org-babel-execute-subtree + :END: + +@example + org-babel-execute-subtree is an interactive Lisp function in + `org-babel.el'. + + It is bound to C-c M-b s. + + (org-babel-execute-subtree &optional ARG) + + Replace EVAL snippets in the entire subtree. +@end example + +@subsubsection org-babel-execute-buffer + :PROPERTIES: + :CUSTOM_ID: function-org-babel-execute-buffer + :END: + +@example + org-babel-execute-buffer is an interactive Lisp function in + `org-babel.el'. + + It is bound to C-c M-b b. + + (org-babel-execute-buffer &optional ARG) + + Replace EVAL snippets in the entire buffer. +@end example + +@subsubsection org-babel-sha1-hash + :PROPERTIES: + :CUSTOM_ID: function-org-babel-sha1-hash + :END: + +@example + org-babel-sha1-hash is an interactive Lisp function in `org-babel.el'. + + It is bound to C-c M-b h. + + (org-babel-sha1-hash &optional INFO) + + Not documented. +@end example + +@subsubsection org-babel-goto-named-source-block + :PROPERTIES: + :CUSTOM_ID: function-org-babel-goto-named-source-block + :END: + +@example + org-babel-goto-named-source-block is an interactive Lisp function in + `org-babel.el'. + + It is bound to C-c M-b g. + + (org-babel-goto-named-source-block &optional NAME) + + Go to a named source-code block. +@end example + +@subsubsection org-babel-lob-ingest + :PROPERTIES: + :CUSTOM_ID: function-org-babel-lob-ingest + :END: + +@example + org-babel-lob-ingest is an interactive Lisp function in + `org-babel-lob.el'. + + It is bound to C-c M-b l. + + (org-babel-lob-ingest &optional FILE) + + Add all source-blocks defined in FILE to `org-babel-library-of-babel'. +@end example + +@section Batch Execution +It is possible to call Org-babel functions from the command line. +This shell script calls [[function-org-babel-tangle][org-babel-tangle]] on every one of its +arguments. + +Be sure to adjust the paths to fit your system. +@example + #!/bin/sh + # -*- mode: shell-script -*- + # + # tangle a file with org-babel + # + DIR=`pwd` + FILES="" + + # wrap each argument in the code required to call tangle on it + for i in $@@; do + FILES="$FILES \"$i\"" + done + + emacsclient \ + --eval "(progn + (add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\")) + (add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\")) + (require 'org)(require 'org-exp)(require 'org-babel) + (mapc (lambda (file) + (find-file (expand-file-name file \"$DIR\")) + (org-babel-tangle) + (kill-buffer)) '($FILES)))" +@end example + +@section Footnotes + +[fn:1] The former use of the =shell= identifier is now deprecated. + +[fn:2] As long as the interpreter executable is found on the remote +machine: see the variable =tramp-remote-path= @node Miscellaneous, Hacking, Working With Source Code, Top @chapter Miscellaneous diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi index dafe4365c..e69de29bb 100644 --- a/doc/source-code-chapter.texi +++ b/doc/source-code-chapter.texi @@ -1,1084 +0,0 @@ -@node Working With Source Code, Miscellaneous, Publishing, Top -@comment node-name, next, previous, up -@comment Working With Source Code, Miscellaneous, Publishing, Top -@chapter ``Working With Source Code'' or ``Embedded Source Code'' - -Source code can be included in Org-mode documents using a @samp{src} block: - -@example -#+BEGIN_SRC emacs-lisp -(defun org-xor (a b) - "Exclusive or." - (if a (not b) b)) -#+END_SRC -@end example - -Org provides the following features for working with such code blocks: - -@itemize @bullet -@item -Editing in the appropriate Emacs major-mode (@ref{Editing Source Code}) -@item -Export with appropriate markup (@ref{Exporting Code Blocks}) -@item -Extraction (``tangling'') into pure code files. (@ref{Extracting Source Code}) -@item -Code execution, with results captured in the Org buffer (@ref{Evaluating Code Blocks}) -@item -Using code blocks in table formulas -@end itemize - -@menu -* Structure of Code Blocks:: -* Editing Source Code:: -* Exporting Code Blocks:: -* Extracting Source Code:: -* Evaluating Code Blocks:: -@end menu - - -@node Structure of Code Blocks, Editing Source Code, Working With Source Code, Working With Source Code -@comment node-name, next, previous, up -@comment Structure of Code Blocks, Editing Source Code, Working With Source Code, Working With Source Code -@section Structure of Code Blocks - -The basic structure of code blocks is as follows: - -@example -#+srcname: name -#+begin_src language header-arguments switches -body -#+end_src -@end example - -@table @code -@item name -The initial name line is optional. If present it is used during code evaluation. -@item language -The language of the code in the block. -@item header-arguments -Header arguments control evaluation, export and tangling of source -code blocks. See the [[header-arguments][Header Arguments]] section. -@item switches -FIXME link/relocate switches discussion in ``Literal examples'' section -@item body -The code -@end table - -@node Editing Source Code, Exporting Code Blocks, Structure of Code Blocks, Working With Source Code -@comment node-name, next, previous, up -@comment Editing Source Code, Exporting Code Blocks, Structure of Code Blocks, Working With Source Code -@section Editing Source Code - -Use @kbd{C-c '} to edit the code block at point. This brings up a -language major-mode buffer containing the body of the code -block. Saving this buffer will write the new contents back to the Org -buffer. Use @kbd{C-c '} again to exit. - -The edit buffer has a minor mode active called -@code{org-src-mode}. The following variables can be used to configure -the behavior of the edit buffer. See also the customization group -@code{org-edit-structure} for futher configuration options. - -@table @code -@item org-src-lang-modes -If an emacs major-mode named @code{-mode} exists, where -@code{} is the language named in header line of the code block, -then the edit buffer will be placed in that major-mode. This variable -can be used to map arbitrary language names to existing major modes. -@item org-src-window-setup -Controls the way Emacs windows are rearranged when the edit buffer is created. -@item org-src-preserve-indentation -This variable is expecially useful for tangling languages such as -python, where whitespace the indentation in the output is critical. -@item org-src-ask-before-returning-to-edit-buffer -By default, Org will ask before returning to an open edit buffer. Set -to a non-nil value to switch without asking. -@end table - -@node Exporting Code Blocks, Extracting Source Code, Editing Source Code, Working With Source Code -@comment node-name, next, previous, up -@comment Exporting Code Blocks, Extracting Source Code, Editing Source Code, Working With Source Code -@section Exporting Code Blocks - -@node Extracting Source Code, Evaluating Code Blocks, Exporting Code Blocks, Working With Source Code -@comment node-name, next, previous, up -@comment Extracting Source Code, Evaluating Code Blocks, Exporting Code Blocks, Working With Source Code -@section Extracting Source Code - -@node Evaluating Code Blocks, , Extracting Source Code, Working With Source Code -@comment node-name, next, previous, up -@comment Evaluating Code Blocks, , Extracting Source Code, Working With Source Code -@section Evaluating Code Blocks - -This syntax can be expanded by naming the source code block. - -@example -#+sourcename -#+begin_src language header-arguments switches -body -#+end_src -@end example - -- name :: This name is associated with the source code block. This is - similar to the =#+tblname= lines that can be used to name tables - in Org-mode files. Referencing the name of a source code - block makes it possible to evaluate the block from other places in - the file, other files, or inside Org-mode tables. It - is also possible to pass arguments to a source code block through - this =#+source:= line (see [[alternate-argument-syntax][Alternate argument syntax]]). - -@subsection Library of Babel -[[file:library-of-babel.org][Library of Babel]] functions can be called using the following syntax. - -@example -#+lob: R-plot(data=R-plot-example-data) -@end example - -@subsection Aliases - Keyword aliases are intended to make Org-babel feel natural to - programmers fluent in a variety of languages. For example, - @example - #+srcname: alias-example - #+begin_src emacs-lisp - '((call lob) - (source function srcname) - (results resname)) - #+end_src - - #+results: alias-example - | call | lob | | - | source | function | srcname | - | results | resname | | - @end example - - =#+srcname:= can be replaced with either of two aliases, =#+source:= or =#+function:=. - - =#+results:= can be replaced with its alias, =#+resname:=. - - When calling Library of Babel functions, as in the following - example, there are two acceptable keywords. The =#+lob= call in - the example could be replaced with its alias, =#+call=. - @example - #+lob: R-plot(data=R-plot-example-data) - @end example - -@subsection Languages - :PROPERTIES: - :CUSTOM_ID: languages - :END: - - Org-babel has support for the following languages. - - | Language | Documentation | Identifier | Requirements | - |----------------+-----------------------------+------------+---------------------------------------------| - | Asymptote | org-babel-doc-asymptote | asymptote | [[http://asymptote.sourceforge.net/][asymptote]], [[http://asymptote.sourceforge.net/doc/Editing-modes.html][asy-mode]] | - | C | [[file:languages/org-babel-doc-C.org][org-babel-doc-C]] | C | none | - | Clojure | [[file:languages/org-babel-doc-clojure.org][org-babel-doc-clojure]] | clojure | [[http://clojure.org/][clojure]], [[http://www.emacswiki.org/emacs/clojure-mode.el][clojure-mode]], [[http://common-lisp.net/project/slime/][slime]], [[http://clojure.codestuffs.com/][swank-clojure]] | - | css | org-babel-doc-css | css | none | - | ditaa | org-babel-doc-ditaa | ditaa | [[http://ditaa.org/ditaa/][ditaa]] (bundled with Org-mode) | - | Graphviz | org-babel-doc-dot | dot | [[http://www.graphviz.org/][dot]] | - | Emacs Lisp | org-babel-doc-emacs-lisp | emacs-lisp | none | - | gnuplot | org-babel-doc-gnuplot | gnuplot | [[http://www.gnuplot.info/][gnuplot]], [[http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html][gnuplot-mode]] | - | Haskell | org-babel-doc-haskell | haskell | [[http://www.haskell.org/][haskell]], [[http://projects.haskell.org/haskellmode-emacs/][haskell-mode]], [[http://www.haskell.org/haskellwiki/Haskell_mode_for_Emacs#inf-haskell.el:_the_best_thing_since_the_breadknife][inf-haskell]], [[http://people.cs.uu.nl/andres/lhs2tex/][lhs2tex]] | - | Matlab | [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] | matlab | matlab, [[http://sourceforge.net/projects/matlab-emacs/][matlab.el]] | - | LaTeX | [[file:languages/org-babel-doc-LaTeX.org][org-babel-doc-latex]] | latex | [[http://www.latex-project.org/][latex]], [[http://www.gnu.org/software/auctex/][auctex]], [[http://www.gnu.org/software/auctex/reftex.html][reftex]] | - | Objective Caml | org-babel-doc-ocaml | ocaml | [[http://caml.inria.fr/][ocaml]], [[http://www-rocq.inria.fr/~acohen/tuareg/][tuareg-mode]] | - | Octave | [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] | octave | octave | - | OZ | [[file:languages/org-babel-doc-oz.org][org-babel-doc-oz]] | oz | [[http://www.mozart-oz.org/][Mozart]] which includes a major mode | - | Perl | org-babel-doc-perl | perl | [[http://www.perl.org/][perl]], [[http://www.emacswiki.org/emacs/CPerlMode][cperl-mode]] (optional) | - | Python | org-babel-doc-python | python | [[http://www.python.org/][python]], [[https://launchpad.net/python-mode][python-mode]] (optional) | - | R | [[file:languages/org-babel-doc-R.org][org-babel-doc-R]] | R | [[http://www.r-project.org/][R]], [[http://ess.r-project.org/][ess-mode]] | - | Ruby | org-babel-doc-ruby | ruby | [[http://www.ruby-lang.org/][ruby]], [[http://www.ruby-lang.org/][irb]], [[http://github.com/eschulte/rinari/raw/master/util/ruby-mode.el][ruby-mode]], [[http://github.com/eschulte/rinari/raw/master/util/inf-ruby.el][inf-ruby mode]] | - | Sass | org-babel-doc-sass | sass | [[http://sass-lang.com/][sass]], [[http://github.com/nex3/haml/blob/master/extra/sass-mode.el][sass-mode]] | - | GNU Screen | [[file:languages/org-babel-doc-screen.org][org-babel-doc-screen]] | screen | [[http://www.gnu.org/software/screen/][screen]], a terminal | - | shell | org-babel-doc-sh | sh[fn:1] | a shell | - | SQL | org-babel-doc-sql | sql | none | - - To add support for a particular language to your Org-babel - installation first make sure that the requirements of the language - are met, then add a line like the following to your Emacs - configuration, (replace "identifier" with one of the - entries in the Identifier column of the table). - @example - (require 'org-babel-identifier) - @end example - -@section Header Arguments - :PROPERTIES: - :CUSTOM_ID: header-arguments - :END: - -Definitions of all Org-babel header arguments are given [[header-argument-specific-documentation][below]]. In -addition, some languages may add their own header arguments. Please -see the language-specific documentation for information on -language-specific header arguments. - -@subsection Using Header Arguments - -The values of header arguments can be set in three different ways, -each more specific than the last. - -@subsubsection System-wide - :PROPERTIES: - :CUSTOM_ID: system-wide-header-argument - :END: - - System-wide values of header arguments can be specified by - customizing the =org-babel-default-header-args= variable: - @example - org-babel-default-header-args is a variable defined in `org-babel.el'. - Its value is - ((:session . "none") - (:results . "replace") - (:exports . "code") - (:cache . "no") - (:noweb . "no")) - - - Documentation: - Default arguments to use when evaluating a source block. - @end example - [[#default-noweb]] - For example, the following example could be used to set the default value - of =:noweb= header arguments to =yes=. This would have the effect of - expanding =:noweb= references by default when evaluating source code blocks. - @example - (setq org-babel-default-header-args - (cons '(:noweb . "yes") - (assq-delete-all :noweb org-babel-default-header-args))) - @end example - -@subsubsection Org-mode Properties - - Header arguments are also read from [[http://orgmode.org/manual/Properties-and-Columns.html#Properties-and-Columns][Org-mode properties]], which - means they can be set on the outline header level. For example, the - value of the =:cache= header argument will default to true in all - source code blocks under the following example of an Org-mode outline header: - @example - * outline header - :PROPERTIES: - :cache: yes - :CUSTOM_ID: property-set-header-arguments - :END: - @end example - Properties defined in this way override the properties set in - =org-babel-default-header-args=. It is convenient to use the - =org-set-property= function bound to =C-c C-x p= to set properties - in Org-mode documents. - -@subsubsection Source Code Block - :PROPERTIES: - :CUSTOM_ID: single-block-header-arguments - :END: - The most common way to assign values to header arguments is at the - source code block level. This can be done by listing a sequence of - header arguments and their values as part of the =#+begin_src= - line. Properties set in this way override both the values of - =org-babel-default-header-args= and header argument specified as - properties. In the following example, the - =:results= header argument is set to =silent=, meaning the results - of execution will not be inserted in the buffer, and the =:exports= - header argument is set to =code=, meaning only the body of the - source code block - will be preserved on export to HTML or LaTeX. - @example - #+source: factorial - #+begin_src haskell :results silent :exports code - fac 0 = 1 - fac n = n * fac (n-1) - #+end_src - @end example - -@subsection Specific Header Arguments - :PROPERTIES: - :CUSTOM_ID: header-argument-specific-documentation - :END: - -@subsubsection =:var= - :PROPERTIES: - :CUSTOM_ID: header-argument-var - :END: - - The =:var= header argument is used to pass arguments to - source code blocks. The specifics of how arguments are included - in a source code block are language specific and are - addressed in the language-specific documentation. However, the - syntax used to specify arguments is the same across all - languages. The values passed to arguments can be or - - literal values - - values from org-mode tables - - the results of other source code blocks - - These values can be indexed in a manner similar to arrays -- see - [[var-argument-indexing][argument indexing]]. - - The following syntax is used to pass arguments to source code - blocks using the =:var= header argument. - - @example - :var name=assign - @end example - - where =assign= can take one of the following forms - - - literal value :: either a string ="string"= or a number =9=. - - reference :: a table name: - - @example - #+tblname: example-table - | 1 | - | 2 | - | 3 | - | 4 | - - #+source: table-length - #+begin_src emacs-lisp :var table=example-table - (length table) - #+end_src - - #+results: table-length - : 4 - @end example - - a source code block name, as assigned by =#+srcname:=, - followed by parentheses: - - @example - #+begin_src emacs-lisp :var length=table-length() - (* 2 length) - #+end_src - - #+results: - : 8 - @end example - - In addition, an argument can be passed to the source code - block referenced by =:var=. The argument is passed within - the parentheses following the source code block name: - - @example - #+source: double - #+begin_src emacs-lisp :var input=8 - (* 2 input) - #+end_src - - #+results: double - : 16 - - #+source: squared - #+begin_src emacs-lisp :var input=double(input=1) - (* input input) - #+end_src - - #+results: squared - : 4 - @end example - -@subsubheading alternate argument syntax - :PROPERTIES: - :CUSTOM_ID: alternate-argument-syntax - :END: - - It is also possible to specify arguments in a potentially more - natural way using the =#+source:= line of a source code block. - As in the following example arguments can be packed inside of - parenthesis following the source name. - @example - #+source: double(input=0) - #+begin_src emacs-lisp - (* 2 input) - #+end_src - @end example - -**** indexable variable values - :PROPERTIES: - :CUSTOM_ID: var-argument-indexing - :END: - - It is possible to assign a portion of a value to a - variable in a source block. The following example - assigns the second and third rows of the table - =example-table= to the variable =data=: - - @example - :var data=example-table[1:2] - @end example - - *Note:* ranges are indexed using the =:= operator. - - *Note:* indices are 0 based. - - The following example assigns the second column of the - first row of =example-table= to =data=: - - @example - :var data=example-table[0,1] - @end example - - It is possible to index into the results of source code blocks - as well as tables. Any number of dimensions can be indexed. - Dimensions are separated from one another by commas. - - For more information on indexing behavior see the documentation - for the =org-babel-ref-index-list= function -- provided below. - - @example - org-babel-ref-index-list is a Lisp function in `org-babel-ref.el'. - - (org-babel-ref-index-list INDEX LIS) - - Return the subset of LIS indexed by INDEX. If INDEX is - separated by ,s then each PORTION is assumed to index into the - next deepest nesting or dimension. A valid PORTION can consist - of either an integer index, or two integers separated by a : in - which case the entire range is returned. - @end example - - *Note:* In Emacs, the documentation for any function or variable - can be read using the =describe-function= (M-x describe - function) and =describe-variable= (M-x describe variable) - functions, respectively. - -@subsubsection =:results= - :PROPERTIES: - :CUSTOM_ID: header-argument-results - :END: - - There are three types of results header argument: - - *collection* header arguments specify how the results should be collected from - the source code block; - - *type* header arguments specify what type of result the source code block - will return -- which has implications for how they will be - inserted into the Org-mode buffer; and - - *handling* header arguments specify how the results of - evaluating the source code block should be handled. - - *Note:* only one option from each type may be supplied per source code - block. - -@subsubheading collection - :PROPERTIES: - :CUSTOM_ID: header-argument-results-collection - :END: - The following options are mutually exclusive, and specify how the - results should be collected from the source code block. - - - value :: This is the default. The result is the value - of the last statement in the source code block. - This header argument places Org-babel in functional - mode. Note that in some languages, e.g., python, - use of this result type requires that a =return= - statement be included in the body of the source code - block. E.g., =:results value=. - - output :: The result is the collection of everything printed - to stdout during the execution of the source code - block. This header argument places Org-babel in scripting - mode. E.g., =:results output=. - -@subsubheading type - The following options are mutually exclusive and specify what - type of results the code block will return. By default, results - are inserted as either a *table* or *scalar* depending on their - value. - - - table, vector :: The results should be interpreted as an Org-mode table. - If a single value is returned, Org-babel will convert it - into a table with one row and one column. E.g., =:results - value table=. - - scalar, verbatim :: The results should be interpreted - literally -- meaning they will not be converted into a table. - The results will be inserted into the Org-mode buffer as - quoted text. E.g., =:results value verbatim=. - - file :: The results will be interpreted as the path to a file, - and will be inserted into the Org-mode buffer as a file - link. E.g., =:results value file=. - - raw, org :: The results are interpreted as raw Org-mode code and - are inserted directly into the buffer. If the results look - like a table they will be aligned as such by Org-mode. - E.g., =:results value raw=. - - html :: Results are assumed to be HTML and will be enclosed in - a =begin_html= block. E.g., =:results value html=. - - latex :: Results assumed to be LaTeX and are enclosed in a - =begin_latex= block. E.g., =:results value latex=. - - code :: Result are assumed to be parseable code and are - enclosed in a code block. E.g., =:results value code=. - - pp :: The result is converted to pretty-printed code and is - enclosed in a code block. This option currently supports - Emacs Lisp, python, and ruby. E.g., =:results value pp=. - -@subsubheading handling - The following results options indicate what Org-babel should do - with the results once they are collected. - - - silent :: The results will be echoed in the minibuffer but - will not be inserted into the Org-mode buffer. E.g., - =:results output silent=. - - replace :: The default value. The results will be inserted - into the Org-mode buffer. E.g., =:results output - replace=. - -@subsubsection =:file= - :PROPERTIES: - :CUSTOM_ID: header-argument-file - :END: - - =:file= is used to specify a path for file output in which case an - [[http://orgmode.org/manual/Link-format.html#Link-format][org style]] =file:= link is inserted into the buffer as the - result. Common examples are graphical output from [[file:languages/org-babel-doc-R.org][R]], gnuplot, - ditaa and [[file:languages/org-babel-doc-LaTeX.org][latex]] blocks. - - See the [[#header-argument-dir][=:dir= and remote execution]] section for examples. - - Note that for some languages, including [[file:languages/org-babel-doc-R.org][R]], gnuplot, [[file:languages/org-babel-doc-LaTeX.org][latex]] and - ditaa, graphical output is sent to the specified file without the - file being referenced explicitly in the code block. See the - documentation for the individual languages for details. In - contrast, general purpose languages such as python and ruby - require that the code explicitly create output corresponding to - the path indicated by =:file=. - - While the =:file= header argument can be used to specify the path - to the output file, - -@subsubsection =:dir= and remote execution - :PROPERTIES: - :CUSTOM_ID: header-argument-dir - :END: - =:dir= specifies the /default directory/ during code block - execution. If it is absent, then the directory associated with the - current buffer is used. In other words, supplying =:dir path= - temporarily has the same effect as changing the current directory - with =M-x cd path=, and then not supplying =:dir=. Under the - surface, =:dir= simply sets the value of the emacs variable - =default-directory=. - - When using =:dir=, you should supply a relative path for [[#header-argument-file][file - output]] (e.g. =:file myfile.jpg= or =:file results/myfile.jpg=) in - which case that path will be interpreted relative to the default - directory. - - In other words, if you want your plot to go into a folder called - Work in your home directory, you could use - -@example - #+begin_src R :file myplot.png :dir ~/Work - matplot(matrix(rnorm(100), 10), type="l") - #+end_src -@end example - -@subsubheading Remote execution - A directory on a remote machine can be specified using [[http://www.gnu.org/software/tramp/#Filename-Syntax][tramp - filename syntax]], in which case the code will be executed on the - remote machine[fn:2]. An example is - -@example -#+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu: - plot(1:10, main=system("hostname", intern=TRUE)) -#+end_src -@end example - -Text results will be returned to the local org buffer as normal, and -file output will be created on the remote machine with relative paths -interpreted relative to the remote directory. An org link to the -remote file will be created. - -So in the above example a plot will be created on the remote machine, -and a link of the following form will be inserted in the org buffer: - -@example -[[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]] -@end example - -Most of this functionality follows immediately from the fact that -=:dir= sets the value of the emacs variable =default-directory=, -thanks to [[http://www.gnu.org/software/tramp/][tramp]]. Those using XEmacs, or GNU Emacs prior to -version 23 may need to install tramp separately in order for the -above features to work correctly. - -@subsubheading Further points - - If =:dir= is used in conjunction with =:session=, although it - will determine the starting directory for a new session as - expected, no attempt is currently made to alter the directory - associated with an existing session. - - =:dir= should typically not be used to create files during - export with =:exports results= or =:exports both=. The reason - is that, in order to retain portability of exported material - between machines, during export, links inserted into the buffer - will *not* be expanded against default directory. Therefore, if - default-directory is altered using =:dir=, it it probable that - the file will be created in a location to which the link does - not point. -@subsubsection =:exports= - :PROPERTIES: - :CUSTOM_ID: header-argument-exports - :END: - - Specify what should be included in HTML or LaTeX exports of the - Org-mode file. - - - code :: the default. The body of code is included - into the exported file. E.g., =:exports code=. - - results :: the result of evaluating the code is included in the - exported file. E.g., =:exports results=. - - both :: both the code and results are included in the exported - file. E.g., =:exports both=. - - none :: nothing is included in the exported file. E.g., - =:exports none=. - -@subsubsection =:tangle= - :PROPERTIES: - :CUSTOM_ID: tangle-header-arguments - :END: - - Specify whether or not the source code block should be included - in tangled extraction of source code files. - - - yes :: the source code block is exported to a source code file - named after the basename (name w/o extension) of the - Org-mode file. E.g., =:tangle yes=. - - no :: the default. The source code block is not - exported to a source code file. E.g., =:tangle no=. - - other :: Any other string passed to the =:tangle= header argument - is interpreted as a file basename to which the block will - be exported. E.g., =:tangle basename=. - -@subsubsection =:session= - :PROPERTIES: - :CUSTOM_ID: header-argument-session - :END: - - Start a session for an interpreted language where state is - preserved. This applies particularly to the supported languages - python, R and ruby. - - By default, a session is not started. - - A string passed to the =:session= header argument will give the - session a name. This makes it possible to run concurrent - sessions for each interpreted language. - -@subsubsection =:noweb= - :PROPERTIES: - :CUSTOM_ID: header-argument-noweb - :END: - - Controls the expansion of [[noweb-reference-syntax][noweb syntax]] references in a - source code block. This header argument can have one of two - values: =yes= or =no=. - - =no= :: the default. No [[noweb-reference-syntax][noweb syntax]] specific action is taken - on evaluating source code blocks/ However, noweb references - will still be expanded during tangling. - - =yes= :: all [[noweb-reference-syntax][noweb syntax]] references in the body of the source - code block will be expanded before the block is evaluated. - -@subsubheading Noweb Prefix Lines - - Noweb insertions are now placed behind the line prefix of the - =<>=. - - This behavior is illustrated in the following example. Because - the =<>= noweb reference appears behind the SQL - comment syntax, each line of the expanded noweb reference will - be commented. - - This source code block: - - @example - -- <> - @end example - - - expands to: - - @example - -- this is the - -- multi-line body of example - @end example - - Note that noweb replacement text that does *not* contain any - newlines will not be affected by this change, so it is still - possible to use inline noweb references. - - Thanks to Sébastien Vauban for this idea. - -@subsubsection =:cache= - :PROPERTIES: - :CUSTOM_ID: header-argument-cache - :END: - - Controls the use of in-buffer caching of source code block - results to avoid re-running unchanged source code blocks. This - header argument can have one of two values: =yes= or =no=. - - =no= :: The default. No caching takes place and the source - code block will be run every time it is executed. - - =yes= :: every time the source code block is run a sha1 hash of - the code and arguments passed to the block will be - generated. This hash is packed into the =#+results:= line - of the results and will be checked on subsequent executions - of the source code block. If the source code block has not - changed since the last time it was evaluated, it will not be - re-evaluated. - -@section Results - :PROPERTIES: - :CUSTOM_ID: results-specification - :END: - - The way in which results are handled depends on whether a [[header-argument-session][session]] - is invoked, as well as on whether - [[header-argument-results-collection][=:results value=] or - [[header-argument-results-collection][=:results output=]] is used. The following table shows the - possibilities: - - | | non-session (default) | =:session= | - |-------------------+--------------------------+-------------------------------------| - | =:results value= | value of last expression | value of last expression | - | =:results output= | contents of stdout | concatenation of interpreter output | - - *Note:* With =:results value=, the result in both =:session= and - non-session is returned to Org-mode as a table (a one- or - two-dimensional vector of strings or numbers) when appropriate. - -@subsection Non-session -@subsubsection =:results value= - This is the default. Internally, the value is obtained by - wrapping the code in a function definition in the external - language, and evaluating that function. Therefore, code should be - written as if it were the body of such a function. In particular, - note that python does not automatically return a value from a - function unless a =return= statement is present, and so a - 'return' statement will usually be required in python. - - This is the only one of the four evaluation contexts in which the - code is automatically wrapped in a function definition. - -@subsubsection =:results output= - The code is passed to the interpreter as an external process, and - the contents of the standard output stream are returned as - text. (In certain languages this also contains the error output - stream; this is an area for future work.) - -@subsection =:session= -@subsubsection =:results value= - The code is passed to the interpreter running as an interactive - Emacs inferior process. The result returned is the result of the - last evaluation performed by the interpreter. (This is obtained in - a language-specific manner: the value of the variable =_= in - python and ruby, and the value of =.Last.value= in R). - -@subsubsection =:results output= - The code is passed to the interpreter running as an interactive - Emacs inferior process. The result returned is the concatenation - of the sequence of (text) output from the interactive - interpreter. Notice that this is not necessarily the same as what - would be sent to stdout if the same code were passed to a - non-interactive interpreter running as an external process. For - example, compare the following two blocks: - - -@example -#+begin_src python :results output - print "hello" - 2 - print "bye" -#+end_src - -#+resname: - : hello - : bye -@end example - - In non-session mode, the '2' is not printed and does not appear. -@example -#+begin_src python :results output :session - print "hello" - 2 - print "bye" -#+end_src - -#+resname: - : hello - : 2 - : bye -@end example - - But in =:session= mode, the interactive interpreter receives input '2' - and prints out its value, '2'. (Indeed, the other print statements are - unnecessary here). - -@section Noweb Reference Syntax - :PROPERTIES: - :CUSTOM_ID: noweb-reference-syntax - :END: - - The [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] Literate Programming system allows named blocks of code to - be referenced by using the familiar Noweb syntax: - : <> - - Noweb references are handled differently during evaluation and - tangling. - - When a document is tangled, Noweb references are replaced with the - named source code block. - - When a source code block is evaluated, the action depends upon the - value of the =:noweb= header argument. If =:noweb yes=, then a - Noweb reference is expanded before evaluation. If =:noweb no=, - the default, then the reference is not expanded before - evaluation. - - *Note:* the default value, =:noweb no=, was chosen to ensure that - Org-babel does not break correct code in a language, such as Ruby, - where =<>= is a syntactically valid construct. If =<>= is - not syntactically valid in languages that you use, then please - consider [[*System%20wide][setting the default value]]. - - An example that uses the Noweb reference syntax is provided in the - [[literate programming example]]. - -@section Key Bindings & Useful Functions - - Org-babel re-binds many common Org-mode key sequences depending on - the context. Within a source-code block the following sequences - are rebound: - | =C-c C-c= | [[function-org-babel-execute][org-babel-execute-src-block]] | - | =C-c C-o= | [[function-org-babel-open-src-block-result][org-babel-open-src-block-result]] | - | =C-up= | [[function-org-babel-load-in-session][org-babel-load-in-session]] | - | =M-down= | [[function-org-babel-pop-to-session][org-babel-pop-to-session]] | - - Org-babel also exposes a number of functions behind the common - =org-babel-key-prefix= of =C-c M-b=: -@example - #+begin_src emacs-lisp :exports none - (lambda (binding - (list (format "\\C-c \\M-b %s" - (car binding)) - (format "[[function-%s][%s]]" - (cdr binding) (cdr binding)))) - org-babel-key-bindings) - #+end_src -@end example - - | =C-c M-b t= | [[function-org-babel-tangle][org-babel-tangle]] | - | =C-c M-b T= | [[function-org-babel-tangle-file][org-babel-tangle-file]] | - | =C-c M-b e= | [[function-org-babel-execute-src-block][org-babel-execute-src-block]] | - | =C-c M-b s= | [[function-org-babel-execute-subtree][org-babel-execute-subtree]] | - | =C-c M-b b= | [[function-org-babel-execute-buffer][org-babel-execute-buffer]] | - | =C-c M-b h= | [[function-org-babel-sha1-hash][org-babel-sha1-hash]] | - | =C-c M-b g= | [[function-org-babel-goto-named-source-block][org-babel-goto-named-source-block]] | - | =C-c M-b l= | [[function-org-babel-lob-ingest][org-babel-lob-ingest]] | - -@subsection Functions -@subsubsection org-babel-execute-src-block - :PROPERTIES: - :CUSTOM_ID: function-org-babel-execute-src-block - :END: - -@example - org-babel-execute-src-block is an interactive Lisp function in - `org-babel.el'. - - (org-babel-execute-src-block &optional ARG INFO PARAMS) - - Execute the current source code block, and insert the results - into the buffer. Source code execution and the collection and - formatting of results can be controlled through a variety of - header arguments. - - Optionally supply a value for INFO in the form returned by - `org-babel-get-src-block-info'. - - Optionally supply a value for PARAMS which will be merged with - the header arguments specified at the front of the source code - block. -@end example - -@subsubsection org-babel-open-src-block-result - :PROPERTIES: - :CUSTOM_ID: function-org-babel-open-src-block-result - :END: - -@example - org-babel-open-src-block-result is an interactive Lisp function in - `org-babel.el'. - - (org-babel-open-src-block-result &optional RE-RUN) - - If `point' is on a src block then open the results of the - source code block, otherwise return nil. With optional prefix - argument RE-RUN the source-code block is evaluated even if - results already exist. -@end example - -@subsubsection org-babel-load-in-session - :PROPERTIES: - :CUSTOM_ID: function-org-babel-load-in-session - :END: - -@example - org-babel-load-in-session is an interactive Lisp function in - `org-babel.el'. - - (org-babel-load-in-session &optional ARG INFO) - - Load the body of the current source-code block. Evaluate the - header arguments for the source block before entering the - session. After loading the body this pops open the session. - - [back] -@end example - -@subsubsection org-babel-pop-to-session - :PROPERTIES: - :CUSTOM_ID: function-org-babel-pop-to-session - :END: - -@example - org-babel-pop-to-session is an interactive Lisp function in - `org-babel.el'. - - (org-babel-pop-to-session &optional ARG INFO) - - Pop to the session of the current source-code block. If - called with a prefix argument then evaluate the header arguments - for the source block before entering the session. Copy the body - of the source block to the kill ring. - - [back] -@end example - -@subsubsection org-babel-tangle - :PROPERTIES: - :CUSTOM_ID: function-org-babel-tangle - :END: - -@example - org-babel-tangle is an interactive Lisp function in - `org-babel-tangle.el'. - - It is bound to C-c M-b t. - - (org-babel-tangle &optional TARGET-FILE LANG) - - Extract the bodies of all source code blocks from the current - file into their own source-specific files. Optional argument - TARGET-FILE can be used to specify a default export file for all - source blocks. Optional argument LANG can be used to limit the - exported source code blocks by language. -@end example - -@subsubsection org-babel-execute-subtree - :PROPERTIES: - :CUSTOM_ID: function-org-babel-execute-subtree - :END: - -@example - org-babel-execute-subtree is an interactive Lisp function in - `org-babel.el'. - - It is bound to C-c M-b s. - - (org-babel-execute-subtree &optional ARG) - - Replace EVAL snippets in the entire subtree. -@end example - -@subsubsection org-babel-execute-buffer - :PROPERTIES: - :CUSTOM_ID: function-org-babel-execute-buffer - :END: - -@example - org-babel-execute-buffer is an interactive Lisp function in - `org-babel.el'. - - It is bound to C-c M-b b. - - (org-babel-execute-buffer &optional ARG) - - Replace EVAL snippets in the entire buffer. -@end example - -@subsubsection org-babel-sha1-hash - :PROPERTIES: - :CUSTOM_ID: function-org-babel-sha1-hash - :END: - -@example - org-babel-sha1-hash is an interactive Lisp function in `org-babel.el'. - - It is bound to C-c M-b h. - - (org-babel-sha1-hash &optional INFO) - - Not documented. -@end example - -@subsubsection org-babel-goto-named-source-block - :PROPERTIES: - :CUSTOM_ID: function-org-babel-goto-named-source-block - :END: - -@example - org-babel-goto-named-source-block is an interactive Lisp function in - `org-babel.el'. - - It is bound to C-c M-b g. - - (org-babel-goto-named-source-block &optional NAME) - - Go to a named source-code block. -@end example - -@subsubsection org-babel-lob-ingest - :PROPERTIES: - :CUSTOM_ID: function-org-babel-lob-ingest - :END: - -@example - org-babel-lob-ingest is an interactive Lisp function in - `org-babel-lob.el'. - - It is bound to C-c M-b l. - - (org-babel-lob-ingest &optional FILE) - - Add all source-blocks defined in FILE to `org-babel-library-of-babel'. -@end example - -@section Batch Execution -It is possible to call Org-babel functions from the command line. -This shell script calls [[function-org-babel-tangle][org-babel-tangle]] on every one of its -arguments. - -Be sure to adjust the paths to fit your system. -@example - #!/bin/sh - # -*- mode: shell-script -*- - # - # tangle a file with org-babel - # - DIR=`pwd` - FILES="" - - # wrap each argument in the code required to call tangle on it - for i in $@@; do - FILES="$FILES \"$i\"" - done - - emacsclient \ - --eval "(progn - (add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\")) - (add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\")) - (require 'org)(require 'org-exp)(require 'org-babel) - (mapc (lambda (file) - (find-file (expand-file-name file \"$DIR\")) - (org-babel-tangle) - (kill-buffer)) '($FILES)))" -@end example - -@section Footnotes - -[fn:1] The former use of the =shell= identifier is now deprecated. - -[fn:2] As long as the interpreter executable is found on the remote -machine: see the variable =tramp-remote-path= From 1e5cd51736b61bb61dc290266196e2fcaf282279 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 22:13:18 -0400 Subject: [PATCH 012/138] Delete separate file for new chapter --- doc/source-code-chapter.texi | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 doc/source-code-chapter.texi diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi deleted file mode 100644 index e69de29bb..000000000 From f2b1a0fd7ce58033cf7e6beec69bb219e9ecc370 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 22:19:19 -0400 Subject: [PATCH 013/138] Use angle bracket tags to refer to structural elements of code block --- doc/org.texi | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 22d5b9fdd..f110024ba 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10890,23 +10890,23 @@ Using code blocks in table formulas The basic structure of code blocks is as follows: @example -#+srcname: name -#+begin_src language header-arguments switches -body +#+srcname: +#+begin_src
+ #+end_src @end example @table @code -@item name +@item The initial name line is optional. If present it is used during code evaluation. -@item language +@item The language of the code in the block. -@item header-arguments +@item
Header arguments control evaluation, export and tangling of source code blocks. See the [[header-arguments][Header Arguments]] section. -@item switches +@item FIXME link/relocate switches discussion in ``Literal examples'' section -@item body +@item The code @end table From 27dcffe5927dba0c739cf506eb6bf8ce8bb6e3f9 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 22:19:32 -0400 Subject: [PATCH 014/138] Minor edits --- doc/org.texi | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index f110024ba..c0515b14b 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10915,27 +10915,27 @@ The code @comment Editing Source Code, Exporting Code Blocks, Structure of Code Blocks, Working With Source Code @section Editing Source Code -Use @kbd{C-c '} to edit the code block at point. This brings up a -language major-mode buffer containing the body of the code -block. Saving this buffer will write the new contents back to the Org -buffer. Use @kbd{C-c '} again to exit. +Use @kbd{C-c '} to edit the code block at point. This brings up a language +major-mode edit buffer containing the body of the code block. Saving this +buffer will write the new contents back to the Org buffer. Use @kbd{C-c '} +again to exit. -The edit buffer has a minor mode active called -@code{org-src-mode}. The following variables can be used to configure -the behavior of the edit buffer. See also the customization group -@code{org-edit-structure} for futher configuration options. +The edit buffer has a minor mode active called @code{org-src-mode}. The +following variables can be used to configure the behavior of the edit +buffer. See also the customization group @code{org-edit-structure} for futher +configuration options. @table @code @item org-src-lang-modes If an emacs major-mode named @code{-mode} exists, where -@code{} is the language named in header line of the code block, +@code{} is the language named in the header line of the code block, then the edit buffer will be placed in that major-mode. This variable can be used to map arbitrary language names to existing major modes. @item org-src-window-setup Controls the way Emacs windows are rearranged when the edit buffer is created. @item org-src-preserve-indentation This variable is expecially useful for tangling languages such as -python, where whitespace the indentation in the output is critical. +python, in which whitespace indentation in the output is critical. @item org-src-ask-before-returning-to-edit-buffer By default, Org will ask before returning to an open edit buffer. Set to a non-nil value to switch without asking. From 77fd62ec3b9fd592d1de25b143bf5ea86a5fba56 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Wed, 14 Apr 2010 16:47:44 -0400 Subject: [PATCH 015/138] Add entry to main menu --- doc/org.texi | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/org.texi b/doc/org.texi index c0515b14b..4a1a31fb9 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -502,6 +502,7 @@ example as: @r{@bullet{} a basic database application} @r{@bullet{} a simple hypertext system, with HTML and La@TeX{} export} @r{@bullet{} a publishing tool to create a set of interlinked webpages} +@r{@bullet{} an environment for literate programming} @end example Org's automatic, context-sensitive table editor with spreadsheet From f5e8f5e87877a6cd2b5ab6461213b9f0fc378852 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sat, 17 Apr 2010 20:19:55 -0400 Subject: [PATCH 016/138] Work on initial sections. --- doc/org.texi | 147 ++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 116 insertions(+), 31 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 4a1a31fb9..caa42f7cc 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10859,7 +10859,7 @@ Source code can be included in Org-mode documents using a @samp{src} block: #+END_SRC @end example -Org provides the following features for working with such code blocks: +Org provides the following features for working with blocks of code: @itemize @bullet @item @@ -10892,21 +10892,21 @@ The basic structure of code blocks is as follows: @example #+srcname: -#+begin_src
+#+begin_src
#+end_src @end example @table @code @item -The initial name line is optional. If present it is used during code evaluation. +An optional name for the block (see @ref{Evaluating Code Blocks}) @item The language of the code in the block. -@item
-Header arguments control evaluation, export and tangling of source -code blocks. See the [[header-arguments][Header Arguments]] section. @item -FIXME link/relocate switches discussion in ``Literal examples'' section +Optional links FIXME link/relocate switches discussion in @ref{Literal examples} +@item
+Optional header arguments control many aspects of evaluation, export and tangling of +source code blocks. See the [[header-arguments][Header Arguments]] section. @item The code @end table @@ -10947,11 +10947,64 @@ to a non-nil value to switch without asking. @comment Exporting Code Blocks, Extracting Source Code, Editing Source Code, Working With Source Code @section Exporting Code Blocks +By default, code blocks export to HTML with the appearance of the fontified +language major-mode Emacs buffer. A similar effect is possible with LaTeX if +you turn on the option @code{org-export-latex-listings} and make sure that +the listings package is included by the LaTeX header FIXME: be more specific +about latex config. + +FIXME: This duplicated discussion in @ref{Literal examples}. Add +documentation of relevant switches. + +The @code{:exports} header argument can be used to specify non-default export behavior: + +@table @code +@item :exports results +On export, the code block will be executed and the block will be replaced by +the results of the code block (as determined by the values of other header +arguments such as @code{results} and @code{file}. +@item :exports both +On export, the code block will be executed and the exported material will +contain the code, followed by the results. +@item :exports code +The default. The body of the code block is exported as described above. +@end table + @node Extracting Source Code, Evaluating Code Blocks, Exporting Code Blocks, Working With Source Code @comment node-name, next, previous, up @comment Extracting Source Code, Evaluating Code Blocks, Exporting Code Blocks, Working With Source Code @section Extracting Source Code +Creating monolingual code files by extracting code from source blocks is +referred to as ``tangling''. + +Header arguments: +@table @code +@item :tangle no +The default. +@item :tangle yes +Include block in tangled output. The output file name is the name of the org +file with the extension @samp{.org} replaced by the extension for the block language. +@item :tangle filename +Include block in tangled output to file @samp{filename} +@end table + +Functions: +@table @code +@item org-babel-tangle @key{C-c M-b t} +Tangle the current file +@item org-babel-tangle-file +Choose a file to tangle +@end table + +Variables: +@table @code +@item org-babel-tangle-langs +FIXME: This variable may have been changed recently +@end table + + + @node Evaluating Code Blocks, , Extracting Source Code, Working With Source Code @comment node-name, next, previous, up @comment Evaluating Code Blocks, , Extracting Source Code, Working With Source Code @@ -11014,30 +11067,62 @@ body Org-babel has support for the following languages. - | Language | Documentation | Identifier | Requirements | - |----------------+-----------------------------+------------+---------------------------------------------| - | Asymptote | org-babel-doc-asymptote | asymptote | [[http://asymptote.sourceforge.net/][asymptote]], [[http://asymptote.sourceforge.net/doc/Editing-modes.html][asy-mode]] | - | C | [[file:languages/org-babel-doc-C.org][org-babel-doc-C]] | C | none | - | Clojure | [[file:languages/org-babel-doc-clojure.org][org-babel-doc-clojure]] | clojure | [[http://clojure.org/][clojure]], [[http://www.emacswiki.org/emacs/clojure-mode.el][clojure-mode]], [[http://common-lisp.net/project/slime/][slime]], [[http://clojure.codestuffs.com/][swank-clojure]] | - | css | org-babel-doc-css | css | none | - | ditaa | org-babel-doc-ditaa | ditaa | [[http://ditaa.org/ditaa/][ditaa]] (bundled with Org-mode) | - | Graphviz | org-babel-doc-dot | dot | [[http://www.graphviz.org/][dot]] | - | Emacs Lisp | org-babel-doc-emacs-lisp | emacs-lisp | none | - | gnuplot | org-babel-doc-gnuplot | gnuplot | [[http://www.gnuplot.info/][gnuplot]], [[http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html][gnuplot-mode]] | - | Haskell | org-babel-doc-haskell | haskell | [[http://www.haskell.org/][haskell]], [[http://projects.haskell.org/haskellmode-emacs/][haskell-mode]], [[http://www.haskell.org/haskellwiki/Haskell_mode_for_Emacs#inf-haskell.el:_the_best_thing_since_the_breadknife][inf-haskell]], [[http://people.cs.uu.nl/andres/lhs2tex/][lhs2tex]] | - | Matlab | [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] | matlab | matlab, [[http://sourceforge.net/projects/matlab-emacs/][matlab.el]] | - | LaTeX | [[file:languages/org-babel-doc-LaTeX.org][org-babel-doc-latex]] | latex | [[http://www.latex-project.org/][latex]], [[http://www.gnu.org/software/auctex/][auctex]], [[http://www.gnu.org/software/auctex/reftex.html][reftex]] | - | Objective Caml | org-babel-doc-ocaml | ocaml | [[http://caml.inria.fr/][ocaml]], [[http://www-rocq.inria.fr/~acohen/tuareg/][tuareg-mode]] | - | Octave | [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] | octave | octave | - | OZ | [[file:languages/org-babel-doc-oz.org][org-babel-doc-oz]] | oz | [[http://www.mozart-oz.org/][Mozart]] which includes a major mode | - | Perl | org-babel-doc-perl | perl | [[http://www.perl.org/][perl]], [[http://www.emacswiki.org/emacs/CPerlMode][cperl-mode]] (optional) | - | Python | org-babel-doc-python | python | [[http://www.python.org/][python]], [[https://launchpad.net/python-mode][python-mode]] (optional) | - | R | [[file:languages/org-babel-doc-R.org][org-babel-doc-R]] | R | [[http://www.r-project.org/][R]], [[http://ess.r-project.org/][ess-mode]] | - | Ruby | org-babel-doc-ruby | ruby | [[http://www.ruby-lang.org/][ruby]], [[http://www.ruby-lang.org/][irb]], [[http://github.com/eschulte/rinari/raw/master/util/ruby-mode.el][ruby-mode]], [[http://github.com/eschulte/rinari/raw/master/util/inf-ruby.el][inf-ruby mode]] | - | Sass | org-babel-doc-sass | sass | [[http://sass-lang.com/][sass]], [[http://github.com/nex3/haml/blob/master/extra/sass-mode.el][sass-mode]] | - | GNU Screen | [[file:languages/org-babel-doc-screen.org][org-babel-doc-screen]] | screen | [[http://www.gnu.org/software/screen/][screen]], a terminal | - | shell | org-babel-doc-sh | sh[fn:1] | a shell | - | SQL | org-babel-doc-sql | sql | none | +@c BEGIN RECEIVE ORGTBL org_babel_lang-table +@multitable @columnfractions 0.036 0.205 0.026 0.733 +@item Language @tab Documentation @tab Identifier @tab Requirements +@item Asymptote @tab org-babel-doc-asymptote @tab asymptote @tab [[http://asymptote.sourceforge.net/][asymptote]], [[http://asymptote.sourceforge.net/doc/Editing-modes.html][asy-mode]] +@item C @tab [[file:languages/org-babel-doc-C.org][org-babel-doc-C]] @tab C @tab none +@item Clojure @tab [[file:languages/org-babel-doc-clojure.org][org-babel-doc-clojure]] @tab clojure @tab [[http://clojure.org/][clojure]], [[http://www.emacswiki.org/emacs/clojure-mode.el][clojure-mode]], [[http://common-lisp.net/project/slime/][slime]], [[http://clojure.codestuffs.com/][swank-clojure]] +@item css @tab org-babel-doc-css @tab css @tab none +@item ditaa @tab org-babel-doc-ditaa @tab ditaa @tab [[http://ditaa.org/ditaa/][ditaa]] (bundled with Org-mode) +@item Graphviz @tab org-babel-doc-dot @tab dot @tab [[http://www.graphviz.org/][dot]] +@item Emacs Lisp @tab org-babel-doc-emacs-lisp @tab emacs-lisp @tab none +@item gnuplot @tab org-babel-doc-gnuplot @tab gnuplot @tab [[http://www.gnuplot.info/][gnuplot]], [[http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html][gnuplot-mode]] +@item Haskell @tab org-babel-doc-haskell @tab haskell @tab [[http://www.haskell.org/][haskell]], [[http://projects.haskell.org/haskellmode-emacs/][haskell-mode]], [[http://www.haskell.org/haskellwiki/Haskell_mode_for_Emacs#inf-haskell.el:_the_best_thing_since_the_breadknife][inf-haskell]], [[http://people.cs.uu.nl/andres/lhs2tex/][lhs2tex]] +@item Matlab @tab [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] @tab matlab @tab matlab, [[http://sourceforge.net/projects/matlab-emacs/][matlab.el]] +@item LaTeX @tab [[file:languages/org-babel-doc-LaTeX.org][org-babel-doc-latex]] @tab latex @tab [[http://www.latex-project.org/][latex]], [[http://www.gnu.org/software/auctex/][auctex]], [[http://www.gnu.org/software/auctex/reftex.html][reftex]] +@item Objective Caml @tab org-babel-doc-ocaml @tab ocaml @tab [[http://caml.inria.fr/][ocaml]], [[http://www-rocq.inria.fr/~acohen/tuareg/][tuareg-mode]] +@item Octave @tab [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] @tab octave @tab octave +@item OZ @tab [[file:languages/org-babel-doc-oz.org][org-babel-doc-oz]] @tab oz @tab [[http://www.mozart-oz.org/][Mozart]] which includes a major mode +@item Perl @tab org-babel-doc-perl @tab perl @tab [[http://www.perl.org/][perl]], [[http://www.emacswiki.org/emacs/CPerlMode][cperl-mode]] (optional) +@item Python @tab org-babel-doc-python @tab python @tab [[http://www.python.org/][python]], [[https://launchpad.net/python-mode][python-mode]] (optional) +@item R @tab [[file:languages/org-babel-doc-R.org][org-babel-doc-R]] @tab R @tab [[http://www.r-project.org/][R]], [[http://ess.r-project.org/][ess-mode]] +@item Ruby @tab org-babel-doc-ruby @tab ruby @tab [[http://www.ruby-lang.org/][ruby]], [[http://www.ruby-lang.org/][irb]], [[http://github.com/eschulte/rinari/raw/master/util/ruby-mode.el][ruby-mode]], [[http://github.com/eschulte/rinari/raw/master/util/inf-ruby.el][inf-ruby mode]] +@item Sass @tab org-babel-doc-sass @tab sass @tab [[http://sass-lang.com/][sass]], [[http://github.com/nex3/haml/blob/master/extra/sass-mode.el][sass-mode]] +@item GNU Screen @tab [[file:languages/org-babel-doc-screen.org][org-babel-doc-screen]] @tab screen @tab [[http://www.gnu.org/software/screen/][screen]], a terminal +@item shell @tab org-babel-doc-sh @tab sh[fn:1] @tab a shell +@item SQL @tab org-babel-doc-sql @tab sql @tab none +@end multitable +@c END RECEIVE ORGTBL org_babel_lang-table + +@ignore + +#+ORGTBL: SEND org-babel-lang-table orgtbl-to-texinfo :splice t :skip 2 + | Language | Documentation | Identifier | Requirements | + |----------------+---------------------------------------------------------------------------------+------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | Asymptote | org-babel-doc-asymptote | asymptote | [[http://asymptote.sourceforge.net/][asymptote]], [[http://asymptote.sourceforge.net/doc/Editing-modes.html][asy-mode]] | + | C | [[file:languages/org-babel-doc-C.org][org-babel-doc-C]] | C | none | + | Clojure | [[file:languages/org-babel-doc-clojure.org][org-babel-doc-clojure]] | clojure | [[http://clojure.org/][clojure]], [[http://www.emacswiki.org/emacs/clojure-mode.el][clojure-mode]], [[http://common-lisp.net/project/slime/][slime]], [[http://clojure.codestuffs.com/][swank-clojure]] | + | css | org-babel-doc-css | css | none | + | ditaa | org-babel-doc-ditaa | ditaa | [[http://ditaa.org/ditaa/][ditaa]] (bundled with Org-mode) | + | Graphviz | org-babel-doc-dot | dot | [[http://www.graphviz.org/][dot]] | + | Emacs Lisp | org-babel-doc-emacs-lisp | emacs-lisp | none | + | gnuplot | org-babel-doc-gnuplot | gnuplot | [[http://www.gnuplot.info/][gnuplot]], [[http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html][gnuplot-mode]] | + | Haskell | org-babel-doc-haskell | haskell | [[http://www.haskell.org/][haskell]], [[http://projects.haskell.org/haskellmode-emacs/][haskell-mode]], [[http://www.haskell.org/haskellwiki/Haskell_mode_for_Emacs#inf-haskell.el:_the_best_thing_since_the_breadknife][inf-haskell]], [[http://people.cs.uu.nl/andres/lhs2tex/][lhs2tex]] | + | Matlab | [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] | matlab | matlab, [[http://sourceforge.net/projects/matlab-emacs/][matlab.el]] | + | LaTeX | [[file:languages/org-babel-doc-LaTeX.org][org-babel-doc-latex]] | latex | [[http://www.latex-project.org/][latex]], [[http://www.gnu.org/software/auctex/][auctex]], [[http://www.gnu.org/software/auctex/reftex.html][reftex]] | + | Objective Caml | org-babel-doc-ocaml | ocaml | [[http://caml.inria.fr/][ocaml]], [[http://www-rocq.inria.fr/~acohen/tuareg/][tuareg-mode]] | + | Octave | [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] | octave | octave | + | OZ | [[file:languages/org-babel-doc-oz.org][org-babel-doc-oz]] | oz | [[http://www.mozart-oz.org/][Mozart]] which includes a major mode | + | Perl | org-babel-doc-perl | perl | [[http://www.perl.org/][perl]], [[http://www.emacswiki.org/emacs/CPerlMode][cperl-mode]] (optional) | + | Python | org-babel-doc-python | python | [[http://www.python.org/][python]], [[https://launchpad.net/python-mode][python-mode]] (optional) | + | R | [[file:languages/org-babel-doc-R.org][org-babel-doc-R]] | R | [[http://www.r-project.org/][R]], [[http://ess.r-project.org/][ess-mode]] | + | Ruby | org-babel-doc-ruby | ruby | [[http://www.ruby-lang.org/][ruby]], [[http://www.ruby-lang.org/][irb]], [[http://github.com/eschulte/rinari/raw/master/util/ruby-mode.el][ruby-mode]], [[http://github.com/eschulte/rinari/raw/master/util/inf-ruby.el][inf-ruby mode]] | + | Sass | org-babel-doc-sass | sass | [[http://sass-lang.com/][sass]], [[http://github.com/nex3/haml/blob/master/extra/sass-mode.el][sass-mode]] | + | GNU Screen | [[file:languages/org-babel-doc-screen.org][org-babel-doc-screen]] | screen | [[http://www.gnu.org/software/screen/][screen]], a terminal | + | shell | org-babel-doc-sh | sh[fn:1] | a shell | + | SQL | org-babel-doc-sql | sql | none | +@end ignore To add support for a particular language to your Org-babel installation first make sure that the requirements of the language From 3ac08f1b4e5669588427c17d584580af050bfeae Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sat, 17 Apr 2010 21:47:57 -0400 Subject: [PATCH 017/138] Edits, mainly to header args section --- doc/org.texi | 160 ++++++++++++++++++++++++++++++++++----------------- 1 file changed, 107 insertions(+), 53 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index caa42f7cc..e4081290b 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10888,7 +10888,7 @@ Using code blocks in table formulas @comment Structure of Code Blocks, Editing Source Code, Working With Source Code, Working With Source Code @section Structure of Code Blocks -The basic structure of code blocks is as follows: +The structure of code blocks is as follows: @example #+srcname: @@ -10905,8 +10905,10 @@ The language of the code in the block. @item Optional links FIXME link/relocate switches discussion in @ref{Literal examples} @item
-Optional header arguments control many aspects of evaluation, export and tangling of -source code blocks. See the [[header-arguments][Header Arguments]] section. +Optional header arguments control many aspects of evaluation, export and +tangling of source code blocks. See the [[header-arguments][Header +Arguments]] section. Header arguments can also be set on a per-buffer or +per-subtree basis using properties. @item The code @end table @@ -10948,10 +10950,14 @@ to a non-nil value to switch without asking. @section Exporting Code Blocks By default, code blocks export to HTML with the appearance of the fontified -language major-mode Emacs buffer. A similar effect is possible with LaTeX if -you turn on the option @code{org-export-latex-listings} and make sure that -the listings package is included by the LaTeX header FIXME: be more specific -about latex config. +language major-mode Emacs buffer + +FIXME: say something more knowledgable about the HTML/CSS output. + +A similar effect is possible with LaTeX if you turn on +the option @code{org-export-latex-listings} and make sure that the listings +package is included by the LaTeX header FIXME: be more specific about latex +config. FIXME: This duplicated discussion in @ref{Literal examples}. Add documentation of relevant switches. @@ -11010,6 +11016,11 @@ FIXME: This variable may have been changed recently @comment Evaluating Code Blocks, , Extracting Source Code, Working With Source Code @section Evaluating Code Blocks +For many languages, blocks of code can be evaluated, with the results being +returned to the org buffer (or linked to from the org buffer). + +FIXME: Are we going to use ``evaluate'' or ``execute'' + This syntax can be expanded by naming the source code block. @example @@ -11065,39 +11076,69 @@ body :CUSTOM_ID: languages :END: - Org-babel has support for the following languages. +Org-babel can evaluate/execute/compile the following languages. See the +language specific documentation on Worg for details. -@c BEGIN RECEIVE ORGTBL org_babel_lang-table -@multitable @columnfractions 0.036 0.205 0.026 0.733 -@item Language @tab Documentation @tab Identifier @tab Requirements -@item Asymptote @tab org-babel-doc-asymptote @tab asymptote @tab [[http://asymptote.sourceforge.net/][asymptote]], [[http://asymptote.sourceforge.net/doc/Editing-modes.html][asy-mode]] -@item C @tab [[file:languages/org-babel-doc-C.org][org-babel-doc-C]] @tab C @tab none -@item Clojure @tab [[file:languages/org-babel-doc-clojure.org][org-babel-doc-clojure]] @tab clojure @tab [[http://clojure.org/][clojure]], [[http://www.emacswiki.org/emacs/clojure-mode.el][clojure-mode]], [[http://common-lisp.net/project/slime/][slime]], [[http://clojure.codestuffs.com/][swank-clojure]] -@item css @tab org-babel-doc-css @tab css @tab none -@item ditaa @tab org-babel-doc-ditaa @tab ditaa @tab [[http://ditaa.org/ditaa/][ditaa]] (bundled with Org-mode) -@item Graphviz @tab org-babel-doc-dot @tab dot @tab [[http://www.graphviz.org/][dot]] -@item Emacs Lisp @tab org-babel-doc-emacs-lisp @tab emacs-lisp @tab none -@item gnuplot @tab org-babel-doc-gnuplot @tab gnuplot @tab [[http://www.gnuplot.info/][gnuplot]], [[http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html][gnuplot-mode]] -@item Haskell @tab org-babel-doc-haskell @tab haskell @tab [[http://www.haskell.org/][haskell]], [[http://projects.haskell.org/haskellmode-emacs/][haskell-mode]], [[http://www.haskell.org/haskellwiki/Haskell_mode_for_Emacs#inf-haskell.el:_the_best_thing_since_the_breadknife][inf-haskell]], [[http://people.cs.uu.nl/andres/lhs2tex/][lhs2tex]] -@item Matlab @tab [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] @tab matlab @tab matlab, [[http://sourceforge.net/projects/matlab-emacs/][matlab.el]] -@item LaTeX @tab [[file:languages/org-babel-doc-LaTeX.org][org-babel-doc-latex]] @tab latex @tab [[http://www.latex-project.org/][latex]], [[http://www.gnu.org/software/auctex/][auctex]], [[http://www.gnu.org/software/auctex/reftex.html][reftex]] -@item Objective Caml @tab org-babel-doc-ocaml @tab ocaml @tab [[http://caml.inria.fr/][ocaml]], [[http://www-rocq.inria.fr/~acohen/tuareg/][tuareg-mode]] -@item Octave @tab [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] @tab octave @tab octave -@item OZ @tab [[file:languages/org-babel-doc-oz.org][org-babel-doc-oz]] @tab oz @tab [[http://www.mozart-oz.org/][Mozart]] which includes a major mode -@item Perl @tab org-babel-doc-perl @tab perl @tab [[http://www.perl.org/][perl]], [[http://www.emacswiki.org/emacs/CPerlMode][cperl-mode]] (optional) -@item Python @tab org-babel-doc-python @tab python @tab [[http://www.python.org/][python]], [[https://launchpad.net/python-mode][python-mode]] (optional) -@item R @tab [[file:languages/org-babel-doc-R.org][org-babel-doc-R]] @tab R @tab [[http://www.r-project.org/][R]], [[http://ess.r-project.org/][ess-mode]] -@item Ruby @tab org-babel-doc-ruby @tab ruby @tab [[http://www.ruby-lang.org/][ruby]], [[http://www.ruby-lang.org/][irb]], [[http://github.com/eschulte/rinari/raw/master/util/ruby-mode.el][ruby-mode]], [[http://github.com/eschulte/rinari/raw/master/util/inf-ruby.el][inf-ruby mode]] -@item Sass @tab org-babel-doc-sass @tab sass @tab [[http://sass-lang.com/][sass]], [[http://github.com/nex3/haml/blob/master/extra/sass-mode.el][sass-mode]] -@item GNU Screen @tab [[file:languages/org-babel-doc-screen.org][org-babel-doc-screen]] @tab screen @tab [[http://www.gnu.org/software/screen/][screen]], a terminal -@item shell @tab org-babel-doc-sh @tab sh[fn:1] @tab a shell -@item SQL @tab org-babel-doc-sql @tab sql @tab none +FIXME: How are we going to refer to the external documentation? + +@c BEGIN RECEIVE ORGTBL org-babel-lang-table +@multitable @columnfractions 0.583 0.417 +@item Language @tab Identifier +@item Asymptote @tab asymptote +@item C @tab C +@item Clojure @tab clojure +@item css @tab css +@item ditaa @tab ditaa +@item Graphviz @tab dot +@item Emacs Lisp @tab emacs-lisp +@item gnuplot @tab gnuplot +@item Haskell @tab haskell +@item Matlab @tab matlab +@item LaTeX @tab latex +@item Objective Caml @tab ocaml +@item Octave @tab octave +@item OZ @tab oz +@item Perl @tab perl +@item Python @tab python +@item R @tab R +@item Ruby @tab ruby +@item Sass @tab sass +@item GNU Screen @tab screen +@item shell @tab sh[fn:1] +@item SQL @tab sql @end multitable -@c END RECEIVE ORGTBL org_babel_lang-table +@c END RECEIVE ORGTBL org-babel-lang-table @ignore +The original table from reference.org is below; I'm just using the first column for now. + +#+ORGTBL: SEND org-babel-lang-table orgtbl-to-texinfo + | Language | Identifier | + |----------------+------------| + | Asymptote | asymptote | + | C | C | + | Clojure | clojure | + | css | css | + | ditaa | ditaa | + | Graphviz | dot | + | Emacs Lisp | emacs-lisp | + | gnuplot | gnuplot | + | Haskell | haskell | + | Matlab | matlab | + | LaTeX | latex | + | Objective Caml | ocaml | + | Octave | octave | + | OZ | oz | + | Perl | perl | + | Python | python | + | R | R | + | Ruby | ruby | + | Sass | sass | + | GNU Screen | screen | + | shell | sh[fn:1] | + | SQL | sql | + -#+ORGTBL: SEND org-babel-lang-table orgtbl-to-texinfo :splice t :skip 2 | Language | Documentation | Identifier | Requirements | |----------------+---------------------------------------------------------------------------------+------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Asymptote | org-babel-doc-asymptote | asymptote | [[http://asymptote.sourceforge.net/][asymptote]], [[http://asymptote.sourceforge.net/doc/Editing-modes.html][asy-mode]] | @@ -11122,31 +11163,34 @@ body | GNU Screen | [[file:languages/org-babel-doc-screen.org][org-babel-doc-screen]] | screen | [[http://www.gnu.org/software/screen/][screen]], a terminal | | shell | org-babel-doc-sh | sh[fn:1] | a shell | | SQL | org-babel-doc-sql | sql | none | + + @end ignore - To add support for a particular language to your Org-babel - installation first make sure that the requirements of the language - are met, then add a line like the following to your Emacs - configuration, (replace "identifier" with one of the - entries in the Identifier column of the table). - @example - (require 'org-babel-identifier) - @end example +To add support for a particular language to your Org-babel installation +first make sure that the requirements of the language are met, then add a +line like the following to your Emacs configuration, (replace "identifier" +with one of the entries in the Identifier column of the table). + +@example +(require 'org-babel-identifier) +@end example @section Header Arguments :PROPERTIES: :CUSTOM_ID: header-arguments :END: -Definitions of all Org-babel header arguments are given [[header-argument-specific-documentation][below]]. In -addition, some languages may add their own header arguments. Please -see the language-specific documentation for information on -language-specific header arguments. +Definitions of all Org-babel header arguments are given +[[header-argument-specific-documentation][below]]. In addition, some +languages may add their own header arguments. Please see the +language-specific documentation for information on language-specific header +arguments. @subsection Using Header Arguments -The values of header arguments can be set in three different ways, -each more specific than the last. +The values of header arguments can be set in four different ways, each +more specific (and having higher priority) than the last. @subsubsection System-wide :PROPERTIES: @@ -11180,10 +11224,20 @@ each more specific than the last. @subsubsection Org-mode Properties - Header arguments are also read from [[http://orgmode.org/manual/Properties-and-Columns.html#Properties-and-Columns][Org-mode properties]], which - means they can be set on the outline header level. For example, the - value of the =:cache= header argument will default to true in all - source code blocks under the following example of an Org-mode outline header: +Header arguments are also read from +[[http://orgmode.org/manual/Properties-and-Columns.html#Properties-and-Columns][Org-mode +properties]], which can be set on a buffer-wide or per-heading basis. An +example of setting a header argument for all code blocks in a buffer is + +#+begin_example +#+property: tangle yes +#+end_example + +When properties are used to set default header arguments, they are looked up +with inheritance, so the value of the =:cache= header argument will default +to true in all source code blocks in the subtree rooted at the following +heading: + @example * outline header :PROPERTIES: From 9e8b6c0831eb0f210da2d114505c6b7263380757 Mon Sep 17 00:00:00 2001 From: Tom Dye Date: Sat, 22 May 2010 07:36:19 -1000 Subject: [PATCH 018/138] Changed old C-c M-b prefixes to C-c C-v --- doc/org.texi | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index e4081290b..e504c21f6 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10997,7 +10997,7 @@ Include block in tangled output to file @samp{filename} Functions: @table @code -@item org-babel-tangle @key{C-c M-b t} +@item org-babel-tangle @key{C-c C-v t} Tangle the current file @item org-babel-tangle-file Choose a file to tangle @@ -11831,7 +11831,7 @@ above features to work correctly. | =M-down= | [[function-org-babel-pop-to-session][org-babel-pop-to-session]] | Org-babel also exposes a number of functions behind the common - =org-babel-key-prefix= of =C-c M-b=: + =org-babel-key-prefix= of =C-c C-v=: @example #+begin_src emacs-lisp :exports none (lambda (binding @@ -11843,14 +11843,14 @@ above features to work correctly. #+end_src @end example - | =C-c M-b t= | [[function-org-babel-tangle][org-babel-tangle]] | - | =C-c M-b T= | [[function-org-babel-tangle-file][org-babel-tangle-file]] | - | =C-c M-b e= | [[function-org-babel-execute-src-block][org-babel-execute-src-block]] | - | =C-c M-b s= | [[function-org-babel-execute-subtree][org-babel-execute-subtree]] | - | =C-c M-b b= | [[function-org-babel-execute-buffer][org-babel-execute-buffer]] | - | =C-c M-b h= | [[function-org-babel-sha1-hash][org-babel-sha1-hash]] | - | =C-c M-b g= | [[function-org-babel-goto-named-source-block][org-babel-goto-named-source-block]] | - | =C-c M-b l= | [[function-org-babel-lob-ingest][org-babel-lob-ingest]] | + | =C-c C-v t= | [[function-org-babel-tangle][org-babel-tangle]] | + | =C-c C-v T= | [[function-org-babel-tangle-file][org-babel-tangle-file]] | + | =C-c C-v e= | [[function-org-babel-execute-src-block][org-babel-execute-src-block]] | + | =C-c C-v s= | [[function-org-babel-execute-subtree][org-babel-execute-subtree]] | + | =C-c C-v b= | [[function-org-babel-execute-buffer][org-babel-execute-buffer]] | + | =C-c C-v h= | [[function-org-babel-sha1-hash][org-babel-sha1-hash]] | + | =C-c C-v g= | [[function-org-babel-goto-named-source-block][org-babel-goto-named-source-block]] | + | =C-c C-v l= | [[function-org-babel-lob-ingest][org-babel-lob-ingest]] | @subsection Functions @subsubsection org-babel-execute-src-block @@ -11940,7 +11940,7 @@ above features to work correctly. org-babel-tangle is an interactive Lisp function in `org-babel-tangle.el'. - It is bound to C-c M-b t. + It is bound to C-c C-v t. (org-babel-tangle &optional TARGET-FILE LANG) @@ -11960,7 +11960,7 @@ above features to work correctly. org-babel-execute-subtree is an interactive Lisp function in `org-babel.el'. - It is bound to C-c M-b s. + It is bound to C-c C-v s. (org-babel-execute-subtree &optional ARG) @@ -11976,7 +11976,7 @@ above features to work correctly. org-babel-execute-buffer is an interactive Lisp function in `org-babel.el'. - It is bound to C-c M-b b. + It is bound to C-c C-v b. (org-babel-execute-buffer &optional ARG) @@ -11991,7 +11991,7 @@ above features to work correctly. @example org-babel-sha1-hash is an interactive Lisp function in `org-babel.el'. - It is bound to C-c M-b h. + It is bound to C-c C-v h. (org-babel-sha1-hash &optional INFO) @@ -12007,7 +12007,7 @@ above features to work correctly. org-babel-goto-named-source-block is an interactive Lisp function in `org-babel.el'. - It is bound to C-c M-b g. + It is bound to C-c C-v g. (org-babel-goto-named-source-block &optional NAME) @@ -12023,7 +12023,7 @@ above features to work correctly. org-babel-lob-ingest is an interactive Lisp function in `org-babel-lob.el'. - It is bound to C-c M-b l. + It is bound to C-c C-v l. (org-babel-lob-ingest &optional FILE) From d7b239718403258a801863aa21dd065ce917826f Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Wed, 9 Jun 2010 14:47:59 -0700 Subject: [PATCH 019/138] pushing through first half or so of babel documentation, compiling --- doc/org.texi | 202 +++++++++++++++++++++++++-------------------------- 1 file changed, 100 insertions(+), 102 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index e504c21f6..210e2d44a 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10847,7 +10847,7 @@ This may be necessary in particular if files include other files via @node Working With Source Code, Miscellaneous, Publishing, Top @comment node-name, next, previous, up @comment Working With Source Code, Miscellaneous, Publishing, Top -@chapter ``Working With Source Code'' or ``Embedded Source Code'' +@chapter Working With Source Code Source code can be included in Org-mode documents using a @samp{src} block: @@ -10880,6 +10880,11 @@ Using code blocks in table formulas * Exporting Code Blocks:: * Extracting Source Code:: * Evaluating Code Blocks:: +* Library of Babel:: +* Languages:: +* Header Arguments:: +* Noweb Reference Syntax:: +* Key Bindings & Useful Functions:: @end menu @@ -10899,16 +10904,21 @@ The structure of code blocks is as follows: @table @code @item -An optional name for the block (see @ref{Evaluating Code Blocks}) +This name is associated with the source code block. This is similar to the +@samp{#+tblname} lines that can be used to name tables in Org-mode files. +Referencing the name of a source code block makes it possible to evaluate the +block from other places in the file, other files, or from inside of Org-mode +tables. @item The language of the code in the block. @item -Optional links FIXME link/relocate switches discussion in @ref{Literal examples} +Switches controling exportation of the code block (see switches discussion in +@ref{Literal examples}) @item
Optional header arguments control many aspects of evaluation, export and -tangling of source code blocks. See the [[header-arguments][Header -Arguments]] section. Header arguments can also be set on a per-buffer or -per-subtree basis using properties. +tangling of source code blocks. See the @ref{Header Arguments} +section. Header arguments can also be set on a per-buffer or per-subtree +basis using properties. @item The code @end table @@ -10923,10 +10933,10 @@ major-mode edit buffer containing the body of the code block. Saving this buffer will write the new contents back to the Org buffer. Use @kbd{C-c '} again to exit. -The edit buffer has a minor mode active called @code{org-src-mode}. The +The @code{org-src-mode} minor mode will be active in the edit buffer. The following variables can be used to configure the behavior of the edit -buffer. See also the customization group @code{org-edit-structure} for futher -configuration options. +buffer. See also the customization group @code{org-edit-structure} for +further configuration options. @table @code @item org-src-lang-modes @@ -10937,7 +10947,7 @@ can be used to map arbitrary language names to existing major modes. @item org-src-window-setup Controls the way Emacs windows are rearranged when the edit buffer is created. @item org-src-preserve-indentation -This variable is expecially useful for tangling languages such as +This variable is especially useful for tangling languages such as python, in which whitespace indentation in the output is critical. @item org-src-ask-before-returning-to-edit-buffer By default, Org will ask before returning to an open edit buffer. Set @@ -10949,31 +10959,31 @@ to a non-nil value to switch without asking. @comment Exporting Code Blocks, Extracting Source Code, Editing Source Code, Working With Source Code @section Exporting Code Blocks -By default, code blocks export to HTML with the appearance of the fontified -language major-mode Emacs buffer +It is possible to export the contents of code blocks, the results of code +block evaluation, or neither or both. For most languages by default only +body of a code blocks will be exported, however some languages +(e.g. @code{ditaa}) default to exporting the results of the code block. For +information on the exportation of code blocks bodies see @ref{Literal +examples}. -FIXME: say something more knowledgable about the HTML/CSS output. - -A similar effect is possible with LaTeX if you turn on -the option @code{org-export-latex-listings} and make sure that the listings -package is included by the LaTeX header FIXME: be more specific about latex -config. - -FIXME: This duplicated discussion in @ref{Literal examples}. Add -documentation of relevant switches. - -The @code{:exports} header argument can be used to specify non-default export behavior: +The @code{:exports} header argument can be used to specify non-default export +behavior: +Header arguments: @table @code @item :exports results -On export, the code block will be executed and the block will be replaced by -the results of the code block (as determined by the values of other header -arguments such as @code{results} and @code{file}. +On export, the code block will be evaluated and the results will be placed in +the org-mode buffer (either updating previous results of the code block +located anywhere in the buffer, or if no previous results exist placing the +new results immediately after the code block). The actual body of the code +block will not be exported. @item :exports both -On export, the code block will be executed and the exported material will -contain the code, followed by the results. +On export, the code block will be evaluated and the results inserted into the +buffer as described above, however the body of the code block will be +exported as well. @item :exports code -The default. The body of the code block is exported as described above. +The default (in most languages). Only the body of the code block is exported +as described in @ref{Literal examples}. @end table @node Extracting Source Code, Evaluating Code Blocks, Exporting Code Blocks, Working With Source Code @@ -10981,8 +10991,11 @@ The default. The body of the code block is exported as described above. @comment Extracting Source Code, Evaluating Code Blocks, Exporting Code Blocks, Working With Source Code @section Extracting Source Code -Creating monolingual code files by extracting code from source blocks is -referred to as ``tangling''. +Creating pure source code files by extracting code from source blocks is +referred to as ``tangling'' -- a term adopted from the literate programming +community. During ``tangling'' of code blocks their bodies are expanded +using @code{org-babel-expand-src-block} which can expand both variable and +``noweb'' (see @ref{Noweb Reference Syntax}) style references. Header arguments: @table @code @@ -10990,7 +11003,8 @@ Header arguments: The default. @item :tangle yes Include block in tangled output. The output file name is the name of the org -file with the extension @samp{.org} replaced by the extension for the block language. +file with the extension @samp{.org} replaced by the extension for the block +language. @item :tangle filename Include block in tangled output to file @samp{filename} @end table @@ -11010,76 +11024,60 @@ FIXME: This variable may have been changed recently @end table - -@node Evaluating Code Blocks, , Extracting Source Code, Working With Source Code +@node Evaluating Code Blocks, Library of Babel, Extracting Source Code, Working With Source Code @comment node-name, next, previous, up @comment Evaluating Code Blocks, , Extracting Source Code, Working With Source Code @section Evaluating Code Blocks -For many languages, blocks of code can be evaluated, with the results being -returned to the org buffer (or linked to from the org buffer). +For many language, blocks of code can be evaluated and the results +incorporated into the org-mode buffer. Check the value of the +@code{org-babel-interpreters} for a list of evaluable languages on your +system, also see @ref{Languages}. See @ref{Structure of Code Blocks} for +information on the syntax used to define a code block. -FIXME: Are we going to use ``evaluate'' or ``execute'' +There are a number of ways of evaluating code blocks. The simplest is to +press @key{C-c C-c} with the point on a code block. This will call the +@code{org-babel-execute-src-block} function evaluating the block and +inserting its results into the Org-mode buffer. -This syntax can be expanded by naming the source code block. +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 +@code{#+function} or @code{#+lob}) lines can be used to remotely execute code +blocks located in the current Org-mode buffer or in the ``Library of Babel'' +(see @ref{Library of Babel}). Both of these lines use the following syntax. @example -#+sourcename -#+begin_src language header-arguments switches -body -#+end_src +#+call: ()
@end example -- name :: This name is associated with the source code block. This is - similar to the =#+tblname= lines that can be used to name tables - in Org-mode files. Referencing the name of a source code - block makes it possible to evaluate the block from other places in - the file, other files, or inside Org-mode tables. It - is also possible to pass arguments to a source code block through - this =#+source:= line (see [[alternate-argument-syntax][Alternate argument syntax]]). +@table @code +@item +This name is associated with the source code block to be evaluated. +@item +Arguments specified in this section will be passed to the code block. +@item
+Header arguments can be placed after the function invocation. See +@ref{Header Arguments} for more information on header arguments. +@end table -@subsection Library of Babel -[[file:library-of-babel.org][Library of Babel]] functions can be called using the following syntax. -@example -#+lob: R-plot(data=R-plot-example-data) -@end example +@node Library of Babel, Languages, Evaluating Code Blocks, Working With Source Code +@section Library of Babel +The ``Library of Babel'' is two things. First it is a library of code blocks +which can be called from any Org-mode file, and second it is an actual +Org-mode file located in the @samp{contrib} directory of Org-mode in which +Org-mode users may deposit contributed functions which they believe to be +generally useful. Code blocks defined in the``Library of Babel'' can be +called remotely as if they were in the current Org-mode buffer (see +@ref{Evaluating Code Blocks} for information on the syntax of remote code +block evaluation). -@subsection Aliases - Keyword aliases are intended to make Org-babel feel natural to - programmers fluent in a variety of languages. For example, - @example - #+srcname: alias-example - #+begin_src emacs-lisp - '((call lob) - (source function srcname) - (results resname)) - #+end_src - #+results: alias-example - | call | lob | | - | source | function | srcname | - | results | resname | | - @end example - - =#+srcname:= can be replaced with either of two aliases, =#+source:= or =#+function:=. - - =#+results:= can be replaced with its alias, =#+resname:=. - - When calling Library of Babel functions, as in the following - example, there are two acceptable keywords. The =#+lob= call in - the example could be replaced with its alias, =#+call=. - @example - #+lob: R-plot(data=R-plot-example-data) - @end example - -@subsection Languages - :PROPERTIES: - :CUSTOM_ID: languages - :END: - -Org-babel can evaluate/execute/compile the following languages. See the -language specific documentation on Worg for details. - -FIXME: How are we going to refer to the external documentation? +@node Languages, Header Arguments, Library of Babel, Working With Source Code +@section Languages +Org-babel provides support for the following languages. See the language +specific documentation and an up to date list of languages is available at +@uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}. @c BEGIN RECEIVE ORGTBL org-babel-lang-table @multitable @columnfractions 0.583 0.417 @@ -11135,7 +11133,7 @@ The original table from reference.org is below; I'm just using the first column | Ruby | ruby | | Sass | sass | | GNU Screen | screen | - | shell | sh[fn:1] | + | shell | sh | | SQL | sql | @@ -11167,15 +11165,17 @@ The original table from reference.org is below; I'm just using the first column @end ignore -To add support for a particular language to your Org-babel installation -first make sure that the requirements of the language are met, then add a -line like the following to your Emacs configuration, (replace "identifier" -with one of the entries in the Identifier column of the table). +To add support for a particular language to your Org-babel installation first +make sure that the requirements of the language are met, then add a line like +the following to your Emacs configuration, (replace ``identifier'' with one +of the language names from the above table). @example (require 'org-babel-identifier) @end example + +@node Header Arguments, Noweb Reference Syntax, Languages, Working With Source Code @section Header Arguments :PROPERTIES: :CUSTOM_ID: header-arguments @@ -11552,7 +11552,7 @@ heading: @subsubheading Remote execution A directory on a remote machine can be specified using [[http://www.gnu.org/software/tramp/#Filename-Syntax][tramp - filename syntax]], in which case the code will be executed on the + filename syntax]], in which case the code will be evaluated on the remote machine[fn:2]. An example is @example @@ -11694,7 +11694,7 @@ above features to work correctly. results to avoid re-running unchanged source code blocks. This header argument can have one of two values: =yes= or =no=. - =no= :: The default. No caching takes place and the source - code block will be run every time it is executed. + code block will be run every time it is evaluated. - =yes= :: every time the source code block is run a sha1 hash of the code and arguments passed to the block will be generated. This hash is packed into the =#+results:= line @@ -11790,11 +11790,9 @@ above features to work correctly. and prints out its value, '2'. (Indeed, the other print statements are unnecessary here). -@section Noweb Reference Syntax - :PROPERTIES: - :CUSTOM_ID: noweb-reference-syntax - :END: +@node Noweb Reference Syntax, Key Bindings & Useful Functions, Header Arguments, Working With Source Code +@section Noweb Reference Syntax The [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] Literate Programming system allows named blocks of code to be referenced by using the familiar Noweb syntax: : <> @@ -11820,6 +11818,8 @@ above features to work correctly. An example that uses the Noweb reference syntax is provided in the [[literate programming example]]. + +@node Key Bindings & Useful Functions, , Noweb Reference Syntax, Working With Source Code @section Key Bindings & Useful Functions Org-babel re-binds many common Org-mode key sequences depending on @@ -11864,7 +11864,7 @@ above features to work correctly. (org-babel-execute-src-block &optional ARG INFO PARAMS) - Execute the current source code block, and insert the results + Evaluate 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. @@ -14216,8 +14216,6 @@ org-customize @key{RET}} and then click yourself through the tree. @end ignore @c Local variables: -@c ispell-local-dictionary: "en_US-w_accents" -@c ispell-local-pdict: "./.aspell.org.pws" @c fill-column: 77 @c End: From 2760c8e79800970e119465105c103e7a9324b90e Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Wed, 9 Jun 2010 16:17:58 -0700 Subject: [PATCH 020/138] babel-doc: working on Header Arguments -- not quite compiling --- doc/org.texi | 578 +++++++++++++++++++++++++-------------------------- 1 file changed, 283 insertions(+), 295 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 210e2d44a..db5709815 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10883,6 +10883,7 @@ Using code blocks in table formulas * Library of Babel:: * Languages:: * Header Arguments:: +* Results:: * Noweb Reference Syntax:: * Key Bindings & Useful Functions:: @end menu @@ -11150,11 +11151,11 @@ The original table from reference.org is below; I'm just using the first column | Haskell | org-babel-doc-haskell | haskell | [[http://www.haskell.org/][haskell]], [[http://projects.haskell.org/haskellmode-emacs/][haskell-mode]], [[http://www.haskell.org/haskellwiki/Haskell_mode_for_Emacs#inf-haskell.el:_the_best_thing_since_the_breadknife][inf-haskell]], [[http://people.cs.uu.nl/andres/lhs2tex/][lhs2tex]] | | Matlab | [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] | matlab | matlab, [[http://sourceforge.net/projects/matlab-emacs/][matlab.el]] | | LaTeX | [[file:languages/org-babel-doc-LaTeX.org][org-babel-doc-latex]] | latex | [[http://www.latex-project.org/][latex]], [[http://www.gnu.org/software/auctex/][auctex]], [[http://www.gnu.org/software/auctex/reftex.html][reftex]] | - | Objective Caml | org-babel-doc-ocaml | ocaml | [[http://caml.inria.fr/][ocaml]], [[http://www-rocq.inria.fr/~acohen/tuareg/][tuareg-mode]] | + | Objective Caml | org-babel-doc-ocaml | ocaml | [[http://caml.inria.fr/][ocaml]], [[http://www-rock.inria.fr/~acohen/tuareg/][tuareg-mode]] | | Octave | [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] | octave | octave | | OZ | [[file:languages/org-babel-doc-oz.org][org-babel-doc-oz]] | oz | [[http://www.mozart-oz.org/][Mozart]] which includes a major mode | | Perl | org-babel-doc-perl | perl | [[http://www.perl.org/][perl]], [[http://www.emacswiki.org/emacs/CPerlMode][cperl-mode]] (optional) | - | Python | org-babel-doc-python | python | [[http://www.python.org/][python]], [[https://launchpad.net/python-mode][python-mode]] (optional) | + | Python | org-babel-doc-python | python | [[http://www.python.org/][python]], [[https://launch pad.net/python-mode][python-mode]] (optional) | | R | [[file:languages/org-babel-doc-R.org][org-babel-doc-R]] | R | [[http://www.r-project.org/][R]], [[http://ess.r-project.org/][ess-mode]] | | Ruby | org-babel-doc-ruby | ruby | [[http://www.ruby-lang.org/][ruby]], [[http://www.ruby-lang.org/][irb]], [[http://github.com/eschulte/rinari/raw/master/util/ruby-mode.el][ruby-mode]], [[http://github.com/eschulte/rinari/raw/master/util/inf-ruby.el][inf-ruby mode]] | | Sass | org-babel-doc-sass | sass | [[http://sass-lang.com/][sass]], [[http://github.com/nex3/haml/blob/master/extra/sass-mode.el][sass-mode]] | @@ -11175,209 +11176,227 @@ of the language names from the above table). @end example -@node Header Arguments, Noweb Reference Syntax, Languages, Working With Source Code +@node Header Arguments, Results, Languages, Working With Source Code @section Header Arguments - :PROPERTIES: - :CUSTOM_ID: header-arguments - :END: -Definitions of all Org-babel header arguments are given -[[header-argument-specific-documentation][below]]. In addition, some -languages may add their own header arguments. Please see the -language-specific documentation for information on language-specific header -arguments. +Definitions of all Org-babel header arguments are given (see @ref{Specific +Header Arguments}). In addition, some languages may add their own header +arguments. Please see the language-specific documentation (available at +@uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}.) +for information on language-specific header arguments. +@menu +* Using Header Arguments:: +* System-wide Header Arguments:: +* Language Specific Header Arguments:: +* Header Arguments in Org-mode Properties:: +* Header Arguments in Source Code Blocks:: +* Specific Header Arguments:: +* Using Header Arguments:: +@end menu + +@node Using Header Arguments, System-wide Header Arguments, , Header Arguments @subsection Using Header Arguments -The values of header arguments can be set in four different ways, each -more specific (and having higher priority) than the last. +The values of header arguments can be set in four different ways, each more +specific (and having higher priority) than the last. -@subsubsection System-wide - :PROPERTIES: - :CUSTOM_ID: system-wide-header-argument - :END: +@node System-wide Header Arguments, Language Specific Header Arguments, Using Header Arguments, Header Arguments +@subsubsection System-wide Header Arguments +System-wide values of header arguments can be specified by customizing the +@code{org-babel-default-header-args} variable: - System-wide values of header arguments can be specified by - customizing the =org-babel-default-header-args= variable: - @example - org-babel-default-header-args is a variable defined in `org-babel.el'. - Its value is - ((:session . "none") - (:results . "replace") - (:exports . "code") - (:cache . "no") - (:noweb . "no")) +@example + org-babel-default-header-args is a variable defined in `org-babel.el'. + Its value is + ((:session . "none") + (:results . "replace") + (:exports . "code") + (:cache . "no") + (:noweb . "no")) - Documentation: - Default arguments to use when evaluating a source block. - @end example - [[#default-noweb]] - For example, the following example could be used to set the default value - of =:noweb= header arguments to =yes=. This would have the effect of - expanding =:noweb= references by default when evaluating source code blocks. - @example - (setq org-babel-default-header-args - (cons '(:noweb . "yes") - (assq-delete-all :noweb org-babel-default-header-args))) - @end example + Documentation: + Default arguments to use when evaluating a source block. +@end example -@subsubsection Org-mode Properties +For example, the following example could be used to set the default value of +@code{:noweb} header arguments to =yes=. This would have the effect of +expanding @code{:noweb} references by default when evaluating source code +blocks. -Header arguments are also read from -[[http://orgmode.org/manual/Properties-and-Columns.html#Properties-and-Columns][Org-mode -properties]], which can be set on a buffer-wide or per-heading basis. An -example of setting a header argument for all code blocks in a buffer is +@example + (setq org-babel-default-header-args + (cons '(:noweb . "yes") + (assq-delete-all :noweb org-babel-default-header-args))) +@end example -#+begin_example + +@node Language Specific Header Arguments, Header Arguments in Org-mode Properties, System-wide Header Arguments, Header Arguments +@subsubsection Header Arguments in Org-mode Properties +Each language can define it's own set of default header arguments. + +@node Header Arguments in Org-mode Properties, Header Arguments in Source Code Blocks, Language Specific Header Arguments, Header Arguments +@subsubsection Header Arguments in Org-mode Properties + +Header arguments are also read from Org-mode properties (see @ref{Property +syntax}), which can be set on a buffer-wide or per-heading basis. An example +of setting a header argument for all code blocks in a buffer is + +@example #+property: tangle yes -#+end_example +@end example When properties are used to set default header arguments, they are looked up with inheritance, so the value of the =:cache= header argument will default to true in all source code blocks in the subtree rooted at the following heading: - @example - * outline header - :PROPERTIES: - :cache: yes - :CUSTOM_ID: property-set-header-arguments - :END: - @end example - Properties defined in this way override the properties set in - =org-babel-default-header-args=. It is convenient to use the - =org-set-property= function bound to =C-c C-x p= to set properties - in Org-mode documents. - -@subsubsection Source Code Block +@example + * outline header :PROPERTIES: - :CUSTOM_ID: single-block-header-arguments + :cache: yes + :CUSTOM_ID: property-set-header-arguments :END: - The most common way to assign values to header arguments is at the - source code block level. This can be done by listing a sequence of - header arguments and their values as part of the =#+begin_src= - line. Properties set in this way override both the values of - =org-babel-default-header-args= and header argument specified as - properties. In the following example, the - =:results= header argument is set to =silent=, meaning the results - of execution will not be inserted in the buffer, and the =:exports= - header argument is set to =code=, meaning only the body of the - source code block - will be preserved on export to HTML or LaTeX. - @example - #+source: factorial - #+begin_src haskell :results silent :exports code - fac 0 = 1 - fac n = n * fac (n-1) - #+end_src - @end example +@end example +Properties defined in this way override the properties set in +@code{org-babel-default-header-args}. It is convenient to use the +@code{org-set-property} function bound to @key{C-c C-x p} to set properties +in Org-mode documents. + + +@node Header Arguments in Source Code Blocks, Specific Header Arguments, Header Arguments in Org-mode Properties, Header Arguments +@subsubsection Header Arguments in Source Code Block + +The most common way to assign values to header arguments is at the source +code block level. This can be done by listing a sequence of header +arguments and their values as part of the @code{#+begin_src} line. +Properties set in this way override both the values of +@code{org-babel-default-header-args} and header argument specified as +properties. In the following example, the @code{:results} header argument +is set to @code{silent}, meaning the results of execution will not be +inserted in the buffer, and the @code{:exports} header argument is set to +@code{code}, meaning only the body of the source code block will be +preserved on export to HTML or LaTeX. + +@example + #+source: factorial + #+begin_src haskell :results silent :exports code + fac 0 = 1 + fac n = n * fac (n-1) + #+end_src +@end example + + +@node Specific Header Arguments, , Header Arguments in Source Code Blocks, Header Arguments @subsection Specific Header Arguments - :PROPERTIES: - :CUSTOM_ID: header-argument-specific-documentation - :END: +Description of every standard (non language-specific) Org-babel header +argument. -@subsubsection =:var= - :PROPERTIES: - :CUSTOM_ID: header-argument-var - :END: +@menu +* @code{var}:: +* @code{results}:: +* @code{file}:: +* @code{dir} and remote execution:: +* @code{exports}:: +* @code{tangle}:: +* @code{session}:: +* @code{noweb}:: +* @code{cache}:: +@end menu - The =:var= header argument is used to pass arguments to - source code blocks. The specifics of how arguments are included - in a source code block are language specific and are - addressed in the language-specific documentation. However, the - syntax used to specify arguments is the same across all - languages. The values passed to arguments can be or - - literal values - - values from org-mode tables - - the results of other source code blocks +@node @code{var}, @code{results}, , Specific Header Arguments +@subsubsection @code{var} +The @code{:var} header argument is used to pass arguments to +source code blocks. The specifics of how arguments are included +in a source code block are language specific and are +addressed in the language-specific documentation. However, the +syntax used to specify arguments is the same across all +languages. The values passed to arguments can be or +- literal values +- values from org-mode tables +- the results of other source code blocks - These values can be indexed in a manner similar to arrays -- see - [[var-argument-indexing][argument indexing]]. +These values can be indexed in a manner similar to arrays -- see argument +indexing FIXME/need section on argument indexing. - The following syntax is used to pass arguments to source code - blocks using the =:var= header argument. +The following syntax is used to pass arguments to source code +blocks using the @code{:var} header argument. - @example - :var name=assign - @end example +@example + :var name=assign +@end example - where =assign= can take one of the following forms +where @code{assign} can take one of the following forms - - literal value :: either a string ="string"= or a number =9=. - - reference :: a table name: +- literal value :: either a string @code{"string"} or a number @code{9}. +- reference :: a table name: - @example - #+tblname: example-table - | 1 | - | 2 | - | 3 | - | 4 | + @example + #+tblname: example-table + | 1 | + | 2 | + | 3 | + | 4 | - #+source: table-length - #+begin_src emacs-lisp :var table=example-table - (length table) - #+end_src + #+source: table-length + #+begin_src emacs-lisp :var table=example-table + (length table) + #+end_src - #+results: table-length - : 4 - @end example + #+results: table-length + : 4 + @end example - a source code block name, as assigned by =#+srcname:=, - followed by parentheses: + a source code block name, as assigned by =#+srcname:=, + followed by parentheses: - @example - #+begin_src emacs-lisp :var length=table-length() - (* 2 length) - #+end_src + @example + #+begin_src emacs-lisp :var length=table-length() + (* 2 length) + #+end_src - #+results: - : 8 - @end example + #+results: + : 8 + @end example - In addition, an argument can be passed to the source code - block referenced by =:var=. The argument is passed within - the parentheses following the source code block name: + In addition, an argument can be passed to the source code + block referenced by =:var=. The argument is passed within + the parentheses following the source code block name: - @example - #+source: double - #+begin_src emacs-lisp :var input=8 - (* 2 input) - #+end_src + @example + #+source: double + #+begin_src emacs-lisp :var input=8 + (* 2 input) + #+end_src - #+results: double - : 16 + #+results: double + : 16 - #+source: squared - #+begin_src emacs-lisp :var input=double(input=1) - (* input input) - #+end_src + #+source: squared + #+begin_src emacs-lisp :var input=double(input=1) + (* input input) + #+end_src - #+results: squared - : 4 - @end example + #+results: squared + : 4 + @end example @subsubheading alternate argument syntax - :PROPERTIES: - :CUSTOM_ID: alternate-argument-syntax - :END: +It is also possible to specify arguments in a potentially more +natural way using the =#+source:= line of a source code block. +As in the following example arguments can be packed inside of +parenthesis following the source name. - It is also possible to specify arguments in a potentially more - natural way using the =#+source:= line of a source code block. - As in the following example arguments can be packed inside of - parenthesis following the source name. - @example - #+source: double(input=0) - #+begin_src emacs-lisp - (* 2 input) - #+end_src - @end example +@example + #+source: double(input=0) + #+begin_src emacs-lisp + (* 2 input) + #+end_src +@end example **** indexable variable values - :PROPERTIES: - :CUSTOM_ID: var-argument-indexing - :END: It is possible to assign a portion of a value to a variable in a source block. The following example @@ -11423,10 +11442,8 @@ heading: function) and =describe-variable= (M-x describe variable) functions, respectively. -@subsubsection =:results= - :PROPERTIES: - :CUSTOM_ID: header-argument-results - :END: +@node @code{results}, @code{file}, @code{var}, Specific Header Arguments +@subsubsection @code{results} There are three types of results header argument: - *collection* header arguments specify how the results should be collected from @@ -11451,13 +11468,13 @@ heading: of the last statement in the source code block. This header argument places Org-babel in functional mode. Note that in some languages, e.g., python, - use of this result type requires that a =return= + use of this result type requires that a @code{return} statement be included in the body of the source code - block. E.g., =:results value=. + block. E.g., @code{:results value}. - output :: The result is the collection of everything printed to stdout during the execution of the source code block. This header argument places Org-babel in scripting - mode. E.g., =:results output=. + mode. E.g., @code{:results output}. @subsubheading type The following options are mutually exclusive and specify what @@ -11467,28 +11484,28 @@ heading: - table, vector :: The results should be interpreted as an Org-mode table. If a single value is returned, Org-babel will convert it - into a table with one row and one column. E.g., =:results - value table=. + into a table with one row and one column. E.g., @code{:results + value table}. - scalar, verbatim :: The results should be interpreted literally -- meaning they will not be converted into a table. The results will be inserted into the Org-mode buffer as - quoted text. E.g., =:results value verbatim=. + quoted text. E.g., @code{:results value verbatim}. - file :: The results will be interpreted as the path to a file, and will be inserted into the Org-mode buffer as a file - link. E.g., =:results value file=. + link. E.g., @code{:results value file}. - raw, org :: The results are interpreted as raw Org-mode code and are inserted directly into the buffer. If the results look like a table they will be aligned as such by Org-mode. - E.g., =:results value raw=. + E.g., @code{:results value raw}. - html :: Results are assumed to be HTML and will be enclosed in - a =begin_html= block. E.g., =:results value html=. + a @code{begin_html} block. E.g., @code{:results value html}. - latex :: Results assumed to be LaTeX and are enclosed in a - =begin_latex= block. E.g., =:results value latex=. + @code{begin_latex} block. E.g., @code{:results value latex}. - code :: Result are assumed to be parseable code and are - enclosed in a code block. E.g., =:results value code=. + enclosed in a code block. E.g., @code{:results value code}. - pp :: The result is converted to pretty-printed code and is enclosed in a code block. This option currently supports - Emacs Lisp, python, and ruby. E.g., =:results value pp=. + Emacs Lisp, python, and ruby. E.g., @code{:results value pp}. @subsubheading handling The following results options indicate what Org-babel should do @@ -11496,48 +11513,40 @@ heading: - silent :: The results will be echoed in the minibuffer but will not be inserted into the Org-mode buffer. E.g., - =:results output silent=. + @code{:results output silent}. - replace :: The default value. The results will be inserted - into the Org-mode buffer. E.g., =:results output - replace=. + into the Org-mode buffer. E.g., @code{:results output + replace}. -@subsubsection =:file= - :PROPERTIES: - :CUSTOM_ID: header-argument-file - :END: +@node @code{file}, @code{dir} and remote execution, @code{results}, Specific Header Arguments +@subsubsection @code{file} + @code{:file} is used to specify a path for file output in which case an + Org-mode style link (see @ref{Link format}) @code{file:} link is inserted + into the buffer as the result. Common examples are graphical output from + R, gnuplot, ditaa and LaTeX blocks. - =:file= is used to specify a path for file output in which case an - [[http://orgmode.org/manual/Link-format.html#Link-format][org style]] =file:= link is inserted into the buffer as the - result. Common examples are graphical output from [[file:languages/org-babel-doc-R.org][R]], gnuplot, - ditaa and [[file:languages/org-babel-doc-LaTeX.org][latex]] blocks. + Note that for some languages, including R, gnuplot, LaTeX and ditaa, + graphical output is sent to the specified file without the file being + referenced explicitly in the code block. See the documentation for the + individual languages for details. In contrast, general purpose languages + such as python and ruby require that the code explicitly create output + corresponding to the path indicated by @code{:file}. - See the [[#header-argument-dir][=:dir= and remote execution]] section for examples. + While the @code{:file} header argument can be used to specify the path to + the output file, - Note that for some languages, including [[file:languages/org-babel-doc-R.org][R]], gnuplot, [[file:languages/org-babel-doc-LaTeX.org][latex]] and - ditaa, graphical output is sent to the specified file without the - file being referenced explicitly in the code block. See the - documentation for the individual languages for details. In - contrast, general purpose languages such as python and ruby - require that the code explicitly create output corresponding to - the path indicated by =:file=. - - While the =:file= header argument can be used to specify the path - to the output file, - -@subsubsection =:dir= and remote execution - :PROPERTIES: - :CUSTOM_ID: header-argument-dir - :END: - =:dir= specifies the /default directory/ during code block +@node @code{dir} and remote execution, @code{exports}, @code{file}, Specific Header Arguments +@subsubsection @code{dir} and remote execution + @code{:dir} specifies the /default directory/ during code block execution. If it is absent, then the directory associated with the - current buffer is used. In other words, supplying =:dir path= - temporarily has the same effect as changing the current directory - with =M-x cd path=, and then not supplying =:dir=. Under the - surface, =:dir= simply sets the value of the emacs variable - =default-directory=. + current buffer is used. In other words, supplying @code{:dir path} + temporarily has the same effect as changing the current directory with + @key{M-x cd path}, and then not supplying @code{:dir}. Under the surface, + @code{:dir} simply sets the value of the emacs variable + @code{default-directory}. - When using =:dir=, you should supply a relative path for [[#header-argument-file][file - output]] (e.g. =:file myfile.jpg= or =:file results/myfile.jpg=) in + When using @code{:dir}, you should supply a relative path for file output + (e.g. @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in which case that path will be interpreted relative to the default directory. @@ -11551,9 +11560,9 @@ heading: @end example @subsubheading Remote execution - A directory on a remote machine can be specified using [[http://www.gnu.org/software/tramp/#Filename-Syntax][tramp - filename syntax]], in which case the code will be evaluated on the - remote machine[fn:2]. An example is + A directory on a remote machine can be specified using tramp file + syntax, in which case the code will be evaluated on the remote + machine. An example is @example #+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu: @@ -11573,95 +11582,82 @@ and a link of the following form will be inserted in the org buffer: [[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]] @end example -Most of this functionality follows immediately from the fact that -=:dir= sets the value of the emacs variable =default-directory=, -thanks to [[http://www.gnu.org/software/tramp/][tramp]]. Those using XEmacs, or GNU Emacs prior to -version 23 may need to install tramp separately in order for the -above features to work correctly. +Most of this functionality follows immediately from the fact that @code{:dir} +sets the value of the emacs variable @code{default-directory}, thanks to +tramp. Those using XEmacs, or GNU Emacs prior to version 23 may need to +install tramp separately in order for the above features to work correctly. @subsubheading Further points - - If =:dir= is used in conjunction with =:session=, although it + - If @code{:dir} is used in conjunction with @code{:session}, although it will determine the starting directory for a new session as expected, no attempt is currently made to alter the directory associated with an existing session. - - =:dir= should typically not be used to create files during - export with =:exports results= or =:exports both=. The reason + - @code{:dir} should typically not be used to create files during + export with @code{:exports results} or @code{:exports both}. The reason is that, in order to retain portability of exported material between machines, during export, links inserted into the buffer will *not* be expanded against default directory. Therefore, if - default-directory is altered using =:dir=, it it probable that + default-directory is altered using @code{:dir}, it it probable that the file will be created in a location to which the link does not point. -@subsubsection =:exports= - :PROPERTIES: - :CUSTOM_ID: header-argument-exports - :END: +@node @code{exports}, @code{tangle}, @code{dir} and remote execution, Specific Header Arguments +@subsubsection @code{exports} Specify what should be included in HTML or LaTeX exports of the Org-mode file. - code :: the default. The body of code is included - into the exported file. E.g., =:exports code=. + into the exported file. E.g., @code{:exports code}. - results :: the result of evaluating the code is included in the - exported file. E.g., =:exports results=. + exported file. E.g., @code{:exports results}. - both :: both the code and results are included in the exported - file. E.g., =:exports both=. + file. E.g., @code{:exports both}. - none :: nothing is included in the exported file. E.g., - =:exports none=. - -@subsubsection =:tangle= - :PROPERTIES: - :CUSTOM_ID: tangle-header-arguments - :END: + @code{:exports none}. +@node @code{tangle}, @code{session}, @code{exports}, Specific Header Arguments +@subsubsection @code{tangle} Specify whether or not the source code block should be included in tangled extraction of source code files. - yes :: the source code block is exported to a source code file named after the basename (name w/o extension) of the - Org-mode file. E.g., =:tangle yes=. + Org-mode file. E.g., @code{:tangle yes}. - no :: the default. The source code block is not - exported to a source code file. E.g., =:tangle no=. - - other :: Any other string passed to the =:tangle= header argument + exported to a source code file. E.g., @code{:tangle no}. + - other :: Any other string passed to the @code{:tangle} header argument is interpreted as a file basename to which the block will - be exported. E.g., =:tangle basename=. - -@subsubsection =:session= - :PROPERTIES: - :CUSTOM_ID: header-argument-session - :END: + be exported. E.g., @code{:tangle basename}. +@node @code{session}, @code{noweb}, @code{tangle}, Specific Header Arguments +@subsubsection @code{session} Start a session for an interpreted language where state is preserved. This applies particularly to the supported languages python, R and ruby. By default, a session is not started. - A string passed to the =:session= header argument will give the + A string passed to the @code{:session} header argument will give the session a name. This makes it possible to run concurrent sessions for each interpreted language. -@subsubsection =:noweb= - :PROPERTIES: - :CUSTOM_ID: header-argument-noweb - :END: - +@node @code{noweb}, @code{cache}, @code{session}, Specific Header Arguments +@subsubsection @code{noweb} Controls the expansion of [[noweb-reference-syntax][noweb syntax]] references in a source code block. This header argument can have one of two - values: =yes= or =no=. - - =no= :: the default. No [[noweb-reference-syntax][noweb syntax]] specific action is taken + values: @code{yes} or @code{no}. + - @code{no} :: the default. No [[noweb-reference-syntax][noweb syntax]] specific action is taken on evaluating source code blocks/ However, noweb references will still be expanded during tangling. - - =yes= :: all [[noweb-reference-syntax][noweb syntax]] references in the body of the source + - @code{yes} :: all [[noweb-reference-syntax][noweb syntax]] references in the body of the source code block will be expanded before the block is evaluated. @subsubheading Noweb Prefix Lines - Noweb insertions are now placed behind the line prefix of the - =<>=. + @code{<>}. This behavior is illustrated in the following example. Because - the =<>= noweb reference appears behind the SQL + the @code{<>} noweb reference appears behind the SQL comment syntax, each line of the expanded noweb reference will be commented. @@ -11685,80 +11681,72 @@ above features to work correctly. Thanks to Sébastien Vauban for this idea. -@subsubsection =:cache= - :PROPERTIES: - :CUSTOM_ID: header-argument-cache - :END: - +@node @code{cache}, , @code{noweb}, Specific Header Arguments +@subsubsection @code{cache} Controls the use of in-buffer caching of source code block results to avoid re-running unchanged source code blocks. This - header argument can have one of two values: =yes= or =no=. - - =no= :: The default. No caching takes place and the source + header argument can have one of two values: @code{yes} or @code{no}. + - @code{no} :: The default. No caching takes place and the source code block will be run every time it is evaluated. - - =yes= :: every time the source code block is run a sha1 hash of + - @code{yes} :: every time the source code block is run a sha1 hash of the code and arguments passed to the block will be - generated. This hash is packed into the =#+results:= line + generated. This hash is packed into the @code{#+results:} line of the results and will be checked on subsequent executions of the source code block. If the source code block has not changed since the last time it was evaluated, it will not be re-evaluated. +@node Results, Noweb Reference Syntax, Header Arguments, Working With Source Code @section Results - :PROPERTIES: - :CUSTOM_ID: results-specification - :END: - - The way in which results are handled depends on whether a [[header-argument-session][session]] - is invoked, as well as on whether - [[header-argument-results-collection][=:results value=] or - [[header-argument-results-collection][=:results output=]] is used. The following table shows the - possibilities: + The way in which results are handled depends on whether a + [[header-argument-session][session]] is invoked, as well as on whether + @code{:results value} or @code{:results output} is used. The following + table shows the possibilities: | | non-session (default) | =:session= | |-------------------+--------------------------+-------------------------------------| | =:results value= | value of last expression | value of last expression | | =:results output= | contents of stdout | concatenation of interpreter output | - *Note:* With =:results value=, the result in both =:session= and + *Note:* With @code{:results value}, the result in both @code{:session} and non-session is returned to Org-mode as a table (a one- or two-dimensional vector of strings or numbers) when appropriate. @subsection Non-session -@subsubsection =:results value= +@subsubsection @code{:results value} This is the default. Internally, the value is obtained by wrapping the code in a function definition in the external language, and evaluating that function. Therefore, code should be written as if it were the body of such a function. In particular, note that python does not automatically return a value from a - function unless a =return= statement is present, and so a + function unless a @code{return} statement is present, and so a 'return' statement will usually be required in python. This is the only one of the four evaluation contexts in which the code is automatically wrapped in a function definition. -@subsubsection =:results output= +@subsubsection @code{:results output} The code is passed to the interpreter as an external process, and the contents of the standard output stream are returned as text. (In certain languages this also contains the error output stream; this is an area for future work.) -@subsection =:session= -@subsubsection =:results value= - The code is passed to the interpreter running as an interactive - Emacs inferior process. The result returned is the result of the - last evaluation performed by the interpreter. (This is obtained in - a language-specific manner: the value of the variable =_= in - python and ruby, and the value of =.Last.value= in R). - -@subsubsection =:results output= - The code is passed to the interpreter running as an interactive - Emacs inferior process. The result returned is the concatenation - of the sequence of (text) output from the interactive - interpreter. Notice that this is not necessarily the same as what - would be sent to stdout if the same code were passed to a - non-interactive interpreter running as an external process. For - example, compare the following two blocks: +@subsection @code{:session} +@subsubsection @code{:results value} + The code is passed to the interpreter running as an interactive Emacs + inferior process. The result returned is the result of the last + evaluation performed by the interpreter. (This is obtained in a + language-specific manner: the value of the variable @code{_} in python + and ruby, and the value of @code{.Last.value} in R). +@subsubsection @code{:results output} + The code is passed to the interpreter running as an interactive Emacs + inferior process. The result returned is the concatenation of the + sequence of (text) output from the interactive interpreter. Notice + that this is not necessarily the same as what would be sent to + @code{STDOUT} if the same code were passed to a non-interactive + interpreter running as an external process. For example, compare the + following two blocks: @example #+begin_src python :results output @@ -11791,7 +11779,7 @@ above features to work correctly. unnecessary here). -@node Noweb Reference Syntax, Key Bindings & Useful Functions, Header Arguments, Working With Source Code +@node Noweb Reference Syntax, Key Bindings & Useful Functions, Results, Working With Source Code @section Noweb Reference Syntax The [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] Literate Programming system allows named blocks of code to be referenced by using the familiar Noweb syntax: From 33cc42ef5394c53439cb9f7f23609d4015ef5638 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Wed, 9 Jun 2010 16:21:52 -0700 Subject: [PATCH 021/138] babel-doc: stripped some @code{} wrappers and everything is now compiling --- doc/org.texi | 52 ++++++++++++++++++++++++++-------------------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index db5709815..09183f6cf 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -11295,18 +11295,18 @@ Description of every standard (non language-specific) Org-babel header argument. @menu -* @code{var}:: -* @code{results}:: -* @code{file}:: -* @code{dir} and remote execution:: -* @code{exports}:: -* @code{tangle}:: -* @code{session}:: -* @code{noweb}:: -* @code{cache}:: +* var:: +* results:: +* file:: +* dir and remote execution:: +* exports:: +* tangle:: +* session:: +* noweb:: +* cache:: @end menu -@node @code{var}, @code{results}, , Specific Header Arguments +@node var, results, , Specific Header Arguments @subsubsection @code{var} The @code{:var} header argument is used to pass arguments to source code blocks. The specifics of how arguments are included @@ -11442,8 +11442,8 @@ parenthesis following the source name. function) and =describe-variable= (M-x describe variable) functions, respectively. -@node @code{results}, @code{file}, @code{var}, Specific Header Arguments -@subsubsection @code{results} +@node results, file, var, Specific Header Arguments +@subsubsection results There are three types of results header argument: - *collection* header arguments specify how the results should be collected from @@ -11518,8 +11518,8 @@ parenthesis following the source name. into the Org-mode buffer. E.g., @code{:results output replace}. -@node @code{file}, @code{dir} and remote execution, @code{results}, Specific Header Arguments -@subsubsection @code{file} +@node file, dir and remote execution, results, Specific Header Arguments +@subsubsection file @code{:file} is used to specify a path for file output in which case an Org-mode style link (see @ref{Link format}) @code{file:} link is inserted into the buffer as the result. Common examples are graphical output from @@ -11535,8 +11535,8 @@ parenthesis following the source name. While the @code{:file} header argument can be used to specify the path to the output file, -@node @code{dir} and remote execution, @code{exports}, @code{file}, Specific Header Arguments -@subsubsection @code{dir} and remote execution +@node dir and remote execution, exports, file, Specific Header Arguments +@subsubsection dir and remote execution @code{:dir} specifies the /default directory/ during code block execution. If it is absent, then the directory associated with the current buffer is used. In other words, supplying @code{:dir path} @@ -11601,8 +11601,8 @@ install tramp separately in order for the above features to work correctly. the file will be created in a location to which the link does not point. -@node @code{exports}, @code{tangle}, @code{dir} and remote execution, Specific Header Arguments -@subsubsection @code{exports} +@node exports, tangle, dir and remote execution, Specific Header Arguments +@subsubsection exports Specify what should be included in HTML or LaTeX exports of the Org-mode file. @@ -11615,8 +11615,8 @@ install tramp separately in order for the above features to work correctly. - none :: nothing is included in the exported file. E.g., @code{:exports none}. -@node @code{tangle}, @code{session}, @code{exports}, Specific Header Arguments -@subsubsection @code{tangle} +@node tangle, session, exports, Specific Header Arguments +@subsubsection tangle Specify whether or not the source code block should be included in tangled extraction of source code files. @@ -11629,8 +11629,8 @@ install tramp separately in order for the above features to work correctly. is interpreted as a file basename to which the block will be exported. E.g., @code{:tangle basename}. -@node @code{session}, @code{noweb}, @code{tangle}, Specific Header Arguments -@subsubsection @code{session} +@node session, noweb, tangle, Specific Header Arguments +@subsubsection session Start a session for an interpreted language where state is preserved. This applies particularly to the supported languages python, R and ruby. @@ -11641,8 +11641,8 @@ install tramp separately in order for the above features to work correctly. session a name. This makes it possible to run concurrent sessions for each interpreted language. -@node @code{noweb}, @code{cache}, @code{session}, Specific Header Arguments -@subsubsection @code{noweb} +@node noweb, cache, session, Specific Header Arguments +@subsubsection noweb Controls the expansion of [[noweb-reference-syntax][noweb syntax]] references in a source code block. This header argument can have one of two values: @code{yes} or @code{no}. @@ -11681,8 +11681,8 @@ install tramp separately in order for the above features to work correctly. Thanks to Sébastien Vauban for this idea. -@node @code{cache}, , @code{noweb}, Specific Header Arguments -@subsubsection @code{cache} +@node cache, , noweb, Specific Header Arguments +@subsubsection cache Controls the use of in-buffer caching of source code block results to avoid re-running unchanged source code blocks. This header argument can have one of two values: @code{yes} or @code{no}. From 653694fff73eec5e52fb34822bc7fdde6a7db8bc Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Wed, 9 Jun 2010 19:13:16 -0700 Subject: [PATCH 022/138] babel-doc: exhausting formulation of babel documentation into texinfo --- doc/org.texi | 963 ++++++++++++++++++++++++++------------------------- 1 file changed, 484 insertions(+), 479 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 09183f6cf..bcc00d199 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -108,7 +108,7 @@ license to the document, as described in section 6 of the license. * Markup:: Prepare text for rich export * Exporting:: Sharing and publishing of notes * Publishing:: Create a web site of linked Org files -* Working With Source Code:: Using Org for literate programming, reproducible research and code evaluation. +* Working With Source Code:: Code evaluation inside Org-mode * Miscellaneous:: All the rest which did not fit elsewhere * Hacking:: How to hack your way around * MobileOrg:: Viewing and capture on a mobile device @@ -10849,7 +10849,8 @@ This may be necessary in particular if files include other files via @comment Working With Source Code, Miscellaneous, Publishing, Top @chapter Working With Source Code -Source code can be included in Org-mode documents using a @samp{src} block: +Source code can be included in Org-mode documents using a @samp{src} block, +e.g. @example #+BEGIN_SRC emacs-lisp @@ -10859,20 +10860,11 @@ Source code can be included in Org-mode documents using a @samp{src} block: #+END_SRC @end example -Org provides the following features for working with blocks of code: - -@itemize @bullet -@item -Editing in the appropriate Emacs major-mode (@ref{Editing Source Code}) -@item -Export with appropriate markup (@ref{Exporting Code Blocks}) -@item -Extraction (``tangling'') into pure code files. (@ref{Extracting Source Code}) -@item -Code execution, with results captured in the Org buffer (@ref{Evaluating Code Blocks}) -@item -Using code blocks in table formulas -@end itemize +Org provides a number of features for working with live source code, +including editing of code blocks in their native major-mode, evaluation of +code blocks, tangling of code blocks, and exportation of code blocks and +their results to a number of formats. The following sections provide a +thorough tour of Org-mode's sophisticated code block handling facilities. @menu * Structure of Code Blocks:: @@ -10908,8 +10900,8 @@ The structure of code blocks is as follows: This name is associated with the source code block. This is similar to the @samp{#+tblname} lines that can be used to name tables in Org-mode files. Referencing the name of a source code block makes it possible to evaluate the -block from other places in the file, other files, or from inside of Org-mode -tables. +block from other places in the file, other files, or from Org-mode table +formulas (see @ref{The spreadsheet}). @item The language of the code in the block. @item @@ -10929,7 +10921,7 @@ The code @comment Editing Source Code, Exporting Code Blocks, Structure of Code Blocks, Working With Source Code @section Editing Source Code -Use @kbd{C-c '} to edit the code block at point. This brings up a language +Use @kbd{C-c '} to edit the current code block. This brings up a language major-mode edit buffer containing the body of the code block. Saving this buffer will write the new contents back to the Org buffer. Use @kbd{C-c '} again to exit. @@ -10960,18 +10952,21 @@ to a non-nil value to switch without asking. @comment Exporting Code Blocks, Extracting Source Code, Editing Source Code, Working With Source Code @section Exporting Code Blocks -It is possible to export the contents of code blocks, the results of code -block evaluation, or neither or both. For most languages by default only -body of a code blocks will be exported, however some languages -(e.g. @code{ditaa}) default to exporting the results of the code block. For -information on the exportation of code blocks bodies see @ref{Literal -examples}. +It is possible to export the @emph{contents} of code blocks, the +@emph{results} of code block evaluation, or @emph{neither} or @emph{both}. +For most languages by default only body of a code blocks will be exported, +however some languages (e.g. @code{ditaa}) default to exporting the results +of the code block. For information on the exportation of code blocks bodies +see @ref{Literal examples}. The @code{:exports} header argument can be used to specify non-default export behavior: Header arguments: @table @code +@item :exports code +The default (in most languages). Only the body of the code block is exported +as described in @ref{Literal examples}. @item :exports results On export, the code block will be evaluated and the results will be placed in the org-mode buffer (either updating previous results of the code block @@ -10982,9 +10977,8 @@ block will not be exported. On export, the code block will be evaluated and the results inserted into the buffer as described above, however the body of the code block will be exported as well. -@item :exports code -The default (in most languages). Only the body of the code block is exported -as described in @ref{Literal examples}. +@item :exports none +No part of the code block or it's results will be exported. @end table @node Extracting Source Code, Evaluating Code Blocks, Exporting Code Blocks, Working With Source Code @@ -10998,7 +10992,8 @@ community. During ``tangling'' of code blocks their bodies are expanded using @code{org-babel-expand-src-block} which can expand both variable and ``noweb'' (see @ref{Noweb Reference Syntax}) style references. -Header arguments: +Relevant header arguments: + @table @code @item :tangle no The default. @@ -11010,7 +11005,8 @@ language. Include block in tangled output to file @samp{filename} @end table -Functions: +Relevant functions: + @table @code @item org-babel-tangle @key{C-c C-v t} Tangle the current file @@ -11018,22 +11014,15 @@ Tangle the current file Choose a file to tangle @end table -Variables: -@table @code -@item org-babel-tangle-langs -FIXME: This variable may have been changed recently -@end table - - @node Evaluating Code Blocks, Library of Babel, Extracting Source Code, Working With Source Code @comment node-name, next, previous, up @comment Evaluating Code Blocks, , Extracting Source Code, Working With Source Code @section Evaluating Code Blocks -For many language, blocks of code can be evaluated and the results -incorporated into the org-mode buffer. Check the value of the -@code{org-babel-interpreters} for a list of evaluable languages on your -system, also see @ref{Languages}. See @ref{Structure of Code Blocks} for +Blocks of code can be evaluated and the results incorporated into the +org-mode buffer. Check the value of the @code{org-babel-interpreters} for a +list of evaluable languages on your system, also 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. There are a number of ways of evaluating code blocks. The simplest is to @@ -11067,12 +11056,16 @@ Header arguments can be placed after the function invocation. See The ``Library of Babel'' is two things. First it is a library of code blocks which can be called from any Org-mode file, and second it is an actual Org-mode file located in the @samp{contrib} directory of Org-mode in which -Org-mode users may deposit contributed functions which they believe to be -generally useful. Code blocks defined in the``Library of Babel'' can be -called remotely as if they were in the current Org-mode buffer (see -@ref{Evaluating Code Blocks} for information on the syntax of remote code -block evaluation). +Org-mode users may deposit functions which they believe to be generally +useful. +Code blocks defined in the``Library of Babel'' can be called remotely as if +they were in the current Org-mode buffer (see @ref{Evaluating Code Blocks} +for information on the syntax of remote code block evaluation). + +Code blocks located in any Org-mode file can be loaded into the ``Library of +Babel'' with the @code{org-babel-lob-ingest} function, bound to @key{C-c C-v +l}. @node Languages, Header Arguments, Library of Babel, Working With Source Code @section Languages @@ -11103,7 +11096,7 @@ specific documentation and an up to date list of languages is available at @item Ruby @tab ruby @item Sass @tab sass @item GNU Screen @tab screen -@item shell @tab sh[fn:1] +@item shell @tab sh @item SQL @tab sql @end multitable @c END RECEIVE ORGTBL org-babel-lang-table @@ -11160,7 +11153,7 @@ The original table from reference.org is below; I'm just using the first column | Ruby | org-babel-doc-ruby | ruby | [[http://www.ruby-lang.org/][ruby]], [[http://www.ruby-lang.org/][irb]], [[http://github.com/eschulte/rinari/raw/master/util/ruby-mode.el][ruby-mode]], [[http://github.com/eschulte/rinari/raw/master/util/inf-ruby.el][inf-ruby mode]] | | Sass | org-babel-doc-sass | sass | [[http://sass-lang.com/][sass]], [[http://github.com/nex3/haml/blob/master/extra/sass-mode.el][sass-mode]] | | GNU Screen | [[file:languages/org-babel-doc-screen.org][org-babel-doc-screen]] | screen | [[http://www.gnu.org/software/screen/][screen]], a terminal | - | shell | org-babel-doc-sh | sh[fn:1] | a shell | + | shell | org-babel-doc-sh | sh | a shell | | SQL | org-babel-doc-sql | sql | none | @@ -11179,30 +11172,30 @@ of the language names from the above table). @node Header Arguments, Results, Languages, Working With Source Code @section Header Arguments -Definitions of all Org-babel header arguments are given (see @ref{Specific -Header Arguments}). In addition, some languages may add their own header -arguments. Please see the language-specific documentation (available at -@uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}.) -for information on language-specific header arguments. +Most code block functionality is configurable using header arguments. This +section provides an overview of the use of header arguments, and then +exhaustively covers all header arguments. @menu * Using Header Arguments:: -* System-wide Header Arguments:: -* Language Specific Header Arguments:: -* Header Arguments in Org-mode Properties:: -* Header Arguments in Source Code Blocks:: * Specific Header Arguments:: -* Using Header Arguments:: @end menu -@node Using Header Arguments, System-wide Header Arguments, , Header Arguments +@node Using Header Arguments, Specific Header Arguments, , Header Arguments @subsection Using Header Arguments -The values of header arguments can be set in four different ways, each more +The values of header arguments can be set in five different ways, each more specific (and having higher priority) than the last. +@menu +* System-wide header arguments:: +* Language Specific header arguments:: +* Buffer Wide header arguments:: +* header arguments in Org-mode Properties:: +* Source Code Block specific header arguments:: +@end menu -@node System-wide Header Arguments, Language Specific Header Arguments, Using Header Arguments, Header Arguments -@subsubsection System-wide Header Arguments +@node System-wide header arguments, Language Specific header arguments, , Using Header Arguments +@subsubheading System-wide header arguments System-wide values of header arguments can be specified by customizing the @code{org-babel-default-header-args} variable: @@ -11221,7 +11214,7 @@ System-wide values of header arguments can be specified by customizing the @end example For example, the following example could be used to set the default value of -@code{:noweb} header arguments to =yes=. This would have the effect of +@code{:noweb} header arguments to @code{yes}. This would have the effect of expanding @code{:noweb} references by default when evaluating source code blocks. @@ -11231,13 +11224,19 @@ blocks. (assq-delete-all :noweb org-babel-default-header-args))) @end example +@node Language Specific header arguments, Buffer Wide header arguments, System-wide header arguments, Using Header Arguments +@subsubheading Language Specific header arguments +Each language can define it's own set of default header arguments. See the +language-specific documentation available at +@uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}. +for information on language-specific header arguments. -@node Language Specific Header Arguments, Header Arguments in Org-mode Properties, System-wide Header Arguments, Header Arguments -@subsubsection Header Arguments in Org-mode Properties -Each language can define it's own set of default header arguments. +@node Buffer Wide header arguments, header arguments in Org-mode Properties, Language Specific header arguments, Using Header Arguments +@subsubheading Buffer Wide header arguments +FIXME -@node Header Arguments in Org-mode Properties, Header Arguments in Source Code Blocks, Language Specific Header Arguments, Header Arguments -@subsubsection Header Arguments in Org-mode Properties +@node header arguments in Org-mode Properties, Source Code Block specific header arguments, Buffer Wide header arguments, Using Header Arguments +@subsubheading header arguments in Org-mode Properties Header arguments are also read from Org-mode properties (see @ref{Property syntax}), which can be set on a buffer-wide or per-heading basis. An example @@ -11256,7 +11255,6 @@ heading: * outline header :PROPERTIES: :cache: yes - :CUSTOM_ID: property-set-header-arguments :END: @end example @@ -11265,9 +11263,8 @@ Properties defined in this way override the properties set in @code{org-set-property} function bound to @key{C-c C-x p} to set properties in Org-mode documents. - -@node Header Arguments in Source Code Blocks, Specific Header Arguments, Header Arguments in Org-mode Properties, Header Arguments -@subsubsection Header Arguments in Source Code Block +@node Source Code Block specific header arguments, , header arguments in Org-mode Properties, Using Header Arguments +@subsubheading Source Code Block specific header arguments The most common way to assign values to header arguments is at the source code block level. This can be done by listing a sequence of header @@ -11282,14 +11279,26 @@ preserved on export to HTML or LaTeX. @example #+source: factorial - #+begin_src haskell :results silent :exports code + #+begin_src haskell :results silent :exports code :var n=0 fac 0 = 1 fac n = n * fac (n-1) #+end_src @end example +Similarly it is possible to set header arguments for inline code blocks as +shown, -@node Specific Header Arguments, , Header Arguments in Source Code Blocks, Header Arguments +@example +src_haskell[:exports both]@{fac 5@} +@end example + +and for ``Library of Babel'' or function call lines as shown below. + +@example +#+call: factorial(n=5) :exports results +@end example + +@node Specific Header Arguments, , Using Header Arguments, Header Arguments @subsection Specific Header Arguments Description of every standard (non language-specific) Org-babel header argument. @@ -11307,19 +11316,21 @@ argument. @end menu @node var, results, , Specific Header Arguments -@subsubsection @code{var} +@subsubsection var The @code{:var} header argument is used to pass arguments to source code blocks. The specifics of how arguments are included in a source code block are language specific and are addressed in the language-specific documentation. However, the syntax used to specify arguments is the same across all languages. The values passed to arguments can be or -- literal values -- values from org-mode tables -- the results of other source code blocks +@itemize @bullet +@item literal values +@item values from org-mode tables +@item the results of other source code blocks +@end itemize -These values can be indexed in a manner similar to arrays -- see argument -indexing FIXME/need section on argument indexing. +These values can be indexed in a manner similar to arrays -- see the argument +``indexable variable values'' heading below. The following syntax is used to pass arguments to source code blocks using the @code{:var} header argument. @@ -11330,64 +11341,68 @@ blocks using the @code{:var} header argument. where @code{assign} can take one of the following forms -- literal value :: either a string @code{"string"} or a number @code{9}. -- reference :: a table name: +@itemize @bullet +@item literal value +either a string @code{"string"} or a number @code{9}. +@item reference +a table name: - @example - #+tblname: example-table - | 1 | - | 2 | - | 3 | - | 4 | +@example + #+tblname: example-table + | 1 | + | 2 | + | 3 | + | 4 | - #+source: table-length - #+begin_src emacs-lisp :var table=example-table - (length table) - #+end_src + #+source: table-length + #+begin_src emacs-lisp :var table=example-table + (length table) + #+end_src - #+results: table-length - : 4 - @end example + #+results: table-length + : 4 +@end example - a source code block name, as assigned by =#+srcname:=, - followed by parentheses: +a source code block name, as assigned by @code{#+srcname:}, followed by +parentheses: - @example - #+begin_src emacs-lisp :var length=table-length() - (* 2 length) - #+end_src +@example + #+begin_src emacs-lisp :var length=table-length() + (* 2 length) + #+end_src - #+results: - : 8 - @end example + #+results: + : 8 +@end example - In addition, an argument can be passed to the source code - block referenced by =:var=. The argument is passed within - the parentheses following the source code block name: +In addition, an argument can be passed to the source code block referenced +by @code{:var}. The argument is passed within the parentheses following the +source code block name: - @example - #+source: double - #+begin_src emacs-lisp :var input=8 - (* 2 input) - #+end_src +@example + #+source: double + #+begin_src emacs-lisp :var input=8 + (* 2 input) + #+end_src - #+results: double - : 16 + #+results: double + : 16 - #+source: squared - #+begin_src emacs-lisp :var input=double(input=1) - (* input input) - #+end_src + #+source: squared + #+begin_src emacs-lisp :var input=double(input=1) + (* input input) + #+end_src - #+results: squared - : 4 - @end example + #+results: squared + : 4 +@end example +@end itemize @subsubheading alternate argument syntax -It is also possible to specify arguments in a potentially more -natural way using the =#+source:= line of a source code block. -As in the following example arguments can be packed inside of -parenthesis following the source name. +It is also possible to specify arguments in a potentially more natural way +using the @code{#+source:} line of a source code block. As in the following +example arguments can be packed inside of parenthesis following the source +name. @example #+source: double(input=0) @@ -11396,173 +11411,187 @@ parenthesis following the source name. #+end_src @end example -**** indexable variable values +@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 +@code{example-table} to the variable @code{data}: - It is possible to assign a portion of a value to a - variable in a source block. The following example - assigns the second and third rows of the table - =example-table= to the variable =data=: +@example + :var data=example-table[1:2] +@end example - @example - :var data=example-table[1:2] - @end example +Note: ranges are indexed using the =:= operator. - *Note:* ranges are indexed using the =:= operator. +Note: indices are 0 based. - *Note:* indices are 0 based. +The following example assigns the second column of the first row of +@code{example-table} to @code{data}: - The following example assigns the second column of the - first row of =example-table= to =data=: +@example + :var data=example-table[0,1] +@end example - @example - :var data=example-table[0,1] - @end example +It is possible to index into the results of source code blocks as well as +tables. Any number of dimensions can be indexed. Dimensions are separated +from one another by commas. - It is possible to index into the results of source code blocks - as well as tables. Any number of dimensions can be indexed. - Dimensions are separated from one another by commas. +For more information on indexing behavior see the documentation for the +@code{org-babel-ref-index-list} function -- provided below. - For more information on indexing behavior see the documentation - for the =org-babel-ref-index-list= function -- provided below. +@example + org-babel-ref-index-list is a Lisp function in `org-babel-ref.el'. - @example - org-babel-ref-index-list is a Lisp function in `org-babel-ref.el'. + (org-babel-ref-index-list INDEX LIS) - (org-babel-ref-index-list INDEX LIS) + Return the subset of LIS indexed by INDEX. If INDEX is + separated by ,s then each PORTION is assumed to index into the + next deepest nesting or dimension. A valid PORTION can consist + of either an integer index, or two integers separated by a : in + which case the entire range is returned. +@end example - Return the subset of LIS indexed by INDEX. If INDEX is - separated by ,s then each PORTION is assumed to index into the - next deepest nesting or dimension. A valid PORTION can consist - of either an integer index, or two integers separated by a : in - which case the entire range is returned. - @end example - - *Note:* In Emacs, the documentation for any function or variable - can be read using the =describe-function= (M-x describe - function) and =describe-variable= (M-x describe variable) - functions, respectively. +Note: In Emacs, the documentation for any function or variable can be read +using the @code{describe-function} (M-x describe function) and +@code{describe-variable} (M-x describe variable) functions, respectively. @node results, file, var, Specific Header Arguments @subsubsection results - There are three types of results header argument: - - *collection* header arguments specify how the results should be collected from - the source code block; - - *type* header arguments specify what type of result the source code block - will return -- which has implications for how they will be - inserted into the Org-mode buffer; and - - *handling* header arguments specify how the results of - evaluating the source code block should be handled. +There are three types of results header argument: - *Note:* only one option from each type may be supplied per source code - block. +Note: only one option from each type may be supplied per source code block. + +@itemize @bullet +@item collection +arguments specify how the results should be collected from the source code +block +@item type +header arguments specify what type of result the source code block will +return -- which has implications for how they will be inserted into the +Org-mode buffer +@item handling +header arguments specify how the results of evaluating the source code block +should be handled. +@end itemize @subsubheading collection - :PROPERTIES: - :CUSTOM_ID: header-argument-results-collection - :END: - The following options are mutually exclusive, and specify how the - results should be collected from the source code block. +The following options are mutually exclusive, and specify how the results +should be collected from the source code block. - - value :: This is the default. The result is the value - of the last statement in the source code block. - This header argument places Org-babel in functional - mode. Note that in some languages, e.g., python, - use of this result type requires that a @code{return} - statement be included in the body of the source code - block. E.g., @code{:results value}. - - output :: The result is the collection of everything printed - to stdout during the execution of the source code - block. This header argument places Org-babel in scripting - mode. E.g., @code{:results output}. +@itemize @bullet +@item value +This is the default. The result is the value of the last statement in the +source code block. This header argument places Org-babel in functional mode. +Note that in some languages, e.g., python, use of this result type requires +that a @code{return} statement be included in the body of the source code +block. E.g., @code{:results value}. +@item output +The result is the collection of everything printed to STDOUT during the +execution of the source code block. This header argument places Org-babel in +scripting mode. E.g., @code{:results output}. +@end itemize @subsubheading type - The following options are mutually exclusive and specify what - type of results the code block will return. By default, results - are inserted as either a *table* or *scalar* depending on their - value. - - table, vector :: The results should be interpreted as an Org-mode table. - If a single value is returned, Org-babel will convert it - into a table with one row and one column. E.g., @code{:results - value table}. - - scalar, verbatim :: The results should be interpreted - literally -- meaning they will not be converted into a table. - The results will be inserted into the Org-mode buffer as - quoted text. E.g., @code{:results value verbatim}. - - file :: The results will be interpreted as the path to a file, - and will be inserted into the Org-mode buffer as a file - link. E.g., @code{:results value file}. - - raw, org :: The results are interpreted as raw Org-mode code and - are inserted directly into the buffer. If the results look - like a table they will be aligned as such by Org-mode. - E.g., @code{:results value raw}. - - html :: Results are assumed to be HTML and will be enclosed in - a @code{begin_html} block. E.g., @code{:results value html}. - - latex :: Results assumed to be LaTeX and are enclosed in a - @code{begin_latex} block. E.g., @code{:results value latex}. - - code :: Result are assumed to be parseable code and are - enclosed in a code block. E.g., @code{:results value code}. - - pp :: The result is converted to pretty-printed code and is - enclosed in a code block. This option currently supports - Emacs Lisp, python, and ruby. E.g., @code{:results value pp}. +The following options are mutually exclusive and specify what type of results +the code block will return. By default, results are inserted as either a +table or scalar depending on their value. + +@itemize @bullet +@item table, vector +The results should be interpreted as an Org-mode table. If a single value is +returned, Org-babel will convert it into a table with one row and one column. +E.g., @code{:results value table}. +@item scalar, verbatim +The results should be interpreted literally -- meaning they will not be +converted into a table. The results will be inserted into the Org-mode +buffer as quoted text. E.g., @code{:results value verbatim}. +@item file +The results will be interpreted as the path to a file, and will be inserted +into the Org-mode buffer as a file link. E.g., @code{:results value file}. +@item raw, org +The results are interpreted as raw Org-mode code and are inserted directly +into the buffer. If the results look like a table they will be aligned as +such by Org-mode. E.g., @code{:results value raw}. +@item html +Results are assumed to be HTML and will be enclosed in a @code{begin_html} +block. E.g., @code{:results value html}. +@item latex +Results assumed to be LaTeX and are enclosed in a @code{begin_latex} block. +E.g., @code{:results value latex}. +@item code +Result are assumed to be parseable code and are enclosed in a code block. +E.g., @code{:results value code}. +@item pp +The result is converted to pretty-printed code and is enclosed in a code +block. This option currently supports Emacs Lisp, python, and ruby. E.g., +@code{:results value pp}. +@end itemize @subsubheading handling - The following results options indicate what Org-babel should do - with the results once they are collected. +The following results options indicate what Org-babel should do with the +results once they are collected. - - silent :: The results will be echoed in the minibuffer but - will not be inserted into the Org-mode buffer. E.g., - @code{:results output silent}. - - replace :: The default value. The results will be inserted - into the Org-mode buffer. E.g., @code{:results output - replace}. +@itemize @bullet +@item silent +The results will be echoed in the minibuffer but will not be inserted into +the Org-mode buffer. E.g., @code{:results output silent}. +@item replace +The default value. Any existing results will be removed, and the new results +will be inserted into the Org-mode buffer in their place. E.g., +@code{:results output replace}. +@item append +If there are pre-existing results of the code block then the new results will +be appended to the existing results. Otherwise the new results will be +inserted as with @code{replace}. +@item prepend +If there are pre-existing results of the code block then the new results will +be prepended to the existing results. Otherwise the new results will be +inserted as with @code{replace}. +@end itemize @node file, dir and remote execution, results, Specific Header Arguments @subsubsection file - @code{:file} is used to specify a path for file output in which case an - Org-mode style link (see @ref{Link format}) @code{file:} link is inserted - into the buffer as the result. Common examples are graphical output from - R, gnuplot, ditaa and LaTeX blocks. +@code{:file} is used to specify a path for file output in which case an +Org-mode style link (see @ref{Link format}) @code{file:} link is inserted +into the buffer as the result. Common examples are graphical output from R, +gnuplot, ditaa and LaTeX blocks. - Note that for some languages, including R, gnuplot, LaTeX and ditaa, - graphical output is sent to the specified file without the file being - referenced explicitly in the code block. See the documentation for the - individual languages for details. In contrast, general purpose languages - such as python and ruby require that the code explicitly create output - corresponding to the path indicated by @code{:file}. +Note that for some languages, including R, gnuplot, LaTeX and ditaa, +graphical output is sent to the specified file without the file being +referenced explicitly in the code block. See the documentation for the +individual languages for details. In contrast, general purpose languages such +as python and ruby require that the code explicitly create output +corresponding to the path indicated by @code{:file}. - While the @code{:file} header argument can be used to specify the path to - the output file, +While the @code{:file} header argument can be used to specify the path to the +output file, @node dir and remote execution, exports, file, Specific Header Arguments @subsubsection dir and remote execution - @code{:dir} specifies the /default directory/ during code block - execution. If it is absent, then the directory associated with the - current buffer is used. In other words, supplying @code{:dir path} - temporarily has the same effect as changing the current directory with - @key{M-x cd path}, and then not supplying @code{:dir}. Under the surface, - @code{:dir} simply sets the value of the emacs variable - @code{default-directory}. +@code{:dir} specifies the /default directory/ during code block execution. If +it is absent, then the directory associated with the current buffer is +used. In other words, supplying @code{:dir path} temporarily has the same +effect as changing the current directory with @key{M-x cd path}, and then not +supplying @code{:dir}. Under the surface, @code{:dir} simply sets the value +of the emacs variable @code{default-directory}. - When using @code{:dir}, you should supply a relative path for file output - (e.g. @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in - which case that path will be interpreted relative to the default - directory. +When using @code{:dir}, you should supply a relative path for file output +(e.g. @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in which +case that path will be interpreted relative to the default directory. - In other words, if you want your plot to go into a folder called - Work in your home directory, you could use +In other words, if you want your plot to go into a folder called Work in your +home directory, you could use @example #+begin_src R :file myplot.png :dir ~/Work - matplot(matrix(rnorm(100), 10), type="l") + matplot(matrix(rnorm(100), 10), type="l") #+end_src @end example @subsubheading Remote execution - A directory on a remote machine can be specified using tramp file - syntax, in which case the code will be evaluated on the remote - machine. An example is +A directory on a remote machine can be specified using tramp file syntax, in +which case the code will be evaluated on the remote machine. An example is @example #+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu: @@ -11588,263 +11617,273 @@ tramp. Those using XEmacs, or GNU Emacs prior to version 23 may need to install tramp separately in order for the above features to work correctly. @subsubheading Further points - - If @code{:dir} is used in conjunction with @code{:session}, although it - will determine the starting directory for a new session as - expected, no attempt is currently made to alter the directory - associated with an existing session. - - @code{:dir} should typically not be used to create files during - export with @code{:exports results} or @code{:exports both}. The reason - is that, in order to retain portability of exported material - between machines, during export, links inserted into the buffer - will *not* be expanded against default directory. Therefore, if - default-directory is altered using @code{:dir}, it it probable that - the file will be created in a location to which the link does - not point. + +@itemize @bullet +@item +If @code{:dir} is used in conjunction with @code{:session}, although it will +determine the starting directory for a new session as expected, no attempt is +currently made to alter the directory associated with an existing session. +@item +@code{:dir} should typically not be used to create files during export with +@code{:exports results} or @code{:exports both}. The reason is that, in order +to retain portability of exported material between machines, during export, +links inserted into the buffer will *not* be expanded against default +directory. Therefore, if default-directory is altered using @code{:dir}, it +it probable that the file will be created in a location to which the link +does not point. +@end itemize @node exports, tangle, dir and remote execution, Specific Header Arguments @subsubsection exports - Specify what should be included in HTML or LaTeX exports of the - Org-mode file. +Specify what should be included in HTML or LaTeX exports of the Org-mode +file. - - code :: the default. The body of code is included - into the exported file. E.g., @code{:exports code}. - - results :: the result of evaluating the code is included in the - exported file. E.g., @code{:exports results}. - - both :: both the code and results are included in the exported - file. E.g., @code{:exports both}. - - none :: nothing is included in the exported file. E.g., - @code{:exports none}. +@itemize @bullet +@item code +the default. The body of code is included into the exported file. E.g., +@code{:exports code}. +@item results +the result of evaluating the code is included in the exported file. E.g., +@code{:exports results}. +@item both +both the code and results are included in the exported file. E.g., +@code{:exports both}. +@item none +nothing is included in the exported file. E.g., @code{:exports none}. +@end itemize @node tangle, session, exports, Specific Header Arguments @subsubsection tangle - Specify whether or not the source code block should be included - in tangled extraction of source code files. +Specify whether or not the source code block should be included in tangled +extraction of source code files. - - yes :: the source code block is exported to a source code file - named after the basename (name w/o extension) of the - Org-mode file. E.g., @code{:tangle yes}. - - no :: the default. The source code block is not - exported to a source code file. E.g., @code{:tangle no}. - - other :: Any other string passed to the @code{:tangle} header argument - is interpreted as a file basename to which the block will - be exported. E.g., @code{:tangle basename}. +@itemize @bullet +@item yes +the source code block is exported to a source code file named after the +basename (name w/o extension) of the Org-mode file. E.g., @code{:tangle +yes}. +@item no +the default. The source code block is not exported to a source code file. +E.g., @code{:tangle no}. +@item other +Any other string passed to the @code{:tangle} header argument is interpreted +as a file basename to which the block will be exported. E.g., @code{:tangle +basename}. +@end itemize @node session, noweb, tangle, Specific Header Arguments @subsubsection session - Start a session for an interpreted language where state is - preserved. This applies particularly to the supported languages - python, R and ruby. +Start a session for an interpreted language where state is preserved. This +applies particularly to the supported languages python, R and ruby. - By default, a session is not started. +By default, a session is not started. - A string passed to the @code{:session} header argument will give the - session a name. This makes it possible to run concurrent - sessions for each interpreted language. +A string passed to the @code{:session} header argument will give the session +a name. This makes it possible to run concurrent sessions for each +interpreted language. @node noweb, cache, session, Specific Header Arguments @subsubsection noweb - Controls the expansion of [[noweb-reference-syntax][noweb syntax]] references in a - source code block. This header argument can have one of two - values: @code{yes} or @code{no}. - - @code{no} :: the default. No [[noweb-reference-syntax][noweb syntax]] specific action is taken - on evaluating source code blocks/ However, noweb references - will still be expanded during tangling. - - @code{yes} :: all [[noweb-reference-syntax][noweb syntax]] references in the body of the source - code block will be expanded before the block is evaluated. +Controls the expansion of ``noweb'' style (see @ref{Noweb Reference Syntax}) +references in a source code block. This header argument can have one of two +values: @code{yes} or @code{no}. + +@itemize @bullet +@item @code{no} +the default. No ``noweb'' syntax specific action is taken on evaluating +source code blocks, However, noweb references will still be expanded during +tangling. +@item @code{yes} +all ``noweb'' syntax references in the body of the source code block will be +expanded before the block is evaluated. +@end itemize @subsubheading Noweb Prefix Lines - Noweb insertions are now placed behind the line prefix of the - @code{<>}. +Noweb insertions are now placed behind the line prefix of the +@code{<>}. +This behavior is illustrated in the following example. Because the +@code{<>} noweb reference appears behind the SQL comment syntax, +each line of the expanded noweb reference will be commented. - This behavior is illustrated in the following example. Because - the @code{<>} noweb reference appears behind the SQL - comment syntax, each line of the expanded noweb reference will - be commented. +This source code block: - This source code block: - - @example - -- <> - @end example +@example + -- <> +@end example - expands to: +expands to: - @example - -- this is the - -- multi-line body of example - @end example +@example + -- this is the + -- multi-line body of example +@end example - Note that noweb replacement text that does *not* contain any - newlines will not be affected by this change, so it is still - possible to use inline noweb references. - - Thanks to Sébastien Vauban for this idea. +Note that noweb replacement text that does not contain any newlines will not +be affected by this change, so it is still possible to use inline noweb +references. @node cache, , noweb, Specific Header Arguments @subsubsection cache - Controls the use of in-buffer caching of source code block - results to avoid re-running unchanged source code blocks. This - header argument can have one of two values: @code{yes} or @code{no}. - - @code{no} :: The default. No caching takes place and the source - code block will be run every time it is evaluated. - - @code{yes} :: every time the source code block is run a sha1 hash of - the code and arguments passed to the block will be - generated. This hash is packed into the @code{#+results:} line - of the results and will be checked on subsequent executions - of the source code block. If the source code block has not - changed since the last time it was evaluated, it will not be - re-evaluated. +Controls the use of in-buffer caching of source code block results to avoid +re-running unchanged source code blocks. This header argument can have one +of two values: @code{yes} or @code{no}. + +@itemize @bullet +@item @code{no} +The default. No caching takes place and the source code block will be run +every time it is evaluated. +@item @code{yes} +every time the source code block is run a sha1 hash of the code and arguments +passed to the block will be generated. This hash is packed into the +@code{#+results:} line of the results and will be checked on subsequent +executions of the source code block. If the source code block has not +changed since the last time it was evaluated, it will not be re-evaluated. +@end itemize @node Results, Noweb Reference Syntax, Header Arguments, Working With Source Code @section Results - The way in which results are handled depends on whether a - [[header-argument-session][session]] is invoked, as well as on whether - @code{:results value} or @code{:results output} is used. The following - table shows the possibilities: +The way in which results are handled depends on whether a session is invoked, +as well as on whether @code{:results value} or @code{:results output} is +used. The following table shows the possibilities: - | | non-session (default) | =:session= | - |-------------------+--------------------------+-------------------------------------| - | =:results value= | value of last expression | value of last expression | - | =:results output= | contents of stdout | concatenation of interpreter output | +@multitable @columnfractions 0.32 0.32 0.32 +@item @tab non-session @tab session +@item @code{results :value} @tab value of last expression @tab value of last expression +@item @code{results :output} @tab contents of STDOUT @tab concatenation of interpreter output +@end multitable - *Note:* With @code{:results value}, the result in both @code{:session} and - non-session is returned to Org-mode as a table (a one- or - two-dimensional vector of strings or numbers) when appropriate. +Note: With @code{:results value}, the result in both @code{:session} and +non-session is returned to Org-mode as a table (a one- or two-dimensional +vector of strings or numbers) when appropriate. @subsection Non-session @subsubsection @code{:results value} - This is the default. Internally, the value is obtained by - wrapping the code in a function definition in the external - language, and evaluating that function. Therefore, code should be - written as if it were the body of such a function. In particular, - note that python does not automatically return a value from a - function unless a @code{return} statement is present, and so a - 'return' statement will usually be required in python. +This is the default. Internally, the value is obtained by wrapping the code +in a function definition in the external language, and evaluating that +function. Therefore, code should be written as if it were the body of such a +function. In particular, note that python does not automatically return a +value from a function unless a @code{return} statement is present, and so a +@samp{return} statement will usually be required in python. - This is the only one of the four evaluation contexts in which the - code is automatically wrapped in a function definition. +This is the only one of the four evaluation contexts in which the code is +automatically wrapped in a function definition. @subsubsection @code{:results output} - The code is passed to the interpreter as an external process, and - the contents of the standard output stream are returned as - text. (In certain languages this also contains the error output - stream; this is an area for future work.) +The code is passed to the interpreter as an external process, and the +contents of the standard output stream are returned as text. (In certain +languages this also contains the error output stream; this is an area for +future work.) @subsection @code{:session} @subsubsection @code{:results value} - The code is passed to the interpreter running as an interactive Emacs - inferior process. The result returned is the result of the last - evaluation performed by the interpreter. (This is obtained in a - language-specific manner: the value of the variable @code{_} in python - and ruby, and the value of @code{.Last.value} in R). +The code is passed to the interpreter running as an interactive Emacs +inferior process. The result returned is the result of the last evaluation +performed by the interpreter. (This is obtained in a language-specific +manner: the value of the variable @code{_} in python and ruby, and the value +of @code{.Last.value} in R). @subsubsection @code{:results output} - The code is passed to the interpreter running as an interactive Emacs - inferior process. The result returned is the concatenation of the - sequence of (text) output from the interactive interpreter. Notice - that this is not necessarily the same as what would be sent to - @code{STDOUT} if the same code were passed to a non-interactive - interpreter running as an external process. For example, compare the - following two blocks: +The code is passed to the interpreter running as an interactive Emacs +inferior process. The result returned is the concatenation of the sequence of +(text) output from the interactive interpreter. Notice that this is not +necessarily the same as what would be sent to @code{STDOUT} if the same code +were passed to a non-interactive interpreter running as an external +process. For example, compare the following two blocks: @example #+begin_src python :results output - print "hello" - 2 - print "bye" + print "hello" + 2 + print "bye" #+end_src #+resname: - : hello - : bye +: hello +: bye @end example - In non-session mode, the '2' is not printed and does not appear. +In non-session mode, the '2' is not printed and does not appear. @example #+begin_src python :results output :session - print "hello" - 2 - print "bye" + print "hello" + 2 + print "bye" #+end_src #+resname: - : hello - : 2 - : bye +: hello +: 2 +: bye @end example - But in =:session= mode, the interactive interpreter receives input '2' - and prints out its value, '2'. (Indeed, the other print statements are - unnecessary here). - +But in @code{:session} mode, the interactive interpreter receives input '2' +and prints out its value, '2'. (Indeed, the other print statements are +unnecessary here). @node Noweb Reference Syntax, Key Bindings & Useful Functions, Results, Working With Source Code @section Noweb Reference Syntax - The [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] Literate Programming system allows named blocks of code to - be referenced by using the familiar Noweb syntax: - : <> +The ``noweb'' (see @uref{http://www.cs.tufts.edu/~nr/noweb/}) Literate +Programming system allows named blocks of code to be referenced by using the +familiar Noweb syntax: - Noweb references are handled differently during evaluation and - tangling. +@example +<> +@end example - When a document is tangled, Noweb references are replaced with the - named source code block. - - When a source code block is evaluated, the action depends upon the - value of the =:noweb= header argument. If =:noweb yes=, then a - Noweb reference is expanded before evaluation. If =:noweb no=, - the default, then the reference is not expanded before - evaluation. - - *Note:* the default value, =:noweb no=, was chosen to ensure that - Org-babel does not break correct code in a language, such as Ruby, - where =<>= is a syntactically valid construct. If =<>= is - not syntactically valid in languages that you use, then please - consider [[*System%20wide][setting the default value]]. - - An example that uses the Noweb reference syntax is provided in the - [[literate programming example]]. +When a source code block is tangled or evaluated, ``noweb'' references are +expanded depends upon the value of the @code{:noweb} header argument. If +@code{:noweb yes}, then a Noweb reference is expanded before evaluation. If +@code{:noweb no}, the default, then the reference is not expanded before +evaluation. +Note: the default value, @code{:noweb no}, was chosen to ensure that +Org-babel does not break correct code in a language, such as Ruby, where +@code{<>} is a syntactically valid construct. If @code{<>} is not +syntactically valid in languages that you use, then please consider setting +the default value. @node Key Bindings & Useful Functions, , Noweb Reference Syntax, Working With Source Code @section Key Bindings & Useful Functions - Org-babel re-binds many common Org-mode key sequences depending on - the context. Within a source-code block the following sequences - are rebound: - | =C-c C-c= | [[function-org-babel-execute][org-babel-execute-src-block]] | - | =C-c C-o= | [[function-org-babel-open-src-block-result][org-babel-open-src-block-result]] | - | =C-up= | [[function-org-babel-load-in-session][org-babel-load-in-session]] | - | =M-down= | [[function-org-babel-pop-to-session][org-babel-pop-to-session]] | +Org-babel re-binds many common Org-mode key sequences depending on +the context. Within a source-code block the following sequences +are rebound: - Org-babel also exposes a number of functions behind the common - =org-babel-key-prefix= of =C-c C-v=: +@multitable @columnfractions 0.25 0.75 +@item @key{C-c C-c} @tab org-babel-execute-src-block +@item @key{C-c C-o} @tab org-babel-open-src-block-result +@item @key{C-up} @tab org-babel-load-in-session +@item @key{M-down} @tab org-babel-pop-to-session +@end multitable + +Org-babel also exposes a number of functions behind the common +=org-babel-key-prefix= of =C-c C-v=: @example - #+begin_src emacs-lisp :exports none - (lambda (binding - (list (format "\\C-c \\M-b %s" - (car binding)) - (format "[[function-%s][%s]]" - (cdr binding) (cdr binding)))) - org-babel-key-bindings) - #+end_src +#+begin_src emacs-lisp :exports none + (lambda (binding + (list (format "\\C-c \\M-b %s" + (car binding)) + (format "[[function-%s][%s]]" + (cdr binding) (cdr binding)))) + org-babel-key-bindings) +#+end_src @end example - | =C-c C-v t= | [[function-org-babel-tangle][org-babel-tangle]] | - | =C-c C-v T= | [[function-org-babel-tangle-file][org-babel-tangle-file]] | - | =C-c C-v e= | [[function-org-babel-execute-src-block][org-babel-execute-src-block]] | - | =C-c C-v s= | [[function-org-babel-execute-subtree][org-babel-execute-subtree]] | - | =C-c C-v b= | [[function-org-babel-execute-buffer][org-babel-execute-buffer]] | - | =C-c C-v h= | [[function-org-babel-sha1-hash][org-babel-sha1-hash]] | - | =C-c C-v g= | [[function-org-babel-goto-named-source-block][org-babel-goto-named-source-block]] | - | =C-c C-v l= | [[function-org-babel-lob-ingest][org-babel-lob-ingest]] | +@multitable @columnfractions 0.25 0.75 +@item @key{C-c C-v t} @tab org-babel-tangle +@item @key{C-c C-v T} @tab org-babel-tangle-file +@item @key{C-c C-v e} @tab org-babel-execute-src-block +@item @key{C-c C-v s} @tab org-babel-execute-subtree +@item @key{C-c C-v b} @tab org-babel-execute-buffer +@item @key{C-c C-v h} @tab org-babel-sha1-hash +@item @key{C-c C-v g} @tab org-babel-goto-named-source-block +@item @key{C-c C-v l} @tab org-babel-lob-ingest +@end multitable @subsection Functions -@subsubsection org-babel-execute-src-block - :PROPERTIES: - :CUSTOM_ID: function-org-babel-execute-src-block - :END: +@itemize @bullet +@item org-babel-execute-src-block @example org-babel-execute-src-block is an interactive Lisp function in @@ -11865,10 +11904,7 @@ install tramp separately in order for the above features to work correctly. block. @end example -@subsubsection org-babel-open-src-block-result - :PROPERTIES: - :CUSTOM_ID: function-org-babel-open-src-block-result - :END: +@item org-babel-open-src-block-result @example org-babel-open-src-block-result is an interactive Lisp function in @@ -11882,10 +11918,7 @@ install tramp separately in order for the above features to work correctly. results already exist. @end example -@subsubsection org-babel-load-in-session - :PROPERTIES: - :CUSTOM_ID: function-org-babel-load-in-session - :END: +@item org-babel-load-in-session @example org-babel-load-in-session is an interactive Lisp function in @@ -11900,10 +11933,7 @@ install tramp separately in order for the above features to work correctly. [back] @end example -@subsubsection org-babel-pop-to-session - :PROPERTIES: - :CUSTOM_ID: function-org-babel-pop-to-session - :END: +@item org-babel-pop-to-session @example org-babel-pop-to-session is an interactive Lisp function in @@ -11919,10 +11949,7 @@ install tramp separately in order for the above features to work correctly. [back] @end example -@subsubsection org-babel-tangle - :PROPERTIES: - :CUSTOM_ID: function-org-babel-tangle - :END: +@item org-babel-tangle @example org-babel-tangle is an interactive Lisp function in @@ -11939,10 +11966,7 @@ install tramp separately in order for the above features to work correctly. exported source code blocks by language. @end example -@subsubsection org-babel-execute-subtree - :PROPERTIES: - :CUSTOM_ID: function-org-babel-execute-subtree - :END: +@item org-babel-execute-subtree @example org-babel-execute-subtree is an interactive Lisp function in @@ -11955,10 +11979,7 @@ install tramp separately in order for the above features to work correctly. Replace EVAL snippets in the entire subtree. @end example -@subsubsection org-babel-execute-buffer - :PROPERTIES: - :CUSTOM_ID: function-org-babel-execute-buffer - :END: +@item org-babel-execute-buffer @example org-babel-execute-buffer is an interactive Lisp function in @@ -11971,10 +11992,7 @@ install tramp separately in order for the above features to work correctly. Replace EVAL snippets in the entire buffer. @end example -@subsubsection org-babel-sha1-hash - :PROPERTIES: - :CUSTOM_ID: function-org-babel-sha1-hash - :END: +@item org-babel-sha1-hash @example org-babel-sha1-hash is an interactive Lisp function in `org-babel.el'. @@ -11986,10 +12004,7 @@ install tramp separately in order for the above features to work correctly. Not documented. @end example -@subsubsection org-babel-goto-named-source-block - :PROPERTIES: - :CUSTOM_ID: function-org-babel-goto-named-source-block - :END: +@item org-babel-goto-named-source-block @example org-babel-goto-named-source-block is an interactive Lisp function in @@ -12002,10 +12017,7 @@ install tramp separately in order for the above features to work correctly. Go to a named source-code block. @end example -@subsubsection org-babel-lob-ingest - :PROPERTIES: - :CUSTOM_ID: function-org-babel-lob-ingest - :END: +@item org-babel-lob-ingest @example org-babel-lob-ingest is an interactive Lisp function in @@ -12017,11 +12029,11 @@ install tramp separately in order for the above features to work correctly. Add all source-blocks defined in FILE to `org-babel-library-of-babel'. @end example +@end itemize @section Batch Execution -It is possible to call Org-babel functions from the command line. -This shell script calls [[function-org-babel-tangle][org-babel-tangle]] on every one of its -arguments. +It is possible to call Org-babel functions from the command line. This shell +script calls @code{org-babel-tangle} on every one of its arguments. Be sure to adjust the paths to fit your system. @example @@ -12049,13 +12061,6 @@ Be sure to adjust the paths to fit your system. (kill-buffer)) '($FILES)))" @end example -@section Footnotes - -[fn:1] The former use of the =shell= identifier is now deprecated. - -[fn:2] As long as the interpreter executable is found on the remote -machine: see the variable =tramp-remote-path= - @node Miscellaneous, Hacking, Working With Source Code, Top @chapter Miscellaneous From 8d2e2caa37db2e73477866685240c145243e4c62 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Wed, 9 Jun 2010 19:23:52 -0700 Subject: [PATCH 023/138] babel-doc: a completed first pass through and it's looking pretty good --- doc/org.texi | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index bcc00d199..be3247427 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10878,6 +10878,7 @@ thorough tour of Org-mode's sophisticated code block handling facilities. * Results:: * Noweb Reference Syntax:: * Key Bindings & Useful Functions:: +* Batch Execution:: @end menu @@ -10962,7 +10963,7 @@ see @ref{Literal examples}. The @code{:exports} header argument can be used to specify non-default export behavior: -Header arguments: +@subsubheading Header arguments: @table @code @item :exports code The default (in most languages). Only the body of the code block is exported @@ -10992,8 +10993,7 @@ community. During ``tangling'' of code blocks their bodies are expanded using @code{org-babel-expand-src-block} which can expand both variable and ``noweb'' (see @ref{Noweb Reference Syntax}) style references. -Relevant header arguments: - +@subsubheading header arguments: @table @code @item :tangle no The default. @@ -11005,8 +11005,7 @@ language. Include block in tangled output to file @samp{filename} @end table -Relevant functions: - +@subsubheading functions: @table @code @item org-babel-tangle @key{C-c C-v t} Tangle the current file @@ -11843,7 +11842,7 @@ Org-babel does not break correct code in a language, such as Ruby, where syntactically valid in languages that you use, then please consider setting the default value. -@node Key Bindings & Useful Functions, , Noweb Reference Syntax, Working With Source Code +@node Key Bindings & Useful Functions, Batch Execution, Noweb Reference Syntax, Working With Source Code @section Key Bindings & Useful Functions Org-babel re-binds many common Org-mode key sequences depending on @@ -12031,6 +12030,7 @@ Org-babel also exposes a number of functions behind the common @end example @end itemize +@node Batch Execution, , Key Bindings & Useful Functions, Working With Source Code @section Batch Execution It is possible to call Org-babel functions from the command line. This shell script calls @code{org-babel-tangle} on every one of its arguments. From b89ce3712ece8614e14de4a2cdc3ab32a3590c53 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Wed, 9 Jun 2010 20:52:09 -0700 Subject: [PATCH 024/138] babel-doc: host of minor aesthetic changes to babel documentation also stripped out superfluous function documentation. --- doc/org.texi | 370 ++++++++++++++++----------------------------------- 1 file changed, 112 insertions(+), 258 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index be3247427..cab37f42c 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -8547,9 +8547,9 @@ be used to fontify the example: @example #+BEGIN_SRC emacs-lisp -(defun org-xor (a b) - "Exclusive or." - (if a (not b) b)) + (defun org-xor (a b) + "Exclusive or." + (if a (not b) b)) #+END_SRC @end example @@ -9425,9 +9425,9 @@ respectively. For example @example #+BEGIN_EXAMPLE -t -w 40 -(defun org-xor (a b) - "Exclusive or." - (if a (not b) b)) + (defun org-xor (a b) + "Exclusive or." + (if a (not b) b)) #+END_EXAMPLE @end example @@ -10854,9 +10854,9 @@ e.g. @example #+BEGIN_SRC emacs-lisp -(defun org-xor (a b) - "Exclusive or." - (if a (not b) b)) + (defun org-xor (a b) + "Exclusive or." + (if a (not b) b)) #+END_SRC @end example @@ -10867,25 +10867,25 @@ their results to a number of formats. The following sections provide a thorough tour of Org-mode's sophisticated code block handling facilities. @menu -* Structure of Code Blocks:: -* Editing Source Code:: -* Exporting Code Blocks:: -* Extracting Source Code:: -* Evaluating Code Blocks:: +* Structure of code blocks:: +* Editing source code:: +* Exporting code blocks:: +* Extracting source code:: +* Evaluating code blocks:: * Library of Babel:: * Languages:: -* Header Arguments:: +* Header arguments:: * Results:: -* Noweb Reference Syntax:: -* Key Bindings & Useful Functions:: -* Batch Execution:: +* Noweb reference syntax:: +* Key bindings & useful functions:: +* Batch execution:: @end menu -@node Structure of Code Blocks, Editing Source Code, Working With Source Code, Working With Source Code +@node Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code @comment node-name, next, previous, up -@comment Structure of Code Blocks, Editing Source Code, Working With Source Code, Working With Source Code -@section Structure of Code Blocks +@comment Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code +@section Structure of code blocks The structure of code blocks is as follows: @@ -10910,17 +10910,17 @@ Switches controling exportation of the code block (see switches discussion in @ref{Literal examples}) @item
Optional header arguments control many aspects of evaluation, export and -tangling of source code blocks. See the @ref{Header Arguments} +tangling of source code blocks. See the @ref{Header arguments} section. Header arguments can also be set on a per-buffer or per-subtree basis using properties. @item The code @end table -@node Editing Source Code, Exporting Code Blocks, Structure of Code Blocks, Working With Source Code +@node Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code @comment node-name, next, previous, up -@comment Editing Source Code, Exporting Code Blocks, Structure of Code Blocks, Working With Source Code -@section Editing Source Code +@comment Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code +@section Editing source code Use @kbd{C-c '} to edit the current code block. This brings up a language major-mode edit buffer containing the body of the code block. Saving this @@ -10948,10 +10948,10 @@ By default, Org will ask before returning to an open edit buffer. Set to a non-nil value to switch without asking. @end table -@node Exporting Code Blocks, Extracting Source Code, Editing Source Code, Working With Source Code +@node Exporting code blocks, Extracting source code, Editing source code, Working With Source Code @comment node-name, next, previous, up -@comment Exporting Code Blocks, Extracting Source Code, Editing Source Code, Working With Source Code -@section Exporting Code Blocks +@comment Exporting code blocks, Extracting source code, Editing source code, Working With Source Code +@section Exporting code blocks It is possible to export the @emph{contents} of code blocks, the @emph{results} of code block evaluation, or @emph{neither} or @emph{both}. @@ -10982,16 +10982,16 @@ exported as well. No part of the code block or it's results will be exported. @end table -@node 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 @comment node-name, next, previous, up -@comment Extracting Source Code, Evaluating Code Blocks, Exporting Code Blocks, Working With Source Code -@section Extracting Source Code +@comment Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code +@section Extracting source code Creating pure source code files by extracting code from source blocks is referred to as ``tangling'' -- a term adopted from the literate programming community. During ``tangling'' of code blocks their bodies are expanded using @code{org-babel-expand-src-block} which can expand both variable and -``noweb'' (see @ref{Noweb Reference Syntax}) style references. +``noweb'' (see @ref{Noweb reference syntax}) style references. @subsubheading header arguments: @table @code @@ -11013,15 +11013,15 @@ Tangle the current file Choose a file to tangle @end table -@node Evaluating Code Blocks, Library of Babel, Extracting Source Code, Working With Source Code +@node Evaluating code blocks, Library of Babel, Extracting source code, Working With Source Code @comment node-name, next, previous, up -@comment Evaluating Code Blocks, , Extracting Source Code, Working With Source Code -@section Evaluating Code Blocks +@comment Evaluating code blocks, , Extracting source code, Working With Source Code +@section Evaluating code blocks Blocks of code can be evaluated and the results incorporated into the org-mode buffer. Check the value of the @code{org-babel-interpreters} for a list of evaluable languages on your system, also see @ref{Languages} for a -list of supported languages. See @ref{Structure of Code Blocks} for +list of supported languages. See @ref{Structure of code blocks} for information on the syntax used to define a code block. There are a number of ways of evaluating code blocks. The simplest is to @@ -11046,11 +11046,11 @@ This name is associated with the source code block to be evaluated. Arguments specified in this section will be passed to the code block. @item
Header arguments can be placed after the function invocation. See -@ref{Header Arguments} for more information on header arguments. +@ref{Header arguments} for more information on header arguments. @end table -@node Library of Babel, Languages, Evaluating Code Blocks, Working With Source Code +@node Library of Babel, Languages, Evaluating code blocks, Working With Source Code @section Library of Babel The ``Library of Babel'' is two things. First it is a library of code blocks which can be called from any Org-mode file, and second it is an actual @@ -11059,14 +11059,14 @@ Org-mode users may deposit functions which they believe to be generally useful. Code blocks defined in the``Library of Babel'' can be called remotely as if -they were in the current Org-mode buffer (see @ref{Evaluating Code Blocks} +they were in the current Org-mode buffer (see @ref{Evaluating code blocks} for information on the syntax of remote code block evaluation). Code blocks located in any Org-mode file can be loaded into the ``Library of Babel'' with the @code{org-babel-lob-ingest} function, bound to @key{C-c C-v l}. -@node Languages, Header Arguments, Library of Babel, Working With Source Code +@node Languages, Header arguments, Library of Babel, Working With Source Code @section Languages Org-babel provides support for the following languages. See the language specific documentation and an up to date list of languages is available at @@ -11168,20 +11168,20 @@ of the language names from the above table). @end example -@node Header Arguments, Results, Languages, Working With Source Code -@section Header Arguments +@node Header arguments, Results, Languages, Working With Source Code +@section Header arguments Most code block functionality is configurable using header arguments. This section provides an overview of the use of header arguments, and then exhaustively covers all header arguments. @menu -* Using Header Arguments:: -* Specific Header Arguments:: +* Using Header arguments:: +* Specific Header arguments:: @end menu -@node Using Header Arguments, Specific Header Arguments, , Header Arguments -@subsection Using Header Arguments +@node Using Header arguments, Specific Header arguments, , Header arguments +@subsection Using Header arguments The values of header arguments can be set in five different ways, each more specific (and having higher priority) than the last. @@ -11193,7 +11193,7 @@ specific (and having higher priority) than the last. * Source Code Block specific header arguments:: @end menu -@node System-wide header arguments, Language Specific header arguments, , Using Header Arguments +@node System-wide header arguments, Language Specific header arguments, , Using Header arguments @subsubheading System-wide header arguments System-wide values of header arguments can be specified by customizing the @code{org-babel-default-header-args} variable: @@ -11223,18 +11223,18 @@ blocks. (assq-delete-all :noweb org-babel-default-header-args))) @end example -@node Language Specific header arguments, Buffer Wide header arguments, System-wide header arguments, Using Header Arguments +@node Language Specific header arguments, Buffer Wide header arguments, System-wide header arguments, Using Header arguments @subsubheading Language Specific header arguments Each language can define it's own set of default header arguments. See the language-specific documentation available at @uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}. for information on language-specific header arguments. -@node Buffer Wide header arguments, header arguments in Org-mode Properties, Language Specific header arguments, Using Header Arguments +@node Buffer Wide header arguments, header arguments in Org-mode Properties, Language Specific header arguments, Using Header arguments @subsubheading Buffer Wide header arguments FIXME -@node header arguments in Org-mode Properties, Source Code Block specific header arguments, Buffer Wide header arguments, Using Header Arguments +@node header arguments in Org-mode Properties, Source Code Block specific header arguments, Buffer Wide header arguments, Using Header arguments @subsubheading header arguments in Org-mode Properties Header arguments are also read from Org-mode properties (see @ref{Property @@ -11262,7 +11262,7 @@ Properties defined in this way override the properties set in @code{org-set-property} function bound to @key{C-c C-x p} to set properties in Org-mode documents. -@node Source Code Block specific header arguments, , header arguments in Org-mode Properties, Using Header Arguments +@node Source Code Block specific header arguments, , header arguments in Org-mode Properties, Using Header arguments @subsubheading Source Code Block specific header arguments The most common way to assign values to header arguments is at the source @@ -11297,8 +11297,8 @@ and for ``Library of Babel'' or function call lines as shown below. #+call: factorial(n=5) :exports results @end example -@node Specific Header Arguments, , Using Header Arguments, Header Arguments -@subsection Specific Header Arguments +@node Specific Header arguments, , Using Header arguments, Header arguments +@subsection Specific Header arguments Description of every standard (non language-specific) Org-babel header argument. @@ -11314,7 +11314,7 @@ argument. * cache:: @end menu -@node var, results, , Specific Header Arguments +@node var, results, , Specific Header arguments @subsubsection var The @code{:var} header argument is used to pass arguments to source code blocks. The specifics of how arguments are included @@ -11453,7 +11453,7 @@ Note: In Emacs, the documentation for any function or variable can be read using the @code{describe-function} (M-x describe function) and @code{describe-variable} (M-x describe variable) functions, respectively. -@node results, file, var, Specific Header Arguments +@node results, file, var, Specific Header arguments @subsubsection results There are three types of results header argument: @@ -11549,7 +11549,7 @@ be prepended to the existing results. Otherwise the new results will be inserted as with @code{replace}. @end itemize -@node file, dir and remote execution, results, Specific Header Arguments +@node file, dir and remote execution, results, Specific Header arguments @subsubsection file @code{:file} is used to specify a path for file output in which case an Org-mode style link (see @ref{Link format}) @code{file:} link is inserted @@ -11566,7 +11566,7 @@ corresponding to the path indicated by @code{:file}. While the @code{:file} header argument can be used to specify the path to the output file, -@node dir and remote execution, exports, file, Specific Header Arguments +@node dir and remote execution, exports, file, Specific Header arguments @subsubsection dir and remote execution @code{:dir} specifies the /default directory/ during code block execution. If it is absent, then the directory associated with the current buffer is @@ -11632,7 +11632,7 @@ it probable that the file will be created in a location to which the link does not point. @end itemize -@node exports, tangle, dir and remote execution, Specific Header Arguments +@node exports, tangle, dir and remote execution, Specific Header arguments @subsubsection exports Specify what should be included in HTML or LaTeX exports of the Org-mode file. @@ -11651,7 +11651,7 @@ both the code and results are included in the exported file. E.g., nothing is included in the exported file. E.g., @code{:exports none}. @end itemize -@node tangle, session, exports, Specific Header Arguments +@node tangle, session, exports, Specific Header arguments @subsubsection tangle Specify whether or not the source code block should be included in tangled extraction of source code files. @@ -11670,7 +11670,7 @@ as a file basename to which the block will be exported. E.g., @code{:tangle basename}. @end itemize -@node session, noweb, tangle, Specific Header Arguments +@node session, noweb, tangle, Specific Header arguments @subsubsection session Start a session for an interpreted language where state is preserved. This applies particularly to the supported languages python, R and ruby. @@ -11681,9 +11681,9 @@ A string passed to the @code{:session} header argument will give the session a name. This makes it possible to run concurrent sessions for each interpreted language. -@node noweb, cache, session, Specific Header Arguments +@node noweb, cache, session, Specific Header arguments @subsubsection noweb -Controls the expansion of ``noweb'' style (see @ref{Noweb Reference Syntax}) +Controls the expansion of ``noweb'' style (see @ref{Noweb reference syntax}) references in a source code block. This header argument can have one of two values: @code{yes} or @code{no}. @@ -11722,7 +11722,7 @@ Note that noweb replacement text that does not contain any newlines will not be affected by this change, so it is still possible to use inline noweb references. -@node cache, , noweb, Specific Header Arguments +@node cache, , noweb, Specific Header arguments @subsubsection cache Controls the use of in-buffer caching of source code block results to avoid re-running unchanged source code blocks. This header argument can have one @@ -11740,7 +11740,7 @@ executions of the source code block. If the source code block has not changed since the last time it was evaluated, it will not be re-evaluated. @end itemize -@node Results, Noweb Reference Syntax, Header Arguments, Working With Source Code +@node Results, Noweb reference syntax, Header arguments, Working With Source Code @section Results The way in which results are handled depends on whether a session is invoked, as well as on whether @code{:results value} or @code{:results output} is @@ -11820,8 +11820,8 @@ But in @code{:session} mode, the interactive interpreter receives input '2' and prints out its value, '2'. (Indeed, the other print statements are unnecessary here). -@node Noweb Reference Syntax, Key Bindings & Useful Functions, Results, Working With Source Code -@section Noweb Reference Syntax +@node Noweb reference syntax, Key bindings & useful functions, Results, Working With Source Code +@section Noweb reference syntax The ``noweb'' (see @uref{http://www.cs.tufts.edu/~nr/noweb/}) Literate Programming system allows named blocks of code to be referenced by using the familiar Noweb syntax: @@ -11842,8 +11842,8 @@ Org-babel does not break correct code in a language, such as Ruby, where syntactically valid in languages that you use, then please consider setting the default value. -@node Key Bindings & Useful Functions, Batch Execution, Noweb Reference Syntax, Working With Source Code -@section Key Bindings & Useful Functions +@node Key bindings & useful functions, Batch execution, Noweb reference syntax, Working With Source Code +@section Key bindings & useful functions Org-babel re-binds many common Org-mode key sequences depending on the context. Within a source-code block the following sequences @@ -11852,213 +11852,67 @@ are rebound: @multitable @columnfractions 0.25 0.75 @item @key{C-c C-c} @tab org-babel-execute-src-block @item @key{C-c C-o} @tab org-babel-open-src-block-result -@item @key{C-up} @tab org-babel-load-in-session -@item @key{M-down} @tab org-babel-pop-to-session +@item @key{C-up} @tab org-babel-load-in-session +@item @key{M-down} @tab org-babel-pop-to-session @end multitable -Org-babel also exposes a number of functions behind the common -=org-babel-key-prefix= of =C-c C-v=: -@example -#+begin_src emacs-lisp :exports none - (lambda (binding - (list (format "\\C-c \\M-b %s" - (car binding)) - (format "[[function-%s][%s]]" - (cdr binding) (cdr binding)))) - org-babel-key-bindings) -#+end_src -@end example - @multitable @columnfractions 0.25 0.75 -@item @key{C-c C-v t} @tab org-babel-tangle -@item @key{C-c C-v T} @tab org-babel-tangle-file -@item @key{C-c C-v e} @tab org-babel-execute-src-block -@item @key{C-c C-v s} @tab org-babel-execute-subtree +@item @key{C-c C-v a} @tab org-babel-sha1-hash @item @key{C-c C-v b} @tab org-babel-execute-buffer -@item @key{C-c C-v h} @tab org-babel-sha1-hash +@item @key{C-c C-v f} @tab org-babel-tangle-file @item @key{C-c C-v g} @tab org-babel-goto-named-source-block +@item @key{C-c C-v h} @tab org-babel-describe-bindings @item @key{C-c C-v l} @tab org-babel-lob-ingest +@item @key{C-c C-v p} @tab org-babel-expand-src-block +@item @key{C-c C-v s} @tab org-babel-execute-subtree +@item @key{C-c C-v t} @tab org-babel-tangle +@item @key{C-c C-v z} @tab org-babel-switch-to-session @end multitable -@subsection Functions -@itemize @bullet -@item org-babel-execute-src-block +When possible these keybindings were extended to work when the control key is +kept pressed, resulting in the following additional keybindings. -@example - org-babel-execute-src-block is an interactive Lisp function in - `org-babel.el'. +@multitable @columnfractions 0.25 0.75 +@item @key{C-c C-v C-a} @tab org-babel-sha1-hash +@item @key{C-c C-v C-b} @tab org-babel-execute-buffer +@item @key{C-c C-v C-f} @tab org-babel-tangle-file +@item @key{C-c C-v C-l} @tab org-babel-lob-ingest +@item @key{C-c C-v C-p} @tab org-babel-expand-src-block +@item @key{C-c C-v C-s} @tab org-babel-execute-subtree +@item @key{C-c C-v C-t} @tab org-babel-tangle +@item @key{C-c C-v C-z} @tab org-babel-switch-to-session +@end multitable - (org-babel-execute-src-block &optional ARG INFO PARAMS) - - Evaluate the current source code block, and insert the results - into the buffer. Source code execution and the collection and - formatting of results can be controlled through a variety of - header arguments. - - Optionally supply a value for INFO in the form returned by - `org-babel-get-src-block-info'. - - Optionally supply a value for PARAMS which will be merged with - the header arguments specified at the front of the source code - block. -@end example - -@item org-babel-open-src-block-result - -@example - org-babel-open-src-block-result is an interactive Lisp function in - `org-babel.el'. - - (org-babel-open-src-block-result &optional RE-RUN) - - If `point' is on a src block then open the results of the - source code block, otherwise return nil. With optional prefix - argument RE-RUN the source-code block is evaluated even if - results already exist. -@end example - -@item org-babel-load-in-session - -@example - org-babel-load-in-session is an interactive Lisp function in - `org-babel.el'. - - (org-babel-load-in-session &optional ARG INFO) - - Load the body of the current source-code block. Evaluate the - header arguments for the source block before entering the - session. After loading the body this pops open the session. - - [back] -@end example - -@item org-babel-pop-to-session - -@example - org-babel-pop-to-session is an interactive Lisp function in - `org-babel.el'. - - (org-babel-pop-to-session &optional ARG INFO) - - Pop to the session of the current source-code block. If - called with a prefix argument then evaluate the header arguments - for the source block before entering the session. Copy the body - of the source block to the kill ring. - - [back] -@end example - -@item org-babel-tangle - -@example - org-babel-tangle is an interactive Lisp function in - `org-babel-tangle.el'. - - It is bound to C-c C-v t. - - (org-babel-tangle &optional TARGET-FILE LANG) - - Extract the bodies of all source code blocks from the current - file into their own source-specific files. Optional argument - TARGET-FILE can be used to specify a default export file for all - source blocks. Optional argument LANG can be used to limit the - exported source code blocks by language. -@end example - -@item org-babel-execute-subtree - -@example - org-babel-execute-subtree is an interactive Lisp function in - `org-babel.el'. - - It is bound to C-c C-v s. - - (org-babel-execute-subtree &optional ARG) - - Replace EVAL snippets in the entire subtree. -@end example - -@item org-babel-execute-buffer - -@example - org-babel-execute-buffer is an interactive Lisp function in - `org-babel.el'. - - It is bound to C-c C-v b. - - (org-babel-execute-buffer &optional ARG) - - Replace EVAL snippets in the entire buffer. -@end example - -@item org-babel-sha1-hash - -@example - org-babel-sha1-hash is an interactive Lisp function in `org-babel.el'. - - It is bound to C-c C-v h. - - (org-babel-sha1-hash &optional INFO) - - Not documented. -@end example - -@item org-babel-goto-named-source-block - -@example - org-babel-goto-named-source-block is an interactive Lisp function in - `org-babel.el'. - - It is bound to C-c C-v g. - - (org-babel-goto-named-source-block &optional NAME) - - Go to a named source-code block. -@end example - -@item org-babel-lob-ingest - -@example - org-babel-lob-ingest is an interactive Lisp function in - `org-babel-lob.el'. - - It is bound to C-c C-v l. - - (org-babel-lob-ingest &optional FILE) - - Add all source-blocks defined in FILE to `org-babel-library-of-babel'. -@end example -@end itemize - -@node Batch Execution, , Key Bindings & Useful Functions, Working With Source Code -@section Batch Execution +@node Batch execution, , Key bindings & useful functions, Working With Source Code +@section Batch execution It is possible to call Org-babel functions from the command line. This shell script calls @code{org-babel-tangle} on every one of its arguments. Be sure to adjust the paths to fit your system. + @example - #!/bin/sh - # -*- mode: shell-script -*- - # - # tangle a file with org-babel - # - DIR=`pwd` - FILES="" +#!/bin/sh +# -*- mode: shell-script -*- +# +# tangle a file with org-babel +# +DIR=`pwd` +FILES="" - # wrap each argument in the code required to call tangle on it - for i in $@@; do - FILES="$FILES \"$i\"" - done +# wrap each argument in the code required to call tangle on it +for i in $@@; do +FILES="$FILES \"$i\"" +done - emacsclient \ - --eval "(progn - (add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\")) - (add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\")) - (require 'org)(require 'org-exp)(require 'org-babel) - (mapc (lambda (file) - (find-file (expand-file-name file \"$DIR\")) - (org-babel-tangle) - (kill-buffer)) '($FILES)))" +emacsclient \ +--eval "(progn +(add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\")) +(add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\")) +(require 'org)(require 'org-exp)(require 'org-babel) +(mapc (lambda (file) + (find-file (expand-file-name file \"$DIR\")) + (org-babel-tangle) + (kill-buffer)) '($FILES)))" @end example @node Miscellaneous, Hacking, Working With Source Code, Top From 16fa9b6c99848068b0c43ef6837dd07c355ea79b Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Thu, 10 Jun 2010 10:39:03 -0700 Subject: [PATCH 025/138] babel-doc: adding information on hlines colnames and rownames header args --- doc/org.texi | 132 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 131 insertions(+), 1 deletion(-) diff --git a/doc/org.texi b/doc/org.texi index cab37f42c..8a2827a9e 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -11312,6 +11312,9 @@ argument. * session:: * noweb:: * cache:: +* hlines:: +* colnames:: +* rownames:: @end menu @node var, results, , Specific Header arguments @@ -11722,7 +11725,7 @@ Note that noweb replacement text that does not contain any newlines will not be affected by this change, so it is still possible to use inline noweb references. -@node cache, , noweb, Specific Header arguments +@node cache, hlines, noweb, Specific Header arguments @subsubsection cache Controls the use of in-buffer caching of source code block results to avoid re-running unchanged source code blocks. This header argument can have one @@ -11740,6 +11743,133 @@ executions of the source code block. If the source code block has not changed since the last time it was evaluated, it will not be re-evaluated. @end itemize +@node hlines, colnames, cache, Specific Header arguments +@subsubsection hlines +Tables are frequently represented with one or more horizontal lines, or +hlines. The @code{:hlines} argument to an Org-babel code block accepts the +values @code{yes} or @code{no}, with a default value of @code{no}. + +@itemize @bullet +@item @code{no} +Strips horizontal lines from the input table. In most languages this is the +desired effect because an @code{hline} symbol is interpreted as an unbound +variable and raises an error. Setting @code{:hlines no} or relying on the +default value yields the following results. + +@example +#+tblname: many-cols +| a | b | c | +|---+---+---| +| d | e | f | +|---+---+---| +| g | h | i | + +#+source: echo-table +#+begin_src python :var tab=many-cols + return tab +#+end_src + +#+results: echo-table +| a | b | c | +| d | e | f | +| g | h | i | +@end example + +@item @code{yes} +Leaves hlines in the table. Setting @code{:hlines yes} has this effect. + +@example +#+tblname: many-cols +| a | b | c | +|---+---+---| +| d | e | f | +|---+---+---| +| g | h | i | + +#+source: echo-table +#+begin_src python :var tab=many-cols :hlines yes + return tab +#+end_src + +#+results: echo-table +| a | b | c | +|---+---+---| +| d | e | f | +|---+---+---| +| g | h | i | +@end example +@end itemize + +@node colnames, rownames, hlines, Specific Header arguments +@subsubsection colnames +The @code{:colnames} header argument accepts the values @code{yes}, +@code{no}, or @code{nil} for unassigned. The default value is @code{nil}. + +@itemize @bullet +@item @code{nil} +If an input table /looks like/ it has column names +(because its second row is an hline), then the column +names will be removed from the table by Org-babel before +processing, then reapplied to the results. + +@example +#+tblname: less-cols +| a | +|---| +| b | +| c | + +#+srcname: echo-table-again +#+begin_src python :var tab=less-cols + return [[val + '*' for val in row] for row in tab] +#+end_src + +#+results: echo-table-again +| a | +|----| +| b* | +| c* | +@end example + +@item @code{no} +No column name pre-processing takes place + +@item @code{yes} +Column names are removed and reapplied as with @code{nil} even if the table +does not /look like/ it has column names (i.e. the second row is not an +hline) +@end itemize + +@node rownames, , colnames, Specific Header arguments +@subsubsection rownames +The @code{:rownames} header argument can take on the values @code{yes} +or @code{no}, with a default value of @code{no}. + +@itemize @bullet +@item @code{no} +No row name pre-processing will take place. + +@item @code{yes} +The first column of the table is removed from the +table by Org-babel before processing, and is then reapplied +to the results. + +@example +#+tblname: with-rownames +| one | 1 | 2 | 3 | 4 | 5 | +| two | 6 | 7 | 8 | 9 | 10 | + +#+srcname: echo-table-once-again +#+begin_src python :var tab=with-rownames :rownames yes + return [[val + 10 for val in row] for row in tab] +#+end_src + +#+results: echo-table-once-again +| one | 11 | 12 | 13 | 14 | 15 | +| two | 16 | 17 | 18 | 19 | 20 | +@end example +@end itemize + @node Results, Noweb reference syntax, Header arguments, Working With Source Code @section Results The way in which results are handled depends on whether a session is invoked, From bb6f835d128f6c79d9944f0c8053cb05b8908dd8 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Thu, 10 Jun 2010 10:39:24 -0700 Subject: [PATCH 026/138] babel-doc: tweak --- doc/org.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/org.texi b/doc/org.texi index 8a2827a9e..6b381d622 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -11836,7 +11836,7 @@ No column name pre-processing takes place @item @code{yes} Column names are removed and reapplied as with @code{nil} even if the table -does not /look like/ it has column names (i.e. the second row is not an +does not ``look like'' it has column names (i.e. the second row is not an hline) @end itemize From bb834903dd42c72b71e224f5d1684e49183b3e0e Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Thu, 10 Jun 2010 11:00:37 -0700 Subject: [PATCH 027/138] babel-doc: adding no-expand header argument --- doc/org.texi | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/doc/org.texi b/doc/org.texi index 6b381d622..005eef624 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -11303,6 +11303,7 @@ Description of every standard (non language-specific) Org-babel header argument. @menu +* no-expand:: * var:: * results:: * file:: @@ -11317,7 +11318,15 @@ argument. * rownames:: @end menu -@node var, results, , Specific Header arguments +@node no-expand, var, , Specific Header arguments +@subsubsection no-expand +By default, code blocks are expanded with @code{org-babel-expand-src-block} +during tangling. This has the effect of assigning values to variables +specified with @code{:var} (see @ref{var}), and of replacing ``noweb'' +references (see @ref{Noweb reference syntax}) with their targets. The +@code{:no-expand} header argument can be used to turn off this behavior. + +@node var, results, no-expand, Specific Header arguments @subsubsection var The @code{:var} header argument is used to pass arguments to source code blocks. The specifics of how arguments are included From 3bb8bdb7e551f16fb3d841ff898035f5c30d8cd4 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Thu, 10 Jun 2010 11:09:42 -0700 Subject: [PATCH 028/138] babel-doc: changed header-argument order --- doc/org.texi | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 005eef624..51b3a87fc 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -11303,13 +11303,13 @@ Description of every standard (non language-specific) Org-babel header argument. @menu -* no-expand:: * var:: * results:: * file:: * dir and remote execution:: * exports:: * tangle:: +* no-expand:: * session:: * noweb:: * cache:: @@ -11318,15 +11318,7 @@ argument. * rownames:: @end menu -@node no-expand, var, , Specific Header arguments -@subsubsection no-expand -By default, code blocks are expanded with @code{org-babel-expand-src-block} -during tangling. This has the effect of assigning values to variables -specified with @code{:var} (see @ref{var}), and of replacing ``noweb'' -references (see @ref{Noweb reference syntax}) with their targets. The -@code{:no-expand} header argument can be used to turn off this behavior. - -@node var, results, no-expand, Specific Header arguments +@node var, results, , Specific Header arguments @subsubsection var The @code{:var} header argument is used to pass arguments to source code blocks. The specifics of how arguments are included @@ -11663,7 +11655,7 @@ both the code and results are included in the exported file. E.g., nothing is included in the exported file. E.g., @code{:exports none}. @end itemize -@node tangle, session, exports, Specific Header arguments +@node tangle, no-expand, exports, Specific Header arguments @subsubsection tangle Specify whether or not the source code block should be included in tangled extraction of source code files. @@ -11682,7 +11674,15 @@ as a file basename to which the block will be exported. E.g., @code{:tangle basename}. @end itemize -@node session, noweb, tangle, Specific Header arguments +@node no-expand, session, tangle, Specific Header arguments +@subsubsection no-expand +By default, code blocks are expanded with @code{org-babel-expand-src-block} +during tangling. This has the effect of assigning values to variables +specified with @code{:var} (see @ref{var}), and of replacing ``noweb'' +references (see @ref{Noweb reference syntax}) with their targets. The +@code{:no-expand} header argument can be used to turn off this behavior. + +@node session, noweb, no-expand, Specific Header arguments @subsubsection session Start a session for an interpreted language where state is preserved. This applies particularly to the supported languages python, R and ruby. From 97928ae08e141eb20f6f01f4b2ede35fa33ae586 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Thu, 10 Jun 2010 14:42:59 -0700 Subject: [PATCH 029/138] babel-doc: tiny doc tweak --- doc/org.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/org.texi b/doc/org.texi index 51b3a87fc..f5a3b148c 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10892,7 +10892,7 @@ The structure of code blocks is as follows: @example #+srcname: #+begin_src
- + #+end_src @end example From 5fa1dcccad0e6ba53f4911d428fad672b8cd6dce Mon Sep 17 00:00:00 2001 From: Tom Dye Date: Fri, 11 Jun 2010 13:43:45 -0700 Subject: [PATCH 030/138] babel-doc: edits --- doc/org.texi | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index f5a3b148c..f2d633451 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10954,11 +10954,11 @@ to a non-nil value to switch without asking. @section Exporting code blocks It is possible to export the @emph{contents} of code blocks, the -@emph{results} of code block evaluation, or @emph{neither} or @emph{both}. -For most languages by default only body of a code blocks will be exported, -however some languages (e.g. @code{ditaa}) default to exporting the results -of the code block. For information on the exportation of code blocks bodies -see @ref{Literal examples}. +@emph{results} of code block evaluation, @emph{neither}, or @emph{both}. For +most languages, the default exports the contents of code blocks. However, for +some languages (e.g. @code{ditaa}) the default exports the results of code +block evaluation. For information on exporting code block bodies, see +@ref{Literal examples}. The @code{:exports} header argument can be used to specify non-default export behavior: @@ -10966,20 +10966,20 @@ behavior: @subsubheading Header arguments: @table @code @item :exports code -The default (in most languages). Only the body of the code block is exported -as described in @ref{Literal examples}. +The default in most languages. The body of the code block is exported, as +described in @ref{Literal examples}. @item :exports results On export, the code block will be evaluated and the results will be placed in -the org-mode buffer (either updating previous results of the code block -located anywhere in the buffer, or if no previous results exist placing the -new results immediately after the code block). The actual body of the code -block will not be exported. +the Org-mode buffer, either updating previous results of the code block +located anywhere in the buffer or, if no previous results exist, placing the +results immediately after the code block. The body of the code block will +not be exported. @item :exports both On export, the code block will be evaluated and the results inserted into the buffer as described above, however the body of the code block will be exported as well. @item :exports none -No part of the code block or it's results will be exported. +Neither the code block nor its results will be exported. @end table @node Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code From 04152d3a06bfe131b6e0c9cfcc12d8de5314f627 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Fri, 11 Jun 2010 15:10:36 -0700 Subject: [PATCH 031/138] moving org-babel into the main org-mode lisp directory we are keeping two things in the contrib directory 1) the library-of-babel.org file, this is with the goal of lowering the barrier of entry for contribution of functions to the library of babel 2) we are also keeping a langs directory in the contrib directory because some language files do not have FSF copyright assignment -- current org-babel-oz.el is the only such file --- contrib/babel/{lisp => }/langs/org-babel-oz.el | 0 {contrib/babel/lisp => lisp/babel}/langs/org-babel-C.el | 0 {contrib/babel/lisp => lisp/babel}/langs/org-babel-R.el | 0 {contrib/babel/lisp => lisp/babel}/langs/org-babel-asymptote.el | 0 {contrib/babel/lisp => lisp/babel}/langs/org-babel-clojure.el | 0 {contrib/babel/lisp => lisp/babel}/langs/org-babel-css.el | 0 {contrib/babel/lisp => lisp/babel}/langs/org-babel-ditaa.el | 0 {contrib/babel/lisp => lisp/babel}/langs/org-babel-dot.el | 0 {contrib/babel/lisp => lisp/babel}/langs/org-babel-emacs-lisp.el | 0 {contrib/babel/lisp => lisp/babel}/langs/org-babel-gnuplot.el | 0 {contrib/babel/lisp => lisp/babel}/langs/org-babel-haskell.el | 0 {contrib/babel/lisp => lisp/babel}/langs/org-babel-latex.el | 0 {contrib/babel/lisp => lisp/babel}/langs/org-babel-matlab.el | 0 {contrib/babel/lisp => lisp/babel}/langs/org-babel-ocaml.el | 0 {contrib/babel/lisp => lisp/babel}/langs/org-babel-octave.el | 0 {contrib/babel/lisp => lisp/babel}/langs/org-babel-perl.el | 0 {contrib/babel/lisp => lisp/babel}/langs/org-babel-python.el | 0 {contrib/babel/lisp => lisp/babel}/langs/org-babel-ruby.el | 0 {contrib/babel/lisp => lisp/babel}/langs/org-babel-sass.el | 0 {contrib/babel/lisp => lisp/babel}/langs/org-babel-screen.el | 0 {contrib/babel/lisp => lisp/babel}/langs/org-babel-sh.el | 0 {contrib/babel/lisp => lisp/babel}/langs/org-babel-sql.el | 0 {contrib/babel/lisp => lisp/babel}/org-babel-comint.el | 0 {contrib/babel/lisp => lisp/babel}/org-babel-exp.el | 0 {contrib/babel/lisp => lisp/babel}/org-babel-keys.el | 0 {contrib/babel/lisp => lisp/babel}/org-babel-lob.el | 0 {contrib/babel/lisp => lisp/babel}/org-babel-ref.el | 0 {contrib/babel/lisp => lisp/babel}/org-babel-table.el | 0 {contrib/babel/lisp => lisp/babel}/org-babel-tangle.el | 0 {contrib/babel/lisp => lisp/babel}/org-babel.el | 0 30 files changed, 0 insertions(+), 0 deletions(-) rename contrib/babel/{lisp => }/langs/org-babel-oz.el (100%) rename {contrib/babel/lisp => lisp/babel}/langs/org-babel-C.el (100%) rename {contrib/babel/lisp => lisp/babel}/langs/org-babel-R.el (100%) rename {contrib/babel/lisp => lisp/babel}/langs/org-babel-asymptote.el (100%) rename {contrib/babel/lisp => lisp/babel}/langs/org-babel-clojure.el (100%) rename {contrib/babel/lisp => lisp/babel}/langs/org-babel-css.el (100%) rename {contrib/babel/lisp => lisp/babel}/langs/org-babel-ditaa.el (100%) rename {contrib/babel/lisp => lisp/babel}/langs/org-babel-dot.el (100%) rename {contrib/babel/lisp => lisp/babel}/langs/org-babel-emacs-lisp.el (100%) rename {contrib/babel/lisp => lisp/babel}/langs/org-babel-gnuplot.el (100%) rename {contrib/babel/lisp => lisp/babel}/langs/org-babel-haskell.el (100%) rename {contrib/babel/lisp => lisp/babel}/langs/org-babel-latex.el (100%) rename {contrib/babel/lisp => lisp/babel}/langs/org-babel-matlab.el (100%) rename {contrib/babel/lisp => lisp/babel}/langs/org-babel-ocaml.el (100%) rename {contrib/babel/lisp => lisp/babel}/langs/org-babel-octave.el (100%) rename {contrib/babel/lisp => lisp/babel}/langs/org-babel-perl.el (100%) rename {contrib/babel/lisp => lisp/babel}/langs/org-babel-python.el (100%) rename {contrib/babel/lisp => lisp/babel}/langs/org-babel-ruby.el (100%) rename {contrib/babel/lisp => lisp/babel}/langs/org-babel-sass.el (100%) rename {contrib/babel/lisp => lisp/babel}/langs/org-babel-screen.el (100%) rename {contrib/babel/lisp => lisp/babel}/langs/org-babel-sh.el (100%) rename {contrib/babel/lisp => lisp/babel}/langs/org-babel-sql.el (100%) rename {contrib/babel/lisp => lisp/babel}/org-babel-comint.el (100%) rename {contrib/babel/lisp => lisp/babel}/org-babel-exp.el (100%) rename {contrib/babel/lisp => lisp/babel}/org-babel-keys.el (100%) rename {contrib/babel/lisp => lisp/babel}/org-babel-lob.el (100%) rename {contrib/babel/lisp => lisp/babel}/org-babel-ref.el (100%) rename {contrib/babel/lisp => lisp/babel}/org-babel-table.el (100%) rename {contrib/babel/lisp => lisp/babel}/org-babel-tangle.el (100%) rename {contrib/babel/lisp => lisp/babel}/org-babel.el (100%) diff --git a/contrib/babel/lisp/langs/org-babel-oz.el b/contrib/babel/langs/org-babel-oz.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-oz.el rename to contrib/babel/langs/org-babel-oz.el diff --git a/contrib/babel/lisp/langs/org-babel-C.el b/lisp/babel/langs/org-babel-C.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-C.el rename to lisp/babel/langs/org-babel-C.el diff --git a/contrib/babel/lisp/langs/org-babel-R.el b/lisp/babel/langs/org-babel-R.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-R.el rename to lisp/babel/langs/org-babel-R.el diff --git a/contrib/babel/lisp/langs/org-babel-asymptote.el b/lisp/babel/langs/org-babel-asymptote.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-asymptote.el rename to lisp/babel/langs/org-babel-asymptote.el diff --git a/contrib/babel/lisp/langs/org-babel-clojure.el b/lisp/babel/langs/org-babel-clojure.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-clojure.el rename to lisp/babel/langs/org-babel-clojure.el diff --git a/contrib/babel/lisp/langs/org-babel-css.el b/lisp/babel/langs/org-babel-css.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-css.el rename to lisp/babel/langs/org-babel-css.el diff --git a/contrib/babel/lisp/langs/org-babel-ditaa.el b/lisp/babel/langs/org-babel-ditaa.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-ditaa.el rename to lisp/babel/langs/org-babel-ditaa.el diff --git a/contrib/babel/lisp/langs/org-babel-dot.el b/lisp/babel/langs/org-babel-dot.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-dot.el rename to lisp/babel/langs/org-babel-dot.el diff --git a/contrib/babel/lisp/langs/org-babel-emacs-lisp.el b/lisp/babel/langs/org-babel-emacs-lisp.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-emacs-lisp.el rename to lisp/babel/langs/org-babel-emacs-lisp.el diff --git a/contrib/babel/lisp/langs/org-babel-gnuplot.el b/lisp/babel/langs/org-babel-gnuplot.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-gnuplot.el rename to lisp/babel/langs/org-babel-gnuplot.el diff --git a/contrib/babel/lisp/langs/org-babel-haskell.el b/lisp/babel/langs/org-babel-haskell.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-haskell.el rename to lisp/babel/langs/org-babel-haskell.el diff --git a/contrib/babel/lisp/langs/org-babel-latex.el b/lisp/babel/langs/org-babel-latex.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-latex.el rename to lisp/babel/langs/org-babel-latex.el diff --git a/contrib/babel/lisp/langs/org-babel-matlab.el b/lisp/babel/langs/org-babel-matlab.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-matlab.el rename to lisp/babel/langs/org-babel-matlab.el diff --git a/contrib/babel/lisp/langs/org-babel-ocaml.el b/lisp/babel/langs/org-babel-ocaml.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-ocaml.el rename to lisp/babel/langs/org-babel-ocaml.el diff --git a/contrib/babel/lisp/langs/org-babel-octave.el b/lisp/babel/langs/org-babel-octave.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-octave.el rename to lisp/babel/langs/org-babel-octave.el diff --git a/contrib/babel/lisp/langs/org-babel-perl.el b/lisp/babel/langs/org-babel-perl.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-perl.el rename to lisp/babel/langs/org-babel-perl.el diff --git a/contrib/babel/lisp/langs/org-babel-python.el b/lisp/babel/langs/org-babel-python.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-python.el rename to lisp/babel/langs/org-babel-python.el diff --git a/contrib/babel/lisp/langs/org-babel-ruby.el b/lisp/babel/langs/org-babel-ruby.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-ruby.el rename to lisp/babel/langs/org-babel-ruby.el diff --git a/contrib/babel/lisp/langs/org-babel-sass.el b/lisp/babel/langs/org-babel-sass.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-sass.el rename to lisp/babel/langs/org-babel-sass.el diff --git a/contrib/babel/lisp/langs/org-babel-screen.el b/lisp/babel/langs/org-babel-screen.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-screen.el rename to lisp/babel/langs/org-babel-screen.el diff --git a/contrib/babel/lisp/langs/org-babel-sh.el b/lisp/babel/langs/org-babel-sh.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-sh.el rename to lisp/babel/langs/org-babel-sh.el diff --git a/contrib/babel/lisp/langs/org-babel-sql.el b/lisp/babel/langs/org-babel-sql.el similarity index 100% rename from contrib/babel/lisp/langs/org-babel-sql.el rename to lisp/babel/langs/org-babel-sql.el diff --git a/contrib/babel/lisp/org-babel-comint.el b/lisp/babel/org-babel-comint.el similarity index 100% rename from contrib/babel/lisp/org-babel-comint.el rename to lisp/babel/org-babel-comint.el diff --git a/contrib/babel/lisp/org-babel-exp.el b/lisp/babel/org-babel-exp.el similarity index 100% rename from contrib/babel/lisp/org-babel-exp.el rename to lisp/babel/org-babel-exp.el diff --git a/contrib/babel/lisp/org-babel-keys.el b/lisp/babel/org-babel-keys.el similarity index 100% rename from contrib/babel/lisp/org-babel-keys.el rename to lisp/babel/org-babel-keys.el diff --git a/contrib/babel/lisp/org-babel-lob.el b/lisp/babel/org-babel-lob.el similarity index 100% rename from contrib/babel/lisp/org-babel-lob.el rename to lisp/babel/org-babel-lob.el diff --git a/contrib/babel/lisp/org-babel-ref.el b/lisp/babel/org-babel-ref.el similarity index 100% rename from contrib/babel/lisp/org-babel-ref.el rename to lisp/babel/org-babel-ref.el diff --git a/contrib/babel/lisp/org-babel-table.el b/lisp/babel/org-babel-table.el similarity index 100% rename from contrib/babel/lisp/org-babel-table.el rename to lisp/babel/org-babel-table.el diff --git a/contrib/babel/lisp/org-babel-tangle.el b/lisp/babel/org-babel-tangle.el similarity index 100% rename from contrib/babel/lisp/org-babel-tangle.el rename to lisp/babel/org-babel-tangle.el diff --git a/contrib/babel/lisp/org-babel.el b/lisp/babel/org-babel.el similarity index 100% rename from contrib/babel/lisp/org-babel.el rename to lisp/babel/org-babel.el From e0e4d76094f269f1786dc5339b939f7900c1a5e6 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Fri, 11 Jun 2010 15:20:22 -0700 Subject: [PATCH 032/138] renaming all org-babel* function to ob* to conform with Emacs conventions --- contrib/babel/langs/{org-babel-oz.el => ob-oz.el} | 0 lisp/babel/langs/{org-babel-C.el => ob-C.el} | 0 lisp/babel/langs/{org-babel-R.el => ob-R.el} | 0 lisp/babel/langs/{org-babel-asymptote.el => ob-asymptote.el} | 0 lisp/babel/langs/{org-babel-clojure.el => ob-clojure.el} | 0 lisp/babel/langs/{org-babel-css.el => ob-css.el} | 0 lisp/babel/langs/{org-babel-ditaa.el => ob-ditaa.el} | 0 lisp/babel/langs/{org-babel-dot.el => ob-dot.el} | 0 lisp/babel/langs/{org-babel-emacs-lisp.el => ob-emacs-lisp.el} | 0 lisp/babel/langs/{org-babel-gnuplot.el => ob-gnuplot.el} | 0 lisp/babel/langs/{org-babel-haskell.el => ob-haskell.el} | 0 lisp/babel/langs/{org-babel-latex.el => ob-latex.el} | 0 lisp/babel/langs/{org-babel-matlab.el => ob-matlab.el} | 0 lisp/babel/langs/{org-babel-ocaml.el => ob-ocaml.el} | 0 lisp/babel/langs/{org-babel-octave.el => ob-octave.el} | 0 lisp/babel/langs/{org-babel-perl.el => ob-perl.el} | 0 lisp/babel/langs/{org-babel-python.el => ob-python.el} | 0 lisp/babel/langs/{org-babel-ruby.el => ob-ruby.el} | 0 lisp/babel/langs/{org-babel-sass.el => ob-sass.el} | 0 lisp/babel/langs/{org-babel-screen.el => ob-screen.el} | 0 lisp/babel/langs/{org-babel-sh.el => ob-sh.el} | 0 lisp/babel/langs/{org-babel-sql.el => ob-sql.el} | 0 lisp/babel/{org-babel-comint.el => ob-comint.el} | 0 lisp/babel/{org-babel-exp.el => ob-exp.el} | 0 lisp/babel/{org-babel-keys.el => ob-keys.el} | 0 lisp/babel/{org-babel-lob.el => ob-lob.el} | 0 lisp/babel/{org-babel-ref.el => ob-ref.el} | 0 lisp/babel/{org-babel-table.el => ob-table.el} | 0 lisp/babel/{org-babel-tangle.el => ob-tangle.el} | 0 lisp/babel/{org-babel.el => ob.el} | 0 30 files changed, 0 insertions(+), 0 deletions(-) rename contrib/babel/langs/{org-babel-oz.el => ob-oz.el} (100%) rename lisp/babel/langs/{org-babel-C.el => ob-C.el} (100%) rename lisp/babel/langs/{org-babel-R.el => ob-R.el} (100%) rename lisp/babel/langs/{org-babel-asymptote.el => ob-asymptote.el} (100%) rename lisp/babel/langs/{org-babel-clojure.el => ob-clojure.el} (100%) rename lisp/babel/langs/{org-babel-css.el => ob-css.el} (100%) rename lisp/babel/langs/{org-babel-ditaa.el => ob-ditaa.el} (100%) rename lisp/babel/langs/{org-babel-dot.el => ob-dot.el} (100%) rename lisp/babel/langs/{org-babel-emacs-lisp.el => ob-emacs-lisp.el} (100%) rename lisp/babel/langs/{org-babel-gnuplot.el => ob-gnuplot.el} (100%) rename lisp/babel/langs/{org-babel-haskell.el => ob-haskell.el} (100%) rename lisp/babel/langs/{org-babel-latex.el => ob-latex.el} (100%) rename lisp/babel/langs/{org-babel-matlab.el => ob-matlab.el} (100%) rename lisp/babel/langs/{org-babel-ocaml.el => ob-ocaml.el} (100%) rename lisp/babel/langs/{org-babel-octave.el => ob-octave.el} (100%) rename lisp/babel/langs/{org-babel-perl.el => ob-perl.el} (100%) rename lisp/babel/langs/{org-babel-python.el => ob-python.el} (100%) rename lisp/babel/langs/{org-babel-ruby.el => ob-ruby.el} (100%) rename lisp/babel/langs/{org-babel-sass.el => ob-sass.el} (100%) rename lisp/babel/langs/{org-babel-screen.el => ob-screen.el} (100%) rename lisp/babel/langs/{org-babel-sh.el => ob-sh.el} (100%) rename lisp/babel/langs/{org-babel-sql.el => ob-sql.el} (100%) rename lisp/babel/{org-babel-comint.el => ob-comint.el} (100%) rename lisp/babel/{org-babel-exp.el => ob-exp.el} (100%) rename lisp/babel/{org-babel-keys.el => ob-keys.el} (100%) rename lisp/babel/{org-babel-lob.el => ob-lob.el} (100%) rename lisp/babel/{org-babel-ref.el => ob-ref.el} (100%) rename lisp/babel/{org-babel-table.el => ob-table.el} (100%) rename lisp/babel/{org-babel-tangle.el => ob-tangle.el} (100%) rename lisp/babel/{org-babel.el => ob.el} (100%) diff --git a/contrib/babel/langs/org-babel-oz.el b/contrib/babel/langs/ob-oz.el similarity index 100% rename from contrib/babel/langs/org-babel-oz.el rename to contrib/babel/langs/ob-oz.el diff --git a/lisp/babel/langs/org-babel-C.el b/lisp/babel/langs/ob-C.el similarity index 100% rename from lisp/babel/langs/org-babel-C.el rename to lisp/babel/langs/ob-C.el diff --git a/lisp/babel/langs/org-babel-R.el b/lisp/babel/langs/ob-R.el similarity index 100% rename from lisp/babel/langs/org-babel-R.el rename to lisp/babel/langs/ob-R.el diff --git a/lisp/babel/langs/org-babel-asymptote.el b/lisp/babel/langs/ob-asymptote.el similarity index 100% rename from lisp/babel/langs/org-babel-asymptote.el rename to lisp/babel/langs/ob-asymptote.el diff --git a/lisp/babel/langs/org-babel-clojure.el b/lisp/babel/langs/ob-clojure.el similarity index 100% rename from lisp/babel/langs/org-babel-clojure.el rename to lisp/babel/langs/ob-clojure.el diff --git a/lisp/babel/langs/org-babel-css.el b/lisp/babel/langs/ob-css.el similarity index 100% rename from lisp/babel/langs/org-babel-css.el rename to lisp/babel/langs/ob-css.el diff --git a/lisp/babel/langs/org-babel-ditaa.el b/lisp/babel/langs/ob-ditaa.el similarity index 100% rename from lisp/babel/langs/org-babel-ditaa.el rename to lisp/babel/langs/ob-ditaa.el diff --git a/lisp/babel/langs/org-babel-dot.el b/lisp/babel/langs/ob-dot.el similarity index 100% rename from lisp/babel/langs/org-babel-dot.el rename to lisp/babel/langs/ob-dot.el diff --git a/lisp/babel/langs/org-babel-emacs-lisp.el b/lisp/babel/langs/ob-emacs-lisp.el similarity index 100% rename from lisp/babel/langs/org-babel-emacs-lisp.el rename to lisp/babel/langs/ob-emacs-lisp.el diff --git a/lisp/babel/langs/org-babel-gnuplot.el b/lisp/babel/langs/ob-gnuplot.el similarity index 100% rename from lisp/babel/langs/org-babel-gnuplot.el rename to lisp/babel/langs/ob-gnuplot.el diff --git a/lisp/babel/langs/org-babel-haskell.el b/lisp/babel/langs/ob-haskell.el similarity index 100% rename from lisp/babel/langs/org-babel-haskell.el rename to lisp/babel/langs/ob-haskell.el diff --git a/lisp/babel/langs/org-babel-latex.el b/lisp/babel/langs/ob-latex.el similarity index 100% rename from lisp/babel/langs/org-babel-latex.el rename to lisp/babel/langs/ob-latex.el diff --git a/lisp/babel/langs/org-babel-matlab.el b/lisp/babel/langs/ob-matlab.el similarity index 100% rename from lisp/babel/langs/org-babel-matlab.el rename to lisp/babel/langs/ob-matlab.el diff --git a/lisp/babel/langs/org-babel-ocaml.el b/lisp/babel/langs/ob-ocaml.el similarity index 100% rename from lisp/babel/langs/org-babel-ocaml.el rename to lisp/babel/langs/ob-ocaml.el diff --git a/lisp/babel/langs/org-babel-octave.el b/lisp/babel/langs/ob-octave.el similarity index 100% rename from lisp/babel/langs/org-babel-octave.el rename to lisp/babel/langs/ob-octave.el diff --git a/lisp/babel/langs/org-babel-perl.el b/lisp/babel/langs/ob-perl.el similarity index 100% rename from lisp/babel/langs/org-babel-perl.el rename to lisp/babel/langs/ob-perl.el diff --git a/lisp/babel/langs/org-babel-python.el b/lisp/babel/langs/ob-python.el similarity index 100% rename from lisp/babel/langs/org-babel-python.el rename to lisp/babel/langs/ob-python.el diff --git a/lisp/babel/langs/org-babel-ruby.el b/lisp/babel/langs/ob-ruby.el similarity index 100% rename from lisp/babel/langs/org-babel-ruby.el rename to lisp/babel/langs/ob-ruby.el diff --git a/lisp/babel/langs/org-babel-sass.el b/lisp/babel/langs/ob-sass.el similarity index 100% rename from lisp/babel/langs/org-babel-sass.el rename to lisp/babel/langs/ob-sass.el diff --git a/lisp/babel/langs/org-babel-screen.el b/lisp/babel/langs/ob-screen.el similarity index 100% rename from lisp/babel/langs/org-babel-screen.el rename to lisp/babel/langs/ob-screen.el diff --git a/lisp/babel/langs/org-babel-sh.el b/lisp/babel/langs/ob-sh.el similarity index 100% rename from lisp/babel/langs/org-babel-sh.el rename to lisp/babel/langs/ob-sh.el diff --git a/lisp/babel/langs/org-babel-sql.el b/lisp/babel/langs/ob-sql.el similarity index 100% rename from lisp/babel/langs/org-babel-sql.el rename to lisp/babel/langs/ob-sql.el diff --git a/lisp/babel/org-babel-comint.el b/lisp/babel/ob-comint.el similarity index 100% rename from lisp/babel/org-babel-comint.el rename to lisp/babel/ob-comint.el diff --git a/lisp/babel/org-babel-exp.el b/lisp/babel/ob-exp.el similarity index 100% rename from lisp/babel/org-babel-exp.el rename to lisp/babel/ob-exp.el diff --git a/lisp/babel/org-babel-keys.el b/lisp/babel/ob-keys.el similarity index 100% rename from lisp/babel/org-babel-keys.el rename to lisp/babel/ob-keys.el diff --git a/lisp/babel/org-babel-lob.el b/lisp/babel/ob-lob.el similarity index 100% rename from lisp/babel/org-babel-lob.el rename to lisp/babel/ob-lob.el diff --git a/lisp/babel/org-babel-ref.el b/lisp/babel/ob-ref.el similarity index 100% rename from lisp/babel/org-babel-ref.el rename to lisp/babel/ob-ref.el diff --git a/lisp/babel/org-babel-table.el b/lisp/babel/ob-table.el similarity index 100% rename from lisp/babel/org-babel-table.el rename to lisp/babel/ob-table.el diff --git a/lisp/babel/org-babel-tangle.el b/lisp/babel/ob-tangle.el similarity index 100% rename from lisp/babel/org-babel-tangle.el rename to lisp/babel/ob-tangle.el diff --git a/lisp/babel/org-babel.el b/lisp/babel/ob.el similarity index 100% rename from lisp/babel/org-babel.el rename to lisp/babel/ob.el From 96e396ba77060b6c1467a6de4196d7dae5408eca Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Fri, 11 Jun 2010 15:23:03 -0700 Subject: [PATCH 033/138] new header for ob.el --- lisp/babel/ob.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lisp/babel/ob.el b/lisp/babel/ob.el index 1ef10823e..992b3aec2 100644 --- a/lisp/babel/ob.el +++ b/lisp/babel/ob.el @@ -1,4 +1,4 @@ -;;; org-babel.el --- facilitating communication between programming languages and people +;;; org-babel.el --- working with code blocks in org-mode ;; Copyright (C) 2009 Eric Schulte, Dan Davison From 93f63607930d03d21ae9b27fb24b0276f2c4dc54 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Fri, 11 Jun 2010 15:23:52 -0700 Subject: [PATCH 034/138] removing contrib/babel/org-babel-install.el -- no longer required --- contrib/lisp/org-babel-init.el | 70 ---------------------------------- 1 file changed, 70 deletions(-) delete mode 100644 contrib/lisp/org-babel-init.el diff --git a/contrib/lisp/org-babel-init.el b/contrib/lisp/org-babel-init.el deleted file mode 100644 index 037773fd3..000000000 --- a/contrib/lisp/org-babel-init.el +++ /dev/null @@ -1,70 +0,0 @@ -;;; org-babel-init.el --- loads org-babel - -;; Copyright (C) 2009 Eric Schulte - -;; Author: Eric Schulte -;; Keywords: literate programming, reproducible research -;; Homepage: http://orgmode.org -;; Version: 0.01 - -;;; License: - -;; This program is free software; you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. -;; -;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. - -;;; Commentary: - -;; for more information see the comments in org-babel.el - -;;; Code: -(let* ((babel-dir (expand-file-name - "lisp" - (expand-file-name - "babel" - (expand-file-name - ".." (file-name-directory (or load-file-name buffer-file-name)))))) - - (langs-dir (expand-file-name "langs" babel-dir))) - - (add-to-list 'load-path babel-dir) - (add-to-list 'load-path langs-dir) - - ;; org-babel core - (require 'cl) - (require 'org) - (require 'org-table) - (require 'org-exp-blocks) - (require 'org-babel) - (require 'org-babel-ref) - (require 'org-babel-exp) - (require 'org-babel-table) - (require 'org-babel-comint) - (require 'org-babel-lob) - (require 'org-babel-tangle) - (require 'org-babel-keys) - - ;; org-babel languages - (require 'org-babel-emacs-lisp) - (require 'org-babel-sh) - - ;; Library of babel - (defvar org-babel-lob-dir - (expand-file-name ".." babel-dir) - "The directory holding the library-of-babel") - (defun org-babel-load-library-of-babel () - (org-babel-lob-ingest (expand-file-name "library-of-babel.org" org-babel-lob-dir)))) - -(provide 'org-babel-init) -;;; org-babel-init.el ends here From 904bdaff9ab9e0ecac0a40ea6402ebdc1064b629 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Fri, 11 Jun 2010 15:25:37 -0700 Subject: [PATCH 035/138] ob.el now adds the lisp/langs/ directory to the load path --- lisp/babel/ob.el | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/lisp/babel/ob.el b/lisp/babel/ob.el index 992b3aec2..34d096ff7 100644 --- a/lisp/babel/ob.el +++ b/lisp/babel/ob.el @@ -31,6 +31,12 @@ ;;; Code: (require 'org) +;; add the langs/ directory to the load path +(add-to-list 'load-path (expand-file-name + "langs" + (file-name-directory (or (buffer-file-name) + load-file-name)))) + (defun org-babel-execute-src-block-maybe () "Detect if this is context for a org-babel src-block and if so then run `org-babel-execute-src-block'." From 07388931605c3c9bd6bc6b713ac2ce63c290bae9 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Fri, 11 Jun 2010 16:02:42 -0700 Subject: [PATCH 036/138] updating require and provide boilerplate for new ob* files --- lisp/babel/langs/ob-C.el | 8 ++++---- lisp/babel/langs/ob-R.el | 8 ++++---- lisp/babel/langs/ob-asymptote.el | 8 ++++---- lisp/babel/langs/ob-clojure.el | 9 +++++---- lisp/babel/langs/ob-css.el | 8 ++++---- lisp/babel/langs/ob-ditaa.el | 8 ++++---- lisp/babel/langs/ob-dot.el | 8 ++++---- lisp/babel/langs/ob-emacs-lisp.el | 8 ++++---- lisp/babel/langs/ob-gnuplot.el | 8 ++++---- lisp/babel/langs/ob-haskell.el | 8 ++++---- lisp/babel/langs/ob-latex.el | 8 ++++---- lisp/babel/langs/ob-matlab.el | 8 ++++---- lisp/babel/langs/ob-ocaml.el | 8 ++++---- lisp/babel/langs/ob-octave.el | 8 ++++---- lisp/babel/langs/ob-perl.el | 8 ++++---- lisp/babel/langs/ob-python.el | 12 ++++++------ lisp/babel/langs/ob-ruby.el | 8 ++++---- lisp/babel/langs/ob-sass.el | 8 ++++---- lisp/babel/langs/ob-screen.el | 8 ++++---- lisp/babel/langs/ob-sh.el | 8 ++++---- lisp/babel/langs/ob-sql.el | 8 ++++---- lisp/babel/ob-comint.el | 8 ++++---- lisp/babel/ob-exp.el | 8 ++++---- lisp/babel/ob-keys.el | 8 ++++---- lisp/babel/ob-lob.el | 12 ++++++------ lisp/babel/ob-ref.el | 8 ++++---- lisp/babel/ob-table.el | 8 ++++---- lisp/babel/ob-tangle.el | 8 ++++---- lisp/babel/ob.el | 7 ++++--- 29 files changed, 121 insertions(+), 119 deletions(-) diff --git a/lisp/babel/langs/ob-C.el b/lisp/babel/langs/ob-C.el index 13e6fcacd..ce6cccd2f 100644 --- a/lisp/babel/langs/ob-C.el +++ b/lisp/babel/langs/ob-C.el @@ -1,4 +1,4 @@ -;;; org-babel-C.el --- org-babel functions for C and similar languages +;;; ob-C.el --- org-babel functions for C and similar languages ;; Copyright (C) 2010 Eric Schulte @@ -33,7 +33,7 @@ ;; - not much in the way of error feedback ;;; Code: -(require 'org-babel) +(require 'ob) (require 'cc-mode) (org-babel-add-interpreter "C") @@ -189,5 +189,5 @@ of the same value. TODO list support." (format "u32 %S = %S;" var val))))) -(provide 'org-babel-C) -;;; org-babel-C.el ends here +(provide 'ob-C) +;;; ob-C.el ends here diff --git a/lisp/babel/langs/ob-R.el b/lisp/babel/langs/ob-R.el index 513577a41..6014dc137 100644 --- a/lisp/babel/langs/ob-R.el +++ b/lisp/babel/langs/ob-R.el @@ -1,4 +1,4 @@ -;;; org-babel-R.el --- org-babel functions for R code evaluation +;;; ob-R.el --- org-babel functions for R code evaluation ;; Copyright (C) 2009 Eric Schulte @@ -29,7 +29,7 @@ ;; Org-Babel support for evaluating R code ;;; Code: -(require 'org-babel) +(require 'ob) (org-babel-add-interpreter "R") @@ -250,5 +250,5 @@ Currently, insert hline if column names in output have been requested." result)) -(provide 'org-babel-R) -;;; org-babel-R.el ends here +(provide 'ob-R) +;;; ob-R.el ends here diff --git a/lisp/babel/langs/ob-asymptote.el b/lisp/babel/langs/ob-asymptote.el index 194e29c13..a879088a6 100644 --- a/lisp/babel/langs/ob-asymptote.el +++ b/lisp/babel/langs/ob-asymptote.el @@ -1,4 +1,4 @@ -;;; org-babel-asymptote.el --- org-babel functions for asymptote evaluation +;;; ob-asymptote.el --- org-babel functions for asymptote evaluation ;; Copyright (C) 2009 Eric Schulte @@ -45,7 +45,7 @@ ;; - asy-mode :: Major mode for editing asymptote files ;;; Code: -(require 'org-babel) +(require 'ob) (org-babel-add-interpreter "asymptote") @@ -151,5 +151,5 @@ every cell must be of int type." (anything-but-int (cdr el))))))) (or (anything-but-int data) 'int))) -(provide 'org-babel-asymptote) -;;; org-babel-asymptote.el ends here +(provide 'ob-asymptote) +;;; ob-asymptote.el ends here diff --git a/lisp/babel/langs/ob-clojure.el b/lisp/babel/langs/ob-clojure.el index cd72d9394..729046e39 100644 --- a/lisp/babel/langs/ob-clojure.el +++ b/lisp/babel/langs/ob-clojure.el @@ -1,4 +1,4 @@ -;;; org-babel-clojure.el --- org-babel functions for clojure evaluation +;;; ob-clojure.el --- org-babel functions for clojure evaluation ;; Copyright (C) 2009 Joel Boehland @@ -26,7 +26,7 @@ ;;; Commentary: -;;; Org-Babel support for evaluating clojure code +;;; ob support for evaluating clojure code ;;; Requirements: @@ -40,7 +40,7 @@ ;;; web page: http://technomancy.us/126 ;;; Code: -(require 'org-babel) +(require 'ob) (require 'cl) (require 'slime) (require 'swank-clojure) @@ -278,4 +278,5 @@ last statement in BODY, as elisp." (org-babel-pick-name (nth 4 processed-params) (cdr (assoc :colnames params))) (org-babel-pick-name (nth 5 processed-params) (cdr (assoc :rownames params)))))) -(provide 'org-babel-clojure) +(provide 'ob-clojure) +;;; ob-clojure.el ends here diff --git a/lisp/babel/langs/ob-css.el b/lisp/babel/langs/ob-css.el index 4b5331d5b..d8ce8b07c 100644 --- a/lisp/babel/langs/ob-css.el +++ b/lisp/babel/langs/ob-css.el @@ -1,4 +1,4 @@ -;;; org-babel-css.el --- org-babel functions for css evaluation +;;; ob-css.el --- org-babel functions for css evaluation ;; Copyright (C) 2009 Eric Schulte @@ -30,7 +30,7 @@ ;; CSS from org-mode files. ;;; Code: -(require 'org-babel) +(require 'ob) (org-babel-add-interpreter "css") @@ -48,5 +48,5 @@ called by `org-babel-execute-src-block'." "Prepare SESSION according to the header arguments specified in PARAMS." (error "CSS sessions are nonsensical")) -(provide 'org-babel-css) -;;; org-babel-css.el ends here +(provide 'ob-css) +;;; ob-css.el ends here diff --git a/lisp/babel/langs/ob-ditaa.el b/lisp/babel/langs/ob-ditaa.el index b85f836b2..b3cfcde42 100644 --- a/lisp/babel/langs/ob-ditaa.el +++ b/lisp/babel/langs/ob-ditaa.el @@ -1,4 +1,4 @@ -;;; org-babel-ditaa.el --- org-babel functions for ditaa evaluation +;;; ob-ditaa.el --- org-babel functions for ditaa evaluation ;; Copyright (C) 2009 Eric Schulte @@ -39,7 +39,7 @@ ;; 4) there are no variables (at least for now) ;;; Code: -(require 'org-babel) +(require 'ob) (org-babel-add-interpreter "ditaa") @@ -69,5 +69,5 @@ called by `org-babel-execute-src-block'." (defun org-babel-prep-session:ditaa (session params) (error "Ditaa does not support sessions")) -(provide 'org-babel-ditaa) -;;; org-babel-ditaa.el ends here +(provide 'ob-ditaa) +;;; ob-ditaa.el ends here diff --git a/lisp/babel/langs/ob-dot.el b/lisp/babel/langs/ob-dot.el index 30798f9c7..2c3e2794d 100644 --- a/lisp/babel/langs/ob-dot.el +++ b/lisp/babel/langs/ob-dot.el @@ -1,4 +1,4 @@ -;;; org-babel-dot.el --- org-babel functions for dot evaluation +;;; ob-dot.el --- org-babel functions for dot evaluation ;; Copyright (C) 2009 Eric Schulte @@ -41,7 +41,7 @@ ;; 4) there are no variables (at least for now) ;;; Code: -(require 'org-babel) +(require 'ob) (org-babel-add-interpreter "dot") @@ -69,5 +69,5 @@ called by `org-babel-execute-src-block'." (defun org-babel-prep-session:dot (session params) (error "Dot does not support sessions")) -(provide 'org-babel-dot) -;;; org-babel-dot.el ends here +(provide 'ob-dot) +;;; ob-dot.el ends here diff --git a/lisp/babel/langs/ob-emacs-lisp.el b/lisp/babel/langs/ob-emacs-lisp.el index 510ce9128..6683bcab1 100644 --- a/lisp/babel/langs/ob-emacs-lisp.el +++ b/lisp/babel/langs/ob-emacs-lisp.el @@ -1,4 +1,4 @@ -;;; org-babel-emacs-lisp.el --- org-babel functions for emacs-lisp code evaluation +;;; ob-emacs-lisp.el --- org-babel functions for emacs-lisp code evaluation ;; Copyright (C) 2009 Eric Schulte @@ -29,7 +29,7 @@ ;; Org-Babel support for evaluating emacs-lisp code ;;; Code: -(require 'org-babel) +(require 'ob) (org-babel-add-interpreter "emacs-lisp") @@ -67,5 +67,5 @@ (org-babel-pick-name (nth 4 processed-params) (cdr (assoc :colnames params))) (org-babel-pick-name (nth 5 processed-params) (cdr (assoc :rownames params))))))) -(provide 'org-babel-emacs-lisp) -;;; org-babel-emacs-lisp.el ends here +(provide 'obemacs-lisp) +;;; ob-emacs-lisp.el ends here diff --git a/lisp/babel/langs/ob-gnuplot.el b/lisp/babel/langs/ob-gnuplot.el index 04d216947..ef45eebe3 100644 --- a/lisp/babel/langs/ob-gnuplot.el +++ b/lisp/babel/langs/ob-gnuplot.el @@ -1,4 +1,4 @@ -;;; org-babel-gnuplot.el --- org-babel functions for gnuplot evaluation +;;; ob-gnuplot.el --- org-babel functions for gnuplot evaluation ;; Copyright (C) 2009 Eric Schulte @@ -41,7 +41,7 @@ ;; - gnuplot-mode :: http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html ;;; Code: -(require 'org-babel) +(require 'ob) (require 'gnuplot) (org-babel-add-interpreter "gnuplot") @@ -210,5 +210,5 @@ Pass PARAMS through to `orgtbl-to-generic' when exporting TABLE." params)))) data-file) -(provide 'org-babel-gnuplot) -;;; org-babel-gnuplot.el ends here +(provide 'ob-gnuplot) +;;; ob-gnuplot.el ends here diff --git a/lisp/babel/langs/ob-haskell.el b/lisp/babel/langs/ob-haskell.el index 9b6785745..edd27f514 100644 --- a/lisp/babel/langs/ob-haskell.el +++ b/lisp/babel/langs/ob-haskell.el @@ -1,4 +1,4 @@ -;;; org-babel-haskell.el --- org-babel functions for haskell evaluation +;;; ob-haskell.el --- org-babel functions for haskell evaluation ;; Copyright (C) 2009 Eric Schulte @@ -42,7 +42,7 @@ ;; - (optionally) lhs2tex :: http://people.cs.uu.nl/andres/lhs2tex/ ;;; Code: -(require 'org-babel) +(require 'ob) (require 'haskell-mode) (require 'inf-haskell) @@ -201,5 +201,5 @@ constructs (header arguments, no-web syntax etc...) are ignored." ;; process .lhs file with lhs2tex (message "running %s" command) (shell-command command) (find-file tex-file)))) -(provide 'org-babel-haskell) -;;; org-babel-haskell.el ends here +(provide 'ob-haskell) +;;; ob-haskell.el ends here diff --git a/lisp/babel/langs/ob-latex.el b/lisp/babel/langs/ob-latex.el index 0dc14a356..ebfae9c9b 100644 --- a/lisp/babel/langs/ob-latex.el +++ b/lisp/babel/langs/ob-latex.el @@ -1,4 +1,4 @@ -;;; org-babel-latex.el --- org-babel functions for latex "evaluation" +;;; ob-latex.el --- org-babel functions for latex "evaluation" ;; Copyright (C) 2009 Eric Schulte @@ -33,7 +33,7 @@ ;; be created directly form the latex source code. ;;; Code: -(require 'org-babel) +(require 'ob) (org-babel-add-interpreter "latex") @@ -136,5 +136,5 @@ called by `org-babel-execute-src-block'." (defun org-babel-prep-session:latex (session params) (error "Latex does not support sessions")) -(provide 'org-babel-latex) -;;; org-babel-latex.el ends here +(provide 'ob-latex) +;;; ob-latex.el ends here diff --git a/lisp/babel/langs/ob-matlab.el b/lisp/babel/langs/ob-matlab.el index b54f571f3..46dec3a57 100644 --- a/lisp/babel/langs/ob-matlab.el +++ b/lisp/babel/langs/ob-matlab.el @@ -1,4 +1,4 @@ -;;; org-babel-matlab.el --- org-babel support for matlab evaluation +;;; ob-matlab.el --- org-babel support for matlab evaluation ;; Copyright (C) Dan Davison @@ -39,7 +39,7 @@ ;;; Code: (require 'matlab) -(require 'org-babel-octave) +(require 'ob-octave) (org-babel-add-interpreter "matlab") (add-to-list 'org-babel-tangle-langs '("matlab" "m" "#!/usr/bin/env matlab")) @@ -76,5 +76,5 @@ If there is not a current inferior-process-buffer in SESSION then create. Return the initialized session." (org-babel-octave-initiate-session session params 'matlab)) -(provide 'org-babel-matlab) -;;; org-babel-matlab.el ends here +(provide 'ob-matlab) +;;; ob-matlab.el ends here diff --git a/lisp/babel/langs/ob-ocaml.el b/lisp/babel/langs/ob-ocaml.el index 27f6ea117..65aa56162 100644 --- a/lisp/babel/langs/ob-ocaml.el +++ b/lisp/babel/langs/ob-ocaml.el @@ -1,4 +1,4 @@ -;;; org-babel-ocaml.el --- org-babel functions for ocaml evaluation +;;; ob-ocaml.el --- org-babel functions for ocaml evaluation ;; Copyright (C) 2009 Eric Schulte @@ -38,7 +38,7 @@ ;; - tuareg-mode :: http://www-rocq.inria.fr/~acohen/tuareg/ ;;; Code: -(require 'org-babel) +(require 'ob) (require 'tuareg) (org-babel-add-interpreter "ocaml") @@ -122,5 +122,5 @@ Emacs-lisp table, otherwise return the results as a string." "'" "\"" results))))) results))) -(provide 'org-babel-ocaml) -;;; org-babel-ocaml.el ends here +(provide 'ob-ocaml) +;;; ob-ocaml.el ends here diff --git a/lisp/babel/langs/ob-octave.el b/lisp/babel/langs/ob-octave.el index 6cb244f00..e29fb0891 100644 --- a/lisp/babel/langs/ob-octave.el +++ b/lisp/babel/langs/ob-octave.el @@ -1,4 +1,4 @@ -;;; org-babel-octave.el --- org-babel functions for octave and matlab evaluation +;;; ob-octave.el --- org-babel functions for octave and matlab evaluation ;; Copyright (C) Dan Davison @@ -32,7 +32,7 @@ ;; octave-mode.el and octave-inf.el come with GNU emacs ;;; Code: -(require 'org-babel) +(require 'ob) (require 'octave-inf) (org-babel-add-interpreter "octave") @@ -214,5 +214,5 @@ This removes initial blank and comment lines and then calls (match-string 1 string) string)) -(provide 'org-babel-octave) -;;; org-babel-octave.el ends here +(provide 'ob-octave) +;;; ob-octave.el ends here diff --git a/lisp/babel/langs/ob-perl.el b/lisp/babel/langs/ob-perl.el index ac1438573..4baed2ea3 100644 --- a/lisp/babel/langs/ob-perl.el +++ b/lisp/babel/langs/ob-perl.el @@ -1,4 +1,4 @@ -;;; org-babel-perl.el --- org-babel functions for perl evaluation +;;; ob-perl.el --- org-babel functions for perl evaluation ;; Copyright (C) 2009 Dan Davison, Eric Schulte @@ -29,7 +29,7 @@ ;; Org-Babel support for evaluating perl source code. ;;; Code: -(require 'org-babel) +(require 'ob) (org-babel-add-interpreter "perl") @@ -126,5 +126,5 @@ last statement in BODY, as elisp." ;; comint session evaluation (error "Sessions are not supported for Perl."))) -(provide 'org-babel-perl) -;;; org-babel-perl.el ends here +(provide 'ob-perl) +;;; ob-perl.el ends here diff --git a/lisp/babel/langs/ob-python.el b/lisp/babel/langs/ob-python.el index 6c8e5de3d..250cfa2fd 100644 --- a/lisp/babel/langs/ob-python.el +++ b/lisp/babel/langs/ob-python.el @@ -1,4 +1,4 @@ -;;; org-babel-python.el --- org-babel functions for python evaluation +;;; ob-python.el --- org-babel functions for python evaluation ;; Copyright (C) 2009 Eric Schulte @@ -29,9 +29,9 @@ ;; Org-Babel support for evaluating python source code. ;;; Code: -(require 'org-babel) -(require 'org-babel-tangle) -(require 'org-babel-comint) +(require 'ob) +(require 'ob-tangle) +(require 'ob-comint) (require (if (featurep 'xemacs) 'python-mode 'python)) (org-babel-add-interpreter "python") @@ -249,5 +249,5 @@ last statement in BODY, as elisp." (match-string 1 string) string)) -(provide 'org-babel-python) -;;; org-babel-python.el ends here +(provide 'ob-python) +;;; ob-python.el ends here diff --git a/lisp/babel/langs/ob-ruby.el b/lisp/babel/langs/ob-ruby.el index ca7ce29df..bc6a23fc3 100644 --- a/lisp/babel/langs/ob-ruby.el +++ b/lisp/babel/langs/ob-ruby.el @@ -1,4 +1,4 @@ -;;; org-babel-ruby.el --- org-babel functions for ruby evaluation +;;; ob-ruby.el --- org-babel functions for ruby evaluation ;; Copyright (C) 2009 Eric Schulte @@ -39,7 +39,7 @@ ;; http://github.com/eschulte/rinari/raw/master/util/inf-ruby.el ;;; Code: -(require 'org-babel) +(require 'ob) (require 'inf-ruby) (org-babel-add-interpreter "ruby") @@ -232,5 +232,5 @@ last statement in BODY, as elisp." (match-string 1 string) string)) -(provide 'org-babel-ruby) -;;; org-babel-ruby.el ends here +(provide 'ob-ruby) +;;; ob-ruby.el ends here diff --git a/lisp/babel/langs/ob-sass.el b/lisp/babel/langs/ob-sass.el index 4bf5b9944..f42f0c268 100644 --- a/lisp/babel/langs/ob-sass.el +++ b/lisp/babel/langs/ob-sass.el @@ -1,4 +1,4 @@ -;;; org-babel-sass.el --- org-babel functions for the sass css generation language +;;; ob-sass.el --- org-babel functions for the sass css generation language ;; Copyright (C) 2009 Eric Schulte @@ -41,7 +41,7 @@ ;; - sass-mode :: http://github.com/nex3/haml/blob/master/extra/sass-mode.el ;;; Code: -(require 'org-babel) +(require 'ob) (require 'sass-mode) (org-babel-add-interpreter "sass") @@ -67,5 +67,5 @@ called by `org-babel-execute-src-block'." (defun org-babel-prep-session:sass (session params) (error "Sass does not support sessions")) -(provide 'org-babel-sass) -;;; org-babel-sass.el ends here +(provide 'ob-sass) +;;; ob-sass.el ends here diff --git a/lisp/babel/langs/ob-screen.el b/lisp/babel/langs/ob-screen.el index d4b5c4c56..079fc1ae5 100644 --- a/lisp/babel/langs/ob-screen.el +++ b/lisp/babel/langs/ob-screen.el @@ -1,4 +1,4 @@ -;;; org-babel-screen.el --- org-babel support for interactive terminal +;;; ob-screen.el --- org-babel support for interactive terminal ;; Copyright (C) 2009 Benjamin Andresen @@ -36,7 +36,7 @@ ;; M-x org-babel-screen-test RET ;;; Code: -(require 'org-babel) +(require 'ob) (org-babel-add-interpreter "screen") @@ -143,5 +143,5 @@ The terminal should shortly flicker." "WORKS." "DOESN'T work."))))) -(provide 'org-babel-screen) -;;; org-babel-screen.el ends here +(provide 'ob-screen) +;;; ob-screen.el ends here diff --git a/lisp/babel/langs/ob-sh.el b/lisp/babel/langs/ob-sh.el index f2adbe59a..a6a8c0f15 100644 --- a/lisp/babel/langs/ob-sh.el +++ b/lisp/babel/langs/ob-sh.el @@ -1,4 +1,4 @@ -;;; org-babel-sh.el --- org-babel functions for shell evaluation +;;; ob-sh.el --- org-babel functions for shell evaluation ;; Copyright (C) 2009 Eric Schulte @@ -29,7 +29,7 @@ ;; Org-Babel support for evaluating shell source code. ;;; Code: -(require 'org-babel) +(require 'ob) (require 'shell) (org-babel-add-interpreter "sh") @@ -187,5 +187,5 @@ last statement in BODY." (setq string (substring string (match-end 0)))) string) -(provide 'org-babel-sh) -;;; org-babel-sh.el ends here +(provide 'ob-sh) +;;; ob-sh.el ends here diff --git a/lisp/babel/langs/ob-sql.el b/lisp/babel/langs/ob-sql.el index b995e4856..2411a0059 100644 --- a/lisp/babel/langs/ob-sql.el +++ b/lisp/babel/langs/ob-sql.el @@ -1,4 +1,4 @@ -;;; org-babel-sql.el --- org-babel functions for sql evaluation +;;; ob-sql.el --- org-babel functions for sql evaluation ;; Copyright (C) 2009 Eric Schulte @@ -45,7 +45,7 @@ ;; ;;; Code: -(require 'org-babel) +(require 'ob) (org-babel-add-interpreter "sql") @@ -83,5 +83,5 @@ called by `org-babel-execute-src-block'." "Prepare SESSION according to the header arguments specified in PARAMS." (error "sql sessions not yet implemented")) -(provide 'org-babel-sql) -;;; org-babel-sql.el ends here +(provide 'ob-sql) +;;; ob-sql.el ends here diff --git a/lisp/babel/ob-comint.el b/lisp/babel/ob-comint.el index 0189c9a2e..bd74fe274 100644 --- a/lisp/babel/ob-comint.el +++ b/lisp/babel/ob-comint.el @@ -1,4 +1,4 @@ -;;; org-babel-comint.el --- org-babel functions for interaction with comint buffers +;;; ob-comint.el --- org-babel functions for interaction with comint buffers ;; Copyright (C) 2009 Eric Schulte @@ -33,7 +33,7 @@ ;; org-babel at large. ;;; Code: -(require 'org-babel) +(require 'ob) (require 'comint) (defun org-babel-comint-buffer-livep (buffer) @@ -123,5 +123,5 @@ code)." "comint-highlight-prompt")))) (accept-process-output (get-buffer-process buffer))))) -(provide 'org-babel-comint) -;;; org-babel-comint.el ends here +(provide 'ob-comint) +;;; ob-comint.el ends here diff --git a/lisp/babel/ob-exp.el b/lisp/babel/ob-exp.el index cef025dff..e3f371a37 100644 --- a/lisp/babel/ob-exp.el +++ b/lisp/babel/ob-exp.el @@ -1,4 +1,4 @@ -;;; org-babel-exp.el --- Exportation of org-babel source blocks +;;; ob-exp.el --- Exportation of org-babel source blocks ;; Copyright (C) 2009 Eric Schulte, Dan Davison @@ -29,7 +29,7 @@ ;; for more information see the comments in org-babel.el ;;; Code: -(require 'org-babel) +(require 'ob) (require 'org-exp-blocks) (org-export-blocks-add-block '(src org-babel-exp-src-blocks nil)) (add-to-list 'org-export-interblocks '(src org-babel-exp-inline-src-blocks)) @@ -273,5 +273,5 @@ results into the buffer." params `((:results . ,(if silent "silent" "replace"))))) ""))))) -(provide 'org-babel-exp) -;;; org-babel-exp.el ends here +(provide 'ob-exp) +;;; ob-exp.el ends here diff --git a/lisp/babel/ob-keys.el b/lisp/babel/ob-keys.el index 85b7ff864..233c4c5da 100644 --- a/lisp/babel/ob-keys.el +++ b/lisp/babel/ob-keys.el @@ -1,4 +1,4 @@ -;;; org-babel-keys.el --- key bindings for org-babel +;;; ob-keys.el --- key bindings for org-babel ;; Copyright (C) 2009 Eric Schulte @@ -32,7 +32,7 @@ ;; interactive functions and their associated keys. ;;; Code: -(require 'org-babel) +(require 'ob) (defvar org-babel-key-prefix "\C-c\C-v" "The `org-babel-key-prefix' variable holds the key prefix @@ -82,5 +82,5 @@ a-list placed behind the generic `org-babel-key-prefix'.") (define-key org-babel-map (car pair) (cdr pair))) org-babel-key-bindings) -(provide 'org-babel-keys) -;;; org-babel-keys.el ends here +(provide 'ob-keys) +;;; ob-keys.el ends here diff --git a/lisp/babel/ob-lob.el b/lisp/babel/ob-lob.el index 06c310ac3..b763d94f4 100644 --- a/lisp/babel/ob-lob.el +++ b/lisp/babel/ob-lob.el @@ -1,4 +1,4 @@ -;;; org-babel-lob.el --- The Library of Babel: off-the-shelf functions for data analysis and plotting using org-babel +;;; ob-lob.el --- The Library of Babel: off-the-shelf functions for data analysis and plotting using org-babel ;; Copyright (C) 2009 Eric Schulte, Dan Davison @@ -29,9 +29,9 @@ ;; See org-babel.org in the parent directory for more information ;;; Code: -(require 'org-babel) -(require 'org-babel-table) -(require 'org-babel-exp) +(require 'ob) +(require 'ob-table) +(require 'ob-exp) (defvar org-babel-library-of-babel nil "Library of source-code blocks. This is an association list. @@ -108,5 +108,5 @@ the word 'call'." (org-babel-execute-src-block nil (list "emacs-lisp" "results" params nil nil (third info))))) -(provide 'org-babel-lob) -;;; org-babel-lob.el ends here +(provide 'ob-lob) +;;; ob-lob.el ends here diff --git a/lisp/babel/ob-ref.el b/lisp/babel/ob-ref.el index 3a006fb89..46f70e362 100644 --- a/lisp/babel/ob-ref.el +++ b/lisp/babel/ob-ref.el @@ -1,4 +1,4 @@ -;;; org-babel-ref.el --- org-babel functions for referencing external data +;;; ob-ref.el --- org-babel functions for referencing external data ;; Copyright (C) 2009 Eric Schulte, Dan Davison @@ -52,7 +52,7 @@ ;; ;;; Code: -(require 'org-babel) +(require 'ob) (defun org-babel-ref-variables (params) "Takes a parameter alist, and return an alist of variable @@ -217,5 +217,5 @@ types are tables and source blocks." ((looking-at org-bracket-link-regexp) 'file) ((looking-at org-babel-result-regexp) 'results-line))) -(provide 'org-babel-ref) -;;; org-babel-ref.el ends here +(provide 'ob-ref) +;;; ob-ref.el ends here diff --git a/lisp/babel/ob-table.el b/lisp/babel/ob-table.el index dff2c9df8..680b89da3 100644 --- a/lisp/babel/ob-table.el +++ b/lisp/babel/ob-table.el @@ -1,4 +1,4 @@ -;;; org-babel-table.el --- integration for calling org-babel functions from tables +;;; ob-table.el --- integration for calling org-babel functions from tables ;; Copyright (C) 2009 Eric Schulte @@ -53,7 +53,7 @@ ;; #+TBLFM: $2='(sbe 'fibbd (n $1)) ;;; Code: -(require 'org-babel) +(require 'ob) (defun org-babel-table-truncate-at-newline (string) (if (and (stringp string) (string-match "[\n\r]" string)) @@ -101,5 +101,5 @@ example above." (org-babel-merge-params '((:results . "silent")) params)))) "")))) -(provide 'org-babel-table) -;;; org-babel-table.el ends here +(provide 'ob-table) +;;; ob-table.el ends here diff --git a/lisp/babel/ob-tangle.el b/lisp/babel/ob-tangle.el index 30bb8fc92..432346adb 100644 --- a/lisp/babel/ob-tangle.el +++ b/lisp/babel/ob-tangle.el @@ -1,4 +1,4 @@ -;;; org-babel-tangle.el --- Extract source code from org-mode files +;;; ob-tangle.el --- Extract source code from org-mode files ;; Copyright (C) 2009 Eric Schulte @@ -29,7 +29,7 @@ ;; Extract the code from source blocks out into raw source-code files. ;;; Code: -(require 'org-babel) +(require 'ob) (defvar org-babel-tangle-langs nil "List of languages supported by `org-babel-tangle'. The first @@ -259,5 +259,5 @@ form "^," "" (org-babel-chomp body)))) (insert-comment (format "%s ends here" source-name))))) -(provide 'org-babel-tangle) -;;; org-babel-tangle.el ends here +(provide 'ob-tangle) +;;; ob-tangle.el ends here diff --git a/lisp/babel/ob.el b/lisp/babel/ob.el index 34d096ff7..e35d50b52 100644 --- a/lisp/babel/ob.el +++ b/lisp/babel/ob.el @@ -1,4 +1,4 @@ -;;; org-babel.el --- working with code blocks in org-mode +;;; ob.el --- working with code blocks in org-mode ;; Copyright (C) 2009 Eric Schulte, Dan Davison @@ -29,6 +29,7 @@ ;; See org-babel.org in the parent directory for more information ;;; Code: +(eval-when-compile (require 'cl)) (require 'org) ;; add the langs/ directory to the load path @@ -1606,5 +1607,5 @@ specifies the value of ERROR-BUFFER." (delete-file error-file)) exit-status)) -(provide 'org-babel) -;;; org-babel.el ends here +(provide 'ob) +;;; ob.el ends here From 8e0faf35de5fa61a7a3d2f86710e0a3a84dd95b6 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Fri, 11 Jun 2010 17:12:15 -0700 Subject: [PATCH 037/138] ensuring the existence of a complete first sentence in the documentation of each babel function --- lisp/babel/langs/ob-C.el | 15 ++++++++----- lisp/babel/langs/ob-R.el | 9 ++++---- lisp/babel/langs/ob-asymptote.el | 10 +++++---- lisp/babel/langs/ob-clojure.el | 21 ++++++++++++------ lisp/babel/langs/ob-css.el | 3 ++- lisp/babel/langs/ob-ditaa.el | 5 ++++- lisp/babel/langs/ob-dot.el | 4 +++- lisp/babel/langs/ob-emacs-lisp.el | 1 + lisp/babel/langs/ob-gnuplot.el | 8 ++++--- lisp/babel/langs/ob-haskell.el | 7 +++--- lisp/babel/langs/ob-latex.el | 8 +++++-- lisp/babel/langs/ob-matlab.el | 10 +++++---- lisp/babel/langs/ob-ocaml.el | 3 +++ lisp/babel/langs/ob-octave.el | 22 +++++++++--------- lisp/babel/langs/ob-perl.el | 1 + lisp/babel/langs/ob-python.el | 3 +++ lisp/babel/langs/ob-ruby.el | 7 +++--- lisp/babel/langs/ob-sass.el | 4 +++- lisp/babel/langs/ob-screen.el | 7 +++--- lisp/babel/langs/ob-sh.el | 3 +++ lisp/babel/langs/ob-sql.el | 3 ++- lisp/babel/ob-comint.el | 7 +++--- lisp/babel/ob-lob.el | 1 + lisp/babel/ob-ref.el | 2 +- lisp/babel/ob-table.el | 2 ++ lisp/babel/ob.el | 37 ++++++++++++++++++++++--------- 26 files changed, 136 insertions(+), 67 deletions(-) diff --git a/lisp/babel/langs/ob-C.el b/lisp/babel/langs/ob-C.el index ce6cccd2f..f84b1d47f 100644 --- a/lisp/babel/langs/ob-C.el +++ b/lisp/babel/langs/ob-C.el @@ -51,6 +51,8 @@ executable.") (defun org-babel-execute:cpp (body params) + "Execute BODY according to PARAMS. This function calls +`org-babel-execute:C'." (org-babel-execute:C body params)) (defun org-babel-execute:c++ (body params) @@ -74,8 +76,8 @@ header arguments (calls `org-babel-C-expand')." (let ((c-variant 'c)) (org-babel-C-expand body params processed-params))) (defun org-babel-C-execute (body params) - "This should only be called by `org-babel-execute:C' or -`org-babel-execute:c++'." + "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 @@ -157,18 +159,21 @@ it's header arguments." (format "int main() {\n%s\n}\n" body))) (defun org-babel-prep-session:C (session params) - "C is a compiled languages -- no support for sessions" + "This function does nothing as C is a compiled language with no +support for sessions" (error "C is a compiled languages -- no support for sessions")) (defun org-babel-load-session:C (session body params) - "C is a compiled languages -- no support for sessions" + "This function does nothing as C is a compiled language with no +support for sessions" (error "C is a compiled languages -- no support for sessions")) ;; helper functions (defun org-babel-C-var-to-C (pair) "Convert an elisp val into a string of C code specifying a var -of the same value. TODO list support." +of the same value." + ;; TODO list support (let ((var (car pair)) (val (cdr pair))) (when (symbolp val) diff --git a/lisp/babel/langs/ob-R.el b/lisp/babel/langs/ob-R.el index 6014dc137..380d1dea4 100644 --- a/lisp/babel/langs/ob-R.el +++ b/lisp/babel/langs/ob-R.el @@ -42,6 +42,7 @@ "R-specific header arguments.") (defun org-babel-expand-body:R (body params &optional processed-params) + "Expand BODY according to PARAMS, return the expanded body." (let* ((processed-params (or processed-params (org-babel-process-params params))) (vars (mapcar (lambda (i) (cons (car (nth i (second processed-params))) @@ -144,7 +145,7 @@ called by `org-babel-execute-src-block'." (if (stringp session) session (buffer-name)))) (current-buffer)))))) (defun org-babel-R-construct-graphics-device-call (out-file params) - "Construct the call to the graphics device" + "Construct the call to the graphics device." (let ((devices '((:bmp . "bmp") (:jpg . "jpeg") @@ -242,9 +243,9 @@ last statement in BODY, as elisp." (delete nil (mapcar #'extractor (mapcar #'org-babel-chomp raw))) "\n")))))))) (defun org-babel-R-process-value-result (result column-names-p) - "R-specific processing of return value prior to return to org-babel. - -Currently, insert hline if column names in output have been requested." + "R-specific processing of return value prior to return to +org-babel. Insert hline if column names in output have been +requested." (if column-names-p (cons (car result) (cons 'hline (cdr result))) result)) diff --git a/lisp/babel/langs/ob-asymptote.el b/lisp/babel/langs/ob-asymptote.el index a879088a6..9cb902207 100644 --- a/lisp/babel/langs/ob-asymptote.el +++ b/lisp/babel/langs/ob-asymptote.el @@ -56,6 +56,7 @@ "Default arguments to use when evaluating a asymptote source block.") (defun org-babel-expand-body:asymptote (body params &optional processed-params) + "Expand BODY according to PARAMS, return the expanded body." (let ((vars (second (or processed-params (org-babel-process-params params))))) (concat (mapconcat 'org-babel-asymptote-var-to-asymptote vars "\n") @@ -85,6 +86,7 @@ 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." (error "Asymptote does not support sessions")) (defun org-babel-asymptote-var-to-asymptote (pair) @@ -133,10 +135,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) diff --git a/lisp/babel/langs/ob-clojure.el b/lisp/babel/langs/ob-clojure.el index 729046e39..b58d335ad 100644 --- a/lisp/babel/langs/ob-clojure.el +++ b/lisp/babel/langs/ob-clojure.el @@ -70,10 +70,12 @@ ;;taken mostly from clojure-test-mode.el (defun org-babel-clojure-clojure-slime-eval (string &optional handler) + "Evaluate a STRING of clojure code using `slime-eval-async'." (slime-eval-async `(swank:eval-and-grab-output ,string) (or handler #'identity))) (defun org-babel-clojure-slime-eval-sync (string) + "Evaluate a STRING of clojure code using `slime-eval'." (slime-eval `(swank:eval-and-grab-output ,string))) ;;taken from swank-clojure.el @@ -102,7 +104,7 @@ "clojure.main")))))) (defun org-babel-clojure-table-or-string (results) - "If the results look like a table, then convert them into an + "If RESULTS looks 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) @@ -123,7 +125,7 @@ specifying a var of the same value." (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 vars." (let ((vars-forms (mapconcat ;; define any variables (lambda (pair) (format "%s %s" (car pair) (org-babel-clojure-var-to-clojure (cdr pair)))) @@ -155,11 +157,12 @@ specifying a var of the same value." (defvar org-babel-clojure-pending-sessions '()) (defun org-babel-clojure-session-buffer (session) + "Return the buffer associated with SESSION." (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 -then create. Return the initialized session." +then create one. Return the initialized session." (save-window-excursion (let* ((session (if session (if (stringp session) (intern session) @@ -187,12 +190,12 @@ then create. Return the initialized 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" +or nil if \"none\" is specified." (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 setting up the bindings of org-babel session to a slime-clojure repl." (let ((pending-session (pop org-babel-clojure-pending-sessions))) (when pending-session (save-excursion @@ -203,16 +206,19 @@ or nil if \"none\" is specified" (add-hook 'slime-connected-hook 'org-babel-clojure-session-connected-hook) (defun org-babel-clojure-bind-session-to-repl-buffer (session repl-buffer) + "Associate SESSION with REPL-BUFFER." (when (stringp session) (setq session (intern session))) (setq org-babel-clojure-buffers (cons (cons session repl-buffer) (assq-delete-all session org-babel-clojure-buffers)))) (defun org-babel-clojure-repl-buffer-pred () - "Predicate used to test whether the passed in buffer is an active slime-clojure repl buffer" + "Test whether the current buffer is an active slime-clojure +repl buffer." (and (buffer-live-p (current-buffer)) (eq major-mode 'slime-repl-mode))) (defun org-babel-clojure-bind-session-to-repl (session) + "Bind SESSION to a clojure repl." (interactive "sEnter session name: ") (let ((repl-bufs (slime-filter-buffers 'org-babel-clojure-repl-buffer-pred))) (unless repl-bufs (error "No existing slime-clojure repl buffers exist")) @@ -244,7 +250,7 @@ or nil if \"none\" is specified" (insert-file-contents (org-babel-maybe-remote-file tmp-file)) (buffer-string))))))))) (defun org-babel-clojure-evaluate-session (buffer body &optional result-type) - "Evaluate the body in the context of a clojure session" + "Evaluate the body in the context of a clojure session." (let ((raw nil) (results nil)) (save-window-excursion @@ -265,6 +271,7 @@ last statement in BODY, as elisp." (org-babel-clojure-evaluate-external-process buffer body result-type))) (defun org-babel-expand-body:clojure (body params &optional processed-params) + "Expand BODY according to PARAMS, return the expanded body." (org-babel-clojure-build-full-form body (second (or processed-params (org-babel-process-params params))))) diff --git a/lisp/babel/langs/ob-css.el b/lisp/babel/langs/ob-css.el index d8ce8b07c..29618177a 100644 --- a/lisp/babel/langs/ob-css.el +++ b/lisp/babel/langs/ob-css.el @@ -36,7 +36,8 @@ (add-to-list 'org-babel-tangle-langs '("css" "css" nil t)) -(defun org-babel-expand-body:css (body params &optional processed-params) body) +(defun org-babel-expand-body:css (body params &optional processed-params) + "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 diff --git a/lisp/babel/langs/ob-ditaa.el b/lisp/babel/langs/ob-ditaa.el index b3cfcde42..5303a2049 100644 --- a/lisp/babel/langs/ob-ditaa.el +++ b/lisp/babel/langs/ob-ditaa.el @@ -49,7 +49,8 @@ '((:results . "file") (:exports . "results")) "Default arguments to use when evaluating a ditaa source block.") -(defun org-babel-expand-body:ditaa (body params &optional processed-params) body) +(defun org-babel-expand-body:ditaa (body params &optional processed-params) + "Expand BODY according to PARAMS, return the expanded body." body) (defun org-babel-execute:ditaa (body params) "Execute a block of Ditaa code with org-babel. This function is @@ -67,6 +68,8 @@ 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." (error "Ditaa does not support sessions")) (provide 'ob-ditaa) diff --git a/lisp/babel/langs/ob-dot.el b/lisp/babel/langs/ob-dot.el index 2c3e2794d..3e85088dd 100644 --- a/lisp/babel/langs/ob-dot.el +++ b/lisp/babel/langs/ob-dot.el @@ -50,7 +50,8 @@ (defvar org-babel-default-header-args:dot '((:results . "file") (:exports . "results")) "Default arguments to use when evaluating a dot source block.") -(defun org-babel-expand-body:dot (body params &optional processed-params) body) +(defun org-babel-expand-body:dot (body params &optional processed-params) + "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 @@ -67,6 +68,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." (error "Dot does not support sessions")) (provide 'ob-dot) diff --git a/lisp/babel/langs/ob-emacs-lisp.el b/lisp/babel/langs/ob-emacs-lisp.el index 6683bcab1..3b163ebd6 100644 --- a/lisp/babel/langs/ob-emacs-lisp.el +++ b/lisp/babel/langs/ob-emacs-lisp.el @@ -40,6 +40,7 @@ "Default arguments to use when evaluating an emacs-lisp source block.") (defun org-babel-expand-body:emacs-lisp (body params &optional processed-params) + "Expand BODY according to PARAMS, return the expanded body." (let* ((processed-params (or processed-params (org-babel-process-params params))) (vars (second processed-params)) (processed-params (org-babel-process-params params)) diff --git a/lisp/babel/langs/ob-gnuplot.el b/lisp/babel/langs/ob-gnuplot.el index ef45eebe3..380be7924 100644 --- a/lisp/babel/langs/ob-gnuplot.el +++ b/lisp/babel/langs/ob-gnuplot.el @@ -56,8 +56,9 @@ (defun org-babel-gnuplot-process-vars (params) "Extract variables from PARAMS and process the variables -dumping all vectors into files returning an association list of -variable names and the value to be used in the gnuplot code." +dumping all vectors into files and returning an association list +of variable names and the related value to be used in the gnuplot +code." (mapcar (lambda (pair) (cons @@ -69,6 +70,7 @@ variable names and the value to be used in the gnuplot code." (org-babel-ref-variables params))) (defun org-babel-expand-body:gnuplot (body params &optional processed-params) + "Expand BODY according to PARAMS, return the expanded body." (save-window-excursion (let* ((vars (org-babel-gnuplot-process-vars params)) (out-file (cdr (assoc :file params))) @@ -176,7 +178,7 @@ called by `org-babel-execute-src-block'." (defun org-babel-gnuplot-initiate-session (&optional session params) "If there is not a current inferior-process-buffer in SESSION -then create. Return the initialized session. The current +then create one. Return the initialized session. The current `gnuplot-mode' doesn't provide support for multiple sessions." (unless (string= session "none") (save-window-excursion (gnuplot-send-string-to-gnuplot "" "line") diff --git a/lisp/babel/langs/ob-haskell.el b/lisp/babel/langs/ob-haskell.el index edd27f514..3929c7cc1 100644 --- a/lisp/babel/langs/ob-haskell.el +++ b/lisp/babel/langs/ob-haskell.el @@ -55,6 +55,7 @@ (defvar org-babel-haskell-eoe "\"org-babel-haskell-eoe\"") (defun org-babel-expand-body:haskell (body params &optional processed-params) + "Expand BODY according to PARAMS, return the expanded body." (let (vars (second (or processed-params (org-babel-process-params params)))) (concat (mapconcat @@ -87,14 +88,14 @@ (org-babel-pick-name (nth 5 processed-params) (cdr (assoc :rownames params)))))) (defun org-babel-haskell-read-string (string) - "Strip \\\"s from around haskell string" + "Strip \\\"s from around a haskell string." (if (string-match "^\"\\([^\000]+\\)\"$" string) (match-string 1 string) string)) (defun org-babel-haskell-initiate-session (&optional session params) "If there is not a current inferior-process-buffer in SESSION -then create. Return the initialized session." +then create one. Return the initialized session." ;; TODO: make it possible to have multiple sessions (run-haskell) (current-buffer)) @@ -141,7 +142,7 @@ Emacs-lisp table, otherwise return the results as a string." results))) (defun org-babel-haskell-export-to-lhs (&optional arg) - "Export to a .lhs with all haskell code blocks escaped + "Export to a .lhs file with all haskell code blocks escaped appropriately. 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 diff --git a/lisp/babel/langs/ob-latex.el b/lisp/babel/langs/ob-latex.el index ebfae9c9b..950ed9a52 100644 --- a/lisp/babel/langs/ob-latex.el +++ b/lisp/babel/langs/ob-latex.el @@ -44,6 +44,7 @@ "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." (mapc (lambda (pair) ;; replace variables (setq body (replace-regexp-in-string @@ -83,7 +84,8 @@ called by `org-babel-execute-src-block'." body)) (defun org-babel-latex-body-to-tex-file (tex-file body &optional height width) - "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 @@ -101,7 +103,8 @@ called by `org-babel-execute-src-block'." (org-export-latex-fix-inputenc))) (defun org-babel-latex-tex-to-pdf (tex-file) - "Extracted from `org-export-as-pdf' in org-latex.el." + "Generate a pdf 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)) @@ -134,6 +137,7 @@ called by `org-babel-execute-src-block'." pdffile))) (defun org-babel-prep-session:latex (session params) + "Create a session named SESSION according to PARAMS." (error "Latex does not support sessions")) (provide 'ob-latex) diff --git a/lisp/babel/langs/ob-matlab.el b/lisp/babel/langs/ob-matlab.el index 46dec3a57..806965fe7 100644 --- a/lisp/babel/langs/ob-matlab.el +++ b/lisp/babel/langs/ob-matlab.el @@ -48,7 +48,8 @@ (defvar org-babel-matlab-shell-command "matlab -nosplash" "Shell command to use to run matlab as an external process.") -(defun org-babel-expand-body:matlab (body params &optional processed-params) body) +(defun org-babel-expand-body:matlab (body params &optional processed-params) + "Expand BODY according to PARAMS, return the expanded body." body) (defvar org-babel-matlab-with-emacs-link nil "If non-nil use matlab-shell-run-region for session @@ -68,12 +69,13 @@ delete('%s') (org-babel-execute:octave body params 'matlab)) (defun org-babel-prep-session:matlab (session params) + "Prepare SESSION according to PARAMS." (org-babel-prep-session:octave session params 'matlab)) (defun org-babel-matlab-initiate-session (&optional session params) - "Create 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." (org-babel-octave-initiate-session session params 'matlab)) (provide 'ob-matlab) diff --git a/lisp/babel/langs/ob-ocaml.el b/lisp/babel/langs/ob-ocaml.el index 65aa56162..a6c70e4ff 100644 --- a/lisp/babel/langs/ob-ocaml.el +++ b/lisp/babel/langs/ob-ocaml.el @@ -49,6 +49,7 @@ (defvar org-babel-ocaml-eoe-output "org-babel-ocaml-eoe") (defun org-babel-expand-body:ocaml (body params &optional processed-params) + "Expand BODY according to PARAMS, return the expanded body." (let ((vars (second (or processed-params (org-babel-process-params params))))) (concat (mapconcat @@ -83,6 +84,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." (let ((regexp "%s = \\(.+\\)$")) (cond ((string-match (format regexp "string") output) diff --git a/lisp/babel/langs/ob-octave.el b/lisp/babel/langs/ob-octave.el index e29fb0891..1ca805d3e 100644 --- a/lisp/babel/langs/ob-octave.el +++ b/lisp/babel/langs/ob-octave.el @@ -42,6 +42,7 @@ "Shell command to use to run octave as an external process.") (defun org-babel-expand-body:octave (body params &optional processed-params) + "Expand BODY according to PARAMS, return the expanded body." (let ((vars (second (or processed-params (org-babel-process-params params))))) (concat ;; prepend code to define all arguments passed to the code block @@ -97,9 +98,9 @@ specifying a variable of the same value." session)) (defun org-babel-octave-initiate-session (&optional session params matlabp) - "Create 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." (unless (string= session "none") (let ((session (or session (if matlabp "*Inferior Matlab*" "*Inferior Octave*")))) (if (org-babel-comint-buffer-livep session) session @@ -120,15 +121,16 @@ end") (defvar org-babel-octave-eoe-output "ans = org_babel_eoe") (defun org-babel-octave-evaluate (session body result-type lang) - "Pass BODY to the octave process. -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))) (defun org-babel-octave-evaluate-external-process (body result-type matlabp) + "Evaluate BODY in an external octave process." (let ((cmd (if matlabp org-babel-matlab-shell-command org-babel-octave-shell-command))) (save-excursion (case result-type @@ -149,6 +151,7 @@ value of the last statement in BODY, as elisp." (org-babel-octave-import-elisp-from-file (org-babel-maybe-remote-file tmp-file)))))))) (defun org-babel-octave-evaluate-session (session body result-type &optional matlabp) + "Evaluate BODY in SESSION." (let* ((tmp-file (make-temp-file "org-babel-results-")) (wait-file (make-temp-file "org-babel-matlab-emacs-link-wait-signal-")) (full-body @@ -196,9 +199,8 @@ value of the last statement in BODY, as elisp." (mapconcat #'identity (reverse results) "\n")))))) (defun org-babel-octave-import-elisp-from-file (file-name) - "Import data written to file by octave. -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) diff --git a/lisp/babel/langs/ob-perl.el b/lisp/babel/langs/ob-perl.el index 4baed2ea3..7104fbd72 100644 --- a/lisp/babel/langs/ob-perl.el +++ b/lisp/babel/langs/ob-perl.el @@ -36,6 +36,7 @@ (add-to-list 'org-babel-tangle-langs '("perl" "pl" "#!/usr/bin/env perl")) (defun org-babel-expand-body:perl (body params &optional processed-params) + "Expand BODY according to PARAMS, return the expanded body." (let ((vars (second (or processed-params (org-babel-process-params params))))) (concat (mapconcat ;; define any variables diff --git a/lisp/babel/langs/ob-python.el b/lisp/babel/langs/ob-python.el index 250cfa2fd..d35d88624 100644 --- a/lisp/babel/langs/ob-python.el +++ b/lisp/babel/langs/ob-python.el @@ -39,6 +39,7 @@ (add-to-list 'org-babel-tangle-langs '("python" "py" "#!/usr/bin/env python")) (defun org-babel-expand-body:python (body params &optional processed-params) + "Expand BODY according to PARAMS, return the expanded body." (concat (mapconcat ;; define any variables (lambda (pair) @@ -117,6 +118,7 @@ Emacs-lisp table, otherwise return the results as a string." (defvar org-babel-python-buffers '(:default . nil)) (defun org-babel-python-session-buffer (session) + "Return the buffer associated with SESSION." (cdr (assoc session org-babel-python-buffers))) (defun org-babel-python-initiate-session-by-key (&optional session) @@ -145,6 +147,7 @@ then create. Return the initialized session." session))) (defun org-babel-python-initiate-session (&optional session params) + "Create a session named SESSION according to PARAMS." (unless (string= session "none") (org-babel-python-session-buffer (org-babel-python-initiate-session-by-key session)))) diff --git a/lisp/babel/langs/ob-ruby.el b/lisp/babel/langs/ob-ruby.el index bc6a23fc3..1a6394e5f 100644 --- a/lisp/babel/langs/ob-ruby.el +++ b/lisp/babel/langs/ob-ruby.el @@ -47,6 +47,7 @@ (add-to-list 'org-babel-tangle-langs '("ruby" "rb" "#!/usr/bin/env ruby")) (defun org-babel-expand-body:ruby (body params &optional processed-params) + "Expand BODY according to PARAMS, return the expanded body." (let ((vars (second (or processed-params (org-babel-process-params params))))) (concat (mapconcat ;; define any variables @@ -113,7 +114,7 @@ specifying a var of the same value." (format "%S" var))) (defun org-babel-ruby-table-or-string (results) - "If the results look like a table, then convert them into an + "If RESULTS look like a table, then convert them into an Emacs-lisp table, otherwise return the results as a string." (message "converting %S" results) (org-babel-read @@ -129,7 +130,7 @@ Emacs-lisp table, otherwise return the results as a string." (defun org-babel-ruby-initiate-session (&optional session params) "If there is not a current inferior-process-buffer in SESSION -then create. Return the initialized session." +then create one. Return the initialized session." (unless (string= session "none") (let ((session-buffer (save-window-excursion (run-ruby nil session) (current-buffer)))) @@ -227,7 +228,7 @@ last statement in BODY, as elisp." (org-babel-ruby-table-or-string (car results)))))))) (defun org-babel-ruby-read-string (string) - "Strip \\\"s from around ruby string" + "Strip \\\"s from around a ruby string." (if (string-match "^\"\\([^\000]+\\)\"$" string) (match-string 1 string) string)) diff --git a/lisp/babel/langs/ob-sass.el b/lisp/babel/langs/ob-sass.el index f42f0c268..a8114fa49 100644 --- a/lisp/babel/langs/ob-sass.el +++ b/lisp/babel/langs/ob-sass.el @@ -48,7 +48,8 @@ (add-to-list 'org-babel-tangle-langs '("sass" "sass")) -(defun org-babel-expand-body:sass (body params &optional processed-params) body) +(defun org-babel-expand-body:sass (body params &optional processed-params) + "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 @@ -65,6 +66,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." (error "Sass does not support sessions")) (provide 'ob-sass) diff --git a/lisp/babel/langs/ob-screen.el b/lisp/babel/langs/ob-screen.el index 079fc1ae5..dadb39a86 100644 --- a/lisp/babel/langs/ob-screen.el +++ b/lisp/babel/langs/ob-screen.el @@ -50,7 +50,8 @@ In case you want to use a different screen than one selected by your $PATH") '((:results . "silent") (:session . "default") (:cmd . "sh") (:terminal . "xterm")) "Default arguments to use when running screen source blocks.") -(defun org-babel-expand-body:screen (body params &optional processed-params) body) +(defun org-babel-expand-body:screen (body params &optional processed-params) + "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. @@ -121,8 +122,8 @@ In case you want to use a different screen than one selected by your $PATH") tmpfile)) (defun org-babel-screen-test () - "Command that tests 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))) diff --git a/lisp/babel/langs/ob-sh.el b/lisp/babel/langs/ob-sh.el index a6a8c0f15..5c6a7ddc6 100644 --- a/lisp/babel/langs/ob-sh.el +++ b/lisp/babel/langs/ob-sh.el @@ -41,6 +41,7 @@ `shell-command-on-region'") (defun org-babel-expand-body:sh (body params &optional processed-params) + "Expand BODY according to PARAMS, return the expanded body." (let ((vars (second (or processed-params (org-babel-process-params params)))) (sep (cdr (assoc :separator params)))) (concat @@ -120,6 +121,7 @@ Emacs-lisp table, otherwise return the results as a string." results))) (defun org-babel-sh-initiate-session (&optional session params) + "Initiate a session named SESSION according to PARAMS." (unless (string= session "none") (save-window-excursion (or (org-babel-comint-buffer-livep session) @@ -183,6 +185,7 @@ last statement in BODY." ""))))) (defun org-babel-sh-strip-weird-long-prompt (string) + "Remove prompt cruft from a string of shell output." (while (string-match "^% +[\r\n$]+ *" string) (setq string (substring string (match-end 0)))) string) diff --git a/lisp/babel/langs/ob-sql.el b/lisp/babel/langs/ob-sql.el index 2411a0059..cdbbbc5df 100644 --- a/lisp/babel/langs/ob-sql.el +++ b/lisp/babel/langs/ob-sql.el @@ -51,7 +51,8 @@ (add-to-list 'org-babel-tangle-langs '("sql" "sql")) -(defun org-babel-expand-body:sql (body params &optional processed-params) body) +(defun org-babel-expand-body:sql (body params &optional processed-params) + "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 diff --git a/lisp/babel/ob-comint.el b/lisp/babel/ob-comint.el index bd74fe274..4070c529a 100644 --- a/lisp/babel/ob-comint.el +++ b/lisp/babel/ob-comint.el @@ -37,6 +37,7 @@ (require 'comint) (defun org-babel-comint-buffer-livep (buffer) + "Check if BUFFER is a comint buffer with a live process." (let ((buffer (if buffer (get-buffer buffer)))) (and buffer (buffer-live-p buffer) (get-buffer-process buffer) buffer))) @@ -111,9 +112,9 @@ during execution of body." (org-babel-comint-wait-for-output buffer))) (defun org-babel-comint-wait-for-output (buffer) - "Wait until output arrives. 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) diff --git a/lisp/babel/ob-lob.el b/lisp/babel/ob-lob.el index b763d94f4..5e1f64f50 100644 --- a/lisp/babel/ob-lob.el +++ b/lisp/babel/ob-lob.el @@ -98,6 +98,7 @@ the word 'call'." (list (length (match-string 1)))))))) (defun org-babel-lob-execute (info) + "Execute the lob call specified by INFO." (let ((params (org-babel-merge-params org-babel-default-header-args (org-babel-params-from-buffer) diff --git a/lisp/babel/ob-ref.el b/lisp/babel/ob-ref.el index 46f70e362..8de7020fd 100644 --- a/lisp/babel/ob-ref.el +++ b/lisp/babel/ob-ref.el @@ -94,7 +94,7 @@ return nil." out))) (defun org-babel-ref-resolve-reference (ref &optional params) - "Resolve the reference and return its value" + "Resolve the reference REF and return its value." (save-excursion (let ((case-fold-search t) type args new-refere new-referent result lob-info split-file split-ref diff --git a/lisp/babel/ob-table.el b/lisp/babel/ob-table.el index 680b89da3..d997043d4 100644 --- a/lisp/babel/ob-table.el +++ b/lisp/babel/ob-table.el @@ -56,6 +56,8 @@ (require 'ob) (defun org-babel-table-truncate-at-newline (string) + "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)) diff --git a/lisp/babel/ob.el b/lisp/babel/ob.el index e35d50b52..dae8f6ebe 100644 --- a/lisp/babel/ob.el +++ b/lisp/babel/ob.el @@ -152,11 +152,13 @@ can not be resolved.") (defvar org-babel-after-execute-hook nil "Hook for functions to be called after `org-babel-execute-src-block'") (defun org-babel-named-src-block-regexp-for-name (name) - "Regexp used to match named src block." + "This generates a regexp used to match a src block named NAME." (concat org-babel-source-name-regexp (regexp-quote name) "[ \t\n]*" (substring org-babel-src-block-regexp 1))) (defun org-babel-set-interpreters (var value) + "Update the regular expressions used to match block and inline +code." (set-default var value) (setq org-babel-src-block-regexp @@ -453,6 +455,7 @@ added to the header-arguments-alist." nil)))) ;; indicate that no source block was found (defun org-babel-sha1-hash (&optional info) + "Generate an sha1 hash based on the value of info." (interactive) (let* ((info (or info (org-babel-get-src-block-info))) (hash (sha1 (format "%s-%s" (mapconcat (lambda (arg) (format "%S" arg)) @@ -462,6 +465,8 @@ added to the header-arguments-alist." hash)) (defun org-babel-result-hash (&optional info) + "Return the in-buffer hash associated with the results +specified in INFO." (org-babel-where-is-src-block-result nil info) (org-babel-clean-text-properties (match-string 3))) @@ -507,6 +512,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 +portions of results lines." (add-to-invisibility-spec '(org-babel-hide-result . t))) (add-hook 'org-mode-hook 'org-babel-result-hide-spec) @@ -635,6 +642,8 @@ may be specified at the top of the current buffer." (org-match-string-no-properties 2)))))))) (defun org-babel-parse-src-block-match () + "Parse the match data resulting 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))) @@ -660,6 +669,8 @@ 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'." (let* ((lang (org-babel-clean-text-properties (match-string 2))) (lang-headers (intern (concat "org-babel-default-header-args:" lang)))) (list lang @@ -714,17 +725,17 @@ 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 colnames, and the `cdr' of which contains a list of the - column names" + "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 (second table)) (cons (cddr table) (car table)) (cons (cdr table) (car table)))) (defun org-babel-get-rownames (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" +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))) (let* ((width (apply 'max (mapcar (lambda (el) (if (listp el) (length el) 0)) table))) (table (trans (mapcar (lambda (row) @@ -1308,6 +1319,8 @@ block but are passed literally to the \"example-block\"." new-body)) (defun org-babel-error-notify (exit-code stderr) + "Open a buffer containing information from STDERR with a +message about the value of EXIT-CODE." (message (format "Shell command exited with code %d" exit-code)) (let ((buf (get-buffer-create "*Org-Babel Error Output*"))) (with-current-buffer buf @@ -1341,7 +1354,7 @@ This is taken almost directly from `org-read-prop'." cell)) (defun org-babel-number-p (string) - "Return t if STRING represents a number" + "Return t if STRING represents a number." (if (and (string-match "^-?[0-9]*\\.?[0-9]*$" string) (= (length (substring string (match-beginning 0) (match-end 0))) @@ -1378,6 +1391,7 @@ the table is trivial, then return it as a scalar." cell))) (defun org-babel-reverse-string (string) + "Return the reverse of STRING." (apply 'string (reverse (string-to-list string)))) (defun org-babel-chomp (string &optional regexp) @@ -1391,15 +1405,16 @@ 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 of the 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)) regexp)) (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) @@ -1415,6 +1430,8 @@ Fixes a bug in `tramp-handle-call-process-region'." 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 +the remote connection." (if (file-remote-p default-directory) (let* ((vec (tramp-dissect-file-name default-directory)) (user (tramp-file-name-user vec)) From 79ae257d98247e32cd296e6d0dbb9ce94b645200 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Fri, 11 Jun 2010 17:38:51 -0700 Subject: [PATCH 038/138] updated makefile to compile all babel files --- Makefile | 146 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 89 insertions(+), 57 deletions(-) diff --git a/Makefile b/Makefile index 12759cda8..37aedfe93 100644 --- a/Makefile +++ b/Makefile @@ -28,8 +28,11 @@ infodir = $(prefix)/share/info # Using emacs in batch mode. -BATCH=$(EMACS) -batch -q -no-site-file -eval \ - "(setq load-path (cons (expand-file-name \"./lisp/\") (cons \"$(lispdir)\" load-path)))" +BATCH=$(EMACS) -batch -q -no-site-file -eval \ + "(setq load-path (cons (expand-file-name\ + \"babel\"\ + (expand-file-name \"./lisp/\"))\ + (cons (expand-file-name \"./lisp/\") (cons \"$(lispdir)\" load-path))))" # Specify the byte-compiler for compiling org-mode files ELC= $(BATCH) -f batch-byte-compile @@ -58,61 +61,90 @@ INSTALL_INFO=install-info ##---------------------------------------------------------------------- # The following variables need to be defined by the maintainer -LISPF = org.el \ - org-agenda.el \ - org-ascii.el \ - org-attach.el \ - org-archive.el \ - org-bbdb.el \ - org-beamer.el \ - org-bibtex.el \ - org-clock.el \ - org-colview.el \ - org-colview-xemacs.el \ - org-compat.el \ - org-crypt.el \ - org-ctags.el \ - org-datetree.el \ - org-docview.el \ - org-entities.el \ - org-exp.el \ - org-exp-blocks.el \ - org-docbook.el \ - org-faces.el \ - org-feed.el \ - org-footnote.el \ - org-freemind.el \ - org-gnus.el \ - org-habit.el \ - org-html.el \ - org-icalendar.el \ - org-id.el \ - org-indent.el \ - org-info.el \ - org-inlinetask.el \ - org-jsinfo.el \ - org-irc.el \ - org-latex.el \ - org-list.el \ - org-mac-message.el \ - org-macs.el \ - org-mew.el \ - org-mhe.el \ - org-mobile.el \ - org-mouse.el \ - org-publish.el \ - org-plot.el \ - org-protocol.el \ - org-remember.el \ - org-rmail.el \ - org-src.el \ - org-table.el \ - org-taskjuggler.el \ - org-timer.el \ - org-vm.el \ - org-w3m.el \ - org-wl.el \ - org-xoxo.el +LISPF = org.el \ + org-agenda.el \ + org-ascii.el \ + org-attach.el \ + org-archive.el \ + org-bbdb.el \ + org-beamer.el \ + org-bibtex.el \ + org-clock.el \ + org-colview.el \ + org-colview-xemacs.el \ + org-compat.el \ + org-crypt.el \ + org-ctags.el \ + org-datetree.el \ + org-docview.el \ + org-entities.el \ + org-exp.el \ + org-exp-blocks.el \ + org-docbook.el \ + org-faces.el \ + org-feed.el \ + org-footnote.el \ + org-freemind.el \ + org-gnus.el \ + org-habit.el \ + org-html.el \ + org-icalendar.el \ + org-id.el \ + org-indent.el \ + org-info.el \ + org-inlinetask.el \ + org-jsinfo.el \ + org-irc.el \ + org-latex.el \ + org-list.el \ + org-mac-message.el \ + org-macs.el \ + org-mew.el \ + org-mhe.el \ + org-mobile.el \ + org-mouse.el \ + org-publish.el \ + org-plot.el \ + org-protocol.el \ + org-remember.el \ + org-rmail.el \ + org-src.el \ + org-table.el \ + org-taskjuggler.el \ + org-timer.el \ + org-vm.el \ + org-w3m.el \ + org-wl.el \ + org-xoxo.el \ + babel/ob-comint.el \ + babel/ob.el \ + babel/ob-exp.el \ + babel/ob-keys.el \ + babel/ob-lob.el \ + babel/ob-ref.el \ + babel/ob-table.el \ + babel/ob-tangle.el \ + babel/langs/ob-asymptote.el \ + babel/langs/ob-C.el \ + babel/langs/ob-clojure.el \ + babel/langs/ob-css.el \ + babel/langs/ob-ditaa.el \ + babel/langs/ob-dot.el \ + babel/langs/ob-emacs-lisp.el \ + babel/langs/ob-gnuplot.el \ + babel/langs/ob-haskell.el \ + babel/langs/ob-latex.el \ + babel/langs/ob-matlab.el \ + babel/langs/ob-ocaml.el \ + babel/langs/ob-octave.el \ + babel/langs/ob-perl.el \ + babel/langs/ob-python.el \ + babel/langs/ob-R.el \ + babel/langs/ob-ruby.el \ + babel/langs/ob-sass.el \ + babel/langs/ob-screen.el \ + babel/langs/ob-sh.el \ + babel/langs/ob-sql.el LISPFILES0 = $(LISPF:%=lisp/%) LISPFILES = $(LISPFILES0) lisp/org-install.el From 6be47552ea8b6bb6e0c18ae0c7050c18568020f8 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Sat, 12 Jun 2010 15:57:38 -0700 Subject: [PATCH 039/138] babel: `org-babel-comint-with-output' no longer assumes `full-body' variable * lisp/babel/ob-comint.el (org-babel-comint-with-output): Fixed egregious oversight in which we were assuming that the `full-body' variable would be in scope at the time of macro execution. Thanks to the compiler for finding this bug. * lisp/babel/langs/ob-R.el (org-babel-R-evaluate): now using the fixed `org-babel-comint-with-output' macro * lisp/babel/langs/ob-haskell.el (org-babel-execute:haskell): now using the fixed `org-babel-comint-with-output' macro * lisp/babel/langs/ob-ocaml.el (org-babel-execute:ocaml): now using the fixed `org-babel-comint-with-output' macro * lisp/babel/langs/ob-octave.el (org-babel-octave-evaluate-session): now using the fixed `org-babel-comint-with-output' macro * lisp/babel/langs/ob-python.el (org-babel-python-evaluate): now using the fixed `org-babel-comint-with-output' macro * lisp/babel/langs/ob-ruby.el (org-babel-ruby-evaluate): now using the fixed `org-babel-comint-with-output' macro * lisp/babel/langs/ob-sh.el (org-babel-sh-evaluate): now using the fixed `org-babel-comint-with-output' macro --- lisp/babel/langs/ob-R.el | 5 +- lisp/babel/langs/ob-haskell.el | 3 +- lisp/babel/langs/ob-ocaml.el | 3 +- lisp/babel/langs/ob-octave.el | 8 ++- lisp/babel/langs/ob-python.el | 3 +- lisp/babel/langs/ob-ruby.el | 2 +- lisp/babel/langs/ob-sh.el | 2 +- lisp/babel/ob-comint.el | 106 ++++++++++++++++++--------------- 8 files changed, 75 insertions(+), 57 deletions(-) diff --git a/lisp/babel/langs/ob-R.el b/lisp/babel/langs/ob-R.el index 380d1dea4..995e1015a 100644 --- a/lisp/babel/langs/ob-R.el +++ b/lisp/babel/langs/ob-R.el @@ -212,8 +212,9 @@ last statement in BODY, as elisp." org-babel-R-eoe-indicator) "\n")) (output (mapconcat #'org-babel-chomp (list body org-babel-R-eoe-indicator) "\n")))) - (raw (org-babel-comint-with-output session org-babel-R-eoe-output nil - (insert full-body) (inferior-ess-send-input))) + (raw + (org-babel-comint-with-output (list session org-babel-R-eoe-output) + (insert full-body) (inferior-ess-send-input))) (comint-prompt-regexp (concat "^\\(" inferior-ess-primary-prompt diff --git a/lisp/babel/langs/ob-haskell.el b/lisp/babel/langs/ob-haskell.el index 3929c7cc1..c9525a0a0 100644 --- a/lisp/babel/langs/ob-haskell.el +++ b/lisp/babel/langs/ob-haskell.el @@ -71,7 +71,8 @@ (result-type (fourth processed-params)) (full-body (org-babel-expand-body:haskell body params processed-params)) (session (org-babel-prep-session:haskell session params)) - (raw (org-babel-comint-with-output session org-babel-haskell-eoe t + (raw (org-babel-comint-with-output + (list session org-babel-haskell-eoe t full-body) (insert (org-babel-trim full-body)) (comint-send-input nil t) (insert org-babel-haskell-eoe) diff --git a/lisp/babel/langs/ob-ocaml.el b/lisp/babel/langs/ob-ocaml.el index a6c70e4ff..e84fdaf9a 100644 --- a/lisp/babel/langs/ob-ocaml.el +++ b/lisp/babel/langs/ob-ocaml.el @@ -63,7 +63,8 @@ (vars (second processed-params)) (full-body (org-babel-expand-body:ocaml body params processed-params)) (session (org-babel-prep-session:ocaml session params)) - (raw (org-babel-comint-with-output session org-babel-ocaml-eoe-output t + (raw (org-babel-comint-with-output + (list session org-babel-ocaml-eoe-output t full-body) (insert (concat (org-babel-chomp full-body) " ;;")) (comint-send-input nil t) (insert org-babel-ocaml-eoe-indicator) diff --git a/lisp/babel/langs/ob-octave.el b/lisp/babel/langs/ob-octave.el index 1ca805d3e..732681f39 100644 --- a/lisp/babel/langs/ob-octave.el +++ b/lisp/babel/langs/ob-octave.el @@ -181,8 +181,12 @@ statement in BODY, as elisp." ;; make *matlab* buffer contents easily ;; available, so :results output currently ;; won't work - (org-babel-comint-with-output session - (if matlabp org-babel-octave-eoe-indicator org-babel-octave-eoe-output) t + (org-babel-comint-with-output + (list session + (if matlabp + org-babel-octave-eoe-indicator + org-babel-octave-eoe-output) + t full-body) (insert full-body) (comint-send-input nil t)))) results) (case result-type (value diff --git a/lisp/babel/langs/ob-python.el b/lisp/babel/langs/ob-python.el index d35d88624..de0b1e3e2 100644 --- a/lisp/babel/langs/ob-python.el +++ b/lisp/babel/langs/ob-python.el @@ -217,7 +217,8 @@ last statement in BODY, as elisp." (org-babel-python-table-or-string raw))))))) ;; comint session evaluation (org-babel-comint-in-buffer buffer - (let* ((raw (org-babel-comint-with-output buffer org-babel-python-eoe-indicator t + (let* ((raw (org-babel-comint-with-output + (list buffer org-babel-python-eoe-indicator t full-body) ;; for some reason python is fussy, and likes enters after every input (let ((comint-process-echoes nil)) (mapc (lambda (statement) (insert statement) (comint-send-input)) diff --git a/lisp/babel/langs/ob-ruby.el b/lisp/babel/langs/ob-ruby.el index 1a6394e5f..f4ff947b7 100644 --- a/lisp/babel/langs/ob-ruby.el +++ b/lisp/babel/langs/ob-ruby.el @@ -214,7 +214,7 @@ last statement in BODY, as elisp." org-babel-ruby-last-value-eval) org-babel-ruby-eoe-indicator) "\n")) (raw (org-babel-comint-with-output - buffer org-babel-ruby-eoe-indicator t + (list buffer org-babel-ruby-eoe-indicator t full-body) (insert full-body) (comint-send-input nil t))) (results (cdr (member org-babel-ruby-eoe-indicator diff --git a/lisp/babel/langs/ob-sh.el b/lisp/babel/langs/ob-sh.el index 5c6a7ddc6..e63a7d35b 100644 --- a/lisp/babel/langs/ob-sh.el +++ b/lisp/babel/langs/ob-sh.el @@ -166,7 +166,7 @@ last statement in BODY." (mapcar #'org-babel-sh-strip-weird-long-prompt (mapcar #'org-babel-trim (org-babel-comint-with-output - session org-babel-sh-eoe-output t + (list session org-babel-sh-eoe-output t full-body) (mapc (lambda (line) (insert line) (comint-send-input)) (strip-empty (split-string body "\n"))) (insert org-babel-sh-eoe-indicator) diff --git a/lisp/babel/ob-comint.el b/lisp/babel/ob-comint.el index 4070c529a..af6183a11 100644 --- a/lisp/babel/ob-comint.el +++ b/lisp/babel/ob-comint.el @@ -53,55 +53,65 @@ body inside the protection of `save-window-excursion' and (set-buffer ,buffer) ,@body))) -(defmacro org-babel-comint-with-output - (buffer eoe-indicator remove-echo &rest 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. This ensures that the -filter is removed in case of an error or user `keyboard-quit' -during execution of body." - (declare (indent 3)) - `(org-babel-comint-in-buffer ,buffer - (let ((string-buffer "") dangling-text) - (flet ((my-filt (text) (setq string-buffer (concat string-buffer text)))) - ;; setup filter - (add-hook 'comint-output-filter-functions 'my-filt) - (unwind-protect - (progn - ;; got located, and save dangling text - (goto-char (process-mark (get-buffer-process (current-buffer)))) - (let ((start (point)) - (end (point-max))) - (setq dangling-text (buffer-substring start end)) - (delete-region start end)) - ;; pass FULL-BODY to process - ,@body - ;; wait for end-of-evaluation indicator - (while (progn - (goto-char comint-last-input-end) - (not (save-excursion - (and (re-search-forward - comint-prompt-regexp nil t) - (re-search-forward - (regexp-quote ,eoe-indicator) nil t))))) - (accept-process-output (get-buffer-process (current-buffer))) - ;; thought the following this would allow async - ;; background running, but I was wrong... - ;; (run-with-timer .5 .5 'accept-process-output - ;; (get-buffer-process (current-buffer))) - ) - ;; replace cut dangling text - (goto-char (process-mark (get-buffer-process (current-buffer)))) - (insert dangling-text)) - ;; remove filter - (remove-hook 'comint-output-filter-functions 'my-filt))) - ;; remove echo'd FULL-BODY from input - (if (and ,remove-echo - (string-match - (replace-regexp-in-string - "\n" "[\r\n]+" (regexp-quote ,full-body)) - string-buffer)) - (setq raw (substring string-buffer (match-end 0)))) - (split-string string-buffer comint-prompt-regexp)))) +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) + +This macro ensures that the filter is removed in case of an error +or user `keyboard-quit' during execution of body." + (declare (indent 1)) + (let ((buffer (car meta)) + (eoe-indicator (cadr meta)) + (remove-echo (caddr meta)) + (full-body (cadddr meta))) + `(org-babel-comint-in-buffer ,buffer + (let ((string-buffer "") dangling-text) + (flet ((my-filt (text) + (setq string-buffer (concat string-buffer text)))) + ;; setup filter + (add-hook 'comint-output-filter-functions 'my-filt) + (unwind-protect + (progn + ;; got located, and save dangling text + (goto-char (process-mark (get-buffer-process (current-buffer)))) + (let ((start (point)) + (end (point-max))) + (setq dangling-text (buffer-substring start end)) + (delete-region start end)) + ;; pass FULL-BODY to process + ,@body + ;; wait for end-of-evaluation indicator + (while (progn + (goto-char comint-last-input-end) + (not (save-excursion + (and (re-search-forward + comint-prompt-regexp nil t) + (re-search-forward + (regexp-quote ,eoe-indicator) nil t))))) + (accept-process-output (get-buffer-process (current-buffer))) + ;; thought the following this would allow async + ;; background running, but I was wrong... + ;; (run-with-timer .5 .5 'accept-process-output + ;; (get-buffer-process (current-buffer))) + ) + ;; replace cut dangling text + (goto-char (process-mark (get-buffer-process (current-buffer)))) + (insert dangling-text)) + ;; remove filter + (remove-hook 'comint-output-filter-functions 'my-filt))) + ;; remove echo'd FULL-BODY from input + (if (and ,remove-echo ,full-body + (string-match + (replace-regexp-in-string + "\n" "[\r\n]+" (regexp-quote ,full-body)) + string-buffer)) + (setq raw (substring string-buffer (match-end 0)))) + (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." From 45841a8a9de62049c15d371831be6673d50a24eb Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Sat, 12 Jun 2010 16:02:50 -0700 Subject: [PATCH 040/138] babel: ensure `org-babel-interpreters' is defined before `org-babel-add-interpreter' * lisp/babel/ob.el: ensure `org-babel-interpreters' is defined before `org-babel-add-interpreter' --- lisp/babel/ob.el | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/lisp/babel/ob.el b/lisp/babel/ob.el index dae8f6ebe..74aeae9bc 100644 --- a/lisp/babel/ob.el +++ b/lisp/babel/ob.el @@ -156,6 +156,16 @@ can not be resolved.") (concat org-babel-source-name-regexp (regexp-quote name) "[ \t\n]*" (substring org-babel-src-block-regexp 1))) +(defun org-babel-add-interpreter (interpreter) + "Add INTERPRETER to `org-babel-interpreters' and update +`org-babel-src-block-regexp' appropriately." + (unless (member interpreter org-babel-interpreters) + (setq org-babel-interpreters + (sort (cons interpreter org-babel-interpreters) + (lambda (left right) + (> (length left) (length right))))) + (org-babel-set-interpreters 'org-babel-interpreters org-babel-interpreters))) + (defun org-babel-set-interpreters (var value) "Update the regular expressions used to match block and inline code." @@ -177,16 +187,6 @@ code." "{\\([^\f\n\r\v]+?\\)}" ;; (5) body "\\)"))) -(defun org-babel-add-interpreter (interpreter) - "Add INTERPRETER to `org-babel-interpreters' and update -`org-babel-src-block-regexp' appropriately." - (unless (member interpreter org-babel-interpreters) - (setq org-babel-interpreters - (sort (cons interpreter org-babel-interpreters) - (lambda (left right) - (> (length left) (length right))))) - (org-babel-set-interpreters 'org-babel-interpreters org-babel-interpreters))) - (defcustom org-babel-interpreters '() "Interpreters allows for evaluation tags. This is a list of program names (as strings) that can evaluate code and From e0b71bf8e2f99862bcfffe8e8c41c6c2d5015159 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Sat, 12 Jun 2010 16:13:34 -0700 Subject: [PATCH 041/138] babel: wrapping free language variable in result insertion code * lisp/babel/ob.el (org-babel-execute-src-block): now passing additional optional argument to `org-babel-inert-results' (org-babel-insert-result): now accepting additional language variable --- lisp/babel/ob.el | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/lisp/babel/ob.el b/lisp/babel/ob.el index 74aeae9bc..242112cf5 100644 --- a/lisp/babel/ob.el +++ b/lisp/babel/ob.el @@ -275,7 +275,8 @@ block." (not (listp result))) (list (list result)) result))) - (org-babel-insert-result result result-params info new-hash indent) + (org-babel-insert-result + result result-params info new-hash indent lang) (run-hooks 'org-babel-after-execute-hook) result)) (setq call-process-region 'call-process-region-original)))) @@ -956,7 +957,8 @@ link is a file path it is expanded using `expand-file-name'." (expand-file-name (match-string 2 raw)))) (t raw)))) -(defun org-babel-insert-result (result &optional result-params info hash indent) +(defun org-babel-insert-result + (result &optional result-params info hash indent lang) "Insert RESULT into the current buffer after the end of the current source block. With optional argument RESULT-PARAMS controls insertion of results in the org-mode file. @@ -987,7 +989,8 @@ latex --- results are added inside of a #+BEGIN_LATEX block. code ---- the results are extracted in the syntax of the source code of the language being evaluated and are added inside of a #+BEGIN_SRC block with the source-code - language set appropriately." + language set appropriately. Note this relies on the + optional LANG argument." (if (stringp result) (progn (setq result (org-babel-clean-text-properties result)) @@ -1048,7 +1051,7 @@ code ---- the results are extracted in the syntax of the source results-switches result))) ((member "code" result-params) (insert (format "#+BEGIN_SRC %s%s\n%s#+END_SRC\n" - lang results-switches result))) + (or lang "none") results-switches result))) ((or (member "raw" result-params) (member "org" result-params)) (save-excursion (insert result)) (if (org-at-table-p) (org-cycle))) (t @@ -1063,11 +1066,6 @@ code ---- the results are extracted in the syntax of the source (indent-rigidly beg end indent)))) (message "finished")))) -(defun org-babel-result-to-org-string (result) - "Return RESULT as a string in org-mode format. This function -relies on `org-babel-insert-result'." - (with-temp-buffer (org-babel-insert-result result) (buffer-string))) - (defun org-babel-remove-result (&optional info) "Remove the result of the current source block." (interactive) From ea8565e2ed46b925a049a231eed983dd6e2c2971 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Sat, 12 Jun 2010 16:16:28 -0700 Subject: [PATCH 042/138] babel: replaced `save-excursion' with `with-current-buffer' * lisp/babel/ob.el (org-babel-expand-noweb-references): `save-excursion' is not longer defeated by `set-buffer' --- lisp/babel/ob.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lisp/babel/ob.el b/lisp/babel/ob.el index 242112cf5..8571c615b 100644 --- a/lisp/babel/ob.el +++ b/lisp/babel/ob.el @@ -1286,7 +1286,7 @@ block but are passed literally to the \"example-block\"." (nb-add (buffer-substring index (point))) (goto-char (match-end 0)) (setq index (point)) - (nb-add (save-excursion + (nb-add (save-current-buffer (set-buffer parent-buffer) (mapconcat ;; interpose `prefix' between every line #'identity From 2dc30adf151f702640011068284cc8d50b4d3889 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Sat, 12 Jun 2010 16:18:50 -0700 Subject: [PATCH 043/138] babel: call-process-region-original is no longer a free variable * lisp/babel/ob.el (org-babel-execute-src-block): call-process-region-original is no longer free (org-babel-org-babel-call-process-region-original): call-process-region-original is no longer free and is now renamed org-babel-call-process-region-original (org-babel-tramp-handle-call-process-region): call-process-region-original is no longer free --- lisp/babel/ob.el | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/lisp/babel/ob.el b/lisp/babel/ob.el index 8571c615b..b4248f030 100644 --- a/lisp/babel/ob.el +++ b/lisp/babel/ob.el @@ -251,8 +251,8 @@ block." (dir (cdr (assoc :dir params))) (default-directory (or (and dir (file-name-as-directory dir)) default-directory)) - (call-process-region-original - (if (boundp 'call-process-region-original) call-process-region-original + (org-babel-call-process-region-original + (if (boundp 'org-babel-call-process-region-original) org-babel-call-process-region-original (symbol-function 'call-process-region))) (indent (car (last info))) result) @@ -279,7 +279,7 @@ block." result result-params info new-hash indent lang) (run-hooks 'org-babel-after-execute-hook) result)) - (setq call-process-region 'call-process-region-original)))) + (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 @@ -1409,6 +1409,7 @@ of the string." (org-babel-chomp (org-babel-reverse-string string) regexp)) regexp)) +(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 @@ -1422,9 +1423,9 @@ of the string." ;; bug in tramp (apply 'process-file program tmpfile buffer display args) (delete-file tmpfile))) - ;; call-process-region-original is the original emacs definition. It + ;; org-babel-call-process-region-original is the original emacs definition. It ;; is in scope from the let binding in org-babel-execute-src-block - (apply call-process-region-original + (apply org-babel-call-process-region-original start end program delete buffer display args))) (defun org-babel-maybe-remote-file (file) From 4c8f008f3f942570ab2571936d10c6045323a12f Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Sat, 12 Jun 2010 16:39:46 -0700 Subject: [PATCH 044/138] removing compilation of optional language files from the Makefile * Makefile (LISPF): let's not compile files that won't often be used. --- Makefile | 21 +-------------------- 1 file changed, 1 insertion(+), 20 deletions(-) diff --git a/Makefile b/Makefile index 37aedfe93..d95390021 100644 --- a/Makefile +++ b/Makefile @@ -124,27 +124,8 @@ LISPF = org.el \ babel/ob-ref.el \ babel/ob-table.el \ babel/ob-tangle.el \ - babel/langs/ob-asymptote.el \ - babel/langs/ob-C.el \ - babel/langs/ob-clojure.el \ - babel/langs/ob-css.el \ - babel/langs/ob-ditaa.el \ - babel/langs/ob-dot.el \ babel/langs/ob-emacs-lisp.el \ - babel/langs/ob-gnuplot.el \ - babel/langs/ob-haskell.el \ - babel/langs/ob-latex.el \ - babel/langs/ob-matlab.el \ - babel/langs/ob-ocaml.el \ - babel/langs/ob-octave.el \ - babel/langs/ob-perl.el \ - babel/langs/ob-python.el \ - babel/langs/ob-R.el \ - babel/langs/ob-ruby.el \ - babel/langs/ob-sass.el \ - babel/langs/ob-screen.el \ - babel/langs/ob-sh.el \ - babel/langs/ob-sql.el + babel/langs/ob-sh.el LISPFILES0 = $(LISPF:%=lisp/%) LISPFILES = $(LISPFILES0) lisp/org-install.el From 49e90002dc6925faf20e05c664322d7dd9f4fa90 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Sat, 12 Jun 2010 16:48:30 -0700 Subject: [PATCH 045/138] babel: define variables before their first use * lisp/babel/ob.el (org-babel-interpreters): define this before it is first used * lisp/babel/ob.el (org-babel-call-process-region-original): define this before it is first used --- lisp/babel/ob.el | 3 +++ 1 file changed, 3 insertions(+) diff --git a/lisp/babel/ob.el b/lisp/babel/ob.el index b4248f030..0319a79fa 100644 --- a/lisp/babel/ob.el +++ b/lisp/babel/ob.el @@ -156,6 +156,9 @@ can not be resolved.") (concat org-babel-source-name-regexp (regexp-quote name) "[ \t\n]*" (substring org-babel-src-block-regexp 1))) +(defvar org-babel-interpreters nil) +(defvar org-babel-call-process-region-original nil) + (defun org-babel-add-interpreter (interpreter) "Add INTERPRETER to `org-babel-interpreters' and update `org-babel-src-block-regexp' appropriately." From 75a82240c6cdf481397eb2fee85301d20c6b580f Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Sat, 12 Jun 2010 17:05:49 -0700 Subject: [PATCH 046/138] babel: correct function name in reference resolution * lisp/babel/ob-ref.el (org-babel-ref-resolve-reference): correcting mis-named function org-babel-read-file to org-babel-read-link --- lisp/babel/ob-ref.el | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/lisp/babel/ob-ref.el b/lisp/babel/ob-ref.el index 8de7020fd..126b02c8c 100644 --- a/lisp/babel/ob-ref.el +++ b/lisp/babel/ob-ref.el @@ -54,6 +54,8 @@ ;;; Code: (require 'ob) +(declare-function org-babel-get-src-block-info "ob" (header-vars-only)) + (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." @@ -155,7 +157,7 @@ return nil." (case type ('results-line (org-babel-read-result)) ('table (org-babel-read-table)) - ('file (org-babel-read-file)) + ('file (org-babel-read-link)) ('source-block (org-babel-execute-src-block nil nil params)) ('lob (org-babel-execute-src-block nil lob-info params)))) (if (symbolp result) From defa2dcb2f55eff45831c6906824511bd9c24213 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Sat, 12 Jun 2010 17:11:36 -0700 Subject: [PATCH 047/138] babel: declaring functions and variables for the compiler --- lisp/babel/langs/ob-emacs-lisp.el | 6 ++++++ lisp/babel/ob-exp.el | 6 ++++++ lisp/babel/ob-lob.el | 2 ++ lisp/babel/ob-ref.el | 2 -- lisp/babel/ob-tangle.el | 2 ++ lisp/babel/ob.el | 23 +++++++++++++++++++---- 6 files changed, 35 insertions(+), 6 deletions(-) diff --git a/lisp/babel/langs/ob-emacs-lisp.el b/lisp/babel/langs/ob-emacs-lisp.el index 3b163ebd6..632889a3e 100644 --- a/lisp/babel/langs/ob-emacs-lisp.el +++ b/lisp/babel/langs/ob-emacs-lisp.el @@ -39,6 +39,12 @@ '((:hlines . "yes") (:colnames . "no")) "Default arguments to use when 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)) +(declare-function org-babel-comint-wait-for-output "ob-comint" (buffer)) +(declare-function org-babel-comint-in-buffer "ob-comint" (buffer &rest body)) +(declare-function orgtbl-to-generic "org-table" (table params)) + (defun org-babel-expand-body:emacs-lisp (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." (let* ((processed-params (or processed-params (org-babel-process-params params))) diff --git a/lisp/babel/ob-exp.el b/lisp/babel/ob-exp.el index e3f371a37..0fc32eefa 100644 --- a/lisp/babel/ob-exp.el +++ b/lisp/babel/ob-exp.el @@ -58,6 +58,12 @@ will be indented by this many characters. See source block function.") (defvar obe-marker nil) +(defvar org-current-export-file) +(defvar org-babel-lob-one-liner-regexp) +(defvar org-babel-ref-split-regexp) +(declare-function org-babel-get-src-block-info "ob" (&optional header-vars-only)) +(declare-function org-babel-lob-get-info "ob-lob" ()) +(declare-function org-babel-ref-literal "ob-ref" (ref)) (defun org-babel-exp-src-blocks (body &rest headers) "Process src block for export. Depending on the 'export' diff --git a/lisp/babel/ob-lob.el b/lisp/babel/ob-lob.el index 5e1f64f50..3d7ff5422 100644 --- a/lisp/babel/ob-lob.el +++ b/lisp/babel/ob-lob.el @@ -33,6 +33,8 @@ (require 'ob-table) (require 'ob-exp) +(declare-function org-babel-get-src-block-info "ob" (&optional header-vars-only)) + (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'.") diff --git a/lisp/babel/ob-ref.el b/lisp/babel/ob-ref.el index 126b02c8c..ef1dd1f0e 100644 --- a/lisp/babel/ob-ref.el +++ b/lisp/babel/ob-ref.el @@ -54,8 +54,6 @@ ;;; Code: (require 'ob) -(declare-function org-babel-get-src-block-info "ob" (header-vars-only)) - (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." diff --git a/lisp/babel/ob-tangle.el b/lisp/babel/ob-tangle.el index 432346adb..1e115fa8d 100644 --- a/lisp/babel/ob-tangle.el +++ b/lisp/babel/ob-tangle.el @@ -31,6 +31,8 @@ ;;; Code: (require 'ob) +(declare-function org-babel-get-src-block-info "ob" (&optional header-vars-only)) + (defvar org-babel-tangle-langs nil "List of languages supported by `org-babel-tangle'. The first element of each language's list is a string indicating the name diff --git a/lisp/babel/ob.el b/lisp/babel/ob.el index 0319a79fa..f35e56cdb 100644 --- a/lisp/babel/ob.el +++ b/lisp/babel/ob.el @@ -32,6 +32,24 @@ (eval-when-compile (require 'cl)) (require 'org) +(defvar org-babel-interpreters nil) +(defvar org-babel-call-process-region-original nil) +(defvar call-process-region) +(defvar org-babel-lob-one-liner-regexp) +(declare-function orgtbl-to-generic "org-table" (table params)) +(declare-function org-babel-ref-split-args "ob-ref" (arg-string)) +(declare-function org-babel-ref-variables "ob-ref" (params)) +(declare-function org-babel-lob-get-info "ob-lob" nil) +(declare-function orgtbl-to-orgtbl "org-table" (table params)) +(declare-function org-babel-ref-resolve-reference + "ob-ref" (ref &optional params)) +(declare-function tramp-compat-make-temp-file + "tramp" (filename &optional dir-flag)) +(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)) + ;; add the langs/ directory to the load path (add-to-list 'load-path (expand-file-name "langs" @@ -156,9 +174,6 @@ can not be resolved.") (concat org-babel-source-name-regexp (regexp-quote name) "[ \t\n]*" (substring org-babel-src-block-regexp 1))) -(defvar org-babel-interpreters nil) -(defvar org-babel-call-process-region-original nil) - (defun org-babel-add-interpreter (interpreter) "Add INTERPRETER to `org-babel-interpreters' and update `org-babel-src-block-regexp' appropriately." @@ -1564,7 +1579,7 @@ specifies the value of ERROR-BUFFER." ;; Clear the output buffer, then run the command with ;; output there. (let ((directory default-directory)) - (save-excursion + (save-current-buffer (set-buffer buffer) (setq buffer-read-only nil) (if (not output-buffer) From 6fa2ab7eacf077e5c7f2e974d09cb10fc1f1d9a8 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Sat, 12 Jun 2010 18:26:08 -0700 Subject: [PATCH 048/138] babel: replacing functions like "fifth" with "nth 4" --- lisp/babel/langs/ob-emacs-lisp.el | 4 +-- lisp/babel/langs/ob-sh.el | 6 ++-- lisp/babel/ob-exp.el | 36 +++++++++---------- lisp/babel/ob-lob.el | 6 ++-- lisp/babel/ob-table.el | 4 +-- lisp/babel/ob-tangle.el | 32 ++++++++--------- lisp/babel/ob.el | 58 +++++++++++++++---------------- 7 files changed, 73 insertions(+), 73 deletions(-) diff --git a/lisp/babel/langs/ob-emacs-lisp.el b/lisp/babel/langs/ob-emacs-lisp.el index 632889a3e..7ac913c02 100644 --- a/lisp/babel/langs/ob-emacs-lisp.el +++ b/lisp/babel/langs/ob-emacs-lisp.el @@ -48,9 +48,9 @@ (defun org-babel-expand-body:emacs-lisp (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." (let* ((processed-params (or processed-params (org-babel-process-params params))) - (vars (second processed-params)) + (vars (nth 1 processed-params)) (processed-params (org-babel-process-params params)) - (result-params (third processed-params)) + (result-params (nth 2 processed-params)) (print-level nil) (print-length nil) (body (if (> (length vars) 0) (concat "(let (" diff --git a/lisp/babel/langs/ob-sh.el b/lisp/babel/langs/ob-sh.el index e63a7d35b..0c86d8573 100644 --- a/lisp/babel/langs/ob-sh.el +++ b/lisp/babel/langs/ob-sh.el @@ -42,7 +42,7 @@ (defun org-babel-expand-body:sh (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." - (let ((vars (second (or processed-params (org-babel-process-params params)))) + (let ((vars (nth 1 (or processed-params (org-babel-process-params params)))) (sep (cdr (assoc :separator params)))) (concat (mapconcat ;; define any variables @@ -57,8 +57,8 @@ function is called by `org-babel-execute-src-block'." (message "executing Shell source code block") (let* ((processed-params (org-babel-process-params params)) - (session (org-babel-sh-initiate-session (first processed-params))) - (result-params (third processed-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 (org-babel-reassemble-table diff --git a/lisp/babel/ob-exp.el b/lisp/babel/ob-exp.el index 0fc32eefa..9c948313a 100644 --- a/lisp/babel/ob-exp.el +++ b/lisp/babel/ob-exp.el @@ -80,18 +80,18 @@ results - just like none only the block is run on export ensuring none ----- do not display either code or results upon export" (interactive) (message "org-babel-exp processing...") - (when (member (first headers) org-babel-interpreters) + (when (member (nth 0 headers) org-babel-interpreters) (save-excursion (goto-char (match-beginning 0)) (let* ((info (org-babel-get-src-block-info)) - (params (third info))) + (params (nth 2 info))) ;; expand noweb references in the original file - (setf (second info) + (setf (nth 1 info) (if (and (cdr (assoc :noweb params)) (string= "yes" (cdr (assoc :noweb params)))) (org-babel-expand-noweb-references info (get-file-buffer org-current-export-file)) - (second info))) + (nth 1 info))) (org-babel-exp-do-export info 'block))))) (defun org-babel-exp-inline-src-blocks (start end) @@ -104,18 +104,18 @@ options and are taken from `org-babel-defualt-inline-header-args'." (while (and (< (point) end) (re-search-forward org-babel-inline-src-block-regexp end t)) (let* ((info (save-match-data (org-babel-parse-inline-src-block-match))) - (params (third info)) + (params (nth 2 info)) (replacement (save-match-data (if (org-babel-in-example-or-verbatim) (buffer-substring (match-beginning 0) (match-end 0)) ;; expand noweb references in the original file - (setf (second info) + (setf (nth 1 info) (if (and (cdr (assoc :noweb params)) (string= "yes" (cdr (assoc :noweb params)))) (org-babel-expand-noweb-references info (get-file-buffer org-current-export-file)) - (second info))) + (nth 1 info))) (org-babel-exp-do-export info 'inline))))) (setq end (+ end (- (length replacement) (length (match-string 1))))) (replace-match replacement t t nil 1))))) @@ -176,13 +176,13 @@ options are taken from `org-babel-default-header-args'." (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." - (flet ((silently () (let ((session (cdr (assoc :session (third info))))) + (flet ((silently () (let ((session (cdr (assoc :session (nth 2 info))))) (when (and session (not (equal "none" session)) - (not (assoc :noeval (third info)))) + (not (assoc :noeval (nth 2 info)))) (org-babel-exp-results info type 'silent)))) (clean () (org-babel-remove-result info))) - (case (intern (or (cdr (assoc :exports (third info))) "code")) + (case (intern (or (cdr (assoc :exports (nth 2 info))) "code")) ('none (silently) (clean) "") ('code (silently) (clean) (org-babel-exp-code info type)) ('results (org-babel-exp-results info type)) @@ -195,13 +195,13 @@ code block respecting the value of the :exports header argument." for exportation by org-mode. This function is called by `org-babel-exp-do-export'. The code block will not be evaluated." - (let ((lang (first info)) - (body (second info)) - (switches (fourth info)) - (name (fifth info)) + (let ((lang (nth 0 info)) + (body (nth 1 info)) + (switches (nth 3 info)) + (name (nth 4 info)) (args (mapcar #'cdr - (remove-if-not (lambda (el) (eq :var (car el))) (third info))))) + (remove-if-not (lambda (el) (eq :var (car el))) (nth 2 info))))) (case type ('inline (format "=%s=" body)) ('block @@ -233,8 +233,8 @@ 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 (first info)) - (body (second info)) + (let ((lang (nth 0 info)) + (body (nth 1 info)) (params ;; lets ensure that we lookup references in the original file (mapcar @@ -247,7 +247,7 @@ results into the buffer." "=" org-current-export-file ":" (match-string 2 (cdr pair)))) pair)) - (third info)))) + (nth 2 info)))) (case type ('inline (let ((raw (org-babel-execute-src-block diff --git a/lisp/babel/ob-lob.el b/lisp/babel/ob-lob.el index 3d7ff5422..5de6fb0fb 100644 --- a/lisp/babel/ob-lob.el +++ b/lisp/babel/ob-lob.el @@ -50,7 +50,7 @@ add files to this list use the `org-babel-lob-ingest' command." (interactive "f") (org-babel-map-source-blocks file (let* ((info (org-babel-get-src-block-info)) - (source-name (intern (fifth info)))) + (source-name (intern (nth 4 info)))) (when source-name (setq org-babel-library-of-babel (cons (cons source-name info) @@ -76,7 +76,7 @@ src-block and if so then run the appropriate source block from the Library." (interactive) (let ((info (org-babel-lob-get-info))) - (if (first info) (progn (org-babel-lob-execute info) t) nil))) + (if (nth 0 info) (progn (org-babel-lob-execute info) t) nil))) (add-hook 'org-ctrl-c-ctrl-c-hook 'org-babel-lob-execute-maybe) @@ -109,7 +109,7 @@ the word 'call'." (org-babel-clean-text-properties (concat ":var results=" (mapconcat #'identity (butlast info) " "))))))) (org-babel-execute-src-block - nil (list "emacs-lisp" "results" params nil nil (third info))))) + nil (list "emacs-lisp" "results" params nil nil (nth 2 info))))) (provide 'ob-lob) ;;; ob-lob.el ends here diff --git a/lisp/babel/ob-table.el b/lisp/babel/ob-table.el index d997043d4..22aa4ca0e 100644 --- a/lisp/babel/ob-table.el +++ b/lisp/babel/ob-table.el @@ -82,7 +82,7 @@ rather than a single \"$\" (i.e. \"$$2\" instead of \"$2\" in the example above." (let ((variables (mapcar (lambda (var) - (if (and (= 3 (length var)) (eq (second var) '$)) + (if (and (= 3 (length var)) (eq (nth 1 var) '$)) (list (car var) (format "\"%s\"" (last var))) var)) variables))) @@ -95,7 +95,7 @@ example above." ,source-block "(" (mapconcat (lambda (var-spec) - (format "%S=%s" (first var-spec) (second var-spec))) + (format "%S=%s" (nth 0 var-spec) (nth 1 var-spec))) ',variables ", ") ")"))))) (org-babel-execute-src-block diff --git a/lisp/babel/ob-tangle.el b/lisp/babel/ob-tangle.el index 1e115fa8d..34cff5d20 100644 --- a/lisp/babel/ob-tangle.el +++ b/lisp/babel/ob-tangle.el @@ -55,7 +55,7 @@ file using `load-file'." (flet ((age (file) (time-to-seconds (time-subtract (current-time) - (sixth (or (file-attributes (file-truename file)) + (nth 5 (or (file-attributes (file-truename file)) (file-attributes file))))))) (let* ((base-name (file-name-sans-extension file)) (exported-file (concat base-name ".el"))) @@ -109,14 +109,14 @@ exported source code blocks by language." lang) "-mode"))) (lang-specs (cdr (assoc lang org-babel-tangle-langs))) - (ext (first lang-specs)) - (she-bang (second lang-specs)) - (commentable (and (fboundp lang-f) (not (third lang-specs)))) + (ext (nth 0 lang-specs)) + (she-bang (nth 1 lang-specs)) + (commentable (and (fboundp lang-f) (not (nth 2 lang-specs)))) she-banged) (mapc (lambda (spec) (flet ((get-spec (name) - (cdr (assoc name (third spec))))) + (cdr (assoc name (nth 2 spec))))) (let* ((tangle (get-spec :tangle)) (she-bang (if (> (length (get-spec :shebang)) 0) (get-spec :shebang) @@ -189,11 +189,11 @@ code blocks by language." (org-babel-clean-text-properties (car (pop org-stored-links))))) (info (org-babel-get-src-block-info)) - (source-name (intern (or (fifth info) + (source-name (intern (or (nth 4 info) (format "block-%d" block-counter)))) - (src-lang (first info)) + (src-lang (nth 0 info)) (expand-cmd (intern (concat "org-babel-expand-body:" src-lang))) - (params (third info)) + (params (nth 2 info)) by-lang) (unless (string= (cdr (assoc :tangle params)) "no") ;; skip (unless (and lang (not (string= lang src-lang))) ;; limit by language @@ -219,8 +219,8 @@ code blocks by language." (cdr (assoc :noweb params)))) (org-babel-expand-noweb-references info) - (second info))) - (third + (nth 1 info))) + (nth 2 (cdr (assoc src-lang org-babel-tangle-langs)))) by-lang)) blocks)))))) @@ -248,14 +248,14 @@ form (progn (insert text) (point))) (end-of-line nil) (insert "\n")))) - (let ((link (first spec)) - (source-name (second spec)) - (body (fourth spec)) - (commentable (not (if (> (length (cdr (assoc :comments (third spec)))) + (let ((link (nth 0 spec)) + (source-name (nth 1 spec)) + (body (nth 3 spec)) + (commentable (not (if (> (length (cdr (assoc :comments (nth 2 spec)))) 0) - (string= (cdr (assoc :comments (third spec))) + (string= (cdr (assoc :comments (nth 2 spec))) "no") - (fifth spec))))) + (nth 4 spec))))) (insert-comment (format "[[%s][%s]]" (org-link-escape link) source-name)) (insert (format "\n%s\n" (replace-regexp-in-string "^," "" (org-babel-chomp body)))) diff --git a/lisp/babel/ob.el b/lisp/babel/ob.el index f35e56cdb..7e91a2180 100644 --- a/lisp/babel/ob.el +++ b/lisp/babel/ob.el @@ -82,8 +82,8 @@ function is called when `org-edit-special' is called with a prefix argument from inside of a source-code block." (when current-prefix-arg (let* ((info (org-babel-get-src-block-info)) - (lang (first info)) - (params (third info)) + (lang (nth 0 info)) + (params (nth 2 info)) (session (cdr (assoc :session params)))) (when (and info session) ;; we are in a source-code block with a session (funcall @@ -246,9 +246,9 @@ the header arguments specified at the front of the source code block." (interactive) (let* ((info (or info (org-babel-get-src-block-info))) - (lang (first info)) - (params (setf (third info) - (sort (org-babel-merge-params (third info) params) + (lang (nth 0 info)) + (params (setf (nth 2 info) + (sort (org-babel-merge-params (nth 2 info) params) (lambda (el1 el2) (string< (symbol-name (car el1)) (symbol-name (car el2))))))) (new-hash @@ -256,11 +256,11 @@ block." (string= "yes" (cdr (assoc :cache params)))) (org-babel-sha1-hash info))) (old-hash (org-babel-result-hash info)) - (body (setf (second info) + (body (setf (nth 1 info) (if (and (cdr (assoc :noweb params)) (string= "yes" (cdr (assoc :noweb params)))) (org-babel-expand-noweb-references info) - (second info)))) + (nth 1 info)))) (result-params (split-string (or (cdr (assoc :results params)) ""))) (result-type (cond ((member "output" result-params) 'output) ((member "value" result-params) 'value) @@ -310,15 +310,15 @@ org-babel-expand-body:lang function." body) arguments, and pop open the results in a preview buffer." (interactive) (let* ((info (or info (org-babel-get-src-block-info))) - (lang (first info)) - (params (setf (third info) - (sort (org-babel-merge-params (third info) params) + (lang (nth 0 info)) + (params (setf (nth 2 info) + (sort (org-babel-merge-params (nth 2 info) params) (lambda (el1 el2) (string< (symbol-name (car el1)) (symbol-name (car el2))))))) - (body (setf (second info) + (body (setf (nth 1 info) (if (and (cdr (assoc :noweb params)) (string= "yes" (cdr (assoc :noweb params)))) - (org-babel-expand-noweb-references info) (second info)))) + (org-babel-expand-noweb-references info) (nth 1 info)))) (cmd (intern (concat "org-babel-expand-body:" lang))) (expanded (funcall (if (fboundp cmd) cmd 'org-babel-expand-body:generic) body params))) @@ -331,9 +331,9 @@ 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 (first info)) - (body (second info)) - (params (third info)) + (lang (nth 0 info)) + (body (nth 1 info)) + (params (nth 2 info)) (session (cdr (assoc :session params)))) (unless (member lang org-babel-interpreters) (error "Language is not in `org-babel-interpreters': %s" lang)) @@ -350,9 +350,9 @@ for the source block before entering the session. Copy the body of the source block to the kill ring." (interactive) (let* ((info (or info (org-babel-get-src-block-info))) - (lang (first info)) - (body (second info)) - (params (third info)) + (lang (nth 0 info)) + (body (nth 1 info)) + (params (nth 2 info)) (session (cdr (assoc :session params))) (dir (cdr (assoc :dir params))) (default-directory @@ -463,8 +463,8 @@ added to the header-arguments-alist." (lambda (ref) (cons :var ref)) (org-babel-ref-split-args args)))))) (unless header-vars-only - (setf (third info) - (org-babel-merge-params (sixth info) (third info))))) + (setf (nth 2 info) + (org-babel-merge-params (nth 5 info) (nth 2 info))))) (setq info (append info (list nil nil)))) (append info (list indent))) (if (save-excursion ;; inline source block @@ -478,8 +478,8 @@ added to the header-arguments-alist." (interactive) (let* ((info (or info (org-babel-get-src-block-info))) (hash (sha1 (format "%s-%s" (mapconcat (lambda (arg) (format "%S" arg)) - (third info) ":") - (second info))))) + (nth 2 info) ":") + (nth 1 info))))) (when (interactive-p) (message hash)) hash)) @@ -747,7 +747,7 @@ Return a list (session vars result-params result-type colnames rownames)." "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 (second table)) + (if (equal 'hline (nth 1 table)) (cons (cddr table) (car table)) (cons (cdr table) (car table)))) @@ -800,7 +800,7 @@ of the vars, cnames and rnames." (lambda (var) (when (listp (cdr var)) (when (and (not (equal colnames "no")) - (or colnames (and (equal (second (cdr var)) 'hline) + (or colnames (and (equal (nth 1 (cdr var)) 'hline) (not (member 'hline (cddr (cdr var))))))) (let ((both (org-babel-get-colnames (cdr var)))) (setq cnames (cons (cons (car var) (cdr both)) @@ -894,8 +894,8 @@ following the source block." (let* ((on-lob-line (progn (beginning-of-line 1) (looking-at org-babel-lob-one-liner-regexp))) (name (if on-lob-line - (first (org-babel-lob-get-info)) - (fifth (or info (org-babel-get-src-block-info))))) + (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) (when head (goto-char head)) (or (and name (org-babel-find-named-result name)) @@ -1031,7 +1031,7 @@ code ---- the results are extracted in the syntax of the source (let ((existing-result (org-babel-where-is-src-block-result t info hash indent)) (results-switches - (cdr (assoc :results_switches (third info)))) + (cdr (assoc :results_switches (nth 2 info)))) beg end) (when existing-result (goto-char existing-result) @@ -1283,8 +1283,8 @@ these arguments are not evaluated in the current source-code block but are passed literally to the \"example-block\"." (let* ((parent-buffer (or parent-buffer (current-buffer))) (info (or info (org-babel-get-src-block-info))) - (lang (first info)) - (body (second info)) + (lang (nth 0 info)) + (body (nth 1 info)) (new-body "") index source-name evaluate prefix) (flet ((nb-add (text) (setq new-body (concat new-body text)))) From 0dabebc444e4caef8a36a61e13a29cdd8bc9e731 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Sat, 12 Jun 2010 18:32:23 -0700 Subject: [PATCH 049/138] babel: eval-when-compile for 'cl in more babel files --- lisp/babel/ob-exp.el | 8 ++++++-- lisp/babel/ob-ref.el | 2 ++ lisp/babel/ob-tangle.el | 2 ++ 3 files changed, 10 insertions(+), 2 deletions(-) diff --git a/lisp/babel/ob-exp.el b/lisp/babel/ob-exp.el index 9c948313a..f23c5aaec 100644 --- a/lisp/babel/ob-exp.el +++ b/lisp/babel/ob-exp.el @@ -31,11 +31,15 @@ ;;; Code: (require 'ob) (require 'org-exp-blocks) -(org-export-blocks-add-block '(src org-babel-exp-src-blocks nil)) +(eval-when-compile + (require 'cl)) + (add-to-list 'org-export-interblocks '(src org-babel-exp-inline-src-blocks)) (add-to-list 'org-export-interblocks '(lob org-babel-exp-lob-one-liners)) (add-hook 'org-export-blocks-postblock-hook 'org-exp-res/src-name-cleanup) +(org-export-blocks-add-block '(src org-babel-exp-src-blocks nil)) + (defvar org-babel-function-def-export-keyword "function" "When exporting a source block function, this keyword will appear in the exported version in the place of source name @@ -201,7 +205,7 @@ evaluated." (name (nth 4 info)) (args (mapcar #'cdr - (remove-if-not (lambda (el) (eq :var (car el))) (nth 2 info))))) + (org-remove-if-not (lambda (el) (eq :var (car el))) (nth 2 info))))) (case type ('inline (format "=%s=" body)) ('block diff --git a/lisp/babel/ob-ref.el b/lisp/babel/ob-ref.el index ef1dd1f0e..17a7e3451 100644 --- a/lisp/babel/ob-ref.el +++ b/lisp/babel/ob-ref.el @@ -53,6 +53,8 @@ ;;; Code: (require 'ob) +(eval-when-compile + (require 'cl)) (defun org-babel-ref-variables (params) "Takes a parameter alist, and return an alist of variable diff --git a/lisp/babel/ob-tangle.el b/lisp/babel/ob-tangle.el index 34cff5d20..ddf942981 100644 --- a/lisp/babel/ob-tangle.el +++ b/lisp/babel/ob-tangle.el @@ -30,6 +30,8 @@ ;;; Code: (require 'ob) +(eval-when-compile + (require 'cl)) (declare-function org-babel-get-src-block-info "ob" (&optional header-vars-only)) From b9a8df9d1c92014d6d40e06ff828bbadeb06d9e3 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Sat, 12 Jun 2010 18:49:02 -0700 Subject: [PATCH 050/138] babel: defvar'ing `org-babel-library-of-babel' for compiler --- lisp/babel/ob-ref.el | 1 + 1 file changed, 1 insertion(+) diff --git a/lisp/babel/ob-ref.el b/lisp/babel/ob-ref.el index 17a7e3451..6307bc025 100644 --- a/lisp/babel/ob-ref.el +++ b/lisp/babel/ob-ref.el @@ -95,6 +95,7 @@ return nil." (read ref)) out))) +(defvar org-babel-library-of-babel) (defun org-babel-ref-resolve-reference (ref &optional params) "Resolve the reference REF and return its value." (save-excursion From 0e939a7df50463fb63fe7381fc8986e0ee13e69b Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Sat, 12 Jun 2010 18:50:05 -0700 Subject: [PATCH 051/138] babel: more compiler satisfaction --- lisp/babel/langs/ob-sh.el | 9 +++++++++ lisp/babel/ob-exp.el | 3 ++- lisp/babel/ob-ref.el | 5 ++++- lisp/babel/ob-tangle.el | 2 +- 4 files changed, 16 insertions(+), 3 deletions(-) diff --git a/lisp/babel/langs/ob-sh.el b/lisp/babel/langs/ob-sh.el index 0c86d8573..1d7c90d7e 100644 --- a/lisp/babel/langs/ob-sh.el +++ b/lisp/babel/langs/ob-sh.el @@ -31,6 +31,15 @@ ;;; Code: (require 'ob) (require 'shell) +(eval-when-compile + (require 'cl)) + +(defun-function org-babel-ref-variables "ob-ref" (params)) +(defun-function org-babel-comint-in-buffer "ob-comint" (buffer &rest body)) +(defun-function org-babel-comint-wait-for-output "ob-comint" (buffer)) +(defun-function org-babel-comint-buffer-livep "ob-comint" (buffer)) +(defun-function org-babel-comint-with-output "ob-comint" (meta &rest body)) +(defun-function orgtbl-to-generic "org-table" (table params)) (org-babel-add-interpreter "sh") diff --git a/lisp/babel/ob-exp.el b/lisp/babel/ob-exp.el index f23c5aaec..be82b6bb7 100644 --- a/lisp/babel/ob-exp.el +++ b/lisp/babel/ob-exp.el @@ -194,6 +194,7 @@ code block respecting the value of the :exports header argument." "\n\n" (org-babel-exp-results info type)))))) +(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 @@ -229,7 +230,7 @@ evaluated." ((eq backend 'html) (format "\n#+HTML: \n" call-line)) - ((t (format ": %s\n" call-line))))))))) + ((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 diff --git a/lisp/babel/ob-ref.el b/lisp/babel/ob-ref.el index 6307bc025..c75930e33 100644 --- a/lisp/babel/ob-ref.el +++ b/lisp/babel/ob-ref.el @@ -105,7 +105,10 @@ return nil." ;; if ref is indexed grab the indices -- beware nested indicies (when (and (string-match "\\[\\(.+\\)\\]" ref) (let ((str (substring ref 0 (match-beginning 0)))) - (= (count ?( str) (count ?) str)))) + (= (length (org-remove-if-not + (lambda (el) (equal ?( el)) (string-to-list "((eric))"))) + (length (org-remove-if-not + (lambda (el) (equal ?) el)) (string-to-list "((eric))")))))) (setq index (match-string 1 ref)) (setq ref (substring ref 0 (match-beginning 0)))) ;; assign any arguments to pass to source block diff --git a/lisp/babel/ob-tangle.el b/lisp/babel/ob-tangle.el index ddf942981..cde7f142e 100644 --- a/lisp/babel/ob-tangle.el +++ b/lisp/babel/ob-tangle.el @@ -55,7 +55,7 @@ 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'." (flet ((age (file) - (time-to-seconds + (float-time (time-subtract (current-time) (nth 5 (or (file-attributes (file-truename file)) (file-attributes file))))))) From b746686dfe6bffa828240a09caf3fcd6a0ead72a Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Mon, 14 Jun 2010 16:36:46 -0700 Subject: [PATCH 052/138] ob-sh: should say declare-function not defun-function --- lisp/babel/langs/ob-sh.el | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/lisp/babel/langs/ob-sh.el b/lisp/babel/langs/ob-sh.el index 1d7c90d7e..edaf8cfa1 100644 --- a/lisp/babel/langs/ob-sh.el +++ b/lisp/babel/langs/ob-sh.el @@ -34,12 +34,12 @@ (eval-when-compile (require 'cl)) -(defun-function org-babel-ref-variables "ob-ref" (params)) -(defun-function org-babel-comint-in-buffer "ob-comint" (buffer &rest body)) -(defun-function org-babel-comint-wait-for-output "ob-comint" (buffer)) -(defun-function org-babel-comint-buffer-livep "ob-comint" (buffer)) -(defun-function org-babel-comint-with-output "ob-comint" (meta &rest body)) -(defun-function orgtbl-to-generic "org-table" (table params)) +(declare-function org-babel-ref-variables "ob-ref" (params)) +(declare-function org-babel-comint-in-buffer "ob-comint" (buffer &rest body)) +(declare-function org-babel-comint-wait-for-output "ob-comint" (buffer)) +(declare-function org-babel-comint-buffer-livep "ob-comint" (buffer)) +(declare-function org-babel-comint-with-output "ob-comint" (meta &rest body)) +(declare-function orgtbl-to-generic "org-table" (table params)) (org-babel-add-interpreter "sh") From 116d9cfa853525574df6d06a6c38f74452de02b6 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Mon, 14 Jun 2010 16:36:56 -0700 Subject: [PATCH 053/138] ob: adding ob-init.el to load everything --- lisp/babel/ob-init.el | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 lisp/babel/ob-init.el diff --git a/lisp/babel/ob-init.el b/lisp/babel/ob-init.el new file mode 100644 index 000000000..4b709d137 --- /dev/null +++ b/lisp/babel/ob-init.el @@ -0,0 +1,12 @@ +;;; ob-init.el --- working with code blocks in org-mode +(require 'ob) +(require 'ob-ref) +(require 'ob-exp) +(require 'ob-tangle) +(require 'ob-lob) +(require 'ob-comint) +(require 'ob-table) +(require 'ob-keys) + +(provide 'ob-init) +;;; ob-init.el ends here \ No newline at end of file From ca3f3baca6118f3051c9597dde3b7d85a82f12af Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Mon, 14 Jun 2010 17:00:49 -0700 Subject: [PATCH 054/138] remember the ob-comint-with-output is a macro --- lisp/babel/langs/ob-R.el | 2 +- lisp/babel/langs/ob-haskell.el | 2 +- lisp/babel/langs/ob-ocaml.el | 2 +- lisp/babel/langs/ob-octave.el | 10 +++++----- lisp/babel/langs/ob-python.el | 2 +- lisp/babel/langs/ob-ruby.el | 2 +- lisp/babel/langs/ob-sh.el | 2 +- 7 files changed, 11 insertions(+), 11 deletions(-) diff --git a/lisp/babel/langs/ob-R.el b/lisp/babel/langs/ob-R.el index 995e1015a..0b6e2d2cf 100644 --- a/lisp/babel/langs/ob-R.el +++ b/lisp/babel/langs/ob-R.el @@ -213,7 +213,7 @@ last statement in BODY, as elisp." (output (mapconcat #'org-babel-chomp (list body org-babel-R-eoe-indicator) "\n")))) (raw - (org-babel-comint-with-output (list session org-babel-R-eoe-output) + (org-babel-comint-with-output (session org-babel-R-eoe-output) (insert full-body) (inferior-ess-send-input))) (comint-prompt-regexp (concat "^\\(" diff --git a/lisp/babel/langs/ob-haskell.el b/lisp/babel/langs/ob-haskell.el index c9525a0a0..2b24822d5 100644 --- a/lisp/babel/langs/ob-haskell.el +++ b/lisp/babel/langs/ob-haskell.el @@ -72,7 +72,7 @@ (full-body (org-babel-expand-body:haskell body params processed-params)) (session (org-babel-prep-session:haskell session params)) (raw (org-babel-comint-with-output - (list session org-babel-haskell-eoe t full-body) + (session org-babel-haskell-eoe t full-body) (insert (org-babel-trim full-body)) (comint-send-input nil t) (insert org-babel-haskell-eoe) diff --git a/lisp/babel/langs/ob-ocaml.el b/lisp/babel/langs/ob-ocaml.el index e84fdaf9a..945b67fb8 100644 --- a/lisp/babel/langs/ob-ocaml.el +++ b/lisp/babel/langs/ob-ocaml.el @@ -64,7 +64,7 @@ (full-body (org-babel-expand-body:ocaml body params processed-params)) (session (org-babel-prep-session:ocaml session params)) (raw (org-babel-comint-with-output - (list session org-babel-ocaml-eoe-output t full-body) + (session org-babel-ocaml-eoe-output t full-body) (insert (concat (org-babel-chomp full-body) " ;;")) (comint-send-input nil t) (insert org-babel-ocaml-eoe-indicator) diff --git a/lisp/babel/langs/ob-octave.el b/lisp/babel/langs/ob-octave.el index 732681f39..2f0713800 100644 --- a/lisp/babel/langs/ob-octave.el +++ b/lisp/babel/langs/ob-octave.el @@ -182,11 +182,11 @@ statement in BODY, as elisp." ;; available, so :results output currently ;; won't work (org-babel-comint-with-output - (list session - (if matlabp - org-babel-octave-eoe-indicator - org-babel-octave-eoe-output) - t full-body) + (session + (if matlabp + org-babel-octave-eoe-indicator + org-babel-octave-eoe-output) + t full-body) (insert full-body) (comint-send-input nil t)))) results) (case result-type (value diff --git a/lisp/babel/langs/ob-python.el b/lisp/babel/langs/ob-python.el index de0b1e3e2..4f51bb78e 100644 --- a/lisp/babel/langs/ob-python.el +++ b/lisp/babel/langs/ob-python.el @@ -218,7 +218,7 @@ last statement in BODY, as elisp." ;; comint session evaluation (org-babel-comint-in-buffer buffer (let* ((raw (org-babel-comint-with-output - (list buffer org-babel-python-eoe-indicator t full-body) + (buffer org-babel-python-eoe-indicator t full-body) ;; for some reason python is fussy, and likes enters after every input (let ((comint-process-echoes nil)) (mapc (lambda (statement) (insert statement) (comint-send-input)) diff --git a/lisp/babel/langs/ob-ruby.el b/lisp/babel/langs/ob-ruby.el index f4ff947b7..ef9f3d2fe 100644 --- a/lisp/babel/langs/ob-ruby.el +++ b/lisp/babel/langs/ob-ruby.el @@ -214,7 +214,7 @@ last statement in BODY, as elisp." org-babel-ruby-last-value-eval) org-babel-ruby-eoe-indicator) "\n")) (raw (org-babel-comint-with-output - (list buffer org-babel-ruby-eoe-indicator t full-body) + (buffer org-babel-ruby-eoe-indicator t full-body) (insert full-body) (comint-send-input nil t))) (results (cdr (member org-babel-ruby-eoe-indicator diff --git a/lisp/babel/langs/ob-sh.el b/lisp/babel/langs/ob-sh.el index edaf8cfa1..789614450 100644 --- a/lisp/babel/langs/ob-sh.el +++ b/lisp/babel/langs/ob-sh.el @@ -175,7 +175,7 @@ last statement in BODY." (mapcar #'org-babel-sh-strip-weird-long-prompt (mapcar #'org-babel-trim (org-babel-comint-with-output - (list session org-babel-sh-eoe-output t full-body) + (session org-babel-sh-eoe-output t full-body) (mapc (lambda (line) (insert line) (comint-send-input)) (strip-empty (split-string body "\n"))) (insert org-babel-sh-eoe-indicator) From 892292c2d9594aa153544c43f014abd3249ed21f Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Mon, 14 Jun 2010 17:01:01 -0700 Subject: [PATCH 055/138] better initialization for call-process-region --- lisp/babel/ob.el | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/lisp/babel/ob.el b/lisp/babel/ob.el index 7e91a2180..09417e36b 100644 --- a/lisp/babel/ob.el +++ b/lisp/babel/ob.el @@ -33,8 +33,7 @@ (require 'org) (defvar org-babel-interpreters nil) -(defvar org-babel-call-process-region-original nil) -(defvar call-process-region) +(defvar org-babel-call-process-region-original) (defvar org-babel-lob-one-liner-regexp) (declare-function orgtbl-to-generic "org-table" (table params)) (declare-function org-babel-ref-split-args "ob-ref" (arg-string)) From b548c3e7944606ff955727ed4508327dfa77ed8c Mon Sep 17 00:00:00 2001 From: Tom Dye Date: Mon, 14 Jun 2010 19:47:59 -0400 Subject: [PATCH 056/138] Minor editorial changes to babel documentation (Seattle Airport) --- doc/org.texi | 66 +++++++++++++++++++++++++--------------------------- 1 file changed, 32 insertions(+), 34 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index f2d633451..a167d4f2c 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10934,7 +10934,7 @@ further configuration options. @table @code @item org-src-lang-modes -If an emacs major-mode named @code{-mode} exists, where +If an Emacs major-mode named @code{-mode} exists, where @code{} is the language named in the header line of the code block, then the edit buffer will be placed in that major-mode. This variable can be used to map arbitrary language names to existing major modes. @@ -10946,7 +10946,7 @@ python, in which whitespace indentation in the output is critical. @item org-src-ask-before-returning-to-edit-buffer By default, Org will ask before returning to an open edit buffer. Set to a non-nil value to switch without asking. -@end table +@End table @node Exporting code blocks, Extracting source code, Editing source code, Working With Source Code @comment node-name, next, previous, up @@ -10969,15 +10969,13 @@ behavior: The default in most languages. The body of the code block is exported, as described in @ref{Literal examples}. @item :exports results -On export, the code block will be evaluated and the results will be placed in -the Org-mode buffer, either updating previous results of the code block -located anywhere in the buffer or, if no previous results exist, placing the -results immediately after the code block. The body of the code block will -not be exported. +The code block will be evaluated and the results will be placed in the +Org-mode buffer for export, either updating previous results of the code +block located anywhere in the buffer or, if no previous results exist, +placing the results immediately after the code block. The body of the code +block will not be exported. @item :exports both -On export, the code block will be evaluated and the results inserted into the -buffer as described above, however the body of the code block will be -exported as well. +Both the code block and its results will be exported. @item :exports none Neither the code block nor its results will be exported. @end table @@ -10988,29 +10986,29 @@ Neither the code block nor its results will be exported. @section Extracting source code Creating pure source code files by extracting code from source blocks is -referred to as ``tangling'' -- a term adopted from the literate programming +referred to as ``tangling''---a term adopted from the literate programming community. During ``tangling'' of code blocks their bodies are expanded using @code{org-babel-expand-src-block} which can expand both variable and -``noweb'' (see @ref{Noweb reference syntax}) style references. +``noweb'' style references (see @ref{Noweb reference syntax}). @subsubheading header arguments: @table @code @item :tangle no -The default. +The default. The code block is not included in the tangled output. @item :tangle yes -Include block in tangled output. The output file name is the name of the org -file with the extension @samp{.org} replaced by the extension for the block -language. +Include the code block in the tangled output. The output file name is the +name of the org file with the extension @samp{.org} replaced by the extension +for the block language. @item :tangle filename -Include block in tangled output to file @samp{filename} +Include the code block in the tangled output to file @samp{filename}. @end table @subsubheading functions: @table @code @item org-babel-tangle @key{C-c C-v t} -Tangle the current file +Tangle the current file. @item org-babel-tangle-file -Choose a file to tangle +Choose a file to tangle. @end table @node Evaluating code blocks, Library of Babel, Extracting source code, Working With Source Code @@ -11018,22 +11016,22 @@ Choose a file to tangle @comment Evaluating code blocks, , Extracting source code, Working With Source Code @section Evaluating code blocks -Blocks of code can be evaluated and the results incorporated into the -org-mode buffer. Check the value of the @code{org-babel-interpreters} for a -list of evaluable languages on your system, also 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. +Code blocks can be evaluated and the results placed in the Org-mode buffer. +Check the value of the @code{org-babel-interpreters} for a list of languages +that can be evaluated on your system. See also @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. -There are a number of ways of evaluating code blocks. The simplest is to +There are a number of ways to evaluate code blocks. The simplest is to press @key{C-c C-c} with the point on a code block. This will call the -@code{org-babel-execute-src-block} function evaluating the block and -inserting its results into the Org-mode buffer. +@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 @code{#+function} or @code{#+lob}) lines can be used to remotely execute code blocks located in the current Org-mode buffer or in the ``Library of Babel'' -(see @ref{Library of Babel}). Both of these lines use the following syntax. +(see @ref{Library of Babel}). These lines use the following syntax. @example #+call: ()
@@ -11041,7 +11039,7 @@ blocks located in the current Org-mode buffer or in the ``Library of Babel'' @table @code @item -This name is associated with the source code block to be evaluated. +The name of the source code block to be evaluated. @item Arguments specified in this section will be passed to the code block. @item
@@ -11052,10 +11050,10 @@ Header arguments can be placed after the function invocation. See @node Library of Babel, Languages, Evaluating code blocks, Working With Source Code @section Library of Babel -The ``Library of Babel'' is two things. First it is a library of code blocks -which can be called from any Org-mode file, and second it is an actual +The ``Library of Babel'' is two things. First, it is a library of code blocks +that can be called from any Org-mode file, and second it is an actual Org-mode file located in the @samp{contrib} directory of Org-mode in which -Org-mode users may deposit functions which they believe to be generally +Org-mode users may deposit functions they believe to be generally useful. Code blocks defined in the``Library of Babel'' can be called remotely as if @@ -11577,7 +11575,7 @@ it is absent, then the directory associated with the current buffer is used. In other words, supplying @code{:dir path} temporarily has the same effect as changing the current directory with @key{M-x cd path}, and then not supplying @code{:dir}. Under the surface, @code{:dir} simply sets the value -of the emacs variable @code{default-directory}. +of the Emacs variable @code{default-directory}. When using @code{:dir}, you should supply a relative path for file output (e.g. @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in which @@ -11615,7 +11613,7 @@ and a link of the following form will be inserted in the org buffer: @end example Most of this functionality follows immediately from the fact that @code{:dir} -sets the value of the emacs variable @code{default-directory}, thanks to +sets the value of the Emacs variable @code{default-directory}, thanks to tramp. Those using XEmacs, or GNU Emacs prior to version 23 may need to install tramp separately in order for the above features to work correctly. From 7dba834dbe5ad7ac6903b4040d8f14cf6fd5195f Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Mon, 14 Jun 2010 17:23:28 -0700 Subject: [PATCH 057/138] minor bug fix --- doc/org.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/org.texi b/doc/org.texi index a167d4f2c..93fdf162d 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10946,7 +10946,7 @@ python, in which whitespace indentation in the output is critical. @item org-src-ask-before-returning-to-edit-buffer By default, Org will ask before returning to an open edit buffer. Set to a non-nil value to switch without asking. -@End table +@end table @node Exporting code blocks, Extracting source code, Editing source code, Working With Source Code @comment node-name, next, previous, up From 0751f2ebfa345f621eacbb694cecdae989e27329 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Mon, 14 Jun 2010 17:28:09 -0700 Subject: [PATCH 058/138] fixes --- lisp/babel/langs/ob-emacs-lisp.el | 2 +- lisp/babel/langs/ob-sh.el | 2 +- lisp/babel/ob-init.el | 2 ++ 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/lisp/babel/langs/ob-emacs-lisp.el b/lisp/babel/langs/ob-emacs-lisp.el index 7ac913c02..e22c06868 100644 --- a/lisp/babel/langs/ob-emacs-lisp.el +++ b/lisp/babel/langs/ob-emacs-lisp.el @@ -74,5 +74,5 @@ (org-babel-pick-name (nth 4 processed-params) (cdr (assoc :colnames params))) (org-babel-pick-name (nth 5 processed-params) (cdr (assoc :rownames params))))))) -(provide 'obemacs-lisp) +(provide 'ob-emacs-lisp) ;;; ob-emacs-lisp.el ends here diff --git a/lisp/babel/langs/ob-sh.el b/lisp/babel/langs/ob-sh.el index 789614450..25a9c886b 100644 --- a/lisp/babel/langs/ob-sh.el +++ b/lisp/babel/langs/ob-sh.el @@ -175,7 +175,7 @@ last statement in BODY." (mapcar #'org-babel-sh-strip-weird-long-prompt (mapcar #'org-babel-trim (org-babel-comint-with-output - (session org-babel-sh-eoe-output t full-body) + (session org-babel-sh-eoe-output t body) (mapc (lambda (line) (insert line) (comint-send-input)) (strip-empty (split-string body "\n"))) (insert org-babel-sh-eoe-indicator) diff --git a/lisp/babel/ob-init.el b/lisp/babel/ob-init.el index 4b709d137..393949cb4 100644 --- a/lisp/babel/ob-init.el +++ b/lisp/babel/ob-init.el @@ -7,6 +7,8 @@ (require 'ob-comint) (require 'ob-table) (require 'ob-keys) +(require 'ob-sh) +(require 'ob-emacs-lisp) (provide 'ob-init) ;;; ob-init.el ends here \ No newline at end of file From df5f954c795de0b225b02234bd18e77613052614 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Mon, 14 Jun 2010 17:50:28 -0700 Subject: [PATCH 059/138] babel: swapping function order to appease the compiler * lisp/babel/ob-tangle.el (org-babel-spec-to-string): swap flet and let order to make compiler happy --- lisp/babel/ob-tangle.el | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/lisp/babel/ob-tangle.el b/lisp/babel/ob-tangle.el index cde7f142e..1b4de97c1 100644 --- a/lisp/babel/ob-tangle.el +++ b/lisp/babel/ob-tangle.el @@ -242,22 +242,22 @@ assumes that the appropriate major-mode is set. SPEC has the form (link source-name params body)" - (flet ((insert-comment (text) - (when (and commentable - org-babel-tangle-w-comments) - (insert "\n") - (comment-region (point) - (progn (insert text) (point))) - (end-of-line nil) - (insert "\n")))) - (let ((link (nth 0 spec)) - (source-name (nth 1 spec)) - (body (nth 3 spec)) - (commentable (not (if (> (length (cdr (assoc :comments (nth 2 spec)))) - 0) - (string= (cdr (assoc :comments (nth 2 spec))) - "no") - (nth 4 spec))))) + (let ((link (nth 0 spec)) + (source-name (nth 1 spec)) + (body (nth 3 spec)) + (commentable (not (if (> (length (cdr (assoc :comments (nth 2 spec)))) + 0) + (string= (cdr (assoc :comments (nth 2 spec))) + "no") + (nth 4 spec))))) + (flet ((insert-comment (text) + (when (and commentable + org-babel-tangle-w-comments) + (insert "\n") + (comment-region (point) + (progn (insert text) (point))) + (end-of-line nil) + (insert "\n")))) (insert-comment (format "[[%s][%s]]" (org-link-escape link) source-name)) (insert (format "\n%s\n" (replace-regexp-in-string "^," "" (org-babel-chomp body)))) From 292799681eb8e87b28b4312500319fbef5e9fcd8 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Mon, 14 Jun 2010 17:51:52 -0700 Subject: [PATCH 060/138] babel: pre-setting variable for compiler * lisp/babel/ob.el (call-process-region): declaring call-process-region as a variable so that we can set it's value later --- lisp/babel/ob.el | 1 + 1 file changed, 1 insertion(+) diff --git a/lisp/babel/ob.el b/lisp/babel/ob.el index 09417e36b..e4a3aac5e 100644 --- a/lisp/babel/ob.el +++ b/lisp/babel/ob.el @@ -231,6 +231,7 @@ lisp code use the `org-babel-add-interpreter' function." (const "ruby"))) ;;; functions +(defvar call-process-region) (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 From e853f1189987d4ed8af88dd7e7487280f5d1bc9b Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Mon, 14 Jun 2010 17:52:13 -0700 Subject: [PATCH 061/138] ob-sh: adding check of existence for session variable --- lisp/babel/langs/ob-sh.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lisp/babel/langs/ob-sh.el b/lisp/babel/langs/ob-sh.el index 25a9c886b..089c23913 100644 --- a/lisp/babel/langs/ob-sh.el +++ b/lisp/babel/langs/ob-sh.el @@ -131,7 +131,7 @@ Emacs-lisp table, otherwise return the results as a string." (defun org-babel-sh-initiate-session (&optional session params) "Initiate a session named SESSION according to PARAMS." - (unless (string= session "none") + (when (and session (not (string= session "none"))) (save-window-excursion (or (org-babel-comint-buffer-livep session) (progn (shell session) (get-buffer (current-buffer))))))) From b329b7a73644af9bc3f579fa765c52f4bdc8063f Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Mon, 14 Jun 2010 18:22:41 -0700 Subject: [PATCH 062/138] babel: uniform declare-function placement at the tops of files --- lisp/babel/ob-comint.el | 2 ++ lisp/babel/ob-exp.el | 16 ++++++++-------- lisp/babel/ob-lob.el | 2 +- lisp/babel/ob-tangle.el | 2 +- 4 files changed, 12 insertions(+), 10 deletions(-) diff --git a/lisp/babel/ob-comint.el b/lisp/babel/ob-comint.el index af6183a11..8bbf9c727 100644 --- a/lisp/babel/ob-comint.el +++ b/lisp/babel/ob-comint.el @@ -36,6 +36,8 @@ (require 'ob) (require 'comint) +(declare-function org-babel-get-src-block-info "ob" (&optional hvo)) + (defun org-babel-comint-buffer-livep (buffer) "Check if BUFFER is a comint buffer with a live process." (let ((buffer (if buffer (get-buffer buffer)))) diff --git a/lisp/babel/ob-exp.el b/lisp/babel/ob-exp.el index be82b6bb7..35f11b2b2 100644 --- a/lisp/babel/ob-exp.el +++ b/lisp/babel/ob-exp.el @@ -34,6 +34,14 @@ (eval-when-compile (require 'cl)) +(defvar obe-marker nil) +(defvar org-current-export-file) +(defvar org-babel-lob-one-liner-regexp) +(defvar org-babel-ref-split-regexp) +(declare-function org-babel-get-src-block-info "ob" (&optional hvo)) +(declare-function org-babel-lob-get-info "ob-lob" ()) +(declare-function org-babel-ref-literal "ob-ref" (ref)) + (add-to-list 'org-export-interblocks '(src org-babel-exp-inline-src-blocks)) (add-to-list 'org-export-interblocks '(lob org-babel-exp-lob-one-liners)) (add-hook 'org-export-blocks-postblock-hook 'org-exp-res/src-name-cleanup) @@ -61,14 +69,6 @@ will be indented by this many characters. See `org-babel-function-def-export-name' for the definition of a source block function.") -(defvar obe-marker nil) -(defvar org-current-export-file) -(defvar org-babel-lob-one-liner-regexp) -(defvar org-babel-ref-split-regexp) -(declare-function org-babel-get-src-block-info "ob" (&optional header-vars-only)) -(declare-function org-babel-lob-get-info "ob-lob" ()) -(declare-function org-babel-ref-literal "ob-ref" (ref)) - (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... diff --git a/lisp/babel/ob-lob.el b/lisp/babel/ob-lob.el index 5de6fb0fb..018ace644 100644 --- a/lisp/babel/ob-lob.el +++ b/lisp/babel/ob-lob.el @@ -33,7 +33,7 @@ (require 'ob-table) (require 'ob-exp) -(declare-function org-babel-get-src-block-info "ob" (&optional header-vars-only)) +(declare-function org-babel-get-src-block-info "ob" (&optional hvo)) (defvar org-babel-library-of-babel nil "Library of source-code blocks. This is an association list. diff --git a/lisp/babel/ob-tangle.el b/lisp/babel/ob-tangle.el index 1b4de97c1..4c3b4a771 100644 --- a/lisp/babel/ob-tangle.el +++ b/lisp/babel/ob-tangle.el @@ -33,7 +33,7 @@ (eval-when-compile (require 'cl)) -(declare-function org-babel-get-src-block-info "ob" (&optional header-vars-only)) +(declare-function org-babel-get-src-block-info "ob" (&optional hvo)) (defvar org-babel-tangle-langs nil "List of languages supported by `org-babel-tangle'. The first From cbd9bba8349a595a67b273e83d5e91fbedecd5a6 Mon Sep 17 00:00:00 2001 From: Tom Dye Date: Tue, 15 Jun 2010 00:48:21 -0400 Subject: [PATCH 063/138] First pass through babel documentation (on airplane) --- doc/org.texi | 175 +++++++++++++++++++++++++-------------------------- 1 file changed, 84 insertions(+), 91 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 93fdf162d..ca9961f6d 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -11050,13 +11050,13 @@ Header arguments can be placed after the function invocation. See @node Library of Babel, Languages, Evaluating code blocks, Working With Source Code @section Library of Babel -The ``Library of Babel'' is two things. First, it is a library of code blocks -that can be called from any Org-mode file, and second it is an actual -Org-mode file located in the @samp{contrib} directory of Org-mode in which -Org-mode users may deposit functions they believe to be generally -useful. +The ``Library of Babel'' is a library of code blocks +that can be called from any Org-mode file. The library is housed in an +Org-mode file located in the @samp{contrib} directory of Org-mode. +Org-mode users can deposit functions they believe to be generally +useful in the library. -Code blocks defined in the``Library of Babel'' can be called remotely as if +Code blocks defined in the ``Library of Babel'' can be called remotely as if they were in the current Org-mode buffer (see @ref{Evaluating code blocks} for information on the syntax of remote code block evaluation). @@ -11066,9 +11066,7 @@ l}. @node Languages, Header arguments, Library of Babel, Working With Source Code @section Languages -Org-babel provides support for the following languages. See the language -specific documentation and an up to date list of languages is available at -@uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}. +Code blocks in the following languages are supported. @c BEGIN RECEIVE ORGTBL org-babel-lang-table @multitable @columnfractions 0.583 0.417 @@ -11155,8 +11153,12 @@ The original table from reference.org is below; I'm just using the first column @end ignore + See the language specific documentation and an up to date list of languages +that is available at +@uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}. -To add support for a particular language to your Org-babel installation first + +To add support for a particular language to your installation, first make sure that the requirements of the language are met, then add a line like the following to your Emacs configuration, (replace ``identifier'' with one of the language names from the above table). @@ -11185,10 +11187,10 @@ The values of header arguments can be set in five different ways, each more specific (and having higher priority) than the last. @menu * System-wide header arguments:: -* Language Specific header arguments:: -* Buffer Wide header arguments:: -* header arguments in Org-mode Properties:: -* Source Code Block specific header arguments:: +* Language-specific header arguments:: +* Buffer-wide header arguments:: +* Header arguments in Org-mode properties:: +* Code block specific header arguments:: @end menu @node System-wide header arguments, Language Specific header arguments, , Using Header arguments @@ -11207,7 +11209,7 @@ System-wide values of header arguments can be specified by customizing the Documentation: - Default arguments to use when evaluating a source block. + Default arguments to use when evaluating a code block. @end example For example, the following example could be used to set the default value of @@ -11222,14 +11224,14 @@ blocks. @end example @node Language Specific header arguments, Buffer Wide header arguments, System-wide header arguments, Using Header arguments -@subsubheading Language Specific header arguments -Each language can define it's own set of default header arguments. See the +@subsubheading Language-specific header arguments +Each language can define its own set of default header arguments. See the language-specific documentation available at @uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}. for information on language-specific header arguments. @node Buffer Wide header arguments, header arguments in Org-mode Properties, Language Specific header arguments, Using Header arguments -@subsubheading Buffer Wide header arguments +@subsubheading Buffer-wide header arguments FIXME @node header arguments in Org-mode Properties, Source Code Block specific header arguments, Buffer Wide header arguments, Using Header arguments @@ -11244,8 +11246,8 @@ of setting a header argument for all code blocks in a buffer is @end example When properties are used to set default header arguments, they are looked up -with inheritance, so the value of the =:cache= header argument will default -to true in all source code blocks in the subtree rooted at the following +with inheritance, so the value of the @code{:cache} header argument will default +to @code{yes} in all source code blocks in the subtree rooted at the following heading: @example @@ -11261,9 +11263,9 @@ Properties defined in this way override the properties set in in Org-mode documents. @node Source Code Block specific header arguments, , header arguments in Org-mode Properties, Using Header arguments -@subsubheading Source Code Block specific header arguments +@subsubheading Code block specific header arguments -The most common way to assign values to header arguments is at the source +The most common way to assign values to header arguments is at the code block level. This can be done by listing a sequence of header arguments and their values as part of the @code{#+begin_src} line. Properties set in this way override both the values of @@ -11282,14 +11284,13 @@ preserved on export to HTML or LaTeX. #+end_src @end example -Similarly it is possible to set header arguments for inline code blocks as -shown, +Similarly, it is possible to set header arguments for inline code blocks: @example src_haskell[:exports both]@{fac 5@} @end example -and for ``Library of Babel'' or function call lines as shown below. +Header arguments for ``Library of Babel'' or function call lines can be set as shown below: @example #+call: factorial(n=5) :exports results @@ -11297,8 +11298,7 @@ and for ``Library of Babel'' or function call lines as shown below. @node Specific Header arguments, , Using Header arguments, Header arguments @subsection Specific Header arguments -Description of every standard (non language-specific) Org-babel header -argument. +The following header arguments are defined: @menu * var:: @@ -11319,22 +11319,22 @@ argument. @node var, results, , Specific Header arguments @subsubsection var The @code{:var} header argument is used to pass arguments to -source code blocks. The specifics of how arguments are included -in a source code block are language specific and are +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 or +languages. The values passed to arguments can be @itemize @bullet @item literal values @item values from org-mode tables @item the results of other source code blocks @end itemize -These values can be indexed in a manner similar to arrays -- see the argument +These values can be indexed in a manner similar to arrays---see the argument ``indexable variable values'' heading below. -The following syntax is used to pass arguments to source code -blocks using the @code{:var} header argument. +The following syntax is used to pass arguments to code blocks using the +@code{:var} header argument. @example :var name=assign @@ -11376,7 +11376,7 @@ parentheses: : 8 @end example -In addition, an argument can be passed to the source code block referenced +In addition, an argument can be passed to the code block referenced by @code{:var}. The argument is passed within the parentheses following the source code block name: @@ -11399,16 +11399,16 @@ source code block name: @end example @end itemize -@subsubheading alternate argument syntax +@subsubheading Alternate argument syntax It is also possible to specify arguments in a potentially more natural way using the @code{#+source:} line of a source code block. As in the following -example arguments can be packed inside of parenthesis following the source -name. +example arguments can be packed inside of parenthesis, separated by commas, +following the source name. @example - #+source: double(input=0) + #+source: double(input=0, x=2) #+begin_src emacs-lisp - (* 2 input) + (* 2 (+ input x)) #+end_src @end example @@ -11421,7 +11421,7 @@ block. The following example assigns the second and third rows of the table :var data=example-table[1:2] @end example -Note: ranges are indexed using the =:= operator. +Note: ranges are indexed using the @code{:} operator. Note: indices are 0 based. @@ -11432,12 +11432,12 @@ The following example assigns the second column of the first row of :var data=example-table[0,1] @end example -It is possible to index into the results of source code blocks as well as +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. For more information on indexing behavior see the documentation for the -@code{org-babel-ref-index-list} function -- provided below. +@code{org-babel-ref-index-list} function, provided below. @example org-babel-ref-index-list is a Lisp function in `org-babel-ref.el'. @@ -11451,16 +11451,11 @@ For more information on indexing behavior see the documentation for the which case the entire range is returned. @end example -Note: In Emacs, the documentation for any function or variable can be read -using the @code{describe-function} (M-x describe function) and -@code{describe-variable} (M-x describe variable) functions, respectively. - @node results, file, var, Specific Header arguments @subsubsection results -There are three types of results header argument: - -Note: only one option from each type may be supplied per source code block. +There are three types of results header argument. Only one option of each +type may be supplied per code block. @itemize @bullet @item collection @@ -11468,7 +11463,7 @@ arguments specify how the results should be collected from the source code block @item type header arguments specify what type of result the source code block will -return -- which has implications for how they will be inserted into the +return---which has implications for how they will be inserted into the Org-mode buffer @item handling header arguments specify how the results of evaluating the source code block @@ -11482,14 +11477,14 @@ should be collected from the source code block. @itemize @bullet @item value This is the default. The result is the value of the last statement in the -source code block. This header argument places Org-babel in functional mode. -Note that in some languages, e.g., python, use of this result type requires -that a @code{return} statement be included in the body of the source code -block. E.g., @code{:results value}. +source code block. This header argument places the evaluation in functional +mode. Note that in some languages, e.g., python, use of this result type +requires that a @code{return} statement be included in the body of the source +code block. E.g., @code{:results value}. @item output The result is the collection of everything printed to STDOUT during the -execution of the source code block. This header argument places Org-babel in -scripting mode. E.g., @code{:results output}. +execution of the source code block. This header argument places the +evaluation in scripting mode. E.g., @code{:results output}. @end itemize @subsubheading type @@ -11501,10 +11496,10 @@ table or scalar depending on their value. @itemize @bullet @item table, vector The results should be interpreted as an Org-mode table. If a single value is -returned, Org-babel will convert it into a table with one row and one column. +returned, it will be converted into a table with one row and one column. E.g., @code{:results value table}. @item scalar, verbatim -The results should be interpreted literally -- meaning they will not be +The results should be interpreted literally---they will not be converted into a table. The results will be inserted into the Org-mode buffer as quoted text. E.g., @code{:results value verbatim}. @item file @@ -11565,17 +11560,16 @@ individual languages for details. In contrast, general purpose languages such as python and ruby require that the code explicitly create output corresponding to the path indicated by @code{:file}. -While the @code{:file} header argument can be used to specify the path to the -output file, @node dir and remote execution, exports, file, Specific Header arguments @subsubsection dir and remote execution -@code{:dir} specifies the /default directory/ during code block execution. If -it is absent, then the directory associated with the current buffer is -used. In other words, supplying @code{:dir path} temporarily has the same -effect as changing the current directory with @key{M-x cd path}, and then not -supplying @code{:dir}. Under the surface, @code{:dir} simply sets the value -of the Emacs variable @code{default-directory}. +While the @code{:file} header argument can be used to specify the path to the +output file, @code{:dir} specifies the default directory during code block +execution. If it is absent, then the directory associated with the current +buffer is used. In other words, supplying @code{:dir path} temporarily has +the same effect as changing the current directory with @key{M-x cd path}, and +then not supplying @code{:dir}. Under the surface, @code{:dir} simply sets +the value of the Emacs variable @code{default-directory}. When using @code{:dir}, you should supply a relative path for file output (e.g. @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in which @@ -11600,12 +11594,12 @@ which case the code will be evaluated on the remote machine. An example is #+end_src @end example -Text results will be returned to the local org buffer as normal, and -file output will be created on the remote machine with relative paths -interpreted relative to the remote directory. An org link to the -remote file will be created. +Text results will be returned to the local Org-mode buffer as usual, and file +output will be created on the remote machine with relative paths interpreted +relative to the remote directory. An Org-mode link to the remote file will be +created. -So in the above example a plot will be created on the remote machine, +So, in the above example a plot will be created on the remote machine, and a link of the following form will be inserted in the org buffer: @example @@ -11615,7 +11609,7 @@ and a link of the following form will be inserted in the org buffer: Most of this functionality follows immediately from the fact that @code{:dir} sets the value of the Emacs variable @code{default-directory}, thanks to tramp. Those using XEmacs, or GNU Emacs prior to version 23 may need to -install tramp separately in order for the above features to work correctly. +install tramp separately in order for the these features to work correctly. @subsubheading Further points @@ -11627,11 +11621,11 @@ currently made to alter the directory associated with an existing session. @item @code{:dir} should typically not be used to create files during export with @code{:exports results} or @code{:exports both}. The reason is that, in order -to retain portability of exported material between machines, during export, -links inserted into the buffer will *not* be expanded against default -directory. Therefore, if default-directory is altered using @code{:dir}, it -it probable that the file will be created in a location to which the link -does not point. +to retain portability of exported material between machines, during export +links inserted into the buffer will *not* be expanded against @code{default +directory}. Therefore, if @code{default-directory} is altered using +@code{:dir}, it is probable that the file will be created in a location to +which the link does not point. @end itemize @node exports, tangle, dir and remote execution, Specific Header arguments @@ -11753,7 +11747,7 @@ changed since the last time it was evaluated, it will not be re-evaluated. @node hlines, colnames, cache, Specific Header arguments @subsubsection hlines Tables are frequently represented with one or more horizontal lines, or -hlines. The @code{:hlines} argument to an Org-babel code block accepts the +hlines. The @code{:hlines} argument to a code block accepts the values @code{yes} or @code{no}, with a default value of @code{no}. @itemize @bullet @@ -11814,9 +11808,9 @@ The @code{:colnames} header argument accepts the values @code{yes}, @itemize @bullet @item @code{nil} -If an input table /looks like/ it has column names +If an input table looks like it has column names (because its second row is an hline), then the column -names will be removed from the table by Org-babel before +names will be removed from the table before processing, then reapplied to the results. @example @@ -11857,9 +11851,8 @@ or @code{no}, with a default value of @code{no}. No row name pre-processing will take place. @item @code{yes} -The first column of the table is removed from the -table by Org-babel before processing, and is then reapplied -to the results. +The first column of the table is removed from the table before processing, +and is then reapplied to the results. @example #+tblname: with-rownames @@ -11967,11 +11960,11 @@ familiar Noweb syntax: <> @end example -When a source code block is tangled or evaluated, ``noweb'' references are -expanded depends upon the value of the @code{:noweb} header argument. If -@code{:noweb yes}, then a Noweb reference is expanded before evaluation. If -@code{:noweb no}, the default, then the reference is not expanded before -evaluation. +When a source code block is tangled or evaluated, whether or not ``noweb'' +references are expanded depends upon the value of the @code{:noweb} header +argument. If @code{:noweb yes}, then a Noweb reference is expanded before +evaluation. If @code{:noweb no}, the default, then the reference is not +expanded before evaluation. Note: the default value, @code{:noweb no}, was chosen to ensure that Org-babel does not break correct code in a language, such as Ruby, where @@ -11982,8 +11975,8 @@ the default value. @node Key bindings & useful functions, Batch execution, Noweb reference syntax, Working With Source Code @section Key bindings & useful functions -Org-babel re-binds many common Org-mode key sequences depending on -the context. Within a source-code block the following sequences +Many common Org-mode key sequences are re-bound depending on +the context. Within a code block the following sequences are rebound: @multitable @columnfractions 0.25 0.75 @@ -12022,7 +12015,7 @@ kept pressed, resulting in the following additional keybindings. @node Batch execution, , Key bindings & useful functions, Working With Source Code @section Batch execution -It is possible to call Org-babel functions from the command line. This shell +It is possible to call functions from the command line. This shell script calls @code{org-babel-tangle} on every one of its arguments. Be sure to adjust the paths to fit your system. From 7513cdb12af4c1235b07740115d0f4644798cc35 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Wed, 16 Jun 2010 09:15:12 -0700 Subject: [PATCH 064/138] ob-sqlite.el -- sqlite3 support to org-babel * lisp/babel/langs/ob-sqlite.el: sqlite3 support for org-babel --- lisp/babel/langs/ob-sqlite.el | 85 +++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 lisp/babel/langs/ob-sqlite.el diff --git a/lisp/babel/langs/ob-sqlite.el b/lisp/babel/langs/ob-sqlite.el new file mode 100644 index 000000000..1311c5aa5 --- /dev/null +++ b/lisp/babel/langs/ob-sqlite.el @@ -0,0 +1,85 @@ +;;; ob-sqlite.el --- org-babel functions for sqlite database interaction + +;; Copyright (C) 2009 Eric Schulte + +;; Author: Eric Schulte +;; Keywords: literate programming, reproducible research +;; Homepage: http://orgmode.org +;; Version: 0.01 + +;;; License: + +;; This program is free software; you can redistribute it and/or modify +;; it under the terms of the GNU General Public License as published by +;; the Free Software Foundation; either version 3, or (at your option) +;; any later version. +;; +;; This program is distributed in the hope that it will be useful, +;; but WITHOUT ANY WARRANTY; without even the implied warranty of +;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;; GNU General Public License for more details. +;; +;; You should have received a copy of the GNU General Public License +;; along with GNU Emacs; see the file COPYING. If not, write to the +;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +;; Boston, MA 02110-1301, USA. + +;;; Commentary: + +;; Org-Babel support for evaluating sqlite source code. + +;;; Code: +(require 'ob) + +(org-babel-add-interpreter "sqlite") + +(add-to-list 'org-babel-tangle-langs '("sqlite" "sqlite")) + +(defun org-babel-expand-body:sqlite + (body params &optional processed-params) body) + +(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") + (let ((result-params (split-string (or (cdr (assoc :results params)) ""))) + (vars (org-babel-ref-variables params))) + (with-temp-buffer + (insert + (shell-command-to-string + (format "%s -csv %s %S" + org-babel-sqlite3-command + (cdr (assoc :db params)) + (org-babel-sqlite-expand-vars body vars)))) + (if (or (member "scalar" result-params) + (member "code" result-params)) + (buffer-string) + (org-table-convert-region (point-min) (point-max)) + (org-babel-sqlite-table-or-scalar (org-table-to-lisp)))))) + +(defun org-babel-sqlite-expand-vars (body vars) + "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))) + vars) + body) + +(defun org-babel-sqlite-table-or-scalar (result) + "If RESULT looks like a trivial table, then unwrap it." + (if (and (equal 1 (length result)) + (equal 1 (length (car result)))) + (caar result) + result)) + +(defun org-babel-prep-session:sqlite (session params) + "Prepare SESSION according to the header arguments specified in PARAMS." + (error "sqlite sessions not yet implemented")) + +(provide 'ob-sqlite) +;;; ob-sqlite.el ends here From 3afe60dcde706fd49f8e03d7951cdfa159b07864 Mon Sep 17 00:00:00 2001 From: Tom Dye Date: Wed, 16 Jun 2010 11:22:14 -0700 Subject: [PATCH 065/138] babel-doc: Changed description of function that asks before switching buffers --- doc/org.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/org.texi b/doc/org.texi index ca9961f6d..1214db821 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10945,7 +10945,7 @@ This variable is especially useful for tangling languages such as python, in which whitespace indentation in the output is critical. @item org-src-ask-before-returning-to-edit-buffer By default, Org will ask before returning to an open edit buffer. Set -to a non-nil value to switch without asking. +this variable to nil to switch without asking. @end table @node Exporting code blocks, Extracting source code, Editing source code, Working With Source Code From 0f633df2641d0dc4eceed64951bffa700c75a827 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Wed, 16 Jun 2010 11:29:59 -0700 Subject: [PATCH 066/138] babel-doc: now compiling again --- doc/org.texi | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 1214db821..340c74eb5 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -11187,10 +11187,10 @@ The values of header arguments can be set in five different ways, each more specific (and having higher priority) than the last. @menu * System-wide header arguments:: -* Language-specific header arguments:: +* Language Specific header arguments:: * Buffer-wide header arguments:: -* Header arguments in Org-mode properties:: -* Code block specific header arguments:: +* Header arguments in Org-mode Properties:: +* Code Block specific header arguments:: @end menu @node System-wide header arguments, Language Specific header arguments, , Using Header arguments @@ -11223,21 +11223,21 @@ blocks. (assq-delete-all :noweb org-babel-default-header-args))) @end example -@node Language Specific header arguments, Buffer Wide header arguments, System-wide header arguments, Using Header arguments -@subsubheading Language-specific header arguments +@node Language Specific header arguments, Buffer-wide header arguments, System-wide header arguments, Using Header arguments +@subsubheading Language Specific header arguments Each language can define its own set of default header arguments. See the language-specific documentation available at @uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}. for information on language-specific header arguments. -@node Buffer Wide header arguments, header arguments in Org-mode Properties, Language Specific header arguments, Using Header arguments +@node Buffer-wide header arguments, Header arguments in Org-mode Properties, Language Specific header arguments, Using Header arguments @subsubheading Buffer-wide header arguments FIXME -@node header arguments in Org-mode Properties, Source Code Block specific header arguments, Buffer Wide header arguments, Using Header arguments +@node Header arguments in Org-mode Properties, Code Block specific header arguments, Buffer-wide header arguments, Using Header arguments @subsubheading header arguments in Org-mode Properties -Header arguments are also read from Org-mode properties (see @ref{Property +Header arguments are also read from Org-mode Properties (see @ref{Property syntax}), which can be set on a buffer-wide or per-heading basis. An example of setting a header argument for all code blocks in a buffer is @@ -11262,8 +11262,8 @@ Properties defined in this way override the properties set in @code{org-set-property} function bound to @key{C-c C-x p} to set properties in Org-mode documents. -@node Source Code Block specific header arguments, , header arguments in Org-mode Properties, Using Header arguments -@subsubheading Code block specific header arguments +@node Code Block specific header arguments, , Header arguments in Org-mode Properties, Using Header arguments +@subsubheading Code Block specific header arguments The most common way to assign values to header arguments is at the code block level. This can be done by listing a sequence of header From 5769cccd6aa7acf084eb1edf1b90dae5273b7074 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Wed, 16 Jun 2010 13:12:31 -0700 Subject: [PATCH 067/138] babel: ob-sqlite now handles column names * lisp/babel/langs/ob-sqlite.el (org-babel-execute:sqlite): now handling column names (org-babel-sqlite-offset-colnames): now handling column names --- lisp/babel/langs/ob-sqlite.el | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/lisp/babel/langs/ob-sqlite.el b/lisp/babel/langs/ob-sqlite.el index 1311c5aa5..fa95b3f33 100644 --- a/lisp/babel/langs/ob-sqlite.el +++ b/lisp/babel/langs/ob-sqlite.el @@ -45,19 +45,23 @@ called by `org-babel-execute-src-block'." (message "executing Sqlite source code block") (let ((result-params (split-string (or (cdr (assoc :results params)) ""))) - (vars (org-babel-ref-variables params))) + (vars (org-babel-ref-variables params)) + (headers-p (equal "yes" (cdr (assoc :colnames params))))) (with-temp-buffer (insert (shell-command-to-string - (format "%s -csv %s %S" + (format "%s %s -csv %s %S" org-babel-sqlite3-command + (if headers-p "-header" "") (cdr (assoc :db params)) (org-babel-sqlite-expand-vars body vars)))) (if (or (member "scalar" result-params) (member "code" result-params)) (buffer-string) (org-table-convert-region (point-min) (point-max)) - (org-babel-sqlite-table-or-scalar (org-table-to-lisp)))))) + (org-babel-sqlite-table-or-scalar + (org-babel-sqlite-offset-colnames + (org-table-to-lisp) headers-p)))))) (defun org-babel-sqlite-expand-vars (body vars) "Expand the variables held in VARS in BODY." @@ -77,6 +81,12 @@ called by `org-babel-execute-src-block'." (caar result) result)) +(defun org-babel-sqlite-offset-colnames (table headers-p) + "If HEADERS-P is non-nil then offset the first row as column names." + (if headers-p + (cons (car table) (cons 'hline (cdr table))) + table)) + (defun org-babel-prep-session:sqlite (session params) "Prepare SESSION according to the header arguments specified in PARAMS." (error "sqlite sessions not yet implemented")) From a86734f52667040ba324d88c8e18fe570acce2c8 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Wed, 16 Jun 2010 17:02:51 -0700 Subject: [PATCH 068/138] babel: eliminated compiler warning about `org-babel-get-src-block-info' --- Makefile | 8 ++-- lisp/babel/ob-exp.el | 3 +- lisp/babel/ob-init.el | 9 +++- lisp/babel/ob-keys.el | 2 + lisp/babel/ob-ref.el | 2 + lisp/babel/ob-table.el | 2 + lisp/babel/ob.el | 97 ++++++++++++++++++++---------------------- 7 files changed, 65 insertions(+), 58 deletions(-) diff --git a/Makefile b/Makefile index d95390021..25a07705d 100644 --- a/Makefile +++ b/Makefile @@ -116,14 +116,14 @@ LISPF = org.el \ org-w3m.el \ org-wl.el \ org-xoxo.el \ - babel/ob-comint.el \ babel/ob.el \ - babel/ob-exp.el \ - babel/ob-keys.el \ + babel/ob-table.el \ babel/ob-lob.el \ babel/ob-ref.el \ - babel/ob-table.el \ + babel/ob-exp.el \ babel/ob-tangle.el \ + babel/ob-comint.el \ + babel/ob-keys.el \ babel/langs/ob-emacs-lisp.el \ babel/langs/ob-sh.el diff --git a/lisp/babel/ob-exp.el b/lisp/babel/ob-exp.el index 35f11b2b2..bf4740d0e 100644 --- a/lisp/babel/ob-exp.el +++ b/lisp/babel/ob-exp.el @@ -34,11 +34,12 @@ (eval-when-compile (require 'cl)) +(declare-function org-babel-get-src-block-info "ob" (&optional hvo)) + (defvar obe-marker nil) (defvar org-current-export-file) (defvar org-babel-lob-one-liner-regexp) (defvar org-babel-ref-split-regexp) -(declare-function org-babel-get-src-block-info "ob" (&optional hvo)) (declare-function org-babel-lob-get-info "ob-lob" ()) (declare-function org-babel-ref-literal "ob-ref" (ref)) diff --git a/lisp/babel/ob-init.el b/lisp/babel/ob-init.el index 393949cb4..64cd197b7 100644 --- a/lisp/babel/ob-init.el +++ b/lisp/babel/ob-init.el @@ -1,11 +1,16 @@ ;;; ob-init.el --- working with code blocks in org-mode +;; add the langs/ directory to the load path +(add-to-list 'load-path (expand-file-name + "langs" + (file-name-directory (or (buffer-file-name) + load-file-name)))) (require 'ob) +(require 'ob-table) +(require 'ob-lob) (require 'ob-ref) (require 'ob-exp) (require 'ob-tangle) -(require 'ob-lob) (require 'ob-comint) -(require 'ob-table) (require 'ob-keys) (require 'ob-sh) (require 'ob-emacs-lisp) diff --git a/lisp/babel/ob-keys.el b/lisp/babel/ob-keys.el index 233c4c5da..33bd714d4 100644 --- a/lisp/babel/ob-keys.el +++ b/lisp/babel/ob-keys.el @@ -34,6 +34,8 @@ ;;; Code: (require 'ob) +(declare-function org-babel-get-src-block-info "ob" (&optional hvo)) + (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. diff --git a/lisp/babel/ob-ref.el b/lisp/babel/ob-ref.el index c75930e33..506e8a32c 100644 --- a/lisp/babel/ob-ref.el +++ b/lisp/babel/ob-ref.el @@ -56,6 +56,8 @@ (eval-when-compile (require 'cl)) +(declare-function org-babel-get-src-block-info "ob" (&optional hvo)) + (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." diff --git a/lisp/babel/ob-table.el b/lisp/babel/ob-table.el index 22aa4ca0e..65fa7dca3 100644 --- a/lisp/babel/ob-table.el +++ b/lisp/babel/ob-table.el @@ -55,6 +55,8 @@ ;;; Code: (require 'ob) +(declare-function org-babel-get-src-block-info "ob" (&optional hvo)) + (defun org-babel-table-truncate-at-newline (string) "If STRING ends in a newline character, then remove the newline character and replace it with ellipses." diff --git a/lisp/babel/ob.el b/lisp/babel/ob.el index e4a3aac5e..d86b81610 100644 --- a/lisp/babel/ob.el +++ b/lisp/babel/ob.el @@ -49,11 +49,52 @@ (declare-function tramp-file-name-user "tramp" (vec)) (declare-function tramp-file-name-host "tramp" (vec)) -;; add the langs/ directory to the load path -(add-to-list 'load-path (expand-file-name - "langs" - (file-name-directory (or (buffer-file-name) - load-file-name)))) +(defun org-babel-get-src-block-info (&optional header-vars-only) + "Get information of the current source block. + +Returns a list + (language body header-arguments-alist switches name function-args indent). +Unless HEADER-VARS-ONLY is non-nil, any variable +references provided in 'function call style' (i.e. in a +parenthesised argument list following the src block name) are +added to the header-arguments-alist." + (let ((case-fold-search t) head info args indent) + (if (setq head (org-babel-where-is-src-block-head)) + (save-excursion + (goto-char head) + (setq info (org-babel-parse-src-block-match)) + (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]+\\)\\(\(\\(.*\\)\)\\|\\)")) + (progn + (setq info (append info (list (org-babel-clean-text-properties + (match-string 2))))) + ;; Note that e.g. "name()" and "name( )" result in + ;; ((:var . "")). We maintain that behaviour, and the + ;; resulting non-nil sixth element is relied upon in + ;; org-babel-exp-code to detect a functional-style + ;; block in those cases. However, "name" without any + ;; parentheses would result in the same thing, so we + ;; explicitly avoid that. + (if (setq args (match-string 4)) + (setq info + (append info (list + (mapcar + (lambda (ref) (cons :var ref)) + (org-babel-ref-split-args args)))))) + (unless header-vars-only + (setf (nth 2 info) + (org-babel-merge-params (nth 5 info) (nth 2 info))))) + (setq info (append info (list nil nil)))) + (append info (list indent))) + (if (save-excursion ;; inline source block + (re-search-backward "[ \f\t\n\r\v]" nil t) + (looking-at org-babel-inline-src-block-regexp)) + (org-babel-parse-inline-src-block-match) + nil)))) (defun org-babel-execute-src-block-maybe () "Detect if this is context for a org-babel src-block and if so @@ -427,52 +468,6 @@ the current subtree." (org-babel-execute-buffer) (widen)))) -(defun org-babel-get-src-block-info (&optional header-vars-only) - "Get information of the current source block. -Returns a list - (language body header-arguments-alist switches name function-args indent). -Unless HEADER-VARS-ONLY is non-nil, any variable -references provided in 'function call style' (i.e. in a -parenthesised argument list following the src block name) are -added to the header-arguments-alist." - (let ((case-fold-search t) head info args indent) - (if (setq head (org-babel-where-is-src-block-head)) - (save-excursion - (goto-char head) - (setq info (org-babel-parse-src-block-match)) - (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]+\\)\\(\(\\(.*\\)\)\\|\\)")) - (progn - (setq info (append info (list (org-babel-clean-text-properties - (match-string 2))))) - ;; Note that e.g. "name()" and "name( )" result in - ;; ((:var . "")). We maintain that behaviour, and the - ;; resulting non-nil sixth element is relied upon in - ;; org-babel-exp-code to detect a functional-style - ;; block in those cases. However, "name" without any - ;; parentheses would result in the same thing, so we - ;; explicitly avoid that. - (if (setq args (match-string 4)) - (setq info - (append info (list - (mapcar - (lambda (ref) (cons :var ref)) - (org-babel-ref-split-args args)))))) - (unless header-vars-only - (setf (nth 2 info) - (org-babel-merge-params (nth 5 info) (nth 2 info))))) - (setq info (append info (list nil nil)))) - (append info (list indent))) - (if (save-excursion ;; inline source block - (re-search-backward "[ \f\t\n\r\v]" nil t) - (looking-at org-babel-inline-src-block-regexp)) - (org-babel-parse-inline-src-block-match) - nil)))) ;; indicate that no source block was found - (defun org-babel-sha1-hash (&optional info) "Generate an sha1 hash based on the value of info." (interactive) From 32c985ffd919dee618779239b09942766ef9119f Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Wed, 16 Jun 2010 17:12:21 -0700 Subject: [PATCH 069/138] babel: more compiler cleanup -- now only throwing 1 warning (which doesn't make sense anyways) --- lisp/babel/ob-comint.el | 6 ++---- lisp/babel/ob-exp.el | 2 -- lisp/babel/ob-keys.el | 2 -- lisp/babel/ob-lob.el | 2 -- lisp/babel/ob-ref.el | 2 -- lisp/babel/ob-table.el | 2 -- lisp/babel/ob-tangle.el | 2 -- lisp/babel/ob.el | 20 ++++++++++---------- 8 files changed, 12 insertions(+), 26 deletions(-) diff --git a/lisp/babel/ob-comint.el b/lisp/babel/ob-comint.el index 8bbf9c727..e847bc44f 100644 --- a/lisp/babel/ob-comint.el +++ b/lisp/babel/ob-comint.el @@ -36,8 +36,6 @@ (require 'ob) (require 'comint) -(declare-function org-babel-get-src-block-info "ob" (&optional hvo)) - (defun org-babel-comint-buffer-livep (buffer) "Check if BUFFER is a comint buffer with a live process." (let ((buffer (if buffer (get-buffer buffer)))) @@ -69,8 +67,8 @@ or user `keyboard-quit' during execution of body." (declare (indent 1)) (let ((buffer (car meta)) (eoe-indicator (cadr meta)) - (remove-echo (caddr meta)) - (full-body (cadddr meta))) + (remove-echo (cadr (cdr meta))) + (full-body (cadr (cdr (cdr meta))))) `(org-babel-comint-in-buffer ,buffer (let ((string-buffer "") dangling-text) (flet ((my-filt (text) diff --git a/lisp/babel/ob-exp.el b/lisp/babel/ob-exp.el index bf4740d0e..18220744d 100644 --- a/lisp/babel/ob-exp.el +++ b/lisp/babel/ob-exp.el @@ -34,8 +34,6 @@ (eval-when-compile (require 'cl)) -(declare-function org-babel-get-src-block-info "ob" (&optional hvo)) - (defvar obe-marker nil) (defvar org-current-export-file) (defvar org-babel-lob-one-liner-regexp) diff --git a/lisp/babel/ob-keys.el b/lisp/babel/ob-keys.el index 33bd714d4..233c4c5da 100644 --- a/lisp/babel/ob-keys.el +++ b/lisp/babel/ob-keys.el @@ -34,8 +34,6 @@ ;;; Code: (require 'ob) -(declare-function org-babel-get-src-block-info "ob" (&optional hvo)) - (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. diff --git a/lisp/babel/ob-lob.el b/lisp/babel/ob-lob.el index 018ace644..064c51228 100644 --- a/lisp/babel/ob-lob.el +++ b/lisp/babel/ob-lob.el @@ -33,8 +33,6 @@ (require 'ob-table) (require 'ob-exp) -(declare-function org-babel-get-src-block-info "ob" (&optional hvo)) - (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'.") diff --git a/lisp/babel/ob-ref.el b/lisp/babel/ob-ref.el index 506e8a32c..c75930e33 100644 --- a/lisp/babel/ob-ref.el +++ b/lisp/babel/ob-ref.el @@ -56,8 +56,6 @@ (eval-when-compile (require 'cl)) -(declare-function org-babel-get-src-block-info "ob" (&optional hvo)) - (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." diff --git a/lisp/babel/ob-table.el b/lisp/babel/ob-table.el index 65fa7dca3..22aa4ca0e 100644 --- a/lisp/babel/ob-table.el +++ b/lisp/babel/ob-table.el @@ -55,8 +55,6 @@ ;;; Code: (require 'ob) -(declare-function org-babel-get-src-block-info "ob" (&optional hvo)) - (defun org-babel-table-truncate-at-newline (string) "If STRING ends in a newline character, then remove the newline character and replace it with ellipses." diff --git a/lisp/babel/ob-tangle.el b/lisp/babel/ob-tangle.el index 4c3b4a771..40978813b 100644 --- a/lisp/babel/ob-tangle.el +++ b/lisp/babel/ob-tangle.el @@ -33,8 +33,6 @@ (eval-when-compile (require 'cl)) -(declare-function org-babel-get-src-block-info "ob" (&optional hvo)) - (defvar org-babel-tangle-langs nil "List of languages supported by `org-babel-tangle'. The first element of each language's list is a string indicating the name diff --git a/lisp/babel/ob.el b/lisp/babel/ob.el index d86b81610..d24ce191a 100644 --- a/lisp/babel/ob.el +++ b/lisp/babel/ob.el @@ -49,6 +49,16 @@ (declare-function tramp-file-name-user "tramp" (vec)) (declare-function tramp-file-name-host "tramp" (vec)) +(defvar org-babel-source-name-regexp + "^[ \t]*#\\+\\(srcname\\|source\\|function\\):[ \t]*" + "Regular expression used to match a source name line.") + +(defvar org-babel-src-block-regexp nil + "Regexp used to test when inside of a org-babel src-block") + +(defvar org-babel-inline-src-block-regexp nil + "Regexp used to test when on an inline org-babel src-block") + (defun org-babel-get-src-block-info (&optional header-vars-only) "Get information of the current source block. @@ -176,22 +186,12 @@ header arguments as well.") (defvar org-babel-current-buffer-properties) (make-variable-buffer-local 'org-babel-current-buffer-properties) -(defvar org-babel-src-block-regexp nil - "Regexp used to test when inside of a org-babel src-block") - -(defvar org-babel-inline-src-block-regexp nil - "Regexp used to test when on an inline org-babel src-block") - (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.") -(defvar org-babel-source-name-regexp - "^[ \t]*#\\+\\(srcname\\|source\\|function\\):[ \t]*" - "Regular expression used to match a source name line.") - (defvar org-babel-min-lines-for-block-output 10 "If number of lines of output is equal to or exceeds this value, the output is placed in a #+begin_example...#+end_example From 4482058c0cb953e9737c65324094a954e9189088 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Wed, 16 Jun 2010 17:15:10 -0700 Subject: [PATCH 070/138] babel: some final compiler tweaks -- no more compiler warnings --- Makefile | 3 +-- lisp/babel/ob-init.el | 13 +++++++------ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/Makefile b/Makefile index 25a07705d..436ed6af7 100644 --- a/Makefile +++ b/Makefile @@ -124,8 +124,7 @@ LISPF = org.el \ babel/ob-tangle.el \ babel/ob-comint.el \ babel/ob-keys.el \ - babel/langs/ob-emacs-lisp.el \ - babel/langs/ob-sh.el + babel/langs/ob-emacs-lisp.el LISPFILES0 = $(LISPF:%=lisp/%) LISPFILES = $(LISPFILES0) lisp/org-install.el diff --git a/lisp/babel/ob-init.el b/lisp/babel/ob-init.el index 64cd197b7..a229dea38 100644 --- a/lisp/babel/ob-init.el +++ b/lisp/babel/ob-init.el @@ -1,9 +1,4 @@ ;;; ob-init.el --- working with code blocks in org-mode -;; add the langs/ directory to the load path -(add-to-list 'load-path (expand-file-name - "langs" - (file-name-directory (or (buffer-file-name) - load-file-name)))) (require 'ob) (require 'ob-table) (require 'ob-lob) @@ -12,7 +7,13 @@ (require 'ob-tangle) (require 'ob-comint) (require 'ob-keys) -(require 'ob-sh) + +;; add the langs/ directory to the load path +(add-to-list + 'load-path (expand-file-name + "langs" + (file-name-directory (or (buffer-file-name) + load-file-name)))) (require 'ob-emacs-lisp) (provide 'ob-init) From b5efd50fb5df175c5cf57bf1033c047a31d5aee1 Mon Sep 17 00:00:00 2001 From: Tom Dye Date: Wed, 16 Jun 2010 17:38:10 -1000 Subject: [PATCH 071/138] Last chance clean-up of org.texi --- doc/org.texi | 1067 ++++++++++++++++++++++++++------------------------ 1 file changed, 566 insertions(+), 501 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 340c74eb5..0702d2414 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -1,7 +1,7 @@ \input texinfo @c %**start of header -@setfilename ../../info/org +@setfilename info/org @settitle The Org Manual @set VERSION 6.36trans @@ -95,349 +95,400 @@ license to the document, as described in section 6 of the license. @end ifnottex @menu -* Introduction:: Getting started -* Document Structure:: A tree works like your brain -* Tables:: Pure magic for quick formatting -* Hyperlinks:: Notes in context -* TODO Items:: Every tree branch can be a TODO item -* Tags:: Tagging headlines and matching sets of tags -* Properties and Columns:: Storing information about an entry -* Dates and Times:: Making items useful for planning -* Capture - Refile - Archive:: The ins and outs for projects -* Agenda Views:: Collecting information into views -* Markup:: Prepare text for rich export -* Exporting:: Sharing and publishing of notes -* Publishing:: Create a web site of linked Org files -* Working With Source Code:: Code evaluation inside Org-mode -* Miscellaneous:: All the rest which did not fit elsewhere -* Hacking:: How to hack your way around -* MobileOrg:: Viewing and capture on a mobile device -* History and Acknowledgments:: How Org came into being -* Main Index:: An index of Org's concepts and features -* Key Index:: Key bindings and where they are described -* Variable Index:: Variables mentioned in the manual +* Introduction:: Getting started +* Document Structure:: A tree works like your brain +* Tables:: Pure magic for quick formatting +* Hyperlinks:: Notes in context +* TODO Items:: Every tree branch can be a TODO item +* Tags:: Tagging headlines and matching sets of tags +* Properties and Columns:: Storing information about an entry +* Dates and Times:: Making items useful for planning +* Capture - Refile - Archive:: The ins and outs for projects +* Agenda Views:: Collecting information into views +* Markup:: Prepare text for rich export +* Exporting:: Sharing and publishing of notes +* Publishing:: Create a web site of linked Org files +* Working With Source Code:: Export, evaluate, and tangle code blocks +* Miscellaneous:: All the rest which did not fit elsewhere +* Hacking:: How to hack your way around +* MobileOrg:: Viewing and capture on a mobile device +* History and Acknowledgments:: How Org came into being +* Main Index:: An index of Org's concepts and features +* Key Index:: Key bindings and where they are described +* Variable Index:: Variables mentioned in the manual @detailmenu --- The Detailed Node Listing --- Introduction -* Summary:: Brief summary of what Org does -* Installation:: How to install a downloaded version of Org -* Activation:: How to activate Org for certain buffers -* Feedback:: Bug reports, ideas, patches etc. -* Conventions:: Type-setting conventions in the manual +* Summary:: Brief summary of what Org does +* Installation:: How to install a downloaded version of Org +* Activation:: How to activate Org for certain buffers +* Feedback:: Bug reports, ideas, patches etc. +* Conventions:: Type-setting conventions in the manual Document Structure -* Outlines:: Org is based on Outline mode -* Headlines:: How to typeset Org tree headlines -* Visibility cycling:: Show and hide, much simplified -* Motion:: Jumping to other headlines -* Structure editing:: Changing sequence and level of headlines -* Sparse trees:: Matches embedded in context -* Plain lists:: Additional structure within an entry -* Drawers:: Tucking stuff away -* Blocks:: Folding blocks -* Footnotes:: How footnotes are defined in Org's syntax -* Orgstruct mode:: Structure editing outside Org +* Outlines:: Org is based on Outline mode +* Headlines:: How to typeset Org tree headlines +* Visibility cycling:: Show and hide, much simplified +* Motion:: Jumping to other headlines +* Structure editing:: Changing sequence and level of headlines +* Sparse trees:: Matches embedded in context +* Plain lists:: Additional structure within an entry +* Drawers:: Tucking stuff away +* Blocks:: Folding blocks +* Footnotes:: How footnotes are defined in Org's syntax +* Orgstruct mode:: Structure editing outside Org Tables -* Built-in table editor:: Simple tables -* Column width and alignment:: Overrule the automatic settings -* Column groups:: Grouping to trigger vertical lines -* Orgtbl mode:: The table editor as minor mode -* The spreadsheet:: The table editor has spreadsheet capabilities -* Org-Plot:: Plotting from org tables +* Built-in table editor:: Simple tables +* Column width and alignment:: Overrule the automatic settings +* Column groups:: Grouping to trigger vertical lines +* Orgtbl mode:: The table editor as minor mode +* The spreadsheet:: The table editor has spreadsheet capabilities +* Org-Plot:: Plotting from org tables The spreadsheet -* References:: How to refer to another field or range -* Formula syntax for Calc:: Using Calc to compute stuff -* Formula syntax for Lisp:: Writing formulas in Emacs Lisp -* Field formulas:: Formulas valid for a single field -* Column formulas:: Formulas valid for an entire column +* References:: How to refer to another field or range +* Formula syntax for Calc:: Using Calc to compute stuff +* Formula syntax for Lisp:: Writing formulas in Emacs Lisp +* Field formulas:: Formulas valid for a single field +* Column formulas:: Formulas valid for an entire column * Editing and debugging formulas:: Fixing formulas -* Updating the table:: Recomputing all dependent fields -* Advanced features:: Field names, parameters and automatic recalc +* Updating the table:: Recomputing all dependent fields +* Advanced features:: Field names, parameters and automatic recalc Hyperlinks -* Link format:: How links in Org are formatted -* Internal links:: Links to other places in the current file -* External links:: URL-like links to the world -* Handling links:: Creating, inserting and following -* Using links outside Org:: Linking from my C source code? -* Link abbreviations:: Shortcuts for writing complex links -* Search options:: Linking to a specific location -* Custom searches:: When the default search is not enough +* Link format:: How links in Org are formatted +* Internal links:: Links to other places in the current file +* External links:: URL-like links to the world +* Handling links:: Creating, inserting and following +* Using links outside Org:: Linking from my C source code? +* Link abbreviations:: Shortcuts for writing complex links +* Search options:: Linking to a specific location +* Custom searches:: When the default search is not enough Internal links -* Radio targets:: Make targets trigger links in plain text +* Radio targets:: Make targets trigger links in plain text TODO Items -* TODO basics:: Marking and displaying TODO entries -* TODO extensions:: Workflow and assignments -* Progress logging:: Dates and notes for progress -* Priorities:: Some things are more important than others -* Breaking down tasks:: Splitting a task into manageable pieces -* Checkboxes:: Tick-off lists +* TODO basics:: Marking and displaying TODO entries +* TODO extensions:: Workflow and assignments +* Progress logging:: Dates and notes for progress +* Priorities:: Some things are more important than others +* Breaking down tasks:: Splitting a task into manageable pieces +* Checkboxes:: Tick-off lists Extended use of TODO keywords -* Workflow states:: From TODO to DONE in steps -* TODO types:: I do this, Fred does the rest -* Multiple sets in one file:: Mixing it all, and still finding your way -* Fast access to TODO states:: Single letter selection of a state -* Per-file keywords:: Different files, different requirements -* Faces for TODO keywords:: Highlighting states -* TODO dependencies:: When one task needs to wait for others +* Workflow states:: From TODO to DONE in steps +* TODO types:: I do this, Fred does the rest +* Multiple sets in one file:: Mixing it all, and still finding your way +* Fast access to TODO states:: Single letter selection of a state +* Per-file keywords:: Different files, different requirements +* Faces for TODO keywords:: Highlighting states +* TODO dependencies:: When one task needs to wait for others Progress logging -* Closing items:: When was this entry marked DONE? -* Tracking TODO state changes:: When did the status change? -* Tracking your habits:: How consistent have you been? +* Closing items:: When was this entry marked DONE? +* Tracking TODO state changes:: When did the status change? +* Tracking your habits:: How consistent have you been? Tags -* Tag inheritance:: Tags use the tree structure of the outline -* Setting tags:: How to assign tags to a headline -* Tag searches:: Searching for combinations of tags +* Tag inheritance:: Tags use the tree structure of the outline +* Setting tags:: How to assign tags to a headline +* Tag searches:: Searching for combinations of tags Properties and Columns -* Property syntax:: How properties are spelled out -* Special properties:: Access to other Org mode features -* Property searches:: Matching property values -* Property inheritance:: Passing values down the tree -* Column view:: Tabular viewing and editing -* Property API:: Properties for Lisp programmers +* Property syntax:: How properties are spelled out +* Special properties:: Access to other Org mode features +* Property searches:: Matching property values +* Property inheritance:: Passing values down the tree +* Column view:: Tabular viewing and editing +* Property API:: Properties for Lisp programmers Column view -* Defining columns:: The COLUMNS format property -* Using column view:: How to create and use column view -* Capturing column view:: A dynamic block for column view +* Defining columns:: The COLUMNS format property +* Using column view:: How to create and use column view +* Capturing column view:: A dynamic block for column view Defining columns -* Scope of column definitions:: Where defined, where valid? -* Column attributes:: Appearance and content of a column +* Scope of column definitions:: Where defined, where valid? +* Column attributes:: Appearance and content of a column Dates and Times -* Timestamps:: Assigning a time to a tree entry -* Creating timestamps:: Commands which insert timestamps -* Deadlines and scheduling:: Planning your work -* Clocking work time:: Tracking how long you spend on a task -* Resolving idle time:: Resolving time if you've been idle -* Effort estimates:: Planning work effort in advance -* Relative timer:: Notes with a running timer +* Timestamps:: Assigning a time to a tree entry +* Creating timestamps:: Commands which insert timestamps +* Deadlines and scheduling:: Planning your work +* Clocking work time:: Tracking how long you spend on a task +* Resolving idle time:: Resolving time if you've been idle +* Effort estimates:: Planning work effort in advance +* Relative timer:: Notes with a running timer Creating timestamps -* The date/time prompt:: How Org mode helps you entering date and time -* Custom time format:: Making dates look different +* The date/time prompt:: How Org mode helps you entering date and time +* Custom time format:: Making dates look different Deadlines and scheduling -* Inserting deadline/schedule:: Planning items -* Repeated tasks:: Items that show up again and again +* Inserting deadline/schedule:: Planning items +* Repeated tasks:: Items that show up again and again Capture - Refile - Archive -* Remember:: Capture new tasks/ideas with little interruption -* Attachments:: Add files to tasks. -* RSS Feeds:: Getting input from RSS feeds -* Protocols:: External (e.g. Browser) access to Emacs and Org -* Refiling notes:: Moving a tree from one place to another -* Archiving:: What to do with finished projects +* Remember:: Capture new tasks/ideas with little interruption +* Attachments:: Add files to tasks. +* RSS Feeds:: Getting input from RSS feeds +* Protocols:: External (e.g. Browser) access to Emacs and Org +* Refiling notes:: Moving a tree from one place to another +* Archiving:: What to do with finished projects Remember -* Setting up Remember for Org:: Some code for .emacs to get things going -* Remember templates:: Define the outline of different note types -* Storing notes:: Directly get the note to where it belongs +* Setting up Remember for Org:: Some code for .emacs to get things going +* Remember templates:: Define the outline of different note types +* Storing notes:: Directly get the note to where it belongs Archiving -* Moving subtrees:: Moving a tree to an archive file -* Internal archiving:: Switch off a tree but keep it in the file +* Moving subtrees:: Moving a tree to an archive file +* Internal archiving:: Switch off a tree but keep it in the file Agenda Views -* Agenda files:: Files being searched for agenda information -* Agenda dispatcher:: Keyboard access to agenda views -* Built-in agenda views:: What is available out of the box? -* Presentation and sorting:: How agenda items are prepared for display -* Agenda commands:: Remote editing of Org trees -* Custom agenda views:: Defining special searches and views -* Exporting Agenda Views:: Writing a view to a file -* Agenda column view:: Using column view for collected entries +* Agenda files:: Files being searched for agenda information +* Agenda dispatcher:: Keyboard access to agenda views +* Built-in agenda views:: What is available out of the box? +* Presentation and sorting:: How agenda items are prepared for display +* Agenda commands:: Remote editing of Org trees +* Custom agenda views:: Defining special searches and views +* Exporting Agenda Views:: Writing a view to a file +* Agenda column view:: Using column view for collected entries The built-in agenda views -* Weekly/daily agenda:: The calendar page with current tasks -* Global TODO list:: All unfinished action items +* Weekly/daily agenda:: The calendar page with current tasks +* Global TODO list:: All unfinished action items * Matching tags and properties:: Structured information with fine-tuned search -* Timeline:: Time-sorted view for single file -* Search view:: Find entries by searching for text -* Stuck projects:: Find projects you need to review +* Timeline:: Time-sorted view for single file +* Search view:: Find entries by searching for text +* Stuck projects:: Find projects you need to review Presentation and sorting -* Categories:: Not all tasks are equal -* Time-of-day specifications:: How the agenda knows the time -* Sorting of agenda items:: The order of things +* Categories:: Not all tasks are equal +* Time-of-day specifications:: How the agenda knows the time +* Sorting of agenda items:: The order of things Custom agenda views -* Storing searches:: Type once, use often -* Block agenda:: All the stuff you need in a single buffer -* Setting Options:: Changing the rules +* Storing searches:: Type once, use often +* Block agenda:: All the stuff you need in a single buffer +* Setting Options:: Changing the rules Markup for rich export -* Structural markup elements:: The basic structure as seen by the exporter -* Images and tables:: Tables and Images will be included -* Literal examples:: Source code examples with special formatting -* Include files:: Include additional files into a document -* Index entries:: -* Macro replacement:: Use macros to create complex output -* Embedded LaTeX:: LaTeX can be freely used inside Org documents +* Structural markup elements:: The basic structure as seen by the exporter +* Images and tables:: Tables and Images will be included +* Literal examples:: Source code examples with special formatting +* Include files:: Include additional files into a document +* Index entries:: +* Macro replacement:: Use macros to create complex output +* Embedded LaTeX:: LaTeX can be freely used inside Org documents Structural markup elements -* Document title:: Where the title is taken from -* Headings and sections:: The document structure as seen by the exporter -* Table of contents:: The if and where of the table of contents -* Initial text:: Text before the first heading? -* Lists:: Lists -* Paragraphs:: Paragraphs -* Footnote markup:: Footnotes -* Emphasis and monospace:: Bold, italic, etc. -* Horizontal rules:: Make a line -* Comment lines:: What will *not* be exported +* Document title:: Where the title is taken from +* Headings and sections:: The document structure as seen by the exporter +* Table of contents:: The if and where of the table of contents +* Initial text:: Text before the first heading? +* Lists:: Lists +* Paragraphs:: Paragraphs +* Footnote markup:: Footnotes +* Emphasis and monospace:: Bold, italic, etc. +* Horizontal rules:: Make a line +* Comment lines:: What will *not* be exported Embedded La@TeX{} -* Special symbols:: Greek letters and other symbols -* Subscripts and superscripts:: Simple syntax for raising/lowering text -* LaTeX fragments:: Complex formulas made easy -* Previewing LaTeX fragments:: What will this snippet look like? -* CDLaTeX mode:: Speed up entering of formulas +* Special symbols:: Greek letters and other symbols +* Subscripts and superscripts:: Simple syntax for raising/lowering text +* LaTeX fragments:: Complex formulas made easy +* Previewing LaTeX fragments:: What will this snippet look like? +* CDLaTeX mode:: Speed up entering of formulas Exporting -* Selective export:: Using tags to select and exclude trees -* Export options:: Per-file export settings -* The export dispatcher:: How to access exporter commands -* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding -* HTML export:: Exporting to HTML -* LaTeX and PDF export:: Exporting to La@TeX{}, and processing to PDF -* DocBook export:: Exporting to DocBook -* TaskJuggler export:: Exporting to TaskJuggler -* Freemind export:: Exporting to Freemind mind maps -* XOXO export:: Exporting to XOXO -* iCalendar export:: Exporting in iCalendar format +* Selective export:: Using tags to select and exclude trees +* Export options:: Per-file export settings +* The export dispatcher:: How to access exporter commands +* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding +* HTML export:: Exporting to HTML +* LaTeX and PDF export:: Exporting to La@TeX{}, and processing to PDF +* DocBook export:: Exporting to DocBook +* TaskJuggler export:: Exporting to TaskJuggler +* Freemind export:: Exporting to Freemind mind maps +* XOXO export:: Exporting to XOXO +* iCalendar export:: Exporting in iCalendar format HTML export -* HTML Export commands:: How to invoke HTML export -* Quoting HTML tags:: Using direct HTML in Org mode -* Links in HTML export:: How links will be interpreted and formatted -* Tables in HTML export:: How to modify the formatting of tables -* Images in HTML export:: How to insert figures into HTML output -* Text areas in HTML export:: An alternative way to show an example -* CSS support:: Changing the appearance of the output -* Javascript support:: Info and Folding in a web browser +* HTML Export commands:: How to invoke HTML export +* Quoting HTML tags:: Using direct HTML in Org mode +* Links in HTML export:: How links will be interpreted and formatted +* Tables in HTML export:: How to modify the formatting of tables +* Images in HTML export:: How to insert figures into HTML output +* Text areas in HTML export:: An alternative way to show an example +* CSS support:: Changing the appearance of the output +* Javascript support:: Info and Folding in a web browser La@TeX{} and PDF export -* LaTeX/PDF export commands:: Which key invokes which commands -* Header and sectioning:: Setting up the export file structure -* Quoting LaTeX code:: Incorporating literal La@TeX{} code -* Tables in LaTeX export:: Options for exporting tables to La@TeX{} -* Images in LaTeX export:: How to insert figures into La@TeX{} output -* Beamer class export:: Turning the file into a presentation +* LaTeX/PDF export commands:: Which key invokes which commands +* Header and sectioning:: Setting up the export file structure +* Quoting LaTeX code:: Incorporating literal La@TeX{} code +* Tables in LaTeX export:: Options for exporting tables to La@TeX{} +* Images in LaTeX export:: How to insert figures into La@TeX{} output +* Beamer class export:: Turning the file into a presentation DocBook export -* DocBook export commands:: How to invoke DocBook export -* Quoting DocBook code:: Incorporating DocBook code in Org files -* Recursive sections:: Recursive sections in DocBook -* Tables in DocBook export:: Tables are exported as HTML tables -* Images in DocBook export:: How to insert figures into DocBook output -* Special characters:: How to handle special characters +* DocBook export commands:: How to invoke DocBook export +* Quoting DocBook code:: Incorporating DocBook code in Org files +* Recursive sections:: Recursive sections in DocBook +* Tables in DocBook export:: Tables are exported as HTML tables +* Images in DocBook export:: How to insert figures into DocBook output +* Special characters:: How to handle special characters Publishing -* Configuration:: Defining projects -* Uploading files:: How to get files up on the server -* Sample configuration:: Example projects -* Triggering publication:: Publication commands +* Configuration:: Defining projects +* Uploading files:: How to get files up on the server +* Sample configuration:: Example projects +* Triggering publication:: Publication commands +* Library of Babel:: +* Languages:: +* Header arguments:: +* Results:: +* Noweb reference syntax:: +* Key bindings & useful functions:: +* Batch execution:: Configuration -* Project alist:: The central configuration variable -* Sources and destinations:: From here to there -* Selecting files:: What files are part of the project? -* Publishing action:: Setting the function doing the publishing -* Publishing options:: Tweaking HTML export -* Publishing links:: Which links keep working after publishing? -* Sitemap:: Generating a list of all pages -* Generating an index:: An index that reaches across pages +* Project alist:: The central configuration variable +* Sources and destinations:: From here to there +* Selecting files:: What files are part of the project? +* Publishing action:: Setting the function doing the publishing +* Publishing options:: Tweaking HTML export +* Publishing links:: Which links keep working after publishing? +* Sitemap:: Generating a list of all pages +* Generating an index:: An index that reaches across pages Sample configuration -* Simple example:: One-component publishing -* Complex example:: A multi-component publishing example +* Simple example:: One-component publishing +* Complex example:: A multi-component publishing example + +Working With Source Code + +* Structure of code blocks:: +* Editing source code:: +* Exporting code blocks:: +* Extracting source code:: +* Evaluating code blocks:: +* Library of Babel:: +* Languages:: +* Header arguments:: +* Results:: +* Noweb reference syntax:: +* Key bindings & useful functions:: +* Batch execution:: + +Header arguments + +* Using header arguments:: +* Specific header arguments:: + +Using header arguments + +* System-wide header arguments:: +* Language-specific header arguments:: +* Buffer-wide header arguments:: +* Header arguments in Org-mode properties:: +* Code block specific header arguments:: + +Specific header arguments + +* var argument:: +* results argument:: +* file argument:: +* dir and remote execution:: +* exports argument:: +* tangle argument:: +* no-expand argument:: +* session argument:: +* noweb argument:: +* cache argument:: +* hlines argument:: +* colnames argument:: +* rownames argument:: Miscellaneous -* Completion:: M-TAB knows what you need -* Speed keys:: Electic commands at the beginning of a headline -* Customization:: Adapting Org to your taste -* In-buffer settings:: Overview of the #+KEYWORDS -* The very busy C-c C-c key:: When in doubt, press C-c C-c -* Clean view:: Getting rid of leading stars in the outline -* TTY keys:: Using Org on a tty -* Interaction:: Other Emacs packages +* Completion:: M-TAB knows what you need +* Speed keys:: Electic commands at the beginning of a headline +* Customization:: Adapting Org to your taste +* In-buffer settings:: Overview of the #+KEYWORDS +* The very busy C-c C-c key:: When in doubt, press C-c C-c +* Clean view:: Getting rid of leading stars in the outline +* TTY keys:: Using Org on a tty +* Interaction:: Other Emacs packages Interaction with other packages -* Cooperation:: Packages Org cooperates with -* Conflicts:: Packages that lead to conflicts +* Cooperation:: Packages Org cooperates with +* Conflicts:: Packages that lead to conflicts Hacking -* Hooks:: Who to reach into Org's internals -* Add-on packages:: Available extensions -* Adding hyperlink types:: New custom link types -* Context-sensitive commands:: How to add functionality to such commands -* Tables in arbitrary syntax:: Orgtbl for La@TeX{} and other programs -* Dynamic blocks:: Automatically filled blocks -* Special agenda views:: Customized views +* Hooks:: Who to reach into Org's internals +* Add-on packages:: Available extensions +* Adding hyperlink types:: New custom link types +* Context-sensitive commands:: How to add functionality to such commands +* Tables in arbitrary syntax:: Orgtbl for La@TeX{} and other programs +* Dynamic blocks:: Automatically filled blocks +* Special agenda views:: Customized views * Extracting agenda information:: Postprocessing of agenda information -* Using the property API:: Writing programs that use entry properties -* Using the mapping API:: Mapping over all or selected entries +* Using the property API:: Writing programs that use entry properties +* Using the mapping API:: Mapping over all or selected entries Tables and lists in arbitrary syntax -* Radio tables:: Sending and receiving radio tables -* A LaTeX example:: Step by step, almost a tutorial -* Translator functions:: Copy and modify -* Radio lists:: Doing the same for lists +* Radio tables:: Sending and receiving radio tables +* A LaTeX example:: Step by step, almost a tutorial +* Translator functions:: Copy and modify +* Radio lists:: Doing the same for lists MobileOrg -* Setting up the staging area:: Where to interact with the mobile device -* Pushing to MobileOrg:: Uploading Org files and agendas -* Pulling from MobileOrg:: Integrating captured and flagged items +* Setting up the staging area:: Where to interact with the mobile device +* Pushing to MobileOrg:: Uploading Org files and agendas +* Pulling from MobileOrg:: Integrating captured and flagged items @end detailmenu @end menu @@ -447,11 +498,11 @@ MobileOrg @cindex introduction @menu -* Summary:: Brief summary of what Org does -* Installation:: How to install a downloaded version of Org -* Activation:: How to activate Org for certain buffers -* Feedback:: Bug reports, ideas, patches etc. -* Conventions:: Type-setting conventions in the manual +* Summary:: Brief summary of what Org does +* Installation:: How to install a downloaded version of Org +* Activation:: How to activate Org for certain buffers +* Feedback:: Bug reports, ideas, patches etc. +* Conventions:: Type-setting conventions in the manual @end menu @node Summary, Installation, Introduction, Introduction @@ -758,17 +809,17 @@ Org is based on Outline mode and provides flexible commands to edit the structure of the document. @menu -* Outlines:: Org is based on Outline mode -* Headlines:: How to typeset Org tree headlines -* Visibility cycling:: Show and hide, much simplified -* Motion:: Jumping to other headlines -* Structure editing:: Changing sequence and level of headlines -* Sparse trees:: Matches embedded in context -* Plain lists:: Additional structure within an entry -* Drawers:: Tucking stuff away -* Blocks:: Folding blocks -* Footnotes:: How footnotes are defined in Org's syntax -* Orgstruct mode:: Structure editing outside Org +* Outlines:: Org is based on Outline mode +* Headlines:: How to typeset Org tree headlines +* Visibility cycling:: Show and hide, much simplified +* Motion:: Jumping to other headlines +* Structure editing:: Changing sequence and level of headlines +* Sparse trees:: Matches embedded in context +* Plain lists:: Additional structure within an entry +* Drawers:: Tucking stuff away +* Blocks:: Folding blocks +* Footnotes:: How footnotes are defined in Org's syntax +* Orgstruct mode:: Structure editing outside Org @end menu @node Outlines, Headlines, Document Structure, Document Structure @@ -1593,12 +1644,12 @@ calculator). @end ifnotinfo @menu -* Built-in table editor:: Simple tables -* Column width and alignment:: Overrule the automatic settings -* Column groups:: Grouping to trigger vertical lines -* Orgtbl mode:: The table editor as minor mode -* The spreadsheet:: The table editor has spreadsheet capabilities -* Org-Plot:: Plotting from org tables +* Built-in table editor:: Simple tables +* Column width and alignment:: Overrule the automatic settings +* Column groups:: Grouping to trigger vertical lines +* Orgtbl mode:: The table editor as minor mode +* The spreadsheet:: The table editor has spreadsheet capabilities +* Org-Plot:: Plotting from org tables @end menu @node Built-in table editor, Column width and alignment, Tables, Tables @@ -1972,14 +2023,14 @@ fields in the table corresponding to the references at the point in the formula, moving these references by arrow keys @menu -* References:: How to refer to another field or range -* Formula syntax for Calc:: Using Calc to compute stuff -* Formula syntax for Lisp:: Writing formulas in Emacs Lisp -* Field formulas:: Formulas valid for a single field -* Column formulas:: Formulas valid for an entire column +* References:: How to refer to another field or range +* Formula syntax for Calc:: Using Calc to compute stuff +* Formula syntax for Lisp:: Writing formulas in Emacs Lisp +* Field formulas:: Formulas valid for a single field +* Column formulas:: Formulas valid for an entire column * Editing and debugging formulas:: Fixing formulas -* Updating the table:: Recomputing all dependent fields -* Advanced features:: Field names, parameters and automatic recalc +* Updating the table:: Recomputing all dependent fields +* Advanced features:: Field names, parameters and automatic recalc @end menu @node References, Formula syntax for Calc, The spreadsheet, The spreadsheet @@ -2683,14 +2734,14 @@ Like HTML, Org provides links inside a file, external links to other files, Usenet articles, emails, and much more. @menu -* Link format:: How links in Org are formatted -* Internal links:: Links to other places in the current file -* External links:: URL-like links to the world -* Handling links:: Creating, inserting and following -* Using links outside Org:: Linking from my C source code? -* Link abbreviations:: Shortcuts for writing complex links -* Search options:: Linking to a specific location -* Custom searches:: When the default search is not enough +* Link format:: How links in Org are formatted +* Internal links:: Links to other places in the current file +* External links:: URL-like links to the world +* Handling links:: Creating, inserting and following +* Using links outside Org:: Linking from my C source code? +* Link abbreviations:: Shortcuts for writing complex links +* Search options:: Linking to a specific location +* Custom searches:: When the default search is not enough @end menu @node Link format, Internal links, Hyperlinks, Hyperlinks @@ -2783,7 +2834,7 @@ several times in direct succession goes back to positions recorded earlier. @menu -* Radio targets:: Make targets trigger links in plain text +* Radio targets:: Make targets trigger links in plain text @end menu @node Radio targets, , Internal links, Internal links @@ -3238,12 +3289,12 @@ throughout your notes file. Org mode compensates for this by providing methods to give you an overview of all the things that you have to do. @menu -* TODO basics:: Marking and displaying TODO entries -* TODO extensions:: Workflow and assignments -* Progress logging:: Dates and notes for progress -* Priorities:: Some things are more important than others -* Breaking down tasks:: Splitting a task into manageable pieces -* Checkboxes:: Tick-off lists +* TODO basics:: Marking and displaying TODO entries +* TODO extensions:: Workflow and assignments +* Progress logging:: Dates and notes for progress +* Priorities:: Some things are more important than others +* Breaking down tasks:: Splitting a task into manageable pieces +* Checkboxes:: Tick-off lists @end menu @node TODO basics, TODO extensions, TODO Items, TODO Items @@ -3334,13 +3385,13 @@ Note that @i{tags} are another way to classify headlines in general and TODO items in particular (@pxref{Tags}). @menu -* Workflow states:: From TODO to DONE in steps -* TODO types:: I do this, Fred does the rest -* Multiple sets in one file:: Mixing it all, and still finding your way -* Fast access to TODO states:: Single letter selection of a state -* Per-file keywords:: Different files, different requirements -* Faces for TODO keywords:: Highlighting states -* TODO dependencies:: When one task needs to wait for others +* Workflow states:: From TODO to DONE in steps +* TODO types:: I do this, Fred does the rest +* Multiple sets in one file:: Mixing it all, and still finding your way +* Fast access to TODO states:: Single letter selection of a state +* Per-file keywords:: Different files, different requirements +* Faces for TODO keywords:: Highlighting states +* TODO dependencies:: When one task needs to wait for others @end menu @node Workflow states, TODO types, TODO extensions, TODO extensions @@ -3631,9 +3682,9 @@ information on how to clock working time for a task, see @ref{Clocking work time}. @menu -* Closing items:: When was this entry marked DONE? -* Tracking TODO state changes:: When did the status change? -* Tracking your habits:: How consistent have you been? +* Closing items:: When was this entry marked DONE? +* Tracking TODO state changes:: When did the status change? +* Tracking your habits:: How consistent have you been? @end menu @node Closing items, Tracking TODO state changes, Progress logging, Progress logging @@ -4095,9 +4146,9 @@ You may specify special faces for specific tags using the variable (@pxref{Faces for TODO keywords}). @menu -* Tag inheritance:: Tags use the tree structure of the outline -* Setting tags:: How to assign tags to a headline -* Tag searches:: Searching for combinations of tags +* Tag inheritance:: Tags use the tree structure of the outline +* Setting tags:: How to assign tags to a headline +* Tag searches:: Searching for combinations of tags @end menu @node Tag inheritance, Setting tags, Tags, Tags @@ -4404,12 +4455,12 @@ Properties can be conveniently edited and viewed in column view (@pxref{Column view}). @menu -* Property syntax:: How properties are spelled out -* Special properties:: Access to other Org mode features -* Property searches:: Matching property values -* Property inheritance:: Passing values down the tree -* Column view:: Tabular viewing and editing -* Property API:: Properties for Lisp programmers +* Property syntax:: How properties are spelled out +* Special properties:: Access to other Org mode features +* Property searches:: Matching property values +* Property inheritance:: Passing values down the tree +* Column view:: Tabular viewing and editing +* Property API:: Properties for Lisp programmers @end menu @node Property syntax, Special properties, Properties and Columns, Properties and Columns @@ -4643,9 +4694,9 @@ Column view also works in agenda buffers (@pxref{Agenda Views}) where queries have collected selected items, possibly from a number of files. @menu -* Defining columns:: The COLUMNS format property -* Using column view:: How to create and use column view -* Capturing column view:: A dynamic block for column view +* Defining columns:: The COLUMNS format property +* Using column view:: How to create and use column view +* Capturing column view:: A dynamic block for column view @end menu @node Defining columns, Using column view, Column view, Column view @@ -4657,8 +4708,8 @@ Setting up a column view first requires defining the columns. This is done by defining a column format line. @menu -* Scope of column definitions:: Where defined, where valid? -* Column attributes:: Appearance and content of a column +* Scope of column definitions:: Where defined, where valid? +* Column attributes:: Appearance and content of a column @end menu @node Scope of column definitions, Column attributes, Defining columns, Defining columns @@ -4940,13 +4991,13 @@ something was created or last changed. However, in Org mode this term is used in a much wider sense. @menu -* Timestamps:: Assigning a time to a tree entry -* Creating timestamps:: Commands which insert timestamps -* Deadlines and scheduling:: Planning your work -* Clocking work time:: Tracking how long you spend on a task -* Resolving idle time:: Resolving time if you've been idle -* Effort estimates:: Planning work effort in advance -* Relative timer:: Notes with a running timer +* Timestamps:: Assigning a time to a tree entry +* Creating timestamps:: Commands which insert timestamps +* Deadlines and scheduling:: Planning your work +* Clocking work time:: Tracking how long you spend on a task +* Resolving idle time:: Resolving time if you've been idle +* Effort estimates:: Planning work effort in advance +* Relative timer:: Notes with a running timer @end menu @@ -5102,8 +5153,8 @@ the following column). @menu -* The date/time prompt:: How Org mode helps you entering date and time -* Custom time format:: Making dates look different +* The date/time prompt:: How Org mode helps you entering date and time +* Custom time format:: Making dates look different @end menu @node The date/time prompt, Custom time format, Creating timestamps, Creating timestamps @@ -5335,8 +5386,8 @@ late warnings. However, it will show the item on each day where the sexp entry matches. @menu -* Inserting deadline/schedule:: Planning items -* Repeated tasks:: Items that show up again and again +* Inserting deadline/schedule:: Planning items +* Repeated tasks:: Items that show up again and again @end menu @node Inserting deadline/schedule, Repeated tasks, Deadlines and scheduling, Deadlines and scheduling @@ -5858,12 +5909,12 @@ system, tasks and projects need to be moved around. Moving completed project trees to an archive file keeps the system compact and fast. @menu -* Remember:: Capture new tasks/ideas with little interruption -* Attachments:: Add files to tasks. -* RSS Feeds:: Getting input from RSS feeds -* Protocols:: External (e.g. Browser) access to Emacs and Org -* Refiling notes:: Moving a tree from one place to another -* Archiving:: What to do with finished projects +* Remember:: Capture new tasks/ideas with little interruption +* Attachments:: Add files to tasks. +* RSS Feeds:: Getting input from RSS feeds +* Protocols:: External (e.g. Browser) access to Emacs and Org +* Refiling notes:: Moving a tree from one place to another +* Archiving:: What to do with finished projects @end menu @node Remember, Attachments, Capture - Refile - Archive, Capture - Refile - Archive @@ -5882,9 +5933,9 @@ with specific templates. It also allows you to select the location where a note should be stored interactively, on the fly. @menu -* Setting up Remember for Org:: Some code for .emacs to get things going -* Remember templates:: Define the outline of different note types -* Storing notes:: Directly get the note to where it belongs +* Setting up Remember for Org:: Some code for .emacs to get things going +* Remember templates:: Define the outline of different note types +* Storing notes:: Directly get the note to where it belongs @end menu @node Setting up Remember for Org, Remember templates, Remember, Remember @@ -6348,8 +6399,8 @@ Archive the current entry using the command specified in the variable @end table @menu -* Moving subtrees:: Moving a tree to an archive file -* Internal archiving:: Switch off a tree but keep it in the file +* Moving subtrees:: Moving a tree to an archive file +* Internal archiving:: Switch off a tree but keep it in the file @end menu @node Moving subtrees, Internal archiving, Archiving, Archiving @@ -6526,14 +6577,14 @@ window configuration is restored when the agenda exits: @code{org-agenda-restore-windows-after-quit}. @menu -* Agenda files:: Files being searched for agenda information -* Agenda dispatcher:: Keyboard access to agenda views -* Built-in agenda views:: What is available out of the box? -* Presentation and sorting:: How agenda items are prepared for display -* Agenda commands:: Remote editing of Org trees -* Custom agenda views:: Defining special searches and views -* Exporting Agenda Views:: Writing a view to a file -* Agenda column view:: Using column view for collected entries +* Agenda files:: Files being searched for agenda information +* Agenda dispatcher:: Keyboard access to agenda views +* Built-in agenda views:: What is available out of the box? +* Presentation and sorting:: How agenda items are prepared for display +* Agenda commands:: Remote editing of Org trees +* Custom agenda views:: Defining special searches and views +* Exporting Agenda Views:: Writing a view to a file +* Agenda column view:: Using column view for collected entries @end menu @node Agenda files, Agenda dispatcher, Agenda Views, Agenda Views @@ -6675,12 +6726,12 @@ a number of special tags matches. @xref{Custom agenda views}. In this section we describe the built-in views. @menu -* Weekly/daily agenda:: The calendar page with current tasks -* Global TODO list:: All unfinished action items +* Weekly/daily agenda:: The calendar page with current tasks +* Global TODO list:: All unfinished action items * Matching tags and properties:: Structured information with fine-tuned search -* Timeline:: Time-sorted view for single file -* Search view:: Find entries by searching for text -* Stuck projects:: Find projects you need to review +* Timeline:: Time-sorted view for single file +* Search view:: Find entries by searching for text +* Stuck projects:: Find projects you need to review @end menu @node Weekly/daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views @@ -7143,9 +7194,9 @@ The prefix is followed by a cleaned-up version of the outline headline associated with the item. @menu -* Categories:: Not all tasks are equal -* Time-of-day specifications:: How the agenda knows the time -* Sorting of agenda items:: The order of things +* Categories:: Not all tasks are equal +* Time-of-day specifications:: How the agenda knows the time +* Sorting of agenda items:: The order of things @end menu @node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting @@ -7869,9 +7920,9 @@ agenda buffers. Custom agenda commands will be accessible through the dispatcher (@pxref{Agenda dispatcher}), just like the default commands. @menu -* Storing searches:: Type once, use often -* Block agenda:: All the stuff you need in a single buffer -* Setting Options:: Changing the rules +* Storing searches:: Type once, use often +* Block agenda:: All the stuff you need in a single buffer +* Setting Options:: Changing the rules @end menu @node Storing searches, Block agenda, Custom agenda views, Custom agenda views @@ -8256,29 +8307,29 @@ Org mode has rules on how to prepare text for rich export. This section summarizes the markup rules used in an Org-mode buffer. @menu -* Structural markup elements:: The basic structure as seen by the exporter -* Images and tables:: Tables and Images will be included -* Literal examples:: Source code examples with special formatting -* Include files:: Include additional files into a document -* Index entries:: -* Macro replacement:: Use macros to create complex output -* Embedded LaTeX:: LaTeX can be freely used inside Org documents +* Structural markup elements:: The basic structure as seen by the exporter +* Images and tables:: Tables and Images will be included +* Literal examples:: Source code examples with special formatting +* Include files:: Include additional files into a document +* Index entries:: +* Macro replacement:: Use macros to create complex output +* Embedded LaTeX:: LaTeX can be freely used inside Org documents @end menu @node Structural markup elements, Images and tables, Markup, Markup @section Structural markup elements @menu -* Document title:: Where the title is taken from -* Headings and sections:: The document structure as seen by the exporter -* Table of contents:: The if and where of the table of contents -* Initial text:: Text before the first heading? -* Lists:: Lists -* Paragraphs:: Paragraphs -* Footnote markup:: Footnotes -* Emphasis and monospace:: Bold, italic, etc. -* Horizontal rules:: Make a line -* Comment lines:: What will *not* be exported +* Document title:: Where the title is taken from +* Headings and sections:: The document structure as seen by the exporter +* Table of contents:: The if and where of the table of contents +* Initial text:: Text before the first heading? +* Lists:: Lists +* Paragraphs:: Paragraphs +* Footnote markup:: Footnotes +* Emphasis and monospace:: Bold, italic, etc. +* Horizontal rules:: Make a line +* Comment lines:: What will *not* be exported @end menu @node Document title, Headings and sections, Structural markup elements, Structural markup elements @@ -8707,11 +8758,11 @@ If you observe a few conventions, Org mode knows how to find it and what to do with it. @menu -* Special symbols:: Greek letters and other symbols -* Subscripts and superscripts:: Simple syntax for raising/lowering text -* LaTeX fragments:: Complex formulas made easy -* Previewing LaTeX fragments:: What will this snippet look like? -* CDLaTeX mode:: Speed up entering of formulas +* Special symbols:: Greek letters and other symbols +* Subscripts and superscripts:: Simple syntax for raising/lowering text +* LaTeX fragments:: Complex formulas made easy +* Previewing LaTeX fragments:: What will this snippet look like? +* CDLaTeX mode:: Speed up entering of formulas @end menu @node Special symbols, Subscripts and superscripts, Embedded LaTeX, Embedded LaTeX @@ -8970,17 +9021,17 @@ Org supports export of selected regions when @code{transient-mark-mode} is enabled (default in Emacs 23). @menu -* Selective export:: Using tags to select and exclude trees -* Export options:: Per-file export settings -* The export dispatcher:: How to access exporter commands -* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding -* HTML export:: Exporting to HTML -* LaTeX and PDF export:: Exporting to La@TeX{}, and processing to PDF -* DocBook export:: Exporting to DocBook -* TaskJuggler export:: Exporting to TaskJuggler -* Freemind export:: Exporting to Freemind mind maps -* XOXO export:: Exporting to XOXO -* iCalendar export:: Exporting in iCalendar format +* Selective export:: Using tags to select and exclude trees +* Export options:: Per-file export settings +* The export dispatcher:: How to access exporter commands +* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding +* HTML export:: Exporting to HTML +* LaTeX and PDF export:: Exporting to La@TeX{}, and processing to PDF +* DocBook export:: Exporting to DocBook +* TaskJuggler export:: Exporting to TaskJuggler +* Freemind export:: Exporting to Freemind mind maps +* XOXO export:: Exporting to XOXO +* iCalendar export:: Exporting in iCalendar format @end menu @node Selective export, Export options, Exporting, Exporting @@ -9233,14 +9284,14 @@ HTML formatting, in ways similar to John Gruber's @emph{markdown} language, but with additional support for tables. @menu -* HTML Export commands:: How to invoke HTML export -* Quoting HTML tags:: Using direct HTML in Org mode -* Links in HTML export:: How links will be interpreted and formatted -* Tables in HTML export:: How to modify the formatting of tables -* Images in HTML export:: How to insert figures into HTML output -* Text areas in HTML export:: An alternative way to show an example -* CSS support:: Changing the appearance of the output -* Javascript support:: Info and Folding in a web browser +* HTML Export commands:: How to invoke HTML export +* Quoting HTML tags:: Using direct HTML in Org mode +* Links in HTML export:: How links will be interpreted and formatted +* Tables in HTML export:: How to modify the formatting of tables +* Images in HTML export:: How to insert figures into HTML output +* Text areas in HTML export:: An alternative way to show an example +* CSS support:: Changing the appearance of the output +* Javascript support:: Info and Folding in a web browser @end menu @node HTML Export commands, Quoting HTML tags, HTML export, HTML export @@ -9587,12 +9638,12 @@ implement links and cross references, the PDF output file will be fully linked. @menu -* LaTeX/PDF export commands:: Which key invokes which commands -* Header and sectioning:: Setting up the export file structure -* Quoting LaTeX code:: Incorporating literal La@TeX{} code -* Tables in LaTeX export:: Options for exporting tables to La@TeX{} -* Images in LaTeX export:: How to insert figures into La@TeX{} output -* Beamer class export:: Turning the file into a presentation +* LaTeX/PDF export commands:: Which key invokes which commands +* Header and sectioning:: Setting up the export file structure +* Quoting LaTeX code:: Incorporating literal La@TeX{} code +* Tables in LaTeX export:: Options for exporting tables to La@TeX{} +* Images in LaTeX export:: How to insert figures into La@TeX{} output +* Beamer class export:: Turning the file into a presentation @end menu @node LaTeX/PDF export commands, Header and sectioning, LaTeX and PDF export, LaTeX and PDF export @@ -9917,12 +9968,12 @@ tools and stylesheets. Currently DocBook exporter only supports DocBook V5.0. @menu -* DocBook export commands:: How to invoke DocBook export -* Quoting DocBook code:: Incorporating DocBook code in Org files -* Recursive sections:: Recursive sections in DocBook -* Tables in DocBook export:: Tables are exported as HTML tables -* Images in DocBook export:: How to insert figures into DocBook output -* Special characters:: How to handle special characters +* DocBook export commands:: How to invoke DocBook export +* Quoting DocBook code:: Incorporating DocBook code in Org files +* Recursive sections:: Recursive sections in DocBook +* Tables in DocBook export:: Tables are exported as HTML tables +* Images in DocBook export:: How to insert figures into DocBook output +* Special characters:: How to handle special characters @end menu @node DocBook export commands, Quoting DocBook code, DocBook export, DocBook export @@ -10349,10 +10400,17 @@ conversion so that files are available in both formats on the server. Publishing has been contributed to Org by David O'Toole. @menu -* Configuration:: Defining projects -* Uploading files:: How to get files up on the server -* Sample configuration:: Example projects -* Triggering publication:: Publication commands +* Configuration:: Defining projects +* Uploading files:: How to get files up on the server +* Sample configuration:: Example projects +* Triggering publication:: Publication commands +* Library of Babel:: +* Languages:: +* Header arguments:: +* Results:: +* Noweb reference syntax:: +* Key bindings & useful functions:: +* Batch execution:: @end menu @node Configuration, Uploading files, Publishing, Publishing @@ -10362,14 +10420,14 @@ Publishing needs significant configuration to specify files, destination and many other properties of a project. @menu -* Project alist:: The central configuration variable -* Sources and destinations:: From here to there -* Selecting files:: What files are part of the project? -* Publishing action:: Setting the function doing the publishing -* Publishing options:: Tweaking HTML export -* Publishing links:: Which links keep working after publishing? -* Sitemap:: Generating a list of all pages -* Generating an index:: An index that reaches across pages +* Project alist:: The central configuration variable +* Sources and destinations:: From here to there +* Selecting files:: What files are part of the project? +* Publishing action:: Setting the function doing the publishing +* Publishing options:: Tweaking HTML export +* Publishing links:: Which links keep working after publishing? +* Sitemap:: Generating a list of all pages +* Generating an index:: An index that reaches across pages @end menu @node Project alist, Sources and destinations, Configuration, Configuration @@ -10743,8 +10801,8 @@ project publishing only a set of Org files. The second example is more complex, with a multi-component project. @menu -* Simple example:: One-component publishing -* Complex example:: A multi-component publishing example +* Simple example:: One-component publishing +* Complex example:: A multi-component publishing example @end menu @node Simple example, Complex example, Sample configuration, Sample configuration @@ -10844,10 +10902,14 @@ above, or by customizing the variable @code{org-publish-use-timestamps-flag}. This may be necessary in particular if files include other files via @code{#+SETUPFILE:} or @code{#+INCLUDE:}. -@node Working With Source Code, Miscellaneous, Publishing, Top @comment node-name, next, previous, up @comment Working With Source Code, Miscellaneous, Publishing, Top + +@node Working With Source Code, Miscellaneous, Publishing, Top @chapter Working With Source Code +@cindex Schulte, Eric +@cindex Davison, Dan +@cindex source code, working with Source code can be included in Org-mode documents using a @samp{src} block, e.g. @@ -10860,11 +10922,11 @@ e.g. #+END_SRC @end example -Org provides a number of features for working with live source code, +Org-mode provides a number of features for working with live source code, including editing of code blocks in their native major-mode, evaluation of code blocks, tangling of code blocks, and exportation of code blocks and -their results to a number of formats. The following sections provide a -thorough tour of Org-mode's sophisticated code block handling facilities. +their results to a number of formats. The following sections describe +Org-mode's code block handling facilities. @menu * Structure of code blocks:: @@ -10898,9 +10960,9 @@ The structure of code blocks is as follows: @table @code @item -This name is associated with the source code block. This is similar to the +This name is associated with the code block. This is similar to the @samp{#+tblname} lines that can be used to name tables in Org-mode files. -Referencing the name of a source code block makes it possible to evaluate the +Referencing the name of a code block makes it possible to evaluate the block from other places in the file, other files, or from Org-mode table formulas (see @ref{The spreadsheet}). @item @@ -10914,7 +10976,7 @@ tangling of source code blocks. See the @ref{Header arguments} section. Header arguments can also be set on a per-buffer or per-subtree basis using properties. @item -The code +The source code. @end table @node Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code @@ -10960,7 +11022,7 @@ some languages (e.g. @code{ditaa}) the default exports the results of code block evaluation. For information on exporting code block bodies, see @ref{Literal examples}. -The @code{:exports} header argument can be used to specify non-default export +The @code{:exports} header argument can be used to specify export behavior: @subsubheading Header arguments: @@ -10980,9 +11042,9 @@ Both the code block and its results will be exported. Neither the code block nor its results will be exported. @end table -@node Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code @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 @section Extracting source code Creating pure source code files by extracting code from source blocks is @@ -11011,13 +11073,14 @@ Tangle the current file. Choose a file to tangle. @end table -@node Evaluating code blocks, Library of Babel, Extracting source code, Working With Source Code @comment node-name, next, previous, up @comment Evaluating code blocks, , Extracting source code, Working With Source Code + +@node Evaluating code blocks, Library of Babel, Extracting source code, Working With Source Code @section Evaluating code blocks Code blocks can be evaluated and the results placed in the Org-mode buffer. -Check the value of the @code{org-babel-interpreters} for a list of languages +Check the value of the variable @code{org-babel-interpreters} for a list of languages that can be evaluated on your system. See also @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. @@ -11035,6 +11098,8 @@ blocks located in the current Org-mode buffer or in the ``Library of Babel'' @example #+call: ()
+#+function: ()
+#+lob: ()
@end example @table @code @@ -11171,29 +11236,29 @@ of the language names from the above table). @node Header arguments, Results, Languages, Working With Source Code @section Header arguments -Most code block functionality is configurable using header arguments. This +Code block functionality can be configured with header arguments. This section provides an overview of the use of header arguments, and then -exhaustively covers all header arguments. +describes each header argument in detail. @menu -* Using Header arguments:: -* Specific Header arguments:: +* Using header arguments:: +* Specific header arguments:: @end menu -@node Using Header arguments, Specific Header arguments, , Header arguments -@subsection Using Header arguments +@node Using header arguments, Specific header arguments, Header arguments, Header arguments +@subsection Using header arguments The values of header arguments can be set in five different ways, each more specific (and having higher priority) than the last. @menu -* System-wide header arguments:: -* Language Specific header arguments:: -* Buffer-wide header arguments:: -* Header arguments in Org-mode Properties:: -* Code Block specific header arguments:: +* System-wide header arguments:: +* Language-specific header arguments:: +* Buffer-wide header arguments:: +* Header arguments in Org-mode properties:: +* Code block specific header arguments:: @end menu -@node System-wide header arguments, Language Specific header arguments, , Using Header arguments +@node System-wide header arguments, Language-specific header arguments, Using header arguments, Using header arguments @subsubheading System-wide header arguments System-wide values of header arguments can be specified by customizing the @code{org-babel-default-header-args} variable: @@ -11223,21 +11288,21 @@ blocks. (assq-delete-all :noweb org-babel-default-header-args))) @end example -@node Language Specific header arguments, Buffer-wide header arguments, System-wide header arguments, Using Header arguments -@subsubheading Language Specific header arguments +@node Language-specific header arguments, Buffer-wide header arguments, System-wide header arguments, Using header arguments +@subsubheading Language-specific header arguments Each language can define its own set of default header arguments. See the language-specific documentation available at -@uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}. +@uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages} for information on language-specific header arguments. -@node Buffer-wide header arguments, Header arguments in Org-mode Properties, Language Specific header arguments, Using Header arguments +@node Buffer-wide header arguments, Header arguments in Org-mode properties, Language-specific header arguments, Using header arguments @subsubheading Buffer-wide header arguments FIXME -@node Header arguments in Org-mode Properties, Code Block specific header arguments, Buffer-wide header arguments, Using Header arguments -@subsubheading header arguments in Org-mode Properties +@node Header arguments in Org-mode properties, Code block specific header arguments, Buffer-wide header arguments, Using header arguments +@subsubheading Header arguments in Org-mode properties -Header arguments are also read from Org-mode Properties (see @ref{Property +Header arguments are also read from Org-mode properties (see @ref{Property syntax}), which can be set on a buffer-wide or per-heading basis. An example of setting a header argument for all code blocks in a buffer is @@ -11262,8 +11327,8 @@ Properties defined in this way override the properties set in @code{org-set-property} function bound to @key{C-c C-x p} to set properties in Org-mode documents. -@node Code Block specific header arguments, , Header arguments in Org-mode Properties, Using Header arguments -@subsubheading Code Block specific header arguments +@node Code block specific header arguments, , Header arguments in Org-mode properties, Using header arguments +@subsubheading Code block specific header arguments The most common way to assign values to header arguments is at the code block level. This can be done by listing a sequence of header @@ -11296,28 +11361,28 @@ Header arguments for ``Library of Babel'' or function call lines can be set as s #+call: factorial(n=5) :exports results @end example -@node Specific Header arguments, , Using Header arguments, Header arguments -@subsection Specific Header arguments +@node Specific header arguments, , Using header arguments, Header arguments +@subsection Specific header arguments The following header arguments are defined: @menu -* var:: -* results:: -* file:: -* dir and remote execution:: -* exports:: -* tangle:: -* no-expand:: -* session:: -* noweb:: -* cache:: -* hlines:: -* colnames:: -* rownames:: +* var argument:: +* results argument:: +* file argument:: +* dir and remote execution:: +* exports argument:: +* tangle argument:: +* no-expand argument:: +* session argument:: +* noweb argument:: +* cache argument:: +* hlines argument:: +* colnames argument:: +* rownames argument:: @end menu -@node var, results, , Specific Header arguments -@subsubsection var +@node var argument, results argument, Specific header arguments, Specific header arguments +@subsubsection var 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 @@ -11412,7 +11477,7 @@ following the source name. #+end_src @end example -@subsubheading indexable variable values +@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 @code{example-table} to the variable @code{data}: @@ -11451,8 +11516,8 @@ For more information on indexing behavior see the documentation for the which case the entire range is returned. @end example -@node results, file, var, Specific Header arguments -@subsubsection results +@node results argument, file argument, var argument, Specific header arguments +@subsubsection results argument There are three types of results header argument. Only one option of each type may be supplied per code block. @@ -11546,8 +11611,8 @@ be prepended to the existing results. Otherwise the new results will be inserted as with @code{replace}. @end itemize -@node file, dir and remote execution, results, Specific Header arguments -@subsubsection file +@node file argument, dir and remote execution, results argument, Specific header arguments +@subsubsection file argument @code{:file} is used to specify a path for file output in which case an Org-mode style link (see @ref{Link format}) @code{file:} link is inserted into the buffer as the result. Common examples are graphical output from R, @@ -11561,7 +11626,7 @@ as python and ruby require that the code explicitly create output corresponding to the path indicated by @code{:file}. -@node dir and remote execution, exports, file, Specific Header arguments +@node dir and remote execution, exports argument, file argument, Specific header arguments @subsubsection dir and remote execution While the @code{:file} header argument can be used to specify the path to the output file, @code{:dir} specifies the default directory during code block @@ -11628,8 +11693,8 @@ directory}. Therefore, if @code{default-directory} is altered using which the link does not point. @end itemize -@node exports, tangle, dir and remote execution, Specific Header arguments -@subsubsection exports +@node exports argument, tangle argument, dir and remote execution, Specific header arguments +@subsubsection exports argument Specify what should be included in HTML or LaTeX exports of the Org-mode file. @@ -11647,8 +11712,8 @@ both the code and results are included in the exported file. E.g., nothing is included in the exported file. E.g., @code{:exports none}. @end itemize -@node tangle, no-expand, exports, Specific Header arguments -@subsubsection tangle +@node tangle argument, no-expand argument, exports argument, Specific header arguments +@subsubsection tangle argument Specify whether or not the source code block should be included in tangled extraction of source code files. @@ -11666,16 +11731,16 @@ as a file basename to which the block will be exported. E.g., @code{:tangle basename}. @end itemize -@node no-expand, session, tangle, Specific Header arguments -@subsubsection no-expand +@node no-expand argument, session argument, tangle argument, Specific header arguments +@subsubsection no-expand argument By default, code blocks are expanded with @code{org-babel-expand-src-block} during tangling. This has the effect of assigning values to variables -specified with @code{:var} (see @ref{var}), and of replacing ``noweb'' +specified with @code{:var} (see @ref{var argument}), and of replacing ``noweb'' references (see @ref{Noweb reference syntax}) with their targets. The @code{:no-expand} header argument can be used to turn off this behavior. -@node session, noweb, no-expand, Specific Header arguments -@subsubsection session +@node session argument, noweb argument, no-expand argument, Specific header arguments +@subsubsection session argument Start a session for an interpreted language where state is preserved. This applies particularly to the supported languages python, R and ruby. @@ -11685,8 +11750,8 @@ A string passed to the @code{:session} header argument will give the session a name. This makes it possible to run concurrent sessions for each interpreted language. -@node noweb, cache, session, Specific Header arguments -@subsubsection noweb +@node noweb argument, cache argument, session argument, Specific header arguments +@subsubsection noweb argument Controls the expansion of ``noweb'' style (see @ref{Noweb reference syntax}) references in a source code block. This header argument can have one of two values: @code{yes} or @code{no}. @@ -11726,8 +11791,8 @@ Note that noweb replacement text that does not contain any newlines will not be affected by this change, so it is still possible to use inline noweb references. -@node cache, hlines, noweb, Specific Header arguments -@subsubsection cache +@node cache argument, hlines argument, noweb argument, Specific header arguments +@subsubsection cache argument Controls the use of in-buffer caching of source code block results to avoid re-running unchanged source code blocks. This header argument can have one of two values: @code{yes} or @code{no}. @@ -11744,8 +11809,8 @@ executions of the source code block. If the source code block has not changed since the last time it was evaluated, it will not be re-evaluated. @end itemize -@node hlines, colnames, cache, Specific Header arguments -@subsubsection hlines +@node hlines argument, colnames argument, cache argument, Specific header arguments +@subsubsection hlines argument Tables are frequently represented with one or more horizontal lines, or hlines. The @code{:hlines} argument to a code block accepts the values @code{yes} or @code{no}, with a default value of @code{no}. @@ -11801,8 +11866,8 @@ Leaves hlines in the table. Setting @code{:hlines yes} has this effect. @end example @end itemize -@node colnames, rownames, hlines, Specific Header arguments -@subsubsection colnames +@node colnames argument, rownames argument, hlines argument, Specific header arguments +@subsubsection colnames argument The @code{:colnames} header argument accepts the values @code{yes}, @code{no}, or @code{nil} for unassigned. The default value is @code{nil}. @@ -11841,8 +11906,8 @@ does not ``look like'' it has column names (i.e. the second row is not an hline) @end itemize -@node rownames, , colnames, Specific Header arguments -@subsubsection rownames +@node rownames argument, , colnames argument, Specific header arguments +@subsubsection rownames argument The @code{:rownames} header argument can take on the values @code{yes} or @code{no}, with a default value of @code{no}. @@ -12013,7 +12078,7 @@ kept pressed, resulting in the following additional keybindings. @item @key{C-c C-v C-z} @tab org-babel-switch-to-session @end multitable -@node Batch execution, , Key bindings & useful functions, Working With Source Code +@node Batch execution, , Key bindings & useful functions, Working With Source Code @section Batch execution It is possible to call functions from the command line. This shell script calls @code{org-babel-tangle} on every one of its arguments. @@ -12049,14 +12114,14 @@ emacsclient \ @chapter Miscellaneous @menu -* Completion:: M-TAB knows what you need -* Speed keys:: Electic commands at the beginning of a headline -* Customization:: Adapting Org to your taste -* In-buffer settings:: Overview of the #+KEYWORDS -* The very busy C-c C-c key:: When in doubt, press C-c C-c -* Clean view:: Getting rid of leading stars in the outline -* TTY keys:: Using Org on a tty -* Interaction:: Other Emacs packages +* Completion:: M-TAB knows what you need +* Speed keys:: Electic commands at the beginning of a headline +* Customization:: Adapting Org to your taste +* In-buffer settings:: Overview of the #+KEYWORDS +* The very busy C-c C-c key:: When in doubt, press C-c C-c +* Clean view:: Getting rid of leading stars in the outline +* TTY keys:: Using Org on a tty +* Interaction:: Other Emacs packages @end menu @@ -12630,8 +12695,8 @@ Org lives in the world of GNU Emacs and interacts in various ways with other code out there. @menu -* Cooperation:: Packages Org cooperates with -* Conflicts:: Packages that lead to conflicts +* Cooperation:: Packages Org cooperates with +* Conflicts:: Packages that lead to conflicts @end menu @node Cooperation, Conflicts, Interaction, Interaction @@ -12824,16 +12889,16 @@ This appendix covers some aspects where users can extend the functionality of Org. @menu -* Hooks:: Who to reach into Org's internals -* Add-on packages:: Available extensions -* Adding hyperlink types:: New custom link types -* Context-sensitive commands:: How to add functionality to such commands -* Tables in arbitrary syntax:: Orgtbl for La@TeX{} and other programs -* Dynamic blocks:: Automatically filled blocks -* Special agenda views:: Customized views +* Hooks:: Who to reach into Org's internals +* Add-on packages:: Available extensions +* Adding hyperlink types:: New custom link types +* Context-sensitive commands:: How to add functionality to such commands +* Tables in arbitrary syntax:: Orgtbl for La@TeX{} and other programs +* Dynamic blocks:: Automatically filled blocks +* Special agenda views:: Customized views * Extracting agenda information:: Postprocessing of agenda information -* Using the property API:: Writing programs that use entry properties -* Using the mapping API:: Mapping over all or selected entries +* Using the property API:: Writing programs that use entry properties +* Using the mapping API:: Mapping over all or selected entries @end menu @node Hooks, Add-on packages, Hacking, Hacking @@ -13026,10 +13091,10 @@ or Texinfo.) @menu -* Radio tables:: Sending and receiving radio tables -* A LaTeX example:: Step by step, almost a tutorial -* Translator functions:: Copy and modify -* Radio lists:: Doing the same for lists +* Radio tables:: Sending and receiving radio tables +* A LaTeX example:: Step by step, almost a tutorial +* Translator functions:: Copy and modify +* Radio lists:: Doing the same for lists @end menu @node Radio tables, A LaTeX example, Tables in arbitrary syntax, Tables in arbitrary syntax @@ -13800,9 +13865,9 @@ in-buffer settings, but it will understand the logistics of TODO state (@pxref{Setting tags}) only for those set in these variables. @menu -* Setting up the staging area:: Where to interact with the mobile device -* Pushing to MobileOrg:: Uploading Org files and agendas -* Pulling from MobileOrg:: Integrating captured and flagged items +* Setting up the staging area:: Where to interact with the mobile device +* Pushing to MobileOrg:: Uploading Org files and agendas +* Pulling from MobileOrg:: Integrating captured and flagged items @end menu @node Setting up the staging area, Pushing to MobileOrg, MobileOrg, MobileOrg From 7b19b0e547f0c0228aab31d0694f1197500533dc Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Wed, 16 Jun 2010 21:24:08 -0700 Subject: [PATCH 072/138] delete trailing whitespace --- doc/org.texi | 152 +++++++++++++++++++++++++-------------------------- 1 file changed, 76 insertions(+), 76 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 0702d2414..e73e5190c 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -108,7 +108,7 @@ license to the document, as described in section 6 of the license. * Markup:: Prepare text for rich export * Exporting:: Sharing and publishing of notes * Publishing:: Create a web site of linked Org files -* Working With Source Code:: Export, evaluate, and tangle code blocks +* Working With Source Code:: Export, evaluate, and tangle code blocks * Miscellaneous:: All the rest which did not fit elsewhere * Hacking:: How to hack your way around * MobileOrg:: Viewing and capture on a mobile device @@ -306,7 +306,7 @@ Markup for rich export * Images and tables:: Tables and Images will be included * Literal examples:: Source code examples with special formatting * Include files:: Include additional files into a document -* Index entries:: +* Index entries:: * Macro replacement:: Use macros to create complex output * Embedded LaTeX:: LaTeX can be freely used inside Org documents @@ -380,13 +380,13 @@ Publishing * Uploading files:: How to get files up on the server * Sample configuration:: Example projects * Triggering publication:: Publication commands -* Library of Babel:: -* Languages:: -* Header arguments:: -* Results:: -* Noweb reference syntax:: -* Key bindings & useful functions:: -* Batch execution:: +* Library of Babel:: +* Languages:: +* Header arguments:: +* Results:: +* Noweb reference syntax:: +* Key bindings & useful functions:: +* Batch execution:: Configuration @@ -421,32 +421,32 @@ Working With Source Code Header arguments -* Using header arguments:: -* Specific header arguments:: +* Using header arguments:: +* Specific header arguments:: Using header arguments -* System-wide header arguments:: -* Language-specific header arguments:: -* Buffer-wide header arguments:: -* Header arguments in Org-mode properties:: -* Code block specific header arguments:: +* System-wide header arguments:: +* Language-specific header arguments:: +* Buffer-wide header arguments:: +* Header arguments in Org-mode properties:: +* Code block specific header arguments:: Specific header arguments -* var argument:: -* results argument:: -* file argument:: -* dir and remote execution:: -* exports argument:: -* tangle argument:: -* no-expand argument:: -* session argument:: -* noweb argument:: -* cache argument:: -* hlines argument:: -* colnames argument:: -* rownames argument:: +* var argument:: +* results argument:: +* file argument:: +* dir and remote execution:: +* exports argument:: +* tangle argument:: +* no-expand argument:: +* session argument:: +* noweb argument:: +* cache argument:: +* hlines argument:: +* colnames argument:: +* rownames argument:: Miscellaneous @@ -1285,7 +1285,7 @@ as bullets. @emph{Ordered} list items start with a numeral followed by either a period or a right parenthesis, such as @samp{1.} or @samp{1)}. If you want a list to start a different value (e.g. 20), start the text of the item with -@code{[@@start:20]}. +@code{[@@start:20]}. @item @emph{Description} list items are unordered list items, and contain the separator @samp{ :: } to separate the description @emph{term} from the @@ -8311,7 +8311,7 @@ summarizes the markup rules used in an Org-mode buffer. * Images and tables:: Tables and Images will be included * Literal examples:: Source code examples with special formatting * Include files:: Include additional files into a document -* Index entries:: +* Index entries:: * Macro replacement:: Use macros to create complex output * Embedded LaTeX:: LaTeX can be freely used inside Org documents @end menu @@ -8705,7 +8705,7 @@ the contains an exclamation mark will create a sub item. See @ref{Generating an index} for more information. @example -* Curriculum Vitae +* Curriculum Vitae #+INDEX: CV #+INDEX: Application!CV @end example @@ -9927,7 +9927,7 @@ Here is a simple example Org document that is intended for beamer export. #+COLUMNS: %35ITEM %10BEAMER_env(Env) %10BEAMER_envargs(Args) %4BEAMER_col(Col) %8BEAMER_extra(Ex) * This is the first structural section - + ** Frame 1 \\ with a subtitle *** Thanks to Eric Fraga :BMCOL:B_block: :PROPERTIES: @@ -10404,13 +10404,13 @@ Publishing has been contributed to Org by David O'Toole. * Uploading files:: How to get files up on the server * Sample configuration:: Example projects * Triggering publication:: Publication commands -* Library of Babel:: -* Languages:: -* Header arguments:: -* Results:: -* Noweb reference syntax:: -* Key bindings & useful functions:: -* Batch execution:: +* Library of Babel:: +* Languages:: +* Header arguments:: +* Results:: +* Noweb reference syntax:: +* Key bindings & useful functions:: +* Batch execution:: @end menu @node Configuration, Uploading files, Publishing, Publishing @@ -10709,7 +10709,7 @@ file is part of any project in @code{org-publish-project-alist}. @subsection Generating a sitemap @cindex sitemap, of published pages -The following properties may be used to control publishing of +The following properties may be used to control publishing of a map of files for a given project. @multitable @columnfractions 0.35 0.65 @@ -11241,8 +11241,8 @@ section provides an overview of the use of header arguments, and then describes each header argument in detail. @menu -* Using header arguments:: -* Specific header arguments:: +* Using header arguments:: +* Specific header arguments:: @end menu @node Using header arguments, Specific header arguments, Header arguments, Header arguments @@ -11251,11 +11251,11 @@ describes each header argument in detail. The values of header arguments can be set in five different ways, each more specific (and having higher priority) than the last. @menu -* System-wide header arguments:: -* Language-specific header arguments:: -* Buffer-wide header arguments:: -* Header arguments in Org-mode properties:: -* Code block specific header arguments:: +* System-wide header arguments:: +* Language-specific header arguments:: +* Buffer-wide header arguments:: +* Header arguments in Org-mode properties:: +* Code block specific header arguments:: @end menu @node System-wide header arguments, Language-specific header arguments, Using header arguments, Using header arguments @@ -11366,19 +11366,19 @@ Header arguments for ``Library of Babel'' or function call lines can be set as s The following header arguments are defined: @menu -* var argument:: -* results argument:: -* file argument:: -* dir and remote execution:: -* exports argument:: -* tangle argument:: -* no-expand argument:: -* session argument:: -* noweb argument:: -* cache argument:: -* hlines argument:: -* colnames argument:: -* rownames argument:: +* var argument:: +* results argument:: +* file argument:: +* dir and remote execution:: +* exports argument:: +* tangle argument:: +* no-expand argument:: +* session argument:: +* noweb argument:: +* cache argument:: +* hlines argument:: +* colnames argument:: +* rownames argument:: @end menu @node var argument, results argument, Specific header arguments, Specific header arguments @@ -11643,7 +11643,7 @@ case that path will be interpreted relative to the default directory. In other words, if you want your plot to go into a folder called Work in your home directory, you could use -@example +@example #+begin_src R :file myplot.png :dir ~/Work matplot(matrix(rnorm(100), 10), type="l") #+end_src @@ -11653,7 +11653,7 @@ home directory, you could use A directory on a remote machine can be specified using tramp file syntax, in which case the code will be evaluated on the remote machine. An example is -@example +@example #+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu: plot(1:10, main=system("hostname", intern=TRUE)) #+end_src @@ -11667,7 +11667,7 @@ created. So, in the above example a plot will be created on the remote machine, and a link of the following form will be inserted in the org buffer: -@example +@example [[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]] @end example @@ -11884,7 +11884,7 @@ processing, then reapplied to the results. |---| | b | | c | - + #+srcname: echo-table-again #+begin_src python :var tab=less-cols return [[val + '*' for val in row] for row in tab] @@ -11922,11 +11922,11 @@ and is then reapplied to the results. @example #+tblname: with-rownames | one | 1 | 2 | 3 | 4 | 5 | -| two | 6 | 7 | 8 | 9 | 10 | +| two | 6 | 7 | 8 | 9 | 10 | #+srcname: echo-table-once-again #+begin_src python :var tab=with-rownames :rownames yes - return [[val + 10 for val in row] for row in tab] + return [[val + 10 for val in row] for row in tab] #+end_src #+results: echo-table-once-again @@ -12666,16 +12666,16 @@ is really only fun with @kbd{S-@key{cursor}} keys, whereas on a tty you would rather use @kbd{C-c .} to re-insert the timestamp. @multitable @columnfractions 0.15 0.2 0.1 0.2 -@item @b{Default} @tab @b{Alternative 1} @tab @b{Speed key} @tab @b{Alternative 2} -@item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab @kbd{C} @tab -@item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{l} @tab @kbd{@key{Esc} @key{left}} -@item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab @kbd{L} @tab +@item @b{Default} @tab @b{Alternative 1} @tab @b{Speed key} @tab @b{Alternative 2} +@item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab @kbd{C} @tab +@item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{l} @tab @kbd{@key{Esc} @key{left}} +@item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab @kbd{L} @tab @item @kbd{M-@key{right}} @tab @kbd{C-c C-x r} @tab @kbd{r} @tab @kbd{@key{Esc} @key{right}} -@item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab @kbd{R} @tab -@item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{ } @tab @kbd{@key{Esc} @key{up}} -@item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab @kbd{U} @tab +@item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab @kbd{R} @tab +@item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{ } @tab @kbd{@key{Esc} @key{up}} +@item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab @kbd{U} @tab @item @kbd{M-@key{down}} @tab @kbd{C-c C-x d} @tab @kbd{ } @tab @kbd{@key{Esc} @key{down}} -@item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab @kbd{D} @tab +@item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab @kbd{D} @tab @item @kbd{S-@key{RET}} @tab @kbd{C-c C-x c} @tab @kbd{ } @tab @item @kbd{M-@key{RET}} @tab @kbd{C-c C-x m} @tab @kbd{ } @tab @kbd{@key{Esc} @key{RET}} @item @kbd{M-S-@key{RET}} @tab @kbd{C-c C-x M} @tab @kbd{ } @tab @@ -13893,7 +13893,7 @@ Emacs about it: @end lisp Org-mode has commands to put files for @i{MobileOrg} into that directory, -and to read captured notes from there. +and to read captured notes from there. @node Pushing to MobileOrg, Pulling from MobileOrg, Setting up the staging area, MobileOrg @section Pushing to MobileOrg From 9c7bad1fabbd0b95393370ba46d000350aea3aab Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Wed, 16 Jun 2010 21:34:30 -0700 Subject: [PATCH 073/138] babel-doc: adding buffer-wide header argument documentation --- doc/org.texi | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index e73e5190c..4604b5e4e 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -11291,13 +11291,24 @@ blocks. @node Language-specific header arguments, Buffer-wide header arguments, System-wide header arguments, Using header arguments @subsubheading Language-specific header arguments Each language can define its own set of default header arguments. See the -language-specific documentation available at -@uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages} -for information on language-specific header arguments. +language-specific documentation available online at +@uref{http://orgmode.org/worg/org-contrib/babel}. @node Buffer-wide header arguments, Header arguments in Org-mode properties, Language-specific header arguments, Using header arguments @subsubheading Buffer-wide header arguments -FIXME +Buffer-wide header arguments may be specified through the use of a special +line placed anywhere in an Org-mode file. The line consists of the +@code{#+BABEL:} keyword followed by a series of header arguments which may be +specified using the standard header argument syntax. + +For example the following would set @code{session} to @code{*R*}, and +@code{results} to @code{silent} for every code block in the buffer, ensuring +that all execution took place in the same session, and no results would be +inserted into the buffer. + +@example +#+BABEL: :session *R* :results silent +@end example @node Header arguments in Org-mode properties, Code block specific header arguments, Buffer-wide header arguments, Using header arguments @subsubheading Header arguments in Org-mode properties From cab1e23d61ef698b17039ab42990383555c53c5a Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Thu, 17 Jun 2010 07:31:16 -0700 Subject: [PATCH 074/138] babel-doc: adding c++ and sqlite as supported languages, and removing table comment --- doc/org.texi | 61 ++-------------------------------------------------- 1 file changed, 2 insertions(+), 59 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 4604b5e4e..e234f0503 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -11133,11 +11133,11 @@ l}. @section Languages Code blocks in the following languages are supported. -@c BEGIN RECEIVE ORGTBL org-babel-lang-table @multitable @columnfractions 0.583 0.417 @item Language @tab Identifier @item Asymptote @tab asymptote @item C @tab C +@item C @tab C++ @item Clojure @tab clojure @item css @tab css @item ditaa @tab ditaa @@ -11158,66 +11158,9 @@ Code blocks in the following languages are supported. @item GNU Screen @tab screen @item shell @tab sh @item SQL @tab sql +@item Sqlite @tab sqlite @end multitable -@c END RECEIVE ORGTBL org-babel-lang-table -@ignore -The original table from reference.org is below; I'm just using the first column for now. - -#+ORGTBL: SEND org-babel-lang-table orgtbl-to-texinfo - | Language | Identifier | - |----------------+------------| - | Asymptote | asymptote | - | C | C | - | Clojure | clojure | - | css | css | - | ditaa | ditaa | - | Graphviz | dot | - | Emacs Lisp | emacs-lisp | - | gnuplot | gnuplot | - | Haskell | haskell | - | Matlab | matlab | - | LaTeX | latex | - | Objective Caml | ocaml | - | Octave | octave | - | OZ | oz | - | Perl | perl | - | Python | python | - | R | R | - | Ruby | ruby | - | Sass | sass | - | GNU Screen | screen | - | shell | sh | - | SQL | sql | - - - | Language | Documentation | Identifier | Requirements | - |----------------+---------------------------------------------------------------------------------+------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| - | Asymptote | org-babel-doc-asymptote | asymptote | [[http://asymptote.sourceforge.net/][asymptote]], [[http://asymptote.sourceforge.net/doc/Editing-modes.html][asy-mode]] | - | C | [[file:languages/org-babel-doc-C.org][org-babel-doc-C]] | C | none | - | Clojure | [[file:languages/org-babel-doc-clojure.org][org-babel-doc-clojure]] | clojure | [[http://clojure.org/][clojure]], [[http://www.emacswiki.org/emacs/clojure-mode.el][clojure-mode]], [[http://common-lisp.net/project/slime/][slime]], [[http://clojure.codestuffs.com/][swank-clojure]] | - | css | org-babel-doc-css | css | none | - | ditaa | org-babel-doc-ditaa | ditaa | [[http://ditaa.org/ditaa/][ditaa]] (bundled with Org-mode) | - | Graphviz | org-babel-doc-dot | dot | [[http://www.graphviz.org/][dot]] | - | Emacs Lisp | org-babel-doc-emacs-lisp | emacs-lisp | none | - | gnuplot | org-babel-doc-gnuplot | gnuplot | [[http://www.gnuplot.info/][gnuplot]], [[http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html][gnuplot-mode]] | - | Haskell | org-babel-doc-haskell | haskell | [[http://www.haskell.org/][haskell]], [[http://projects.haskell.org/haskellmode-emacs/][haskell-mode]], [[http://www.haskell.org/haskellwiki/Haskell_mode_for_Emacs#inf-haskell.el:_the_best_thing_since_the_breadknife][inf-haskell]], [[http://people.cs.uu.nl/andres/lhs2tex/][lhs2tex]] | - | Matlab | [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] | matlab | matlab, [[http://sourceforge.net/projects/matlab-emacs/][matlab.el]] | - | LaTeX | [[file:languages/org-babel-doc-LaTeX.org][org-babel-doc-latex]] | latex | [[http://www.latex-project.org/][latex]], [[http://www.gnu.org/software/auctex/][auctex]], [[http://www.gnu.org/software/auctex/reftex.html][reftex]] | - | Objective Caml | org-babel-doc-ocaml | ocaml | [[http://caml.inria.fr/][ocaml]], [[http://www-rock.inria.fr/~acohen/tuareg/][tuareg-mode]] | - | Octave | [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] | octave | octave | - | OZ | [[file:languages/org-babel-doc-oz.org][org-babel-doc-oz]] | oz | [[http://www.mozart-oz.org/][Mozart]] which includes a major mode | - | Perl | org-babel-doc-perl | perl | [[http://www.perl.org/][perl]], [[http://www.emacswiki.org/emacs/CPerlMode][cperl-mode]] (optional) | - | Python | org-babel-doc-python | python | [[http://www.python.org/][python]], [[https://launch pad.net/python-mode][python-mode]] (optional) | - | R | [[file:languages/org-babel-doc-R.org][org-babel-doc-R]] | R | [[http://www.r-project.org/][R]], [[http://ess.r-project.org/][ess-mode]] | - | Ruby | org-babel-doc-ruby | ruby | [[http://www.ruby-lang.org/][ruby]], [[http://www.ruby-lang.org/][irb]], [[http://github.com/eschulte/rinari/raw/master/util/ruby-mode.el][ruby-mode]], [[http://github.com/eschulte/rinari/raw/master/util/inf-ruby.el][inf-ruby mode]] | - | Sass | org-babel-doc-sass | sass | [[http://sass-lang.com/][sass]], [[http://github.com/nex3/haml/blob/master/extra/sass-mode.el][sass-mode]] | - | GNU Screen | [[file:languages/org-babel-doc-screen.org][org-babel-doc-screen]] | screen | [[http://www.gnu.org/software/screen/][screen]], a terminal | - | shell | org-babel-doc-sh | sh | a shell | - | SQL | org-babel-doc-sql | sql | none | - - -@end ignore See the language specific documentation and an up to date list of languages that is available at @uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}. From c981f6d697c087b87bc90e417ccdb4dea59532a4 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Thu, 17 Jun 2010 09:01:24 -0700 Subject: [PATCH 075/138] babel: simplifying handling of tangle langs - Removed the org-babel-tangle-langs variable. - Added the org-babel-tangle-lang-exts alist for associating languages with file extensions - Comments now only added when the :comments header argument is set to yes * lisp/babel/ob-tangle.el (org-babel-tangle-w-comments): this is now a defcustom (org-babel-tangle-lang-exts): alist associating languages with file extension, this is also a defcustom (org-babel-spec-to-string): no longer using the complex tangle-lang variables --- lisp/babel/ob-tangle.el | 51 ++++++++++++++++++----------------------- 1 file changed, 22 insertions(+), 29 deletions(-) diff --git a/lisp/babel/ob-tangle.el b/lisp/babel/ob-tangle.el index 40978813b..30a962307 100644 --- a/lisp/babel/ob-tangle.el +++ b/lisp/babel/ob-tangle.el @@ -33,19 +33,25 @@ (eval-when-compile (require 'cl)) -(defvar org-babel-tangle-langs nil - "List of languages supported by `org-babel-tangle'. The first -element of each language's list is a string indicating the name -of the language, the second element should be the file extension -of the language, an optional third element the shebang(#!) line -to use when writing out the language to file, and an optional -fourth element is a flag which when true indicates that the -language does not support comments.") - -(defvar org-babel-tangle-w-comments nil +(defcustom org-babel-tangle-w-comments nil "Control the insertion of comments into tangled code. Non-nil value will result in the insertion of comments for those -languages with comment support.") +languages with comment support." + :group 'org-babel-tangle + :type 'boolean) + +(defcustom org-babel-tangle-lang-exts + '(("emacs-lisp" . "el")) + "Alist mapping languages to their file extensions. +The key is the language name, the value is the string that should +be inserted as the extension commonly used to identify files +written in this language. If no entry is found in this list, +then the name of the language is used." + :group 'org-babel-tangle + :type '(repeat + (cons + (string "Language name") + (string "File Extension")))) (defun org-babel-load-file (file) "Load the contents of the Emacs Lisp source code blocks in the @@ -101,6 +107,7 @@ exported source code blocks by language." (lambda (by-lang) (let* ((lang (car by-lang)) (specs (cdr by-lang)) + (ext (or (cdr (assoc lang org-babel-tangle-lang-exts)) lang)) (lang-f (intern (concat (or (and (cdr (assoc lang org-src-lang-modes)) @@ -108,19 +115,14 @@ exported source code blocks by language." (cdr (assoc lang org-src-lang-modes)))) lang) "-mode"))) - (lang-specs (cdr (assoc lang org-babel-tangle-langs))) - (ext (nth 0 lang-specs)) - (she-bang (nth 1 lang-specs)) - (commentable (and (fboundp lang-f) (not (nth 2 lang-specs)))) she-banged) (mapc (lambda (spec) (flet ((get-spec (name) (cdr (assoc name (nth 2 spec))))) (let* ((tangle (get-spec :tangle)) - (she-bang (if (> (length (get-spec :shebang)) 0) - (get-spec :shebang) - she-bang)) + (she-bang ((lambda (sheb) (when (> (length sheb) 0) sheb)) + (get-spec :shebang))) (base-name (or (cond ((string= "yes" tangle) (file-name-sans-extension @@ -219,18 +221,13 @@ code blocks by language." (cdr (assoc :noweb params)))) (org-babel-expand-noweb-references info) - (nth 1 info))) - (nth 2 - (cdr (assoc src-lang - org-babel-tangle-langs)))) + (nth 1 info)))) by-lang)) blocks)))))) ;; ensure blocks in the correct order (setq blocks (mapcar (lambda (by-lang) (cons (car by-lang) (reverse (cdr by-lang)))) blocks)) - ;; blocks should contain all source-blocks organized by language - ;; (message "blocks=%S" blocks) ;; debugging blocks)) (defun org-babel-spec-to-string (spec) @@ -243,11 +240,7 @@ form (let ((link (nth 0 spec)) (source-name (nth 1 spec)) (body (nth 3 spec)) - (commentable (not (if (> (length (cdr (assoc :comments (nth 2 spec)))) - 0) - (string= (cdr (assoc :comments (nth 2 spec))) - "no") - (nth 4 spec))))) + (commentable (string= (cdr (assoc :comments (nth 2 spec))) "yes"))) (flet ((insert-comment (text) (when (and commentable org-babel-tangle-w-comments) From 9ae48928ca560631e39197414b6e15018993e241 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Thu, 17 Jun 2010 09:29:38 -0700 Subject: [PATCH 076/138] babel: removed ob-interpreters variable -- more natural evaluation decisions Babel will now try to evaluate any source code block for which the required language-specific functions are defined. --- lisp/babel/ob-exp.el | 101 ++++++++++++++++++------------------- lisp/babel/ob.el | 116 ++++++++++++++----------------------------- 2 files changed, 87 insertions(+), 130 deletions(-) diff --git a/lisp/babel/ob-exp.el b/lisp/babel/ob-exp.el index 18220744d..a12f2795f 100644 --- a/lisp/babel/ob-exp.el +++ b/lisp/babel/ob-exp.el @@ -83,19 +83,18 @@ results - just like none only the block is run on export ensuring none ----- do not display either code or results upon export" (interactive) (message "org-babel-exp processing...") - (when (member (nth 0 headers) org-babel-interpreters) - (save-excursion - (goto-char (match-beginning 0)) - (let* ((info (org-babel-get-src-block-info)) - (params (nth 2 info))) - ;; expand noweb references in the original file - (setf (nth 1 info) - (if (and (cdr (assoc :noweb params)) - (string= "yes" (cdr (assoc :noweb params)))) - (org-babel-expand-noweb-references - info (get-file-buffer org-current-export-file)) - (nth 1 info))) - (org-babel-exp-do-export info 'block))))) + (save-excursion + (goto-char (match-beginning 0)) + (let* ((info (org-babel-get-src-block-info)) + (params (nth 2 info))) + ;; expand noweb references in the original file + (setf (nth 1 info) + (if (and (cdr (assoc :noweb params)) + (string= "yes" (cdr (assoc :noweb params)))) + (org-babel-expand-noweb-references + info (get-file-buffer org-current-export-file)) + (nth 1 info))) + (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. @@ -209,11 +208,11 @@ evaluated." (case type ('inline (format "=%s=" body)) ('block - (let ((str + (let ((str (format "#+BEGIN_SRC %s %s\n%s%s#+END_SRC\n" lang switches body (if (and body (string-match "\n$" body)) "" "\n")))) - (when name + (when name (add-text-properties 0 (length str) (list 'org-caption @@ -224,12 +223,12 @@ evaluated." str)) ('lob (let ((call-line (and (string-match "results=" (car args)) - (substring (car args) (match-end 0))))) - (cond - ((eq backend 'html) - (format "\n#+HTML: \n" + (substring (car args) (match-end 0))))) + (cond + ((eq backend 'html) + (format "\n#+HTML: \n" call-line)) - ((format ": %s\n" call-line)))))))) + ((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 @@ -252,36 +251,38 @@ results into the buffer." ":" (match-string 2 (cdr pair)))) pair)) (nth 2 info)))) - (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)=" - (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"))))) - ""))))) + ;; 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)=" + (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) ;;; ob-exp.el ends here diff --git a/lisp/babel/ob.el b/lisp/babel/ob.el index d24ce191a..27886bfa8 100644 --- a/lisp/babel/ob.el +++ b/lisp/babel/ob.el @@ -32,9 +32,7 @@ (eval-when-compile (require 'cl)) (require 'org) -(defvar org-babel-interpreters nil) (defvar org-babel-call-process-region-original) -(defvar org-babel-lob-one-liner-regexp) (declare-function orgtbl-to-generic "org-table" (table params)) (declare-function org-babel-ref-split-args "ob-ref" (arg-string)) (declare-function org-babel-ref-variables "ob-ref" (params)) @@ -53,11 +51,27 @@ "^[ \t]*#\\+\\(srcname\\|source\\|function\\):[ \t]*" "Regular expression used to match a source name line.") -(defvar org-babel-src-block-regexp nil - "Regexp used to test when inside of a org-babel src-block") +(defvar org-babel-src-block-regexp + (concat + ;; (1) indentation (2) lang + "^\\([ \t]*\\)#\\+begin_src[ \t]+\\([^ \t]+\\)[ \t]*" + ;; (3) switches + "\\([^\":\n]*\"[^\"\n*]*\"[^\":\n]*\\|[^\":\n]*\\)" + ;; (4) header arguments + "\\([^\n]*\\)\n" + ;; (5) body + "\\([^\000]+?\n\\)[ \t]*#\\+end_src") + "Regexp used to identify code blocks.") -(defvar org-babel-inline-src-block-regexp nil - "Regexp used to test when on an inline org-babel src-block") +(defvar org-babel-inline-src-block-regexp + (concat + ;; (1) replacement target (2) lang + "[ \f\t\n\r\v]\\(src_\\([^ \t]+\\)" + ;; (3,4) (unused, headers) + "\\(\\|\\[\\(.*?\\)\\]\\)" + ;; (5) body + "{\\([^\f\n\r\v]+?\\)}\\)") + "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. @@ -214,63 +228,6 @@ can not be resolved.") (concat org-babel-source-name-regexp (regexp-quote name) "[ \t\n]*" (substring org-babel-src-block-regexp 1))) -(defun org-babel-add-interpreter (interpreter) - "Add INTERPRETER to `org-babel-interpreters' and update -`org-babel-src-block-regexp' appropriately." - (unless (member interpreter org-babel-interpreters) - (setq org-babel-interpreters - (sort (cons interpreter org-babel-interpreters) - (lambda (left right) - (> (length left) (length right))))) - (org-babel-set-interpreters 'org-babel-interpreters org-babel-interpreters))) - -(defun org-babel-set-interpreters (var value) - "Update the regular expressions used to match block and inline -code." - (set-default var value) - (setq - org-babel-src-block-regexp - (concat "^\\([ \t]*\\)#\\+begin_src[ \t]+\\(" ;; (1) indentation (2) lang - (mapconcat 'regexp-quote value "\\|") - "\\)[ \t]*" - "\\([^\":\n]*\"[^\"\n*]*\"[^\":\n]*\\|[^\":\n]*\\)" ;; (3) switches - "\\([^\n]*\\)\n" ;; (4) header arguments - "\\([^\000]+?\n\\)[ \t]*#\\+end_src"));; (5) body - (setq org-babel-inline-src-block-regexp - (concat "[ \f\t\n\r\v]\\(src_" ;; (1) replacement target - "\\(" ;; (2) lang - (mapconcat 'regexp-quote value "\\|") - "\\)" - "\\(\\|\\[\\(.*?\\)\\]\\)" ;; (3,4) (unused, headers) - "{\\([^\f\n\r\v]+?\\)}" ;; (5) body - "\\)"))) - -(defcustom org-babel-interpreters '() - "Interpreters allows for evaluation tags. -This is a list of program names (as strings) that can evaluate code and -insert the output into an Org-mode buffer. Valid choices are - -R Evaluate R code -emacs-lisp Evaluate Emacs Lisp code and display the result -sh Pass command to the shell and display the result -perl The perl interpreter -python The python interpreter -ruby The ruby interpreter - -The source block regexp `org-babel-src-block-regexp' is updated -when a new interpreter is added to this list through the -customize interface. To add interpreters to this variable from -lisp code use the `org-babel-add-interpreter' function." - :group 'org-babel - :set 'org-babel-set-interpreters - :type '(set :greedy t - (const "R") - (const "emacs-lisp") - (const "sh") - (const "perl") - (const "python") - (const "ruby"))) - ;;; functions (defvar call-process-region) (defun org-babel-execute-src-block (&optional arg info params) @@ -318,8 +275,8 @@ block." (unwind-protect (flet ((call-process-region (&rest args) (apply 'org-babel-tramp-handle-call-process-region args))) - (unless (member lang org-babel-interpreters) - (error "Language is not in `org-babel-interpreters': %s" lang)) + (unless (fboundp cmd) + (error "No org-babel-execute function for %s!" lang)) (if (and (not arg) new-hash (equal new-hash old-hash)) (save-excursion ;; return cached result (goto-char (org-babel-where-is-src-block-result nil info)) @@ -375,13 +332,11 @@ session. After loading the body this pops open the session." (lang (nth 0 info)) (body (nth 1 info)) (params (nth 2 info)) - (session (cdr (assoc :session params)))) - (unless (member lang org-babel-interpreters) - (error "Language is not in `org-babel-interpreters': %s" lang)) - ;; if called with a prefix argument, then process header arguments - (pop-to-buffer - (funcall (intern (concat "org-babel-load-session:" lang)) - session body params)) + (session (cdr (assoc :session params))) + (cmd (intern (concat "org-babel-load-session:" lang)))) + (unless (fboundp cmd) + (error "No org-babel-load-session function for %s!" lang)) + (pop-to-buffer (funcall cmd session body params)) (end-of-line 1))) (defun org-babel-switch-to-session (&optional arg info) @@ -397,19 +352,20 @@ of the source block to the kill ring." (session (cdr (assoc :session params))) (dir (cdr (assoc :dir params))) (default-directory - (or (and dir (file-name-as-directory dir)) default-directory))) - (unless (member lang org-babel-interpreters) - (error "Language is not in `org-babel-interpreters': %s" lang)) + (or (and dir (file-name-as-directory dir)) default-directory)) + (cmd (intern (format "org-babel-%s-initiate-session" lang))) + (cmd2 (intern (concat "org-babel-prep-session:" lang)))) + (unless (fboundp cmd) + (error "No org-babel-initiate-session function for %s!" lang)) ;; copy body to the kill ring (with-temp-buffer (insert (org-babel-trim body)) (copy-region-as-kill (point-min) (point-max))) ;; if called with a prefix argument, then process header arguments - (when arg - (funcall (intern (concat "org-babel-prep-session:" lang)) session params)) + (unless (fboundp cmd2) + (error "No org-babel-prep-session function for %s!" lang)) + (when arg (funcall cmd2 session params)) ;; just to the session using pop-to-buffer - (pop-to-buffer - (funcall (intern (format "org-babel-%s-initiate-session" lang)) - session params)) + (pop-to-buffer (funcall cmd session params)) (end-of-line 1))) (defalias 'org-babel-pop-to-session 'org-babel-switch-to-session) From 97ead27f78cbaadef69d8f9bad0d08bc9563b380 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Thu, 17 Jun 2010 09:44:25 -0700 Subject: [PATCH 077/138] babel: remove all language file reference to define language variables --- contrib/babel/langs/ob-oz.el | 8 -------- lisp/babel/langs/ob-C.el | 6 ------ lisp/babel/langs/ob-R.el | 4 ---- lisp/babel/langs/ob-asymptote.el | 4 ---- lisp/babel/langs/ob-clojure.el | 5 ----- lisp/babel/langs/ob-css.el | 4 ---- lisp/babel/langs/ob-ditaa.el | 4 ---- lisp/babel/langs/ob-dot.el | 4 ---- lisp/babel/langs/ob-emacs-lisp.el | 4 ---- lisp/babel/langs/ob-gnuplot.el | 4 ---- lisp/babel/langs/ob-haskell.el | 4 ---- lisp/babel/langs/ob-latex.el | 4 ---- lisp/babel/langs/ob-matlab.el | 4 ---- lisp/babel/langs/ob-ocaml.el | 4 ---- lisp/babel/langs/ob-octave.el | 3 --- lisp/babel/langs/ob-perl.el | 4 ---- lisp/babel/langs/ob-python.el | 4 ---- lisp/babel/langs/ob-ruby.el | 4 ---- lisp/babel/langs/ob-sass.el | 4 ---- lisp/babel/langs/ob-screen.el | 4 ---- lisp/babel/langs/ob-sh.el | 4 ---- lisp/babel/langs/ob-sql.el | 4 ---- lisp/babel/langs/ob-sqlite.el | 4 ---- 23 files changed, 98 deletions(-) diff --git a/contrib/babel/langs/ob-oz.el b/contrib/babel/langs/ob-oz.el index d11e9a036..b8c416f4e 100644 --- a/contrib/babel/langs/ob-oz.el +++ b/contrib/babel/langs/ob-oz.el @@ -92,14 +92,6 @@ ;;; major mode for editing Oz programs (require 'mozart) -;; Add Oz to the list of supported languages. Org-babel will match -;; the string below against the declared language of the source-code -;; block. -(org-babel-add-interpreter "oz") - -;; specify the name and file extension for Oz -(add-to-list 'org-babel-tangle-langs '("oz" "oz" nil nil)) - ;; ;; Interface to communicate with Oz. ;; (1) For statements without any results: oz-send-string diff --git a/lisp/babel/langs/ob-C.el b/lisp/babel/langs/ob-C.el index f84b1d47f..0feee6c50 100644 --- a/lisp/babel/langs/ob-C.el +++ b/lisp/babel/langs/ob-C.el @@ -36,12 +36,6 @@ (require 'ob) (require 'cc-mode) -(org-babel-add-interpreter "C") -(add-to-list 'org-babel-tangle-langs '("C" "c" nil)) - -(org-babel-add-interpreter "c++") -(add-to-list 'org-babel-tangle-langs '("c++" "cpp" nil)) - (defvar org-babel-C-compiler "gcc" "Command used to compile a C source code file into an executable.") diff --git a/lisp/babel/langs/ob-R.el b/lisp/babel/langs/ob-R.el index 0b6e2d2cf..c3e63d421 100644 --- a/lisp/babel/langs/ob-R.el +++ b/lisp/babel/langs/ob-R.el @@ -31,10 +31,6 @@ ;;; Code: (require 'ob) -(org-babel-add-interpreter "R") - -(add-to-list 'org-babel-tangle-langs '("R" "R" "#!/usr/bin/env Rscript")) - (defconst org-babel-header-arg-names:R '(width height bg units pointsize antialias quality compression res type family title fonts version paper encoding diff --git a/lisp/babel/langs/ob-asymptote.el b/lisp/babel/langs/ob-asymptote.el index 9cb902207..53b42bfd4 100644 --- a/lisp/babel/langs/ob-asymptote.el +++ b/lisp/babel/langs/ob-asymptote.el @@ -47,10 +47,6 @@ ;;; Code: (require 'ob) -(org-babel-add-interpreter "asymptote") - -(add-to-list 'org-babel-tangle-langs '("asymptote" "asymptote")) - (defvar org-babel-default-header-args:asymptote '((:results . "file") (:exports . "results")) "Default arguments to use when evaluating a asymptote source block.") diff --git a/lisp/babel/langs/ob-clojure.el b/lisp/babel/langs/ob-clojure.el index b58d335ad..1a2af9428 100644 --- a/lisp/babel/langs/ob-clojure.el +++ b/lisp/babel/langs/ob-clojure.el @@ -45,11 +45,6 @@ (require 'slime) (require 'swank-clojure) - -(org-babel-add-interpreter "clojure") - -(add-to-list 'org-babel-tangle-langs '("clojure" "clj")) - (defvar org-babel-clojure-wrapper-method " (defn spit diff --git a/lisp/babel/langs/ob-css.el b/lisp/babel/langs/ob-css.el index 29618177a..525215dc8 100644 --- a/lisp/babel/langs/ob-css.el +++ b/lisp/babel/langs/ob-css.el @@ -32,10 +32,6 @@ ;;; Code: (require 'ob) -(org-babel-add-interpreter "css") - -(add-to-list 'org-babel-tangle-langs '("css" "css" nil t)) - (defun org-babel-expand-body:css (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." body) diff --git a/lisp/babel/langs/ob-ditaa.el b/lisp/babel/langs/ob-ditaa.el index 5303a2049..e7c04750b 100644 --- a/lisp/babel/langs/ob-ditaa.el +++ b/lisp/babel/langs/ob-ditaa.el @@ -41,10 +41,6 @@ ;;; Code: (require 'ob) -(org-babel-add-interpreter "ditaa") - -(add-to-list 'org-babel-tangle-langs '("ditaa" "ditaa")) - (defvar org-babel-default-header-args:ditaa '((:results . "file") (:exports . "results")) "Default arguments to use when evaluating a ditaa source block.") diff --git a/lisp/babel/langs/ob-dot.el b/lisp/babel/langs/ob-dot.el index 3e85088dd..0a8376796 100644 --- a/lisp/babel/langs/ob-dot.el +++ b/lisp/babel/langs/ob-dot.el @@ -43,10 +43,6 @@ ;;; Code: (require 'ob) -(org-babel-add-interpreter "dot") - -(add-to-list 'org-babel-tangle-langs '("dot" "dot")) - (defvar org-babel-default-header-args:dot '((:results . "file") (:exports . "results")) "Default arguments to use when evaluating a dot source block.") diff --git a/lisp/babel/langs/ob-emacs-lisp.el b/lisp/babel/langs/ob-emacs-lisp.el index e22c06868..c1c9da2c3 100644 --- a/lisp/babel/langs/ob-emacs-lisp.el +++ b/lisp/babel/langs/ob-emacs-lisp.el @@ -31,10 +31,6 @@ ;;; Code: (require 'ob) -(org-babel-add-interpreter "emacs-lisp") - -(add-to-list 'org-babel-tangle-langs '("emacs-lisp" "el")) - (defvar org-babel-default-header-args:emacs-lisp '((:hlines . "yes") (:colnames . "no")) "Default arguments to use when evaluating an emacs-lisp source block.") diff --git a/lisp/babel/langs/ob-gnuplot.el b/lisp/babel/langs/ob-gnuplot.el index 380be7924..e11466377 100644 --- a/lisp/babel/langs/ob-gnuplot.el +++ b/lisp/babel/langs/ob-gnuplot.el @@ -44,10 +44,6 @@ (require 'ob) (require 'gnuplot) -(org-babel-add-interpreter "gnuplot") - -(add-to-list 'org-babel-tangle-langs '("gnuplot" "gnuplot")) - (defvar org-babel-default-header-args:gnuplot '((:results . "file") (:exports . "results") (:session . nil)) "Default arguments to use when evaluating a gnuplot source block.") diff --git a/lisp/babel/langs/ob-haskell.el b/lisp/babel/langs/ob-haskell.el index 2b24822d5..d35ab2be8 100644 --- a/lisp/babel/langs/ob-haskell.el +++ b/lisp/babel/langs/ob-haskell.el @@ -46,10 +46,6 @@ (require 'haskell-mode) (require 'inf-haskell) -(org-babel-add-interpreter "haskell") - -(add-to-list 'org-babel-tangle-langs '("haskell" "hs")) - (defvar org-babel-haskell-lhs2tex-command "lhs2tex") (defvar org-babel-haskell-eoe "\"org-babel-haskell-eoe\"") diff --git a/lisp/babel/langs/ob-latex.el b/lisp/babel/langs/ob-latex.el index 950ed9a52..b6353bf6b 100644 --- a/lisp/babel/langs/ob-latex.el +++ b/lisp/babel/langs/ob-latex.el @@ -35,10 +35,6 @@ ;;; Code: (require 'ob) -(org-babel-add-interpreter "latex") - -(add-to-list 'org-babel-tangle-langs '("latex" "tex")) - (defvar org-babel-default-header-args:latex '((:results . "latex") (:exports . "results")) "Default arguments to use when evaluating a latex source block.") diff --git a/lisp/babel/langs/ob-matlab.el b/lisp/babel/langs/ob-matlab.el index 806965fe7..fff035f60 100644 --- a/lisp/babel/langs/ob-matlab.el +++ b/lisp/babel/langs/ob-matlab.el @@ -41,10 +41,6 @@ (require 'matlab) (require 'ob-octave) -(org-babel-add-interpreter "matlab") -(add-to-list 'org-babel-tangle-langs '("matlab" "m" "#!/usr/bin/env matlab")) - - (defvar org-babel-matlab-shell-command "matlab -nosplash" "Shell command to use to run matlab as an external process.") diff --git a/lisp/babel/langs/ob-ocaml.el b/lisp/babel/langs/ob-ocaml.el index 945b67fb8..7284cf970 100644 --- a/lisp/babel/langs/ob-ocaml.el +++ b/lisp/babel/langs/ob-ocaml.el @@ -41,10 +41,6 @@ (require 'ob) (require 'tuareg) -(org-babel-add-interpreter "ocaml") - -(add-to-list 'org-babel-tangle-langs '("ocaml" "ml")) - (defvar org-babel-ocaml-eoe-indicator "\"org-babel-ocaml-eoe\";;") (defvar org-babel-ocaml-eoe-output "org-babel-ocaml-eoe") diff --git a/lisp/babel/langs/ob-octave.el b/lisp/babel/langs/ob-octave.el index 2f0713800..f01337243 100644 --- a/lisp/babel/langs/ob-octave.el +++ b/lisp/babel/langs/ob-octave.el @@ -35,9 +35,6 @@ (require 'ob) (require 'octave-inf) -(org-babel-add-interpreter "octave") -(add-to-list 'org-babel-tangle-langs '("octave" "m" "#!/usr/bin/env octave")) - (defvar org-babel-octave-shell-command "octave -q" "Shell command to use to run octave as an external process.") diff --git a/lisp/babel/langs/ob-perl.el b/lisp/babel/langs/ob-perl.el index 7104fbd72..1ac7b9479 100644 --- a/lisp/babel/langs/ob-perl.el +++ b/lisp/babel/langs/ob-perl.el @@ -31,10 +31,6 @@ ;;; Code: (require 'ob) -(org-babel-add-interpreter "perl") - -(add-to-list 'org-babel-tangle-langs '("perl" "pl" "#!/usr/bin/env perl")) - (defun org-babel-expand-body:perl (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." (let ((vars (second (or processed-params (org-babel-process-params params))))) diff --git a/lisp/babel/langs/ob-python.el b/lisp/babel/langs/ob-python.el index 4f51bb78e..4f3a65acd 100644 --- a/lisp/babel/langs/ob-python.el +++ b/lisp/babel/langs/ob-python.el @@ -34,10 +34,6 @@ (require 'ob-comint) (require (if (featurep 'xemacs) 'python-mode 'python)) -(org-babel-add-interpreter "python") - -(add-to-list 'org-babel-tangle-langs '("python" "py" "#!/usr/bin/env python")) - (defun org-babel-expand-body:python (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." (concat diff --git a/lisp/babel/langs/ob-ruby.el b/lisp/babel/langs/ob-ruby.el index ef9f3d2fe..0b7db58ee 100644 --- a/lisp/babel/langs/ob-ruby.el +++ b/lisp/babel/langs/ob-ruby.el @@ -42,10 +42,6 @@ (require 'ob) (require 'inf-ruby) -(org-babel-add-interpreter "ruby") - -(add-to-list 'org-babel-tangle-langs '("ruby" "rb" "#!/usr/bin/env ruby")) - (defun org-babel-expand-body:ruby (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." (let ((vars (second (or processed-params (org-babel-process-params params))))) diff --git a/lisp/babel/langs/ob-sass.el b/lisp/babel/langs/ob-sass.el index a8114fa49..58ece16e1 100644 --- a/lisp/babel/langs/ob-sass.el +++ b/lisp/babel/langs/ob-sass.el @@ -44,10 +44,6 @@ (require 'ob) (require 'sass-mode) -(org-babel-add-interpreter "sass") - -(add-to-list 'org-babel-tangle-langs '("sass" "sass")) - (defun org-babel-expand-body:sass (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." body) diff --git a/lisp/babel/langs/ob-screen.el b/lisp/babel/langs/ob-screen.el index dadb39a86..8c690e89d 100644 --- a/lisp/babel/langs/ob-screen.el +++ b/lisp/babel/langs/ob-screen.el @@ -38,10 +38,6 @@ ;;; Code: (require 'ob) -(org-babel-add-interpreter "screen") - -(add-to-list 'org-src-lang-modes '("screen" . sh)) - (defvar org-babel-screen-location "screen" "The command location for screen. In case you want to use a different screen than one selected by your $PATH") diff --git a/lisp/babel/langs/ob-sh.el b/lisp/babel/langs/ob-sh.el index 089c23913..4b18ad14c 100644 --- a/lisp/babel/langs/ob-sh.el +++ b/lisp/babel/langs/ob-sh.el @@ -41,10 +41,6 @@ (declare-function org-babel-comint-with-output "ob-comint" (meta &rest body)) (declare-function orgtbl-to-generic "org-table" (table params)) -(org-babel-add-interpreter "sh") - -(add-to-list 'org-babel-tangle-langs '("sh" "sh" "#!/usr/bin/env sh")) - (defvar org-babel-sh-command "sh" "Command used to invoke a shell. This will be passed to `shell-command-on-region'") diff --git a/lisp/babel/langs/ob-sql.el b/lisp/babel/langs/ob-sql.el index cdbbbc5df..f48f1a577 100644 --- a/lisp/babel/langs/ob-sql.el +++ b/lisp/babel/langs/ob-sql.el @@ -47,10 +47,6 @@ ;;; Code: (require 'ob) -(org-babel-add-interpreter "sql") - -(add-to-list 'org-babel-tangle-langs '("sql" "sql")) - (defun org-babel-expand-body:sql (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." body) diff --git a/lisp/babel/langs/ob-sqlite.el b/lisp/babel/langs/ob-sqlite.el index fa95b3f33..d2331e710 100644 --- a/lisp/babel/langs/ob-sqlite.el +++ b/lisp/babel/langs/ob-sqlite.el @@ -31,10 +31,6 @@ ;;; Code: (require 'ob) -(org-babel-add-interpreter "sqlite") - -(add-to-list 'org-babel-tangle-langs '("sqlite" "sqlite")) - (defun org-babel-expand-body:sqlite (body params &optional processed-params) body) From 752a59c58f2b841cc46c7f470dffc39313022179 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Thu, 17 Jun 2010 10:08:31 -0700 Subject: [PATCH 078/138] babel: ensure no whitespace in language names * lisp/babel/ob.el (org-babel-src-block-regexp): ensure no whitespace in language names (org-babel-inline-src-block-regexp): ensure no whitespace in language names --- lisp/babel/ob.el | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/lisp/babel/ob.el b/lisp/babel/ob.el index 27886bfa8..8664187f3 100644 --- a/lisp/babel/ob.el +++ b/lisp/babel/ob.el @@ -53,23 +53,23 @@ (defvar org-babel-src-block-regexp (concat - ;; (1) indentation (2) lang - "^\\([ \t]*\\)#\\+begin_src[ \t]+\\([^ \t]+\\)[ \t]*" - ;; (3) switches + ;; (1) indentation (2) lang + "^\\([ \t]*\\)#\\+begin_src[ \t]+\\([^ \f\t\n\r\v]+\\)[ \t]*" + ;; (3) switches "\\([^\":\n]*\"[^\"\n*]*\"[^\":\n]*\\|[^\":\n]*\\)" - ;; (4) header arguments + ;; (4) header arguments "\\([^\n]*\\)\n" - ;; (5) body + ;; (5) body "\\([^\000]+?\n\\)[ \t]*#\\+end_src") "Regexp used to identify code blocks.") (defvar org-babel-inline-src-block-regexp (concat - ;; (1) replacement target (2) lang - "[ \f\t\n\r\v]\\(src_\\([^ \t]+\\)" + ;; (1) replacement target (2) lang + "[ \f\t\n\r\v]\\(src_\\([^ \f\t\n\r\v]+\\)" ;; (3,4) (unused, headers) "\\(\\|\\[\\(.*?\\)\\]\\)" - ;; (5) body + ;; (5) body "{\\([^\f\n\r\v]+?\\)}\\)") "Regexp used to identify inline src-blocks.") From ffbeb7ffe6696e10f3e5b2968a7234e8c8e8db26 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Thu, 17 Jun 2010 10:21:14 -0700 Subject: [PATCH 079/138] babel: languages adding their extensions to `'org-babel-tangle-lang-exts' --- lisp/babel/langs/ob-C.el | 2 ++ lisp/babel/langs/ob-asymptote.el | 2 ++ lisp/babel/langs/ob-clojure.el | 2 ++ lisp/babel/langs/ob-haskell.el | 2 ++ lisp/babel/langs/ob-latex.el | 2 ++ lisp/babel/langs/ob-ocaml.el | 2 ++ lisp/babel/langs/ob-perl.el | 2 ++ lisp/babel/langs/ob-python.el | 2 ++ lisp/babel/langs/ob-ruby.el | 2 ++ 9 files changed, 18 insertions(+) diff --git a/lisp/babel/langs/ob-C.el b/lisp/babel/langs/ob-C.el index 0feee6c50..75f7b0b72 100644 --- a/lisp/babel/langs/ob-C.el +++ b/lisp/babel/langs/ob-C.el @@ -36,6 +36,8 @@ (require 'ob) (require 'cc-mode) +(add-to-list 'org-babel-tangle-lang-exts '("c++" . "cpp")) + (defvar org-babel-C-compiler "gcc" "Command used to compile a C source code file into an executable.") diff --git a/lisp/babel/langs/ob-asymptote.el b/lisp/babel/langs/ob-asymptote.el index 53b42bfd4..ecc062953 100644 --- a/lisp/babel/langs/ob-asymptote.el +++ b/lisp/babel/langs/ob-asymptote.el @@ -47,6 +47,8 @@ ;;; Code: (require 'ob) +(add-to-list 'org-babel-tangle-lang-exts '("asymptote" . "asy")) + (defvar org-babel-default-header-args:asymptote '((:results . "file") (:exports . "results")) "Default arguments to use when evaluating a asymptote source block.") diff --git a/lisp/babel/langs/ob-clojure.el b/lisp/babel/langs/ob-clojure.el index 1a2af9428..029090148 100644 --- a/lisp/babel/langs/ob-clojure.el +++ b/lisp/babel/langs/ob-clojure.el @@ -45,6 +45,8 @@ (require 'slime) (require 'swank-clojure) +(add-to-list 'org-babel-tangle-lang-exts '("clojure" . "clj")) + (defvar org-babel-clojure-wrapper-method " (defn spit diff --git a/lisp/babel/langs/ob-haskell.el b/lisp/babel/langs/ob-haskell.el index d35ab2be8..959073df2 100644 --- a/lisp/babel/langs/ob-haskell.el +++ b/lisp/babel/langs/ob-haskell.el @@ -46,6 +46,8 @@ (require 'haskell-mode) (require 'inf-haskell) +(add-to-list 'org-babel-tangle-lang-exts '("haskell" . "hs")) + (defvar org-babel-haskell-lhs2tex-command "lhs2tex") (defvar org-babel-haskell-eoe "\"org-babel-haskell-eoe\"") diff --git a/lisp/babel/langs/ob-latex.el b/lisp/babel/langs/ob-latex.el index b6353bf6b..3526d86d2 100644 --- a/lisp/babel/langs/ob-latex.el +++ b/lisp/babel/langs/ob-latex.el @@ -35,6 +35,8 @@ ;;; Code: (require 'ob) +(add-to-list 'org-babel-tangle-lang-exts '("latex" . "tex")) + (defvar org-babel-default-header-args:latex '((:results . "latex") (:exports . "results")) "Default arguments to use when evaluating a latex source block.") diff --git a/lisp/babel/langs/ob-ocaml.el b/lisp/babel/langs/ob-ocaml.el index 7284cf970..6ed8457a8 100644 --- a/lisp/babel/langs/ob-ocaml.el +++ b/lisp/babel/langs/ob-ocaml.el @@ -41,6 +41,8 @@ (require 'ob) (require 'tuareg) +(add-to-list 'org-babel-tangle-lang-exts '("ocaml" . "ml")) + (defvar org-babel-ocaml-eoe-indicator "\"org-babel-ocaml-eoe\";;") (defvar org-babel-ocaml-eoe-output "org-babel-ocaml-eoe") diff --git a/lisp/babel/langs/ob-perl.el b/lisp/babel/langs/ob-perl.el index 1ac7b9479..fcb84f392 100644 --- a/lisp/babel/langs/ob-perl.el +++ b/lisp/babel/langs/ob-perl.el @@ -31,6 +31,8 @@ ;;; Code: (require 'ob) +(add-to-list 'org-babel-tangle-lang-exts '("perl" . "pl")) + (defun org-babel-expand-body:perl (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." (let ((vars (second (or processed-params (org-babel-process-params params))))) diff --git a/lisp/babel/langs/ob-python.el b/lisp/babel/langs/ob-python.el index 4f3a65acd..48953adf9 100644 --- a/lisp/babel/langs/ob-python.el +++ b/lisp/babel/langs/ob-python.el @@ -34,6 +34,8 @@ (require 'ob-comint) (require (if (featurep 'xemacs) 'python-mode 'python)) +(add-to-list 'org-babel-tangle-lang-exts '("python" . "py")) + (defun org-babel-expand-body:python (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." (concat diff --git a/lisp/babel/langs/ob-ruby.el b/lisp/babel/langs/ob-ruby.el index 0b7db58ee..c7ff56f92 100644 --- a/lisp/babel/langs/ob-ruby.el +++ b/lisp/babel/langs/ob-ruby.el @@ -42,6 +42,8 @@ (require 'ob) (require 'inf-ruby) +(add-to-list 'org-babel-tangle-lang-exts '("ruby" . "rb")) + (defun org-babel-expand-body:ruby (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." (let ((vars (second (or processed-params (org-babel-process-params params))))) From 0d1aaf735f81cd7c94212e3080f96de681e3e90d Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Thu, 17 Jun 2010 10:22:54 -0700 Subject: [PATCH 080/138] babel: declaring variable to satisfy compiler --- lisp/babel/ob.el | 1 + 1 file changed, 1 insertion(+) diff --git a/lisp/babel/ob.el b/lisp/babel/ob.el index 8664187f3..5d26d5582 100644 --- a/lisp/babel/ob.el +++ b/lisp/babel/ob.el @@ -836,6 +836,7 @@ buffer or nil if no such result exists." "[ \t]" (regexp-quote name) "[ \t\n\f\v\r]") nil t) (beginning-of-line 0) (point)))) +(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 source block. Specifically at the beginning of the results line. From c201da51b88703a71e6eda64b52d53a5441c594f Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Fri, 18 Jun 2010 08:49:25 +0200 Subject: [PATCH 081/138] Fix source code example bug with plain list export to HTML * lisp/org-exp.el (org-export-format-source-code-or-example): Mark examples by a property. o * lisp/org-html.el (org-export-html-close-lists-maybe): Check if raw HTML stuff was actually made from an example Daniel Mahler writes: > 2. I would like to embed source blocks in numbered lists, without > breaking the numbering ie: > > 1) get ready > #+BEGIN_SRC sh > get_ready > #+END_SRC > 2) go > #+BEGIN_SRC sh > go > #+END_SRC > > currently the src blocks cause the numbering to reset, so all > items in a sequence like this are numbered 1 This patch fixes this issue - but I cannot say anymore why the code in org-export-html-close-lists-maybe does in fact work. The code looks wrong, but it seems to work. What looks wrong is that i does not check for the true indentation in the case when the line is not protected. It must be that this case is covered by some other code further down in the exporter. --- lisp/org-exp.el | 8 ++++---- lisp/org-html.el | 10 ++++++++-- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/lisp/org-exp.el b/lisp/org-exp.el index 919288ae1..cd979c774 100644 --- a/lisp/org-exp.el +++ b/lisp/org-exp.el @@ -2147,7 +2147,7 @@ INDENT was the original indentation of the block." (org-add-props (concat "\n") - '(org-protected t)) + '(org-protected t org-example t)) "#+END_DOCBOOK\n")) ((eq backend 'html) ;; We are exporting to HTML @@ -2217,7 +2217,7 @@ INDENT was the original indentation of the block." cont rpllbl fmt))) (if (string-match "\\(\\`<[^>]*>\\)\n" rtn) (setq rtn (replace-match "\\1" t nil rtn))) - (concat "\n#+BEGIN_HTML\n" (org-add-props rtn '(org-protected t)) "\n#+END_HTML\n\n")) + (concat "\n#+BEGIN_HTML\n" (org-add-props rtn '(org-protected t org-example t)) "\n#+END_HTML\n\n")) ((eq backend 'latex) (setq rtn (org-export-number-lines rtn 'latex 0 0 num cont rpllbl fmt)) (concat "#+BEGIN_LaTeX\n" @@ -2241,7 +2241,7 @@ INDENT was the original indentation of the block." rtn "\\end{lstlisting}\n") (concat (car org-export-latex-verbatim-wrap) rtn (cdr org-export-latex-verbatim-wrap))) - '(org-protected t)) + '(org-protected t org-example t)) "#+END_LaTeX\n")) ((eq backend 'ascii) ;; This is not HTML or LaTeX, so just make it an example. @@ -2255,7 +2255,7 @@ INDENT was the original indentation of the block." (org-split-string rtn "\n") "\n") "\n") - '(org-protected t)) + '(org-protected t org-example t)) "#+END_ASCII\n")))) (org-add-props rtn nil 'original-indentation indent)))) diff --git a/lisp/org-html.el b/lisp/org-html.el index d5809abb8..4a6ded4a4 100644 --- a/lisp/org-html.el +++ b/lisp/org-html.el @@ -2146,11 +2146,17 @@ If there are links in the string, don't modify these." (defvar local-list-indent) (defvar local-list-type) (defun org-export-html-close-lists-maybe (line) + "Close local lists based on the original indentation of the line." (let* ((rawhtml (and in-local-list - (get-text-property 0 'org-protected line))) + (get-text-property 0 'org-protected line) + (not (get-text-property 0 'org-example line)))) + ;; rawhtml means: This was between #+begin_html..#+end_html + ;; originally, thus it excludes stuff that was a source code example + ;; Actually, this code seems wrong, I don't know why it works, but + ;; it seems to work.... So keep it like this for now. (ind (if rawhtml (org-get-indentation line) - (or (get-text-property 0 'original-indentation line)))) + (get-text-property 0 'original-indentation line))) didclose) (when ind (while (and in-local-list From 42ea7d35b7e214dc5e026be468a40c29d30ba14c Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Fri, 18 Jun 2010 09:10:44 +0200 Subject: [PATCH 082/138] No longer define comments in the syntax table * lisp/org.el (org-mode): Set `comment-start' instead of changing the syntax of the `#' character. Leo writes: > Setting a comment starter without a corresponding comment ender is > problematic and the # creeps in mysteriously under auto-fill. For > example, in my current running emacs, this happens almost certainly in > all org files that has # in their header. The only (temporary) solution > seems to reboot emacs (which is painful and disruptive). > > If you try eval (forward-comment 1) at the beginning of an org file that > has some "#+..." it will move to the end of file (the whole file is > regarded as one single comment). So when auto-fill a long text, it will > find the common prefix to be #. > > In addition, I don't think org mode has clear comment syntax or ideas on > what to do with it. > > I can't see any gain from (modify-syntax-entry ?# "<") so I am proposing > removing it entirely and get rid of this mysterious and annoying bug > once and for all. > > The attached patch may (though I think it is quite safe) cause some bugs > but those will be fixable unlike the one mentioned above. > > Best wishes, > > Leo --- lisp/org.el | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/lisp/org.el b/lisp/org.el index b00a0d5c6..e25194c91 100755 --- a/lisp/org.el +++ b/lisp/org.el @@ -4571,10 +4571,8 @@ The following commands are available: 'org-block-todo-from-checkboxes)) ;; Comment characters - ;; (org-set-local 'comment-start "#") + (org-set-local 'comment-start "#") (org-set-local 'comment-padding " ") - (modify-syntax-entry ?# "<") - ;; (modify-syntax-entry ?\n ">") ;; Align options lines (org-set-local From eade8e6fa3450e2eddcd8b4491f1f40fd3ba1ac9 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Mon, 21 Jun 2010 15:18:36 +0200 Subject: [PATCH 083/138] Revert "* lisp/org-agenda.el (org-agenda-get-deadlines):" This reverts commit 14b689946d398d352f7157bed8a1aa1e31a9e934. See discussion in http://thread.gmane.org/gmane.emacs.orgmode/26154/focus=26400 --- lisp/org-agenda.el | 4 ++-- lisp/org.el | 10 ++++------ 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el index 1977b8416..93334b696 100644 --- a/lisp/org-agenda.el +++ b/lisp/org-agenda.el @@ -4573,7 +4573,7 @@ be skipped." pos (1- (match-beginning 1)) d2 (org-time-string-to-absolute (match-string 1) d1 'past - org-agenda-repeating-timestamp-show-all t) + org-agenda-repeating-timestamp-show-all) diff (- d2 d1) wdays (if suppress-prewarning (let ((org-deadline-warning-days suppress-prewarning)) @@ -4675,7 +4675,7 @@ FRACTION is what fraction of the head-warning time has passed." pos (1- (match-beginning 1)) d2 (org-time-string-to-absolute (match-string 1) d1 'past - org-agenda-repeating-timestamp-show-all t) + org-agenda-repeating-timestamp-show-all) diff (- d2 d1)) (setq pastschedp (and todayp (< diff 0))) ;; When to show a scheduled item in the calendar: diff --git a/lisp/org.el b/lisp/org.el index e25194c91..19b2b1d6e 100755 --- a/lisp/org.el +++ b/lisp/org.el @@ -14682,20 +14682,18 @@ days in order to avoid rounding problems." (defun org-time-string-to-seconds (s) (org-float-time (org-time-string-to-time s))) -(defun org-time-string-to-absolute (s &optional daynr prefer show-all ignore-cyclic) +(defun org-time-string-to-absolute (s &optional daynr prefer show-all) "Convert a time stamp to an absolute day number. -If there is a specifier for a cyclic time stamp, get the closest date to +If there is a specifyer for a cyclic time stamp, get the closest date to DAYNR. PREFER and SHOW-ALL are passed through to `org-closest-date'. -the variable date is bound by the calendar when this is called. -IGNORE-CYCLIC ignores cyclic repeaters so the returned absolute date -is based on the original date." +the variable date is bound by the calendar when this is called." (cond ((and daynr (string-match "\\`%%\\((.*)\\)" s)) (if (org-diary-sexp-entry (match-string 1 s) "" date) daynr (+ daynr 1000))) - ((and (not ignore-cyclic) daynr (string-match "\\+[0-9]+[dwmy]" s)) + ((and daynr (string-match "\\+[0-9]+[dwmy]" s)) (org-closest-date s (if (and (boundp 'daynr) (integerp daynr)) daynr (time-to-days (current-time))) (match-string 0 s) prefer show-all)) From 1d52e54efd541c1c2452e930aad5cf2b1dbf64a1 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Tue, 13 Oct 2009 09:41:40 +0200 Subject: [PATCH 084/138] New capture system org-capture * lisp/org-agenda.el (org-agenda-action): Make `c' key call org-capture. * lisp/org-capture.el: New file. * lisp/org-compat.el (org-get-x-clipboard): Function moved here from remember.el. * lisp/org-mks.el: New file * lisp/org.el (org-set-regexps-and-options): Allow statistic cookies as part of complex headlines. (org-find-olp): New argument THIS-BUFFER. When set, assume that the OLP does not contain a file name. --- doc/org.texi | 4 +- lisp/org-agenda.el | 2 + lisp/org-capture.el | 1126 ++++++++++++++++++++++++++++++++++++++++++ lisp/org-compat.el | 6 + lisp/org-datetree.el | 4 +- lisp/org-mks.el | 123 +++++ lisp/org-remember.el | 6 - lisp/org.el | 17 +- 8 files changed, 1273 insertions(+), 15 deletions(-) create mode 100644 lisp/org-capture.el create mode 100644 lisp/org-mks.el mode change 100755 => 100644 lisp/org.el diff --git a/doc/org.texi b/doc/org.texi index 17615e0fa..4ed169a87 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -5953,8 +5953,8 @@ as level 1 entries to the beginning or end of the file, respectively. It may also be the symbol @code{date-tree}. Then, a tree with year on level 1, month on level 2 and day on level three will be built in the file, and the entry will be filed into the tree under the current date@footnote{If the file -contains an entry with a @code{DATE_TREE} property, the entire date tree will -be built under that entry.} +contains an entry with a @code{DATE_TREE} property (arbitrary value), the +entire date tree will be built under that entry.} An optional sixth element specifies the contexts in which the user can select the template. This element can be a list of major modes or a function. diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el index 93334b696..97490ec42 100644 --- a/lisp/org-agenda.el +++ b/lisp/org-agenda.el @@ -6991,6 +6991,8 @@ The cursor may be at a date in the calendar, or in the Org agenda." (org-agenda-do-action '(org-deadline nil org-overriding-default-time))) ((equal ans ?r) (org-agenda-do-action '(org-remember) t)) + ((equal ans ?c) + (org-agenda-do-action '(org-capture) t)) ((equal ans ?\ ) (let ((cw (selected-window))) (org-switch-to-buffer-other-window diff --git a/lisp/org-capture.el b/lisp/org-capture.el new file mode 100644 index 000000000..01cd3c240 --- /dev/null +++ b/lisp/org-capture.el @@ -0,0 +1,1126 @@ +;;; org-capture.el --- Fast note taking in Org-mode + +;; Copyright (C) 2010 Free Software Foundation, Inc. + +;; Author: Carsten Dominik +;; Keywords: outlines, hypermedia, calendar, wp +;; Homepage: http://orgmode.org +;; Version: 6.36trans +;; +;; This file is part of GNU Emacs. +;; +;; GNU Emacs is free software: you can redistribute it and/or modify +;; it under the terms of the GNU General Public License as published by +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, +;; but WITHOUT ANY WARRANTY; without even the implied warranty of +;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;; GNU General Public License for more details. + +;; You should have received a copy of the GNU General Public License +;; along with GNU Emacs. If not, see . +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +;; +;;; Commentary: + +;; This file contains an alternaive implementation of the same functionality +;; that is also provided by org-remember.el. The implementation is more +;; streamlined, can produce more target types (e.g. plain list items or +;; table lines). Also, it does not use a temporary buffer for editing +;; the captured entry - instead it uses an indirect buffer that visits +;; the new entry already in the target buffer (this was an idea by Samuel +;; Wales). John Wiegley's excellent `remember.el' is not needed for this +;; implementation, even though we borrow heavily from its ideas. + +;; This implementation heavily draws on ideas by James TD Smith and +;; Samuel Wales, and, of cause, uses John Wiegley's remember.el as inspiration. + +;;; TODO + +;; - find a clever way to not always insert an annotation maybe a +;; predicate function that can check for conditions for %a to be +;; used. This could be one of the properties. + +;; - Should there be plist members that arrange for properties to be +;; asked for, like James proposed in his RFC? + +;;; Code: + +(eval-when-compile + (require 'cl)) +(require 'org) +(require 'org-mks) + +(defvar org-capture-clock-was-started nil + "Internal flag, noting if the clock was started.") + +(defvar org-capture-last-stored-marker (make-marker) + "Marker pointing to the entry most recently stored with `org-capture'.") + +(defgroup org-capture nil + "Options concerning capturing new entries." + :tag "Org Capture" + :group 'org) + +(defcustom org-capture-templates nil + "Templates for the creation of new entries. + +Each entry is a list with the following items: + +keys The keys that will select the template, as a string, characters + only, for example \"a\" for a template to be selected with a + single key, or \"bt\" for selection with two keys. When using + several keys, keys using the same prefix key must be together + in the list and preceded by a 2-element entry explaining the + prefix key, for example + + (\"b\" \"Templates for marking stuff to buy\") + + Do not use \"C\" as a key, it is reserved for customizing the + template variable. + +description A short string describing the template, will be shown during + selection. + +type The type of entry. Valid 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. + table-line a new line in the first table at target location. + plain text to be inserted as it is. + +target Specification of where the captured item should be placed. + In Org-mode files, targets usually define a node. Entries will + become children of this node, other types will be added to the + table or list in the body of this node. + + Valid values are: + + (file \"path/to/file\") + 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+headline \"path/to/file\" \"node headline\") + Fast configuration if the target heading is unique in the file + + (file+olp \"path/to/file\" \"Level 1 heading\" \"Level 2\" ...) + For non-unique headings, the full path is safer + + (file+regexp \"path/to/file\" \"regexp to find location\") + + (file+datetree \"path/to/file\") + 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. + + (clock) + 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. + + +template The template for creating the capture item. If you leave this + empty, an appropriate default template will be used. See below + for more details. + +The rest of the entry is a property list of additional options. Recognized +properties are: + + :prepend Normally new captured information will be appended at + the target location (last child, last table line, + last list item...). Setting this property will + change that. + + :immediate-finish When set, do not offer to edit the information, just + file it away immediately. This makes sense if the + template only needs information that can be added + automatically. + + :empty-lines Set this to the number of lines the should be inserted + before and after the new item. Default 0, only common + other value is 1. + + :clock-in Start the clock in this item. + + :clock-resume Start the interrupted clock when finishing the capture. + + :unnarrowed Do not narrow the target buffer, simply show the + full buffer. Default is to narrow it so that you + only see the new stuff. + +The template defined the text to be inserted. Often then 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. + A default value and a completion table ca be specified like this: + %^{prompt|default|completion2|completion3|...} + %t time stamp, date only + %T time stamp with date and time + %u, %U like the above, but inactive time stamps + %^t like %t, but prompt for date. Similarly %^T, %^u, %^U. + You may define a prompt like %^{Please specify birthday + %n user name (taken from `user-full-name') + %a annotation, normally the link created with `org-store-link' + %i initial content, copied from the active region. If %i is + 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 + %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' + %: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 + + %? After completing the template, position cursor here. + +Apart from these general escapes, you can access information specific to the +link type that is created. For example, calling `org-capture' in emails +or gnus will record the author and the subject of the message, which you +can access with \"%:author\" and \"%:subject\", respectively. Here is a +complete list of what is recorded for each link type. + +Link type | Available information +-------------------+------------------------------------------------------ +bbdb | %:type %:name %:company +vm, wl, mh, rmail | %:type %:subject %:message-id + | %:from %:fromname %:fromaddress + | %:to %:toname %:toaddress + | %:fromto (either \"to NAME\" or \"from NAME\") +gnus | %:group, for messages also all email fields +w3, w3m | %:type %:url +info | %:type %:file %:node +calendar | %:type %:date" + :group 'org-capture + :type + '(repeat + (choice :value ("" "" entry (file "~/org/notes.org") "") + (list :tag "Multikey description" + (string :tag "Keys ") + (string :tag "Description")) + (list :tag "Template entry" + (string :tag "Keys ") + (string :tag "Description ") + (choice :tag "Capture Type " :value entry + (const :tag "Org entry" entry) + (const :tag "Plain list item" item) + (const :tag "Checkbox item" checkitem) + (const :tag "Plain text" plain) + (const :tag "Table line" table-line)) + (choice :tag "Target location" + (list :tag "File" + (const :format "" file) + (file :tag " File")) + (list :tag "ID" + (const :format "" id) + (string :tag " ID")) + (list :tag "File & Headline" + (const :format "" file+headline) + (file :tag " File ") + (string :tag " Headline")) + (list :tag "File & Outline path" + (const :format "" file+olp) + (file :tag " File ") + (repeat :tag "Outline path" :inline t + (string :tag "Headline"))) + (list :tag "File & Regexp" + (const :format "" file+regexp) + (file :tag " File ") + (regexp :tag " Regexp")) + (list :tag "File & Date tree" + (const :format "" file+datetree) + (file :tag " File")) + (list :tag "File & function" + (const :format "" file+function) + (file :tag " File ") + (sexp :tag " Function")) + (list :tag "Current clocking task" + (const :format "" clock)) + (list :tag "Function" + (const :format "" function) + (sexp :tag " Function"))) + (string :tag "Template (opt) ") + (plist :inline t + ;; Give the most common options as checkboxes + :options (((const :format "%v " :prepend) (const t)) + ((const :format "%v " :immediate-finish) (const t)) + ((const :format "%v " :empty-lines) (const 1)) + ((const :format "%v " :clock-in) (const t)) + ((const :format "%v " :clock-resume) (const t)) + ((const :format "%v " :unnarrowed) (const t)))))))) + +(defcustom org-capture-before-finalize-hook nil + "Hook that is run right before a remember process is finalized. +The remember buffer is still current when this hook runs." + :group 'org-capture + :type 'hook) + +;;; The property list for keeping information about the capture process + +(defvar org-capture-plist nil + "Plist for the current capture process, global, to avoid having to pass it.") +(defvar org-capture-current-plist nil + "Local variable holding the plist in a capture buffer. +This is used to store the plist for use when finishing a capture process. +Another such process might have changed the global varaible by then.") + +(defun org-capture-put (&rest stuff) + (while stuff + (setq org-capture-plist (plist-put org-capture-plist + (pop stuff) (pop stuff))))) +(defun org-capture-get (prop &optional local) + (plist-get (if local org-capture-current-plist org-capture-plist) prop)) + +(defun org-capture-member (prop) + (plist-get org-capture-plist prop)) + +;;; The minor mode + +(defvar org-capture-mode-map (make-sparse-keymap) + "Keymap for org-capture-mode, a minor mode. +Use this map to set additional keybindings for when Org-mode is used +for a Remember buffer.") + +(defvar org-capture-mode-hook nil + "Hook for the minor `org-capture-mode'.") + +(define-minor-mode org-capture-mode + "Minor mode for special key bindings in a remember buffer." + nil " Rem" org-capture-mode-map + (org-set-local + 'header-line-format + "Capture buffer. Finish `C-c C-c', refile `C-c C-w', abort `C-c C-k'.") + (run-hooks 'org-capture-mode-hook)) +(define-key org-capture-mode-map "\C-c\C-c" 'org-capture-finalize) +(define-key org-capture-mode-map "\C-c\C-k" 'org-capture-kill) +(define-key org-capture-mode-map "\C-c\C-w" 'org-capture-refile) + +;;; The main commands + +(defun org-capture (&optional goto keys) + "Capture something. + +This will let you select a template from org-capture-templates, and then +file new captured information. The text is immediately inserted at the +target location, and an indirect buffer is shown where you can edit it. +Pressing `C-c C-c' brings you back to the previous state of Emacs, +so that you can continue your work. + +When called interactively with a `C-u' prefix argument GOTO, don't capture +anything, just go to the file/headline where the selected template +stores its notes. With a double prefix arg `C-u C-u', go to the last +note stored. + +When called with a `C-0' (zero) prefix, insert a template at point. + +Lisp programs can set KEYS to a string associated with a template in +`org-capture-templates'. In this case, interactive selection will be +bypassed." + (interactive "P") + (cond + ((equal goto '(4)) (org-capture-goto-target)) + ((equal goto '(16)) (org-capture-goto-last-stored)) + (t + ;; set temporary variables that will be needed in + ;; `org-select-remember-template' + (let* ((orig-buf (current-buffer)) + (annotation (org-store-link nil)) + (initial (and (org-region-active-p) + (buffer-substring (point) (mark)))) + (entry (org-capture-select-template keys))) + (if (equal entry "C") + (customize-variable 'org-capture-templates) + (org-capture-set-plist entry) + (org-capture-put :original-buffer orig-buf :annotation annotation + :initial initial) + (org-capture-put :default-time + (or org-overriding-default-time + (org-current-time))) + (org-capture-set-target-location) + (org-capture-put :template (org-capture-fill-template)) + (if (equal goto 0) + ;;insert at point + (org-capture-insert-template-here) + (org-capture-place-template) + (if (org-capture-get :immediate-finish) + (org-capture-finalize) + (if (and (org-mode-p) + (org-capture-get :clock-in)) + (condition-case nil + (progn + (if (org-clock-is-active) + (org-capture-put :interrupted-clock + (copy-marker org-clock-marker))) + (org-clock-in) + (org-set-local 'org-capture-clock-was-started t)) + (error + "Could not start the clock in this capture buffer")))))))))) + +(defun org-capture-finalize () + "Finalize the capture process." + (interactive) + (unless (and org-capture-mode + (buffer-base-buffer (current-buffer))) + (error "This does not seem to be a capture buffer for Org-mode")) + + (let ((beg (point-min)) + (end (point-max))) + (widen) + ;; Make sure that the empty lines after are correct + (when (and (> (point-max) end) ; indeed, the buffer was still narrowed + (member (org-capture-get :type 'local) + '(entry item checkitem plain))) + (save-excursion + (goto-char end) + (org-capture-empty-lines-after + (or (org-capture-get :empty-lines 'local) 0)))) + ;; Postprocessing: Update Statistics cookies, do the sorting + (when (org-mode-p) + (save-excursion + (when (ignore-errors (org-back-to-heading)) + (org-update-parent-todo-statistics) + (org-update-checkbox-count))) + ;; FIXME Here we should do the sorting + ;; If we have added a table line, maybe recompute? + (when (and (eq (org-capture-get :type 'local) 'table-line) + (org-at-table-p)) + (if (org-table-get-stored-formulas) + (org-table-recalculate 'all) ;; FIXME: Should we iterate??? + (org-table-align))) + ) + ;; Store this place as the last one where we stored something + ;; Do the marking in the base buffer, so that it makes sense after + ;; the indirect buffer has been killed. + (let ((pos (point))) + (with-current-buffer (buffer-base-buffer (current-buffer)) + (save-excursion + (save-restriction + (widen) + (goto-char pos) + (bookmark-set "org-capture-last-stored") + (move-marker org-capture-last-stored-marker (point)))))) + ;; Run the hook + (run-hooks 'org-capture-before-finalize-hook) + ;; Did we start the clock in this capture buffer? + (when (and org-capture-clock-was-started + org-clock-marker (marker-buffer org-clock-marker) + (equal (marker-buffer org-clock-marker) (buffer-base-buffer)) + (> org-clock-marker (point-min)) + (< org-clock-marker (point-max))) + ;; Looks like the clock we started is still running. Clock out. + (let (org-log-note-clock-out) (org-clock-out)) + (when (and (org-capture-get :clock-resume 'local) + (markerp (org-capture-get :interrupted-clock 'local)) + (buffer-live-p (marker-buffer + (org-capture-get :interrupted-clock 'local)))) + (org-with-point-at (org-capture-get :interrupted-clock 'local) + (org-clock-in)) + (message "Interrupted clock has been resumed"))) + + ;; Kill the indirect buffer + (save-buffer) + (let ((return-wconf (org-capture-get :return-to-wconf 'local))) + (kill-buffer (current-buffer)) + ;; Restore the window configuration before capture + (set-window-configuration return-wconf)))) + +(defun org-capture-refile () + "Finalize the current capture and then refile the entry. +Refiling is done from the base buffer, because the indirect buffer is then +already gone." + (interactive) + (let ((pos (point)) (base (buffer-base-buffer (current-buffer)))) + (org-capture-finalize) + (save-window-excursion + (save-excursion + (set-buffer (or base (current-buffer))) + (save-excursion + (save-restriction + (widen) + (goto-char pos) + (call-interactively 'org-refile))))))) + +(defun org-capture-kill () + "Abort the current capture process." + (interactive) + ;; FIXME: This does not do the right thing, we need to remove the new stuff + ;; By hand it is easy: undo, then kill the buffer + (let ((org-note-abort t)) + (org-capture-finalize))) + +(defun org-capture-goto-last-stored () + "Go to the location where the last remember note was stored." + (interactive) + (org-goto-marker-or-bmk org-capture-last-stored-marker + "org-capture-last-stored") + (message "This is the last note stored by in a capture process")) + +;;; Supporting functions for handling the process + +(defun org-capture-set-target-location (&optional target) + "Find target buffer and position and store then in the property list." + (let ((target-entry-p t)) + (setq target (or target (org-capture-get :target))) + (save-excursion + (cond + ((eq (car target) 'file) + (set-buffer (org-capture-target-buffer (nth 1 target))) + (setq target-entry-p nil)) + + ((eq (car target) 'id) + (let ((loc (org-id-find (nth 1 target)))) + (if (not loc) + (error "Cannot find target ID \"%s\"" (nth 1 target)) + (set-buffer (org-capture-target-buffer (car loc))) + (goto-char (cdr loc))))) + + ((eq (car target) 'file+headline) + (set-buffer (org-capture-target-buffer (nth 1 target))) + (let ((hd (nth 2 target))) + (goto-char (point-min)) + (if (re-search-forward + (format org-complex-heading-regexp-format (regexp-quote hd)) + nil t) + (goto-char (point-at-bol)) + (goto-char (point-max)) + (or (bolp) (insert "\n")) + (insert "* " hd "\n") + (beginning-of-line 0)))) + + ((eq (car target) 'file+olp) + (let ((m (org-find-olp (cdr target)))) + (set-buffer (marker-buffer m)) + (goto-char m))) + + ((eq (car target) 'file+regexp) + (set-buffer (org-capture-target-buffer (nth 1 target))) + (goto-char (point-min)) + (if (re-search-forward (nth 1 target) nil t) + (progn + (goto-char (match-beginning 0)) + (setq target-entry-p (and (org-mode-p) (org-at-heading-p)))) + (kill-buffer (current-buffer)) + (error "No match for target regexp in file %s" (nth 1 target)))) + + ((eq (car target) 'file+datetree) + (set-buffer (org-capture-target-buffer (nth 1 target))) + ;; Make a date tree entry, with the current date (or yesterday, + ;; if we are extending dates for a couple of hours) + (org-datetree-find-date-create + (calendar-gregorian-from-absolute + (time-to-days + (time-subtract (current-time) + (list 0 (* 3600 org-extend-today-until) 0)))))) + + ((eq (car target) 'file+function) + (set-buffer (org-capture-target-buffer (nth 1 target))) + (funcall (nth 1 target)) + (setq target-entry-p (and (org-mode-p) (org-at-heading-p)))) + + ((eq (car target) 'clock) + (if (and (markerp org-clock-hd-marker) + (marker-buffer org-clock-hd-marker)) + (progn (set-buffer (org-capture-target-buffer + (marker-buffer org-clock-hd-marker))) + (goto-char org-clock-hd-marker)) + (error "No running clock that could be used as capture target"))) + + (t (error "Invalid capture target specification"))) + + (org-capture-put :buffer (current-buffer) :pos (point) + :target-entry-p target-entry-p)))) + +(defun org-capture-target-buffer (file) + "Get a buffer for FILE." + (or (org-find-base-buffer-visiting file) + (find-file-noselect (expand-file-name file org-directory)))) + +(defun org-capture-steal-local-variables (buffer) + "Install Org-mode local variables" + (mapc (lambda (v) + (ignore-errors (org-set-local (car v) (cdr v)))) + (buffer-local-variables buffer))) + +(defun org-capture-place-template () + "Insert the template at the target location, and display the buffer." + (org-capture-put :return-to-wconf (current-window-configuration)) + (delete-other-windows) + (org-switch-to-buffer-other-window + (org-capture-get-indirect-buffer (org-capture-get :buffer) "CAPTURE")) + (show-all) + (goto-char (org-capture-get :pos)) + (org-set-local 'org-capture-target-marker + (move-marker (make-marker) (point))) + (let* ((template (org-capture-get :template)) + (type (org-capture-get :type))) + (case type + ((nil entry) (org-capture-place-entry)) + (table-line (org-capture-place-table-line)) + (plain (org-capture-place-plain-text)) + (item (org-capture-place-item)))) + (org-capture-mode 1) + (org-set-local 'org-capture-current-plist org-capture-plist)) + +(defun org-capture-place-entry () + "Place the template as a new Org entry." + (let* ((txt (org-capture-get :template)) + (reversed (org-capture-get :prepend)) + (target-entry-p (org-capture-get :target-entry-p)) + level beg end) + (cond + ((not target-entry-p) + ;; Insert as top-level entry, either at beginning or at end of file + (setq level 1) + (if reversed + (progn (goto-char (point-min)) + (outline-next-heading)) + (goto-char (point-max)) + (or (bolp) (insert "\n")))) + (t + ;; Insert as a child of the current entry + (and (looking-at "\\*+") + (setq level (- (match-end 0) (match-beginning 0)))) + (setq level (org-get-valid-level (or level 1) 1)) + (if reversed + (progn + (outline-next-heading) + (or (bolp) (insert "\n"))) + (org-end-of-subtree t t) + (or (bolp) (insert "\n"))))) + (org-capture-empty-lines-before) + (setq beg (point)) + (org-paste-subtree level txt 'for-yank) + (org-capture-empty-lines-after 1) + (outline-next-heading) + (setq end (point)) + (org-capture-narrow beg (1- end)) + (if (re-search-forward "%\\?" end t) (replace-match "")))) + +(defun org-capture-place-item () + "Place the template as a new plain list item." + (let* ((txt (org-capture-get :template)) + (target-entry-p (org-capture-get :target-entry-p)) + ind beg end) + (cond + ((not target-entry-p) + ;; Insert as top-level entry, either at beginning or at end of file + (setq beg (point-min) end (point-max))) + (t + (setq beg (1+ (point-at-eol)) + end (save-excursion (outline-next-heading) (point))))) + (if (org-capture-get :prepend) + (progn + (goto-char beg) + (if (re-search-forward (concat "^" (org-item-re)) nil t) + (progn + (goto-char (match-beginning 0)) + (setq ind (org-get-indentation))) + (goto-char end) + (setq ind 0))) + (goto-char end) + (if (re-search-backward (concat "^" (org-item-re)) nil t) + (progn + (setq ind (org-get-indentation)) + (org-end-of-item)) + (setq ind 0))) + ;; Remove common indentation + (setq txt (org-remove-indentation txt)) + ;; Make sure this is indeed an item + (unless (string-match (concat "\\`" (org-item-re)) txt) + (setq txt (concat "- " + (mapconcat 'identity (split-string txt "\n") + "\n ")))) + ;; Set the correct indentation, depending on context + (setq ind (make-string ind ?\ )) + (setq txt (concat ind + (mapconcat 'identity (split-string txt "\n") + (concat "\n" ind)))) + ;; Insert, with surrounding empty lines + (org-capture-empty-lines-before) + (setq beg (point)) + (insert txt) + (org-capture-empty-lines-after 1) + (setq end (point)) + (org-capture-narrow beg (1- end)) + (if (re-search-forward "%\\?" end t) (replace-match "")))) + +(defun org-capture-place-table-line () + "Place the template as a table line." + (let* ((txt (org-capture-get :template)) + (target-entry-p (org-capture-get :target-entry-p)) + ind beg end) + (cond + ((not target-entry-p) + (setq beg (point-min) end (point-max))) + (t + (setq beg (1+ (point-at-eol)) + end (save-excursion (outline-next-heading) (point))))) + (if (re-search-forward org-table-dataline-regexp end t) + (let ((b (org-table-begin)) (e (org-table-end))) + (goto-char e) + (if (looking-at "[ \t]*#\\+TBLFM:") + (forward-line 1)) + (narrow-to-region b (point))) + (goto-char end) + (insert "\n\n") + (narrow-to-region (1- (point)) (point))) + ;; We are narrowed to the table, or to an empty line if there was no table + + ;; Check if the template is good + (if (not (string-match org-table-dataline-regexp txt)) + (setq txt "| %?Bad template |\n")) + + (if (org-capture-get :prepend) + (progn + (goto-char (point-min)) + (re-search-forward org-table-hline-regexp nil t) + (beginning-of-line 1) + (re-search-forward org-table-dataline-regexp nil t) + (beginning-of-line 1) + (setq beg (point)) + (org-table-insert-row) + (beginning-of-line 1) + (delete-region (point) (1+ (point-at-eol))) + (insert txt) + (setq end (point))) + (goto-char (point-max)) + (re-search-backward org-table-dataline-regexp nil t) + (beginning-of-line 1) + (org-table-insert-row 'below) + (beginning-of-line 1) + (delete-region (point) (1+ (point-at-eol))) + (setq beg (point)) + (insert txt) + (setq end (point))) + (goto-char beg) + (if (re-search-forward "%\\?" end t) (replace-match "")) + (org-table-align))) + +(defun org-capture-place-plain-text () + "Place the template plainly." + (let* ((txt (org-capture-get :template)) + beg end) + (goto-char (if (org-capture-get :prepend) (point-min) (point-max))) + (or (bolp) (newline)) + (org-capture-empty-lines-before) + (setq beg (point)) + (insert txt) + (org-capture-empty-lines-after 1) + (setq end (point)) + (org-capture-narrow beg (1- end)) + (if (re-search-forward "%\\?" end t) (replace-match "")))) + +(defun org-capture-narrow (beg end) + "Narrow, unless configuraion says not to narrow." + (unless (org-capture-get :unnarrowed) + (narrow-to-region beg end) + (goto-char beg))) + +(defun org-capture-empty-lines-before (&optional n) + "Arrange for the correct number of empty lines before the insertion point. +Point will be after the empty lines, so insertion can direcetly be done." + (setq n (or n (org-capture-get :empty-lines) 0)) + (let ((pos (point))) + (org-back-over-empty-lines) + (delete-region (point) pos) + (newline n))) + +(defun org-capture-empty-lines-after (&optional n) + "Arrange for the correct number of empty lines after the inserted string. +Point will remain at the first line after the inserted text." + (setq n (or n (org-capture-get :empty-lines) 0)) + (org-back-over-empty-lines) + (while (looking-at "[ \t]*\n") (replace-match "")) + (let ((pos (point))) + (newline n) + (goto-char pos))) + +(defvar org-clock-marker) ; Defined in org.el +;;;###autoload +(defun org-capture-insert-template-here () + (let* ((template (org-capture-get :template)) + (type (org-capture-get :type)) + beg end pp) + (or (bolp) (newline)) + (setq beg (point)) + (cond + ((and (eq type 'entry) (org-mode-p)) + (org-paste-subtree nil template t)) + ((and (memq type '(item checkitem)) + (org-mode-p) + (save-excursion (skip-chars-backward " \t\n") + (setq pp (point)) + (org-in-item-p))) + (goto-char pp) + (org-insert-item) + (skip-chars-backward " ") + (skip-chars-backward "-+*0123456789).") + (delete-region (point) (point-at-eol)) + (setq beg (point)) + (org-remove-indentation template) + (insert template) + (org-capture-empty-lines-after) + (goto-char beg) + (org-maybe-renumber-ordered-list) + (org-end-of-item) + (setq end (point))) + (t (insert template))) + (setq end (point)) + (goto-char beg) + (if (re-search-forward "%\\?" end t) + (replace-match "")))) + +(defun org-capture-set-plist (entry) + "Initialize the property list from the template definition." + (setq org-capture-plist (copy-sequence (nthcdr 5 entry))) + (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))) + ;; The template may be empty or omitted for special types. + ;; Here we insert the default templates for such cases. + (cond + ((eq type 'item) (setq txt "- %?")) + ((eq type 'checkitem) (setq txt "- [ ] %?")) + ((eq type 'table-line) (setq txt "| %? |")) + ((member type '(nil entry)) (setq txt "* %?")))) + (org-capture-put :template txt :type type))) + +(defun org-capture-goto-target (&optional template-key) + "Go to the target location of a capture template. +The user is queried for the template." + (interactive) + (let* (org-select-template-temp-major-mode + (entry (org-capture-select-template template-key))) + (unless entry + (error "No capture emplate selected")) + (org-capture-set-plist entry) + (org-capture-set-target-location) + (switch-to-buffer (org-capture-get :buffer)) + (goto-char (org-capture-get :pos)))) + +(defun org-capture-get-indirect-buffer (&optional buffer prefix) + "Make an indirect buffer for a capture process. +Use PREFIX as a prefix for the name of the indirect buffer." + (setq buffer (or buffer (current-buffer))) + (let ((n 1) (base (buffer-name buffer)) bname) + (setq bname (concat prefix "-" base)) + (while (buffer-live-p (get-buffer bname)) + (setq bname (concat prefix "-" (number-to-string (incf n)) "-" base))) + (condition-case nil + (make-indirect-buffer buffer bname 'clone) + (error (make-indirect-buffer buffer bname))))) + + +;;; The template code + +(defun org-capture-select-template (&optional keys) + "Select a capture template. +Lisp programs can force the template by setting KEYS to a string." + (when org-capture-templates + (if keys + (or (assoc keys org-capture-templates) + (error "No capture template referred to by \"%s\" keys")) + (org-mks org-capture-templates + "Select a capture template\n=========================" + "Template key: " + '(("C" "Customize org-capture-templates")))))) + +(defun org-capture-fill-template (&optional template initial annotation) + "Fill a template and return the filled template as a string. +The template may still contain \"%?\" for cursor positioning." + (setq template (or template (org-capture-get :template))) + (when (stringp initial) + (setq initial (org-no-properties initial)) + (remove-text-properties 0 (length initial) '(read-only t) initial)) + (let* ((buffer (org-capture-get :buffer)) + (file (buffer-file-name (or (buffer-base-buffer buffer) buffer))) + (ct (org-capture-get :default-time)) + (dct (decode-time ct)) + (ct1 + (if (< (nth 2 dct) org-extend-today-until) + (encode-time 0 59 23 (1- (nth 3 dct)) (nth 4 dct) (nth 5 dct)) + ct)) + (plist-p (if org-store-link-plist t nil)) + (v-c (and (> (length kill-ring) 0) (current-kill 0))) + (v-x (or (org-get-x-clipboard 'PRIMARY) + (org-get-x-clipboard 'CLIPBOARD) + (org-get-x-clipboard 'SECONDARY))) + (v-t (format-time-string (car org-time-stamp-formats) ct)) + (v-T (format-time-string (cdr org-time-stamp-formats) ct)) + (v-u (concat "[" (substring v-t 1 -1) "]")) + (v-U (concat "[" (substring v-T 1 -1) "]")) + ;; `initial' and `annotation' might habe been passed. + ;; But if the property list has them, we prefer those values + (v-i (or (plist-get org-store-link-plist :initial) + initial + (org-capture-get :initial) + "")) + (v-a (or (plist-get org-store-link-plist :annotation) + annotation + (org-capture-get :annotation) + "")) + ;; Is the link empty? Then we do not want it... + (v-a (if (equal v-a "[[]]") "" v-a)) + (clipboards (remove nil (list v-i + (org-get-x-clipboard 'PRIMARY) + (org-get-x-clipboard 'CLIPBOARD) + (org-get-x-clipboard 'SECONDARY) + v-c))) + (v-A (if (and v-a + (string-match + "\\[\\(\\[.*?\\]\\)\\(\\[.*?\\]\\)?\\]" v-a)) + (replace-match "[\\1[%^{Link description}]]" nil nil v-a) + v-a)) + (v-n user-full-name) + (v-k (if (marker-buffer org-clock-marker) + (org-substring-no-properties org-clock-heading))) + (v-K (if (marker-buffer org-clock-marker) + (org-make-link-string + (buffer-file-name (marker-buffer org-clock-marker)) + org-clock-heading))) + v-I + (org-startup-folded nil) + (org-inhibit-startup t) + org-time-was-given org-end-time-was-given x + prompt completions char time pos default histvar) + + (setq org-store-link-plist + (plist-put org-store-link-plist :annotation v-a) + org-store-link-plist + (plist-put org-store-link-plist :initial v-i)) + + (unless template (setq template "") (message "No template") (ding) + (sit-for 1)) + (save-window-excursion + (delete-other-windows) + (switch-to-buffer (get-buffer-create "*Capture*")) + (insert template) + (goto-char (point-min)) + (org-capture-steal-local-variables buffer) + ;; Simple %-escapes + (while (re-search-forward "%\\([tTuUaiAcxkKI]\\)" nil t) + (unless (org-capture-escaped-%) + (when (and initial (equal (match-string 0) "%i")) + (save-match-data + (let* ((lead (buffer-substring + (point-at-bol) (match-beginning 0)))) + (setq v-i (mapconcat 'identity + (org-split-string initial "\n") + (concat "\n" lead)))))) + (replace-match + (or (eval (intern (concat "v-" (match-string 1)))) "") + t t))) + + ;; %[] Insert contents of a file. + (goto-char (point-min)) + (while (re-search-forward "%\\[\\(.+\\)\\]" nil t) + (unless (org-capture-escaped-%) + (let ((start (match-beginning 0)) + (end (match-end 0)) + (filename (expand-file-name (match-string 1)))) + (goto-char start) + (delete-region start end) + (condition-case error + (insert-file-contents filename) + (error (insert (format "%%![Couldn't insert %s: %s]" + filename error))))))) + ;; %() embedded elisp + (goto-char (point-min)) + (while (re-search-forward "%\\((.+)\\)" nil t) + (unless (org-capture-escaped-%) + (goto-char (match-beginning 0)) + (let ((template-start (point))) + (forward-char 1) + (let ((result + (condition-case error + (eval (read (current-buffer))) + (error (format "%%![Error: %s]" error))))) + (delete-region template-start (point)) + (insert result))))) + + ;; From the property list + (when plist-p + (goto-char (point-min)) + (while (re-search-forward "%\\(:[-a-zA-Z]+\\)" nil t) + (unless (org-capture-escaped-%) + (and (setq x (or (plist-get org-store-link-plist + (intern (match-string 1))) "")) + (replace-match x t t))))) + + ;; Turn on org-mode in temp buffer, set local variables + ;; This is to support completion in interactive prompts + (let ((org-inhibit-startup t)) (org-mode)) + ;; Interactive template entries + (goto-char (point-min)) + (while (re-search-forward "%^\\({\\([^}]*\\)}\\)?\\([gGtTuUCLp]\\)?" + nil t) + (unless (org-capture-escaped-%) + (setq char (if (match-end 3) (match-string 3)) + prompt (if (match-end 2) (match-string 2))) + (goto-char (match-beginning 0)) + (replace-match "") + (setq completions nil default nil) + (when prompt + (setq completions (org-split-string prompt "|") + prompt (pop completions) + default (car completions) + histvar (intern (concat + "org-capture-template-prompt-history::" + (or prompt ""))) + completions (mapcar 'list completions))) + (cond + ((member char '("G" "g")) + (let* ((org-last-tags-completion-table + (org-global-tags-completion-table + (if (equal char "G") + (org-agenda-files) + (and file (list file))))) + (org-add-colon-after-tag-completion t) + (ins (org-icompleting-read + (if prompt (concat prompt ": ") "Tags: ") + 'org-tags-completion-function nil nil nil + 'org-tags-history))) + (setq ins (mapconcat 'identity + (org-split-string + ins (org-re "[^[:alnum:]_@]+")) + ":")) + (when (string-match "\\S-" ins) + (or (equal (char-before) ?:) (insert ":")) + (insert ins) + (or (equal (char-after) ?:) (insert ":"))))) + ((equal char "C") + (cond ((= (length clipboards) 1) (insert (car clipboards))) + ((> (length clipboards) 1) + (insert (read-string "Clipboard/kill value: " + (car clipboards) '(clipboards . 1) + (car clipboards)))))) + ((equal char "L") + (cond ((= (length clipboards) 1) + (org-insert-link 0 (car clipboards))) + ((> (length clipboards) 1) + (org-insert-link 0 (read-string "Clipboard/kill value: " + (car clipboards) + '(clipboards . 1) + (car clipboards)))))) + ((equal char "p") + (let* + ((prop (org-substring-no-properties prompt)) + (pall (concat prop "_ALL")) + (allowed + (with-current-buffer + (get-buffer (file-name-nondirectory file)) + (or (cdr (assoc pall org-file-properties)) + (cdr (assoc pall org-global-properties)) + (cdr (assoc pall org-global-properties-fixed))))) + (existing (with-current-buffer + (get-buffer (file-name-nondirectory file)) + (mapcar 'list (org-property-values prop)))) + (propprompt (concat "Value for " prop ": ")) + (val (if allowed + (org-completing-read + propprompt + (mapcar 'list (org-split-string allowed + "[ \t]+")) + nil 'req-match) + (org-completing-read-no-i propprompt + existing nil nil + "" nil "")))) + (org-set-property prop val))) + (char + ;; These are the date/time related ones + (setq org-time-was-given (equal (upcase char) char)) + (setq time (org-read-date (equal (upcase char) "U") t nil + prompt)) + (org-insert-time-stamp time org-time-was-given + (member char '("u" "U")) + nil nil (list org-end-time-was-given))) + (t + (let (org-completion-use-ido) + (insert (org-completing-read-no-i + (concat (if prompt prompt "Enter string") + (if default (concat " [" default "]")) + ": ") + completions nil nil nil histvar default))))))) + ;; Make sure there are no empty lines before the text, and that + ;; it ends with a newline character + (goto-char (point-min)) + (while (looking-at "[ \t]*\n") (replace-match "")) + (if (re-search-forward "[ \t\n]*\\'" nil t) (replace-match "\n")) + ;; Return the expanded tempate and kill the temporary buffer + (untabify (point-min) (point-max)) + (set-buffer-modified-p nil) + (prog1 (buffer-string) (kill-buffer (current-buffer)))))) + +(defun org-capture-escaped-% () + "Check if % was escaped - if yes, unescape it now." + (if (equal (char-before (match-beginning 0)) ?\\) + (progn + (delete-region (1- (match-beginning 0)) (match-beginning 0)) + t) + nil)) + +;;;###autoload +(defun org-capture-import-remember-templates () + "Set org-capture-templates to be similar to `org-remember-templates'." + (interactive) + (when (and (yes-or-no-p + "Import old remember templates into org-capture-templates? ") + (yes-or-no-p + "Note that this will remove any templates currently defined in `org-capture-templates'. Do you still want to go ahead? ")) + (setq org-capture-templates + (mapcar + (lambda (entry) + (let ((desc (car entry)) + (key (char-to-string (nth 1 entry))) + (template (nth 2 entry)) + (file (or (nth 3 entry) org-default-notes-file)) + (position (nth 4 entry)) + (type 'entry) + (prepend org-reverse-note-order) + immediate target) + (cond + ((member position '(top bottom)) + (setq target (list 'file file) + prepend (eq position 'top))) + ((eq position 'date-tree) + (setq target (list 'file+datetree file) + prepend nil)) + (t (setq target + (list 'file+headline file + (or position org-remember-default-headline))))) + + (when (string-match "%!" template) + (setq template (replace-match "" t t template) + immediate t)) + + (append (list key desc type target template) + (if prepend '(:prepend t)) + (if immediate '(:immediate-finish t))))) + + org-remember-templates)))) + +(provide 'org-capture) + +;; arch-tag: 986bf41b-8ada-4e28-bf20-e8388a7205a0 + +;;; org-capture.el ends here + + diff --git a/lisp/org-compat.el b/lisp/org-compat.el index 2ead4a366..bfd4f8eb2 100644 --- a/lisp/org-compat.el +++ b/lisp/org-compat.el @@ -132,6 +132,12 @@ If DELETE is non-nil, delete all those overlays." (if delete (delete-overlay ov) (push ov found)))) found)) +(defun org-get-x-clipboard (value) + "Get the value of the x clipboard, compatible with XEmacs, and GNU Emacs 21." + (if (eq window-system 'x) + (let ((x (org-get-x-clipboard-compat value))) + (if x (org-no-properties x))))) + ;; Miscellaneous functions (defun org-add-hook (hook function &optional append local) diff --git a/lisp/org-datetree.el b/lisp/org-datetree.el index 2c2efad32..55e97d339 100644 --- a/lisp/org-datetree.el +++ b/lisp/org-datetree.el @@ -36,8 +36,8 @@ (defvar org-datetree-base-level 1 "The level at which years should be placed in the date tree. This is normally one, but if the buffer has an entry with a DATE_TREE -property, the date tree will become a subtree under that entry, so the -base level will be properly adjusted.") +property (any value), the date tree will become a subtree under that entry, +so the base level will be properly adjusted.") ;;;###autoload (defun org-datetree-find-date-create (date &optional keep-restriction) diff --git a/lisp/org-mks.el b/lisp/org-mks.el new file mode 100644 index 000000000..b0b102d3e --- /dev/null +++ b/lisp/org-mks.el @@ -0,0 +1,123 @@ +;;; org-mks.el --- Multi-key-selection for Org-mode + +;; Copyright (C) 2010 Free Software Foundation, Inc. + +;; Author: Carsten Dominik +;; Keywords: outlines, hypermedia, calendar, wp +;; Homepage: http://orgmode.org +;; Version: 6.36trans +;; +;; This file is part of GNU Emacs. +;; +;; GNU Emacs is free software: you can redistribute it and/or modify +;; it under the terms of the GNU General Public License as published by +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, +;; but WITHOUT ANY WARRANTY; without even the implied warranty of +;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;; GNU General Public License for more details. + +;; You should have received a copy of the GNU General Public License +;; along with GNU Emacs. If not, see . +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + +(defun org-mks (table title &optional prompt specials) + "Select a member of an alist with multiple keys. +TABLE is the alist which should contain entries where the car is a string. +There should be two types of entries. + +1. prefix descriptions like (\"a\" \"Description\") + This indicates that `a' is a prefix key for multi-letter selection, and + that there are entries following with keys like \"ab\", \"ax\"... + +2. Selectable members must have more than two elements, with the first + being the string of keys that lead to selecting it, and the second a + short description string of the item. + +The command will then make a temporary buffer listing all entries +that can be selected with a single key, and all the sinke key +prefixes. When you press the key for a single-letter enty, it is selected. +When you press a prefix key, the commands (and maybe further prefixes) +under this key will be shown and offered for selection. + +TITLE will be placed over the selection in the temporary buffer, +PROMPT will be used when prompting for a key. SPECIAL is an alist with +also (\"key\" \"description\") entries. When they are selected, + + +" + (setq prompt (or prompt "Select: ")) + (let (tbl orig-table dkey ddesc des-keys allowed-keys current prefix rtn) + (save-window-excursion + (org-switch-to-buffer-other-window "*Org Select*") + (setq orig-table table) + (catch 'exit + (while t + (erase-buffer) + (insert title "\n\n") + (setq tbl table + des-keys nil + allowed-keys nil) + (setq prefix (if current (concat current " ") "")) + (while tbl + (cond + ((and (= 2 (length (car tbl))) (= (length (caar tbl)) 1)) + ;; This is a description on this level + (setq dkey (caar tbl) ddesc (cadar tbl)) + (pop tbl) + (push dkey des-keys) + (push dkey allowed-keys) + (insert prefix "[" dkey "]" "..." " " ddesc "..." "\n") + ;; Skip keys which are below this prefix + (setq re (concat "\\`" (regexp-quote dkey))) + (while (and tbl (string-match re (caar tbl))) (pop tbl))) + ((= 2 (length (car tbl))) + ;; Not yet a usable description, skip it + ) + (t + ;; usable entry on this level + (insert prefix "[" (caar tbl) "]" " " (nth 1 (car tbl)) "\n") + (push (caar tbl) allowed-keys) + (pop tbl)))) + (when specials + (insert "-------------------------------------------------------------------------------\n") + (let ((sp specials)) + (while sp + (insert (format "[%s] %s\n" + (caar sp) (nth 1 (car sp)))) + (push (caar sp) allowed-keys) + (pop sp)))) + (push "\C-g" allowed-keys) + (goto-char (point-min)) + (if (not (pos-visible-in-window-p (point-max))) + (org-fit-window-to-buffer)) + (message prompt) + (setq pressed (char-to-string (read-char-exclusive))) + (while (not (member pressed allowed-keys)) + (message "Invalid key `%s'" pressed) (sit-for 1) + (message prompt) + (setq pressed (char-to-string (read-char-exclusive)))) + (if (equal pressed "\C-g") (error "Abort")) + (if (assoc pressed specials) (throw 'exit (setq rtn pressed))) + (unless (member pressed des-keys) + (throw 'exit (setq rtn (rassoc (cdr (assoc pressed table)) + orig-table)))) + (setq current (concat current pressed)) + (setq table (mapcar + (lambda (x) + (if (and (> (length (car x)) 1) + (equal (substring (car x) 0 1) pressed)) + (cons (substring (car x) 1) (cdr x)) + nil)) + table)) + (setq table (remove nil table))))) + (kill-buffer "*Org Select*") + rtn)) + +(provide 'org-mks) + +;; arch-tag: 4ea90d0e-c6e4-4684-bd61-baf878712f9f + +;;; org-mks.el ends here diff --git a/lisp/org-remember.el b/lisp/org-remember.el index 59e015f7a..d9d52cbdd 100644 --- a/lisp/org-remember.el +++ b/lisp/org-remember.el @@ -392,12 +392,6 @@ RET at beg-of-buf -> Append to file as level 2 headline char0)))))) (cddr (assoc char templates))))) -(defun org-get-x-clipboard (value) - "Get the value of the x clipboard, compatible with XEmacs, and GNU Emacs 21." - (if (eq window-system 'x) - (let ((x (org-get-x-clipboard-compat value))) - (if x (org-no-properties x))))) - ;;;###autoload (defun org-remember-apply-template (&optional use-char skip-interactive) "Initialize *remember* buffer with template, invoke `org-mode'. diff --git a/lisp/org.el b/lisp/org.el old mode 100755 new mode 100644 index 19b2b1d6e..cbc702c76 --- a/lisp/org.el +++ b/lisp/org.el @@ -4317,7 +4317,11 @@ means to push this value onto the list in the variable.") org-complex-heading-regexp-format (concat "^\\(\\*+\\)[ \t]+\\(?:\\(" (mapconcat 'regexp-quote org-todo-keywords-1 "\\|") - "\\)\\>\\)?\\(?:[ \t]*\\(\\[#.\\]\\)\\)?[ \t]*\\(%s\\)" + "\\)\\>\\)?" + "\\(?:[ \t]*\\(\\[#.\\]\\)\\)?" + "\\(?:[ \t]*\\(?:\\[[0-9%%/]+\\]\\)\\)?" ;; stats cookie + "[ \t]*\\(%s\\)" + "\\(?:[ \t]*\\(?:\\[[0-9%%/]+\\]\\)\\)?" ;; stats cookie "\\(?:[ \t]+\\(:[[:alnum:]_@:]+:\\)\\)?[ \t]*$") org-nl-done-regexp (concat "\n\\*+[ \t]+" @@ -13775,7 +13779,7 @@ completion." (skip-chars-forward " \t") (run-hook-with-args 'org-property-changed-functions key nval))) -(defun org-find-olp (path) +(defun org-find-olp (path &optional this-buffer) "Return a marker pointing to the entry at outline path OLP. If anything goes wrong, throw an error. You can wrap this call to cathc the error like this: @@ -13785,9 +13789,12 @@ You can wrap this call to cathc the error like this: (error (nth 1 msg))) The return value will then be either a string with the error message, -or a marker if everyhing is OK." - (let* ((file (pop path)) - (buffer (find-file-noselect file)) +or a marker if everyhing is OK. + +If THIS-BUFFER is set, the putline path does not contain a file, +only headings." + (let* ((file (if this-buffer buffer-file-name (pop path))) + (buffer (if this-buffer (current-buffer) (find-file-noselect file))) (level 1) (lmin 1) (lmax 1) From 0c4e2ab0ed42e7fd8e9054c929a944f815c5dd30 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Tue, 22 Jun 2010 14:29:13 +0200 Subject: [PATCH 085/138] Add autoloads for org-capture --- lisp/org-capture.el | 3 ++- lisp/org.el | 5 +++++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/lisp/org-capture.el b/lisp/org-capture.el index 01cd3c240..32db51762 100644 --- a/lisp/org-capture.el +++ b/lisp/org-capture.el @@ -314,6 +314,7 @@ for a Remember buffer.") ;;; The main commands +;;;###autoload (defun org-capture (&optional goto keys) "Capture something. @@ -470,7 +471,7 @@ already gone." (interactive) (org-goto-marker-or-bmk org-capture-last-stored-marker "org-capture-last-stored") - (message "This is the last note stored by in a capture process")) + (message "This is the last note stored by a capture process")) ;;; Supporting functions for handling the process diff --git a/lisp/org.el b/lisp/org.el index cbc702c76..00f624d8b 100644 --- a/lisp/org.el +++ b/lisp/org.el @@ -3611,6 +3611,11 @@ If TABLE-TYPE is non-nil, also check for table.el-type tables." '(org-remember-insinuate org-remember-annotation org-remember-apply-template org-remember org-remember-handler))) +(eval-and-compile + (org-autoload "org-capture" + '(org-capture org-capture-insert-template-here + org-capture-import-remember-templates))) + ;; Autoload org-clock.el From b67492596a471c1d77a31e8b3143ae7338262bc3 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Tue, 22 Jun 2010 14:42:45 +0200 Subject: [PATCH 086/138] Merge Glen Morris' change from downstream Emacs --- lisp/org-entities.el | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/lisp/org-entities.el b/lisp/org-entities.el index f7c20d56a..58fba0491 100644 --- a/lisp/org-entities.el +++ b/lisp/org-entities.el @@ -506,6 +506,10 @@ Kind can be any of `latex', `html', `ascii', `latin1', or `utf8'." (provide 'org-entities) +;; Local variables: +;; coding: utf-8 +;; End: + ;; arch-tag: e6bd163f-7419-4009-9c93-a74623016424 ;;; org-entities.el ends here From 2e73ce217779330d446a908627ec19875dc3fd05 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Tue, 22 Jun 2010 08:26:24 +0200 Subject: [PATCH 087/138] Clarify that TODO matches only match not-DONE states by default Bernt Hansen writes: > I was talking to Jeff Stern about tags todo matching offlist and we > think the documentation for tags-todo matching can probably be improved. > > The description of C-c a M at > http://orgmode.org/manual/Matching-tags-and-properties.html > states > > C-c a M > > Like C-c a m, but only select headlines that are also TODO items and > force checking subitems (see variable > org-tags-match-list-sublevels). To exclude scheduled/deadline items, > see the variable org-agenda-tags-todo-honor-ignore-options. Matching > specific TODO keywords together with a tags match is also possible, > see Tag searches. > > When I read this I think TODO items is any todo keyword but this isn't > the case. It is only non-done TODO state keywords. This makes > tags-todo matching not work for finding tasks to archive (normally > DONE | CANCELLED keywords in my setup) > > Should we explicitly state that 'headlines that are also TODO items' > does not match DONE state keywords? Or alternatively should TODO items > and DONE items be separate (and explicitly defined) in the documentation > -- like org-todo-keywords and org-done-keywords? > > I still think 'TODO keyword' matches any todo keyword defined in > org-todo-keywords and maybe I need to be re-educated :) Bernt is right, and this patch tries to clarify the issue. --- doc/org.texi | 79 ++++++++++++++++++++++++---------------------- lisp/org-agenda.el | 2 +- 2 files changed, 42 insertions(+), 39 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 17615e0fa..e233e058e 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -1232,7 +1232,7 @@ as bullets. @emph{Ordered} list items start with a numeral followed by either a period or a right parenthesis, such as @samp{1.} or @samp{1)}. If you want a list to start a different value (e.g. 20), start the text of the item with -@code{[@@start:20]}. +@code{[@@start:20]}. @item @emph{Description} list items are unordered list items, and contain the separator @samp{ :: } to separate the description @emph{term} from the @@ -3293,20 +3293,21 @@ with @code{shift-selection-mode}. See also the variable @itemx C-c / t @vindex org-todo-keywords View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the -entire buffer, but shows all TODO items and the headings hierarchy above -them. With a prefix argument (or by using @kbd{C-c / T}), search for a -specific TODO. You will be prompted for the keyword, and you can also give a -list of keywords like @code{KWD1|KWD2|...} to list entries that match any one -of these keywords. With numeric prefix argument N, show the tree for the Nth -keyword in the variable @code{org-todo-keywords}. With two prefix arguments, -find all TODO and DONE entries. +entire buffer, but shows all TODO items (with not-DONE state) and the +headings hierarchy above them. With a prefix argument (or by using @kbd{C-c +/ T}), search for a specific TODO. You will be prompted for the keyword, and +you can also give a list of keywords like @code{KWD1|KWD2|...} to list +entries that match any one of these keywords. With numeric prefix argument +N, show the tree for the Nth keyword in the variable +@code{org-todo-keywords}. With two prefix arguments, find all TODO states, +both un-done and done. @kindex C-c a t @item C-c a t -Show the global TODO list. Collects the TODO items from all agenda -files (@pxref{Agenda Views}) into a single buffer. The new buffer will -be in @code{agenda-mode}, which provides commands to examine and -manipulate the TODO entries from the new buffer (@pxref{Agenda -commands}). @xref{Global TODO list}, for more information. +Show the global TODO list. Collects the TODO items (with not-DONE states) +from all agenda files (@pxref{Agenda Views}) into a single buffer. The new +buffer will be in @code{agenda-mode}, which provides commands to examine and +manipulate the TODO entries from the new buffer (@pxref{Agenda commands}). +@xref{Global TODO list}, for more information. @kindex S-M-@key{RET} @item S-M-@key{RET} Insert a new TODO entry below the current one. @@ -6816,20 +6817,20 @@ collected into a single place. @table @kbd @kindex C-c a t @item C-c a t -Show the global TODO list. This collects the TODO items from all -agenda files (@pxref{Agenda Views}) into a single buffer. The buffer is in -@code{agenda-mode}, so there are commands to examine and manipulate -the TODO entries directly from that buffer (@pxref{Agenda commands}). +Show the global TODO list. This collects the TODO items from all agenda +files (@pxref{Agenda Views}) into a single buffer. By default, this lists +items with a state the is not a DONE state. The buffer is in +@code{agenda-mode}, so there are commands to examine and manipulate the TODO +entries directly from that buffer (@pxref{Agenda commands}). @kindex C-c a T @item C-c a T @cindex TODO keyword matching @vindex org-todo-keywords -Like the above, but allows selection of a specific TODO keyword. You -can also do this by specifying a prefix argument to @kbd{C-c a t}. With -a @kbd{C-u} prefix you are prompted for a keyword, and you may also -specify several keywords by separating them with @samp{|} as the boolean OR -operator. With a numeric prefix, the nth keyword in -@code{org-todo-keywords} is selected. +Like the above, but allows selection of a specific TODO keyword. You can +also do this by specifying a prefix argument to @kbd{C-c a t}. You are +prompted for a keyword, and you may also specify several keywords by +separating them with @samp{|} as the boolean OR operator. With a numeric +prefix, the nth keyword in @code{org-todo-keywords} is selected. @kindex r The @kbd{r} key in the agenda buffer regenerates it, and you can give a prefix argument to this command to change the selected TODO keyword, @@ -6891,11 +6892,12 @@ define a custom command for it (@pxref{Agenda dispatcher}). @item C-c a M @vindex org-tags-match-list-sublevels @vindex org-agenda-tags-todo-honor-ignore-options -Like @kbd{C-c a m}, but only select headlines that are also TODO items and -force checking subitems (see variable @code{org-tags-match-list-sublevels}). -To exclude scheduled/deadline items, see the variable -@code{org-agenda-tags-todo-honor-ignore-options}. Matching specific TODO -keywords together with a tags match is also possible, see @ref{Tag searches}. +Like @kbd{C-c a m}, but only select headlines that are also TODO items in a +not-DONE state and force checking subitems (see variable +@code{org-tags-match-list-sublevels}). To exclude scheduled/deadline items, +see the variable @code{org-agenda-tags-todo-honor-ignore-options}. Matching +specific TODO keywords together with a tags match is also possible, see +@ref{Tag searches}. @end table The commands available in the tags list are described in @ref{Agenda @@ -7009,12 +7011,13 @@ different way to test TODO states in a search. For this, terminate the tags/property part of the search string (which may include several terms connected with @samp{|}) with a @samp{/} and then specify a Boolean expression just for TODO keywords. The syntax is then similar to that for -tags, but should be applied with care: for example, a positive -selection on several TODO keywords cannot meaningfully be combined with -boolean AND. However, @emph{negative selection} combined with AND can be -meaningful. To make sure that only lines are checked that actually have any -TODO keyword (resulting in a speed-up), use @kbd{C-c a M}, or equivalently -start the TODO part after the slash with @samp{!}. Examples: +tags, but should be applied with care: for example, a positive selection on +several TODO keywords cannot meaningfully be combined with boolean AND. +However, @emph{negative selection} combined with AND can be meaningful. To +make sure that only lines are checked that actually have any TODO keyword +(resulting in a speed-up), use @kbd{C-c a M}, or equivalently start the TODO +part after the slash with @samp{!}. Using @kbd{C-c a M} or @samp{/!} will +not match TODO keywords in a DONE state. Examples: @table @samp @item work/WAITING @@ -8258,7 +8261,7 @@ summarizes the markup rules used in an Org-mode buffer. * Images and tables:: Tables and Images will be included * Literal examples:: Source code examples with special formatting * Include files:: Include additional files into a document -* Index entries:: +* Index entries:: Making an index * Macro replacement:: Use macros to create complex output * Embedded LaTeX:: LaTeX can be freely used inside Org documents @end menu @@ -8652,7 +8655,7 @@ the contains an exclamation mark will create a sub item. See @ref{Generating an index} for more information. @example -* Curriculum Vitae +* Curriculum Vitae #+INDEX: CV #+INDEX: Application!CV @end example @@ -10649,7 +10652,7 @@ file is part of any project in @code{org-publish-project-alist}. @subsection Generating a sitemap @cindex sitemap, of published pages -The following properties may be used to control publishing of +The following properties may be used to control publishing of a map of files for a given project. @multitable @columnfractions 0.35 0.65 @@ -12625,7 +12628,7 @@ Emacs about it: @end lisp Org-mode has commands to put files for @i{MobileOrg} into that directory, -and to read captured notes from there. +and to read captured notes from there. @node Pushing to MobileOrg, Pulling from MobileOrg, Setting up the staging area, MobileOrg @section Pushing to MobileOrg diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el index 93334b696..dc9abce78 100644 --- a/lisp/org-agenda.el +++ b/lisp/org-agenda.el @@ -3621,7 +3621,7 @@ in `org-agenda-text-search-extra-files'." ;;;###autoload (defun org-todo-list (arg) - "Show all TODO entries from all agenda file in a single list. + "Show all (not done) TODO entries from all agenda file in a single list. The prefix arg can be used to select a specific TODO keyword and limit the list to these. When using \\[universal-argument], you will be prompted for a keyword. A numeric prefix directly selects the Nth keyword in From 80531d8d7162a0117ab3d607ce30c27df1d7d102 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Tue, 22 Jun 2010 14:51:48 +0200 Subject: [PATCH 088/138] * contrib/lisp/org-special-blocks.el (org-special-blocks-convert-latex-special-cookies): Allow arguments to TeX macros --- contrib/lisp/org-special-blocks.el | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/contrib/lisp/org-special-blocks.el b/contrib/lisp/org-special-blocks.el index d97cff387..11d4c0172 100644 --- a/contrib/lisp/org-special-blocks.el +++ b/contrib/lisp/org-special-blocks.el @@ -64,13 +64,14 @@ seen. This is run after a few special cases are taken care of." (defun org-special-blocks-convert-latex-special-cookies () "Converts the special cookies into LaTeX blocks." (goto-char (point-min)) - (while (re-search-forward "^ORG-\\(.*\\)-\\(START\\|END\\)$" nil t) + (while (re-search-forward "^ORG-\\([^ \t\n]*\\)[ \t]*\\(.*\\)-\\(START\\|END\\)$" nil t) (replace-match - (if (equal (match-string 2) "START") - (concat "\\begin{" (match-string 1) "}") + (if (equal (match-string 3) "START") + (concat "\\begin{" (match-string 1) "}" (match-string 2)) (concat "\\end{" (match-string 1) "}")) t t))) + (add-hook 'org-export-latex-after-blockquotes-hook 'org-special-blocks-convert-latex-special-cookies) From 80bcadf605c3adba2fc83e0b53da7bd9551c4f4a Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Tue, 22 Jun 2010 16:14:55 +0200 Subject: [PATCH 089/138] Fix behavior of org-timestamp-change for explicit number of day changes * lisp/org.el (org-timestamp-change): New optional argument UPDOWN. Use this to identify calls from org-timestamp-up/down, so that we can skip by rounding minutes in this case. (org-timestamp-up): (org-timestamp-down): (org-timestamp-up-day): (org-timestamp-down-day): Call org-timestamp-change with the updown argument. This function used to look only if there was a prefix argument in the current interactive call. Now we have an explicit marker indicating that the function is called from the updown commands. --- lisp/org.el | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/lisp/org.el b/lisp/org.el index 00f624d8b..26281520a 100644 --- a/lisp/org.el +++ b/lisp/org.el @@ -14887,7 +14887,7 @@ If the cursor is on the year, change the year. If it is on the month or the day, change that. With prefix ARG, change by that many units." (interactive "p") - (org-timestamp-change (prefix-numeric-value arg))) + (org-timestamp-change (prefix-numeric-value arg) nil 'updown)) (defun org-timestamp-down (&optional arg) "Decrease the date item at the cursor by one. @@ -14895,7 +14895,7 @@ If the cursor is on the year, change the year. If it is on the month or the day, change that. With prefix ARG, change by that many units." (interactive "p") - (org-timestamp-change (- (prefix-numeric-value arg)))) + (org-timestamp-change (- (prefix-numeric-value arg)) nil 'updown)) (defun org-timestamp-up-day (&optional arg) "Increase the date in the time stamp by one day. @@ -14904,7 +14904,7 @@ With prefix ARG, change that many days." (if (and (not (org-at-timestamp-p t)) (org-on-heading-p)) (org-todo 'up) - (org-timestamp-change (prefix-numeric-value arg) 'day))) + (org-timestamp-change (prefix-numeric-value arg) 'day 'updown))) (defun org-timestamp-down-day (&optional arg) "Decrease the date in the time stamp by one day. @@ -14913,7 +14913,7 @@ With prefix ARG, change that many days." (if (and (not (org-at-timestamp-p t)) (org-on-heading-p)) (org-todo 'down) - (org-timestamp-change (- (prefix-numeric-value arg)) 'day))) + (org-timestamp-change (- (prefix-numeric-value arg)) 'day) 'updown)) (defun org-at-timestamp-p (&optional inactive-ok) "Determine if the cursor is in or at a timestamp." @@ -14958,7 +14958,7 @@ With prefix ARG, change that many days." (message "Timestamp is now %sactive" (if (equal (char-after beg) ?<) "" "in"))))) -(defun org-timestamp-change (n &optional what) +(defun org-timestamp-change (n &optional what updown) "Change the date in the time stamp at point. The date will be changed by N times WHAT. WHAT can be `day', `month', `year', `minute', `second'. If WHAT is not given, the cursor position @@ -14989,8 +14989,10 @@ in the timestamp determines what will be changed." (if (string-match "^.\\{10\\}.*?[0-9]+:[0-9][0-9]" ts) (setq with-hm t)) (setq time0 (org-parse-time-string ts)) - (when (and (eq org-ts-what 'minute) - (eq current-prefix-arg nil)) + (when (and updown + (eq org-ts-what 'minute) + (not current-prefix-arg)) + ;; This looks like s-up and s-down. Change by one rounding step. (setq n (* dm (cond ((> n 0) 1) ((< n 0) -1) (t 0)))) (when (not (= 0 (setq rem (% (nth 1 time0) dm)))) (setcar (cdr time0) (+ (nth 1 time0) From b816a85ac08e224135ab1a3b0fa28c120da99829 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Tue, 22 Jun 2010 11:46:28 -0700 Subject: [PATCH 090/138] babel: wrapped `org-babel-params-from-buffer' in `save-match-data' * lisp/babel/ob.el (org-babel-params-from-buffer): wrapped in save-match-data --- lisp/babel/ob.el | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/lisp/babel/ob.el b/lisp/babel/ob.el index 5d26d5582..56eb0c83a 100644 --- a/lisp/babel/ob.el +++ b/lisp/babel/ob.el @@ -602,14 +602,15 @@ may be specified in the properties of the current outline entry." may be specified at the top of the current buffer." (or org-babel-current-buffer-properties (setq org-babel-current-buffer-properties - (save-excursion - (save-restriction - (widen) - (goto-char (point-min)) - (when (re-search-forward - (org-make-options-regexp (list "BABEL")) nil t) - (org-babel-parse-header-arguments - (org-match-string-no-properties 2)))))))) + (save-match-data + (save-excursion + (save-restriction + (widen) + (goto-char (point-min)) + (when (re-search-forward + (org-make-options-regexp (list "BABEL")) nil t) + (org-babel-parse-header-arguments + (org-match-string-no-properties 2))))))))) (defun org-babel-parse-src-block-match () "Parse the match data resulting from a match of the From 2ea8652235dbb161400ce59439d29efbe9c929bd Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Wed, 23 Jun 2010 06:24:26 +0200 Subject: [PATCH 091/138] Minor fixes to org-capture.el --- lisp/org-capture.el | 7 ++++--- lisp/org-mks.el | 5 ++++- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/lisp/org-capture.el b/lisp/org-capture.el index 32db51762..a39759b9a 100644 --- a/lisp/org-capture.el +++ b/lisp/org-capture.el @@ -78,8 +78,9 @@ keys The keys that will select the template, as a string, characters (\"b\" \"Templates for marking stuff to buy\") - Do not use \"C\" as a key, it is reserved for customizing the - template variable. + The \"C\" key is used by default for quick access to the + customization of the template variable. But if you want to use + that key for a template, you can. description A short string describing the template, will be shown during selection. @@ -801,7 +802,7 @@ Point will remain at the first line after the inserted text." ((eq type 'item) (setq txt "- %?")) ((eq type 'checkitem) (setq txt "- [ ] %?")) ((eq type 'table-line) (setq txt "| %? |")) - ((member type '(nil entry)) (setq txt "* %?")))) + ((member type '(nil entry)) (setq txt "* %?\n %a")))) (org-capture-put :template txt :type type))) (defun org-capture-goto-target (&optional template-key) diff --git a/lisp/org-mks.el b/lisp/org-mks.el index b0b102d3e..59f65278e 100644 --- a/lisp/org-mks.el +++ b/lisp/org-mks.el @@ -100,7 +100,10 @@ also (\"key\" \"description\") entries. When they are selected, (message prompt) (setq pressed (char-to-string (read-char-exclusive)))) (if (equal pressed "\C-g") (error "Abort")) - (if (assoc pressed specials) (throw 'exit (setq rtn pressed))) + (when (and (not (assoc pressed table)) + (not (member pressed des-keys)) + (assoc pressed specials)) + (throw 'exit (setq rtn pressed))) (unless (member pressed des-keys) (throw 'exit (setq rtn (rassoc (cdr (assoc pressed table)) orig-table)))) From 9f4452f43c5a68346dfadb6ac5b75872828d92bb Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Wed, 23 Jun 2010 06:37:54 +0200 Subject: [PATCH 092/138] Add org-capture.el and org-mks.el to the Makefile --- Makefile | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Makefile b/Makefile index 12759cda8..f485b2081 100644 --- a/Makefile +++ b/Makefile @@ -66,6 +66,7 @@ LISPF = org.el \ org-bbdb.el \ org-beamer.el \ org-bibtex.el \ + org-capture.el \ org-clock.el \ org-colview.el \ org-colview-xemacs.el \ @@ -98,6 +99,7 @@ LISPF = org.el \ org-macs.el \ org-mew.el \ org-mhe.el \ + org-mks.el \ org-mobile.el \ org-mouse.el \ org-publish.el \ @@ -348,6 +350,7 @@ lisp/org-archive.elc: lisp/org.el lisp/org-bbdb.elc: lisp/org.el lisp/org-beamer.elc: lisp/org.el lisp/org-bibtex.elc: lisp/org.el +lisp/org-capture.elc: lisp/org.el lisp/org-mks.el lisp/org-clock.elc: lisp/org.el lisp/org-colview.elc: lisp/org.el lisp/org-colview-xemacs.elc: lisp/org.el @@ -380,6 +383,7 @@ lisp/org-mac-message.elc: lisp/org.el lisp/org-macs.elc: lisp/org-mew.elc: lisp/org.el lisp/org-mhe.elc: lisp/org.el +lisp/org-mks.elc: lisp/org-mobile.elc: lisp/org.el lisp/org-mouse.elc: lisp/org.el lisp/org-plot.elc: lisp/org.el lisp/org-exp.el lisp/org-table.el From 19602fa56e1576042f625f2115d720e68367656c Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Wed, 23 Jun 2010 07:39:56 +0200 Subject: [PATCH 093/138] Fix minor bugs in org-capture.el, and keep byte-compiler happy --- lisp/org-capture.el | 12 +++++++++--- lisp/org-mks.el | 7 ++++++- 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/lisp/org-capture.el b/lisp/org-capture.el index a39759b9a..1edfb0869 100644 --- a/lisp/org-capture.el +++ b/lisp/org-capture.el @@ -53,6 +53,11 @@ (require 'org) (require 'org-mks) +(declare-function org-datetree-find-date-create "org-datetree" + (DATE &optional KEEP-RESTRICTION)) +(defvar org-remember-default-headline) +(defvar org-remember-templates) + (defvar org-capture-clock-was-started nil "Internal flag, noting if the clock was started.") @@ -451,8 +456,7 @@ already gone." (let ((pos (point)) (base (buffer-base-buffer (current-buffer)))) (org-capture-finalize) (save-window-excursion - (save-excursion - (set-buffer (or base (current-buffer))) + (with-current-buffer (or base (current-buffer)) (save-excursion (save-restriction (widen) @@ -522,6 +526,7 @@ already gone." (error "No match for target regexp in file %s" (nth 1 target)))) ((eq (car target) 'file+datetree) + (require 'org-datetree) (set-buffer (org-capture-target-buffer (nth 1 target))) ;; Make a date tree entry, with the current date (or yesterday, ;; if we are extending dates for a couple of hours) @@ -839,7 +844,7 @@ Lisp programs can force the template by setting KEYS to a string." (when org-capture-templates (if keys (or (assoc keys org-capture-templates) - (error "No capture template referred to by \"%s\" keys")) + (error "No capture template referred to by \"%s\" keys" keys)) (org-mks org-capture-templates "Select a capture template\n=========================" "Template key: " @@ -1087,6 +1092,7 @@ The template may still contain \"%?\" for cursor positioning." "Import old remember templates into org-capture-templates? ") (yes-or-no-p "Note that this will remove any templates currently defined in `org-capture-templates'. Do you still want to go ahead? ")) + (require 'org-remember) (setq org-capture-templates (mapcar (lambda (entry) diff --git a/lisp/org-mks.el b/lisp/org-mks.el index 59f65278e..abf5e799e 100644 --- a/lisp/org-mks.el +++ b/lisp/org-mks.el @@ -23,6 +23,10 @@ ;; along with GNU Emacs. If not, see . ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +(require 'org) +(eval-when-compile + (require 'cl)) + (defun org-mks (table title &optional prompt specials) "Select a member of an alist with multiple keys. TABLE is the alist which should contain entries where the car is a string. @@ -49,7 +53,8 @@ also (\"key\" \"description\") entries. When they are selected, " (setq prompt (or prompt "Select: ")) - (let (tbl orig-table dkey ddesc des-keys allowed-keys current prefix rtn) + (let (tbl orig-table dkey ddesc des-keys allowed-keys + current prefix rtn re pressed) (save-window-excursion (org-switch-to-buffer-other-window "*Org Select*") (setq orig-table table) From 85e6bb964d875f5457e7e1e9a63f4e108208ba0e Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Wed, 23 Jun 2010 08:41:14 +0200 Subject: [PATCH 094/138] Improve importing of remember templates into org-capture Tassilo Horn had set org-remember-default-headline to `bottom', and the importer did not handle this special case. --- lisp/org-capture.el | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/lisp/org-capture.el b/lisp/org-capture.el index 1edfb0869..870632ea0 100644 --- a/lisp/org-capture.el +++ b/lisp/org-capture.el @@ -1100,7 +1100,7 @@ The template may still contain \"%?\" for cursor positioning." (key (char-to-string (nth 1 entry))) (template (nth 2 entry)) (file (or (nth 3 entry) org-default-notes-file)) - (position (nth 4 entry)) + (position (or (nth 4 entry) org-remember-default-headline)) (type 'entry) (prepend org-reverse-note-order) immediate target) @@ -1111,9 +1111,7 @@ The template may still contain \"%?\" for cursor positioning." ((eq position 'date-tree) (setq target (list 'file+datetree file) prepend nil)) - (t (setq target - (list 'file+headline file - (or position org-remember-default-headline))))) + (t (setq target (list 'file+headline file position)))) (when (string-match "%!" template) (setq template (replace-match "" t t template) From fab06f546310b2d03f8394f0ead79d6c6e01cbb1 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Wed, 23 Jun 2010 10:36:42 +0200 Subject: [PATCH 095/138] Implement aborting a capture note with `C-c C-k' --- lisp/org-capture.el | 141 +++++++++++++++++++++++++++----------------- 1 file changed, 88 insertions(+), 53 deletions(-) diff --git a/lisp/org-capture.el b/lisp/org-capture.el index 870632ea0..b0db6bcd8 100644 --- a/lisp/org-capture.el +++ b/lisp/org-capture.el @@ -387,72 +387,94 @@ bypassed." (buffer-base-buffer (current-buffer))) (error "This does not seem to be a capture buffer for Org-mode")) + ;; Did we start the clock in this capture buffer? + (when (and org-capture-clock-was-started + org-clock-marker (marker-buffer org-clock-marker) + (equal (marker-buffer org-clock-marker) (buffer-base-buffer)) + (> org-clock-marker (point-min)) + (< org-clock-marker (point-max))) + ;; Looks like the clock we started is still running. Clock out. + (let (org-log-note-clock-out) (org-clock-out)) + (when (and (org-capture-get :clock-resume 'local) + (markerp (org-capture-get :interrupted-clock 'local)) + (buffer-live-p (marker-buffer + (org-capture-get :interrupted-clock 'local)))) + (org-with-point-at (org-capture-get :interrupted-clock 'local) + (org-clock-in)) + (message "Interrupted clock has been resumed"))) + (let ((beg (point-min)) - (end (point-max))) + (end (point-max)) + (abort-note nil)) (widen) - ;; Make sure that the empty lines after are correct - (when (and (> (point-max) end) ; indeed, the buffer was still narrowed - (member (org-capture-get :type 'local) - '(entry item checkitem plain))) - (save-excursion - (goto-char end) - (org-capture-empty-lines-after - (or (org-capture-get :empty-lines 'local) 0)))) - ;; Postprocessing: Update Statistics cookies, do the sorting - (when (org-mode-p) - (save-excursion - (when (ignore-errors (org-back-to-heading)) - (org-update-parent-todo-statistics) - (org-update-checkbox-count))) - ;; FIXME Here we should do the sorting - ;; If we have added a table line, maybe recompute? - (when (and (eq (org-capture-get :type 'local) 'table-line) - (org-at-table-p)) - (if (org-table-get-stored-formulas) - (org-table-recalculate 'all) ;; FIXME: Should we iterate??? - (org-table-align))) - ) - ;; Store this place as the last one where we stored something - ;; Do the marking in the base buffer, so that it makes sense after - ;; the indirect buffer has been killed. - (let ((pos (point))) - (with-current-buffer (buffer-base-buffer (current-buffer)) + + (if org-note-abort + (let ((m1 (org-capture-get :begin-marker 'local)) + (m2 (org-capture-get :end-marker 'local))) + (if (and m1 m2 (= m1 beg) (= m2 end)) + (progn + (setq abort-note 'clean) + (kill-region m1 m2)) + (setq abort-note 'dirty))) + + ;; Make sure that the empty lines after are correct + (when (and (> (point-max) end) ; indeed, the buffer was still narrowed + (member (org-capture-get :type 'local) + '(entry item checkitem plain))) (save-excursion - (save-restriction - (widen) - (goto-char pos) - (bookmark-set "org-capture-last-stored") - (move-marker org-capture-last-stored-marker (point)))))) - ;; Run the hook - (run-hooks 'org-capture-before-finalize-hook) - ;; Did we start the clock in this capture buffer? - (when (and org-capture-clock-was-started - org-clock-marker (marker-buffer org-clock-marker) - (equal (marker-buffer org-clock-marker) (buffer-base-buffer)) - (> org-clock-marker (point-min)) - (< org-clock-marker (point-max))) - ;; Looks like the clock we started is still running. Clock out. - (let (org-log-note-clock-out) (org-clock-out)) - (when (and (org-capture-get :clock-resume 'local) - (markerp (org-capture-get :interrupted-clock 'local)) - (buffer-live-p (marker-buffer - (org-capture-get :interrupted-clock 'local)))) - (org-with-point-at (org-capture-get :interrupted-clock 'local) - (org-clock-in)) - (message "Interrupted clock has been resumed"))) + (goto-char end) + (org-capture-empty-lines-after + (or (org-capture-get :empty-lines 'local) 0)))) + ;; Postprocessing: Update Statistics cookies, do the sorting + (when (org-mode-p) + (save-excursion + (when (ignore-errors (org-back-to-heading)) + (org-update-parent-todo-statistics) + (org-update-checkbox-count))) + ;; FIXME Here we should do the sorting + ;; If we have added a table line, maybe recompute? + (when (and (eq (org-capture-get :type 'local) 'table-line) + (org-at-table-p)) + (if (org-table-get-stored-formulas) + (org-table-recalculate 'all) ;; FIXME: Should we iterate??? + (org-table-align))) + ) + ;; Store this place as the last one where we stored something + ;; Do the marking in the base buffer, so that it makes sense after + ;; the indirect buffer has been killed. + (let ((pos (point))) + (with-current-buffer (buffer-base-buffer (current-buffer)) + (save-excursion + (save-restriction + (widen) + (goto-char pos) + (bookmark-set "org-capture-last-stored") + (move-marker org-capture-last-stored-marker (point)))))) + ;; Run the hook + (run-hooks 'org-capture-before-finalize-hook) + ) ;; Kill the indirect buffer (save-buffer) (let ((return-wconf (org-capture-get :return-to-wconf 'local))) (kill-buffer (current-buffer)) ;; Restore the window configuration before capture - (set-window-configuration return-wconf)))) + (set-window-configuration return-wconf)) + (when abort-note + (cond + ((equal abort-note 'clean) + (message "Capture process aborted and target file cleaned up")) + ((equal abort-note 'dirty) + (error "Capture process aborted, but target buffer could not be cleaned up correctly")))))) (defun org-capture-refile () "Finalize the current capture and then refile the entry. Refiling is done from the base buffer, because the indirect buffer is then already gone." (interactive) + (unless (eq (org-capture-get :type 'local) 'entry) + (error + "Refiling from a capture buffer makes only sense for `entry'-type templates")) (let ((pos (point)) (base (buffer-base-buffer (current-buffer)))) (org-capture-finalize) (save-window-excursion @@ -466,9 +488,10 @@ already gone." (defun org-capture-kill () "Abort the current capture process." (interactive) + (debug) ;; FIXME: This does not do the right thing, we need to remove the new stuff ;; By hand it is easy: undo, then kill the buffer - (let ((org-note-abort t)) + (let ((org-note-abort t) (org-capture-before-finalize-hook nil)) (org-capture-finalize))) (defun org-capture-goto-last-stored () @@ -617,6 +640,7 @@ already gone." (org-capture-empty-lines-after 1) (outline-next-heading) (setq end (point)) + (org-capture-mark-kill-region beg (1- end)) (org-capture-narrow beg (1- end)) (if (re-search-forward "%\\?" end t) (replace-match "")))) @@ -658,13 +682,17 @@ already gone." (setq ind (make-string ind ?\ )) (setq txt (concat ind (mapconcat 'identity (split-string txt "\n") - (concat "\n" ind)))) + (concat "\n" ind)) + "\n")) ;; Insert, with surrounding empty lines (org-capture-empty-lines-before) (setq beg (point)) (insert txt) + (or (bolp) (insert "\n")) (org-capture-empty-lines-after 1) + (forward-char 1) (setq end (point)) + (org-capture-mark-kill-region beg (1- end)) (org-capture-narrow beg (1- end)) (if (re-search-forward "%\\?" end t) (replace-match "")))) @@ -731,9 +759,16 @@ already gone." (insert txt) (org-capture-empty-lines-after 1) (setq end (point)) + (org-capture-mark-kill-region beg (1- end)) (org-capture-narrow beg (1- end)) (if (re-search-forward "%\\?" end t) (replace-match "")))) +(defun org-capture-mark-kill-region (bed end) + (let ((m1 (move-marker (make-marker) beg)) + (m2 (move-marker (make-marker) end))) + (org-capture-put :begin-marker m1) + (org-capture-put :end-marker m2))) + (defun org-capture-narrow (beg end) "Narrow, unless configuraion says not to narrow." (unless (org-capture-get :unnarrowed) From 94e76bd7e21596b1bb5b981133e23a73c19130dd Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Wed, 23 Jun 2010 10:37:11 +0200 Subject: [PATCH 096/138] Remove forgotten (debug) form --- lisp/org-capture.el | 1 - 1 file changed, 1 deletion(-) diff --git a/lisp/org-capture.el b/lisp/org-capture.el index b0db6bcd8..0585c6584 100644 --- a/lisp/org-capture.el +++ b/lisp/org-capture.el @@ -488,7 +488,6 @@ already gone." (defun org-capture-kill () "Abort the current capture process." (interactive) - (debug) ;; FIXME: This does not do the right thing, we need to remove the new stuff ;; By hand it is easy: undo, then kill the buffer (let ((org-note-abort t) (org-capture-before-finalize-hook nil)) From c303801202d0f42b9b42340833ad1dcfa6544c26 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Wed, 23 Jun 2010 13:26:25 +0200 Subject: [PATCH 097/138] Fix typo --- lisp/org-capture.el | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lisp/org-capture.el b/lisp/org-capture.el index 0585c6584..c47cdf443 100644 --- a/lisp/org-capture.el +++ b/lisp/org-capture.el @@ -762,7 +762,8 @@ already gone." (org-capture-narrow beg (1- end)) (if (re-search-forward "%\\?" end t) (replace-match "")))) -(defun org-capture-mark-kill-region (bed end) +(defun org-capture-mark-kill-region (beg end) + "Mark the region that will have to be killed when aborting capture." (let ((m1 (move-marker (make-marker) beg)) (m2 (move-marker (make-marker) end))) (org-capture-put :begin-marker m1) From 99e7f33f0aa4a364f931aab31dd3494cca24f135 Mon Sep 17 00:00:00 2001 From: Sebastian Rose Date: Tue, 22 Jun 2010 16:20:13 +0200 Subject: [PATCH 098/138] New implementation of the Org remember process ready for comments and testing Carsten Dominik writes: > 3 Why a new name? > ~~~~~~~~~~~~~~~~~~ > > I have - at least for now - chosen a new name for the new setup: > ` org-capture'. There are two reasons for this: In the manual it is "Capture - Refile - Archive". I remember searching for "Remember" and never found it :) > 5 Setup > ~~~~~~~~ > > To use the new setup, do the following: > > 1. Run > > M-x org-capture-import-remember-templates RET Worked perfectly here :) I tested all my important templates and they work. Abandoning org-remember seems painless. > '(("t" "templates adding table lines") > ("ta" "add to table a" table-line (file+headline "~/notes.org" "Table A)) > ("tb" "add to table b" table-line (file+headline "~/notes.org" "Table B)) > ("tc" "add to table c" table-line (file+headline "~/notes.org" "Table C))) > > When starting capture, you can then first press "t" and then see > the individual options. This is great. Number of templates is constantly growing and the new features will increase the speed of this process. > 7 Request for comments > ~~~~~~~~~~~~~~~~~~~~~~~ > > None of what I describe is set in stone yet - let me know if you have > comments, change requests or other ideas. > > My feeling right now is that this should become the default capture > system, and that we will keep the current org-remember in the > distribution for quite some time, for compatibility. Good track I guess. Here's the tested and working patch for org-protocol.el. To use `org-remember' and/or `org-capture' alike, copy your org-remember link and change javascript:location.href='org-protocol://remember://'+... to javascript:location.href='org-protocol://capture://'+... The template char used is the same for both --- which is OK for me, but could be changed. --- lisp/org-protocol.el | 103 +++++++++++++++++++++++++++---------------- 1 file changed, 65 insertions(+), 38 deletions(-) diff --git a/lisp/org-protocol.el b/lisp/org-protocol.el index 0642227e7..88676f45d 100644 --- a/lisp/org-protocol.el +++ b/lisp/org-protocol.el @@ -87,12 +87,17 @@ ;; pushes the browsers URL to the `kill-ring' for yanking. This handler is ;; triggered through the sub-protocol \"store-link\". ;; -;; * Call `org-protocol-remember' by using the sub-protocol \"remember\". If -;; Org-mode is loaded, emacs will pop-up a remember buffer and fill the +;; * Call `org-protocol-capture' by using the sub-protocol \"capture\". If +;; Org-mode is loaded, emacs will pop-up a capture buffer and fill the ;; template with the data provided. I.e. the browser's URL is inserted as an ;; Org-link of which the page title will be the description part. If text ;; was select in the browser, that text will be the body of the entry. ;; +;; * Call `org-protocol-remember' by using the sub-protocol \"remember\". +;; This is provided for backward compatibility. +;; You may read `org-capture' as `org-remember' throughout this file if +;; you still use `org-remember'. +;; ;; You may use the same bookmark URL for all those standard handlers and just ;; adjust the sub-protocol used: ;; @@ -101,7 +106,7 @@ ;; encodeURIComponent(document.title)+'/'+ ;; encodeURIComponent(window.getSelection()) ;; -;; The handler for the sub-protocol \"remember\" detects an optional template +;; The handler for the sub-protocol \"capture\" detects an optional template ;; char that, if present, triggers the use of a special template. ;; Example: ;; @@ -143,6 +148,7 @@ for `org-protocol-the-protocol' and sub-procols defined in (defconst org-protocol-protocol-alist-default '(("org-remember" :protocol "remember" :function org-protocol-remember :kill-client t) + ("org-capture" :protocol "capture" :function org-protocol-capture :kill-client t) ("org-store-link" :protocol "store-link" :function org-protocol-store-link) ("org-open-source" :protocol "open-source" :function org-protocol-open-source)) "Default protocols to use. @@ -260,7 +266,6 @@ Here is an example: :group 'org-protocol :type 'string) - ;;; Helper functions: (defun org-protocol-sanitize-uri (uri) @@ -443,10 +448,6 @@ The sub-protocol used to reach this function is set in (defun org-protocol-remember (info) "Process an org-protocol://remember:// style url. -The sub-protocol used to reach this function is set in -`org-protocol-protocol-alist'. - -This function detects an URL, title and optional text, separated by '/' The location for a browser's bookmark has to look like this: javascript:location.href='org-protocol://remember://'+ \\ @@ -454,40 +455,66 @@ The location for a browser's bookmark has to look like this: encodeURIComponent(document.title)+'/'+ \\ encodeURIComponent(window.getSelection()) -By default, it uses the character `org-protocol-default-template-key', -which should be associated with a template in `org-remember-templates'. -But you may prepend the encoded URL with a character and a slash like so: - - javascript:location.href='org-protocol://org-store-link://b/'+ ... - -Now template ?b will be used." +See the docs for `org-protocol-capture' for more information." (if (and (boundp 'org-stored-links) - (fboundp 'org-remember)) - (let* ((parts (org-protocol-split-data info t)) - (template (or (and (= 1 (length (car parts))) (pop parts)) - org-protocol-default-template-key)) - (url (org-protocol-sanitize-uri (car parts))) - (type (if (string-match "^\\([a-z]+\\):" url) - (match-string 1 url))) - (title (or (cadr parts) "")) - (region (or (caddr parts) "")) - (orglink (org-make-link-string - url (if (string-match "[^[:space:]]" title) title url))) - remember-annotation-functions) - (setq org-stored-links - (cons (list url title) org-stored-links)) - (kill-new orglink) - (org-store-link-props :type type - :link url - :description title - :initial region) - (raise-frame) - (org-remember nil (string-to-char template))) - - (message "Org-mode not loaded.")) + (or (fboundp 'org-capture)) + (org-protocol-do-capture info 'org-remember)) + (message "Org-mode not loaded.")) nil) +(defun org-protocol-capture (info) + "Process an org-protocol://capture:// style url. + +The sub-protocol used to reach this function is set in +`org-protocol-protocol-alist'. + +This function detects an URL, title and optional text, separated by '/' +The location for a browser's bookmark has to look like this: + + javascript:location.href='org-protocol://capture://'+ \\ + encodeURIComponent(location.href)+'/' \\ + encodeURIComponent(document.title)+'/'+ \\ + encodeURIComponent(window.getSelection()) + +By default, it uses the character `org-protocol-default-template-key', +which should be associated with a template in `org-capture-templates'. +But you may prepend the encoded URL with a character and a slash like so: + + javascript:location.href='org-protocol://capture://b/'+ ... + +Now template ?b will be used." + (if (and (boundp 'org-stored-links) + (or (fboundp 'org-capture)) + (org-protocol-do-capture info 'org-capture)) + (message "Org-mode not loaded.")) + nil) + +(defun org-protocol-do-capture (info capture-func) + "Support `org-capture' and `org-remember' alike. +CAPTURE-FUNC is either the symbol `org-remember' or `org-capture'." + (let* ((parts (org-protocol-split-data info t)) + (template (or (and (= 1 (length (car parts))) (pop parts)) + org-protocol-default-template-key)) + (url (org-protocol-sanitize-uri (car parts))) + (type (if (string-match "^\\([a-z]+\\):" url) + (match-string 1 url))) + (title(or (cadr parts) "")) + (region (or (caddr parts) "")) + (orglink (org-make-link-string + url (if (string-match "[^[:space:]]" title) title url))) + remember-annotation-functions) + (setq org-stored-links + (cons (list url title) org-stored-links)) + (kill-new orglink) + (org-store-link-props :type type + :link url + :description title + :initial region) + (raise-frame) + (funcall capture-func nil template))) + + (defun org-protocol-open-source (fname) "Process an org-protocol://open-source:// style url. From fb46cf11d315f5c6a4cbba717137362216cb0e2f Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Wed, 23 Jun 2010 16:21:22 +0200 Subject: [PATCH 099/138] Make the link properties from org-protocol work in capture --- lisp/org-capture.el | 8 +++++++- lisp/org-protocol.el | 2 ++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/lisp/org-capture.el b/lisp/org-capture.el index c47cdf443..19df17e98 100644 --- a/lisp/org-capture.el +++ b/lisp/org-capture.el @@ -64,6 +64,10 @@ (defvar org-capture-last-stored-marker (make-marker) "Marker pointing to the entry most recently stored with `org-capture'.") +;; The following variable is scoped dynamically by org-protocol +;; to indicate that the link properties have already been stored +(defvar org-capture-link-is-already-stored nil) + (defgroup org-capture nil "Options concerning capturing new entries." :tag "Org Capture" @@ -348,7 +352,9 @@ bypassed." ;; set temporary variables that will be needed in ;; `org-select-remember-template' (let* ((orig-buf (current-buffer)) - (annotation (org-store-link nil)) + (annotation (if org-capture-link-is-already-stored + (plist-get org-store-link-plist :annotation) + (org-store-link nil))) (initial (and (org-region-active-p) (buffer-substring (point) (mark)))) (entry (org-capture-select-template keys))) diff --git a/lisp/org-protocol.el b/lisp/org-protocol.el index 88676f45d..a02a17097 100644 --- a/lisp/org-protocol.el +++ b/lisp/org-protocol.el @@ -503,6 +503,7 @@ CAPTURE-FUNC is either the symbol `org-remember' or `org-capture'." (region (or (caddr parts) "")) (orglink (org-make-link-string url (if (string-match "[^[:space:]]" title) title url))) + (org-capture-link-is-already-stored t) ;; avoid call to org-store-link remember-annotation-functions) (setq org-stored-links (cons (list url title) org-stored-links)) @@ -510,6 +511,7 @@ CAPTURE-FUNC is either the symbol `org-remember' or `org-capture'." (org-store-link-props :type type :link url :description title + :annotation orglink :initial region) (raise-frame) (funcall capture-func nil template))) From a46e01358e575502e85f04ec2a331f32f96b6b56 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Wed, 23 Jun 2010 17:16:44 +0200 Subject: [PATCH 100/138] Org Capture: Make ?q abort, and allow to specify the line position in table --- lisp/org-capture.el | 76 ++++++++++++++++++++++++++++++++------------- 1 file changed, 54 insertions(+), 22 deletions(-) diff --git a/lisp/org-capture.el b/lisp/org-capture.el index 19df17e98..baeab6e7b 100644 --- a/lisp/org-capture.el +++ b/lisp/org-capture.el @@ -169,6 +169,11 @@ properties are: full buffer. Default is to narrow it so that you only see the new stuff. + :table-line-pos Specification of the location in the table where the + new line should be inserted. It looks like \"II-3\" + 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 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. @@ -358,8 +363,12 @@ bypassed." (initial (and (org-region-active-p) (buffer-substring (point) (mark)))) (entry (org-capture-select-template keys))) - (if (equal entry "C") - (customize-variable 'org-capture-templates) + (cond + ((equal entry "C") + (customize-variable 'org-capture-templates)) + ((equal entry "q") + (error "Abort")) + (t (org-capture-set-plist entry) (org-capture-put :original-buffer orig-buf :annotation annotation :initial initial) @@ -384,7 +393,7 @@ bypassed." (org-clock-in) (org-set-local 'org-capture-clock-was-started t)) (error - "Could not start the clock in this capture buffer")))))))))) + "Could not start the clock in this capture buffer"))))))))))) (defun org-capture-finalize () "Finalize the capture process." @@ -560,9 +569,11 @@ already gone." ;; if we are extending dates for a couple of hours) (org-datetree-find-date-create (calendar-gregorian-from-absolute - (time-to-days - (time-subtract (current-time) - (list 0 (* 3600 org-extend-today-until) 0)))))) + (if org-overriding-default-time + (time-to-days org-overriding-default-time) + (time-to-days + (time-subtract (current-time) + (list 0 (* 3600 org-extend-today-until) 0))))))) ((eq (car target) 'file+function) (set-buffer (org-capture-target-buffer (nth 1 target))) @@ -705,6 +716,7 @@ already gone." "Place the template as a table line." (let* ((txt (org-capture-get :template)) (target-entry-p (org-capture-get :target-entry-p)) + (table-line-pos (org-capture-get :table-line-pos)) ind beg end) (cond ((not target-entry-p) @@ -726,20 +738,39 @@ already gone." ;; Check if the template is good (if (not (string-match org-table-dataline-regexp txt)) (setq txt "| %?Bad template |\n")) - - (if (org-capture-get :prepend) - (progn - (goto-char (point-min)) - (re-search-forward org-table-hline-regexp nil t) - (beginning-of-line 1) - (re-search-forward org-table-dataline-regexp nil t) - (beginning-of-line 1) - (setq beg (point)) - (org-table-insert-row) - (beginning-of-line 1) - (delete-region (point) (1+ (point-at-eol))) - (insert txt) - (setq end (point))) + (cond + ((and table-line-pos + (string-match "\\(I+\\)\\([-+][0-9]\\)" table-line-pos)) + (goto-char (point-min)) + (let ((nh (- (match-end 1) (match-beginning 1))) + (delta (string-to-number (match-string 2 table-line-pos))) + ll) + ;; The user wants a special position in the table + (org-table-get-specials) + (setq ll (aref org-table-hlines nh)) + (unless ll (error "Invalid table line specification \"%s\"" + table-line-pos)) + (setq ll (+ ll delta (if (< delta 0) 0 -1))) + (org-goto-line ll) + (org-table-insert-row 'below) + (beginning-of-line 1) + (delete-region (point) (1+ (point-at-eol))) + (setq beg (point)) + (insert txt) + (setq end (point)))) + ((org-capture-get :prepend) + (goto-char (point-min)) + (re-search-forward org-table-hline-regexp nil t) + (beginning-of-line 1) + (re-search-forward org-table-dataline-regexp nil t) + (beginning-of-line 1) + (setq beg (point)) + (org-table-insert-row) + (beginning-of-line 1) + (delete-region (point) (1+ (point-at-eol))) + (insert txt) + (setq end (point))) + (t (goto-char (point-max)) (re-search-backward org-table-dataline-regexp nil t) (beginning-of-line 1) @@ -748,7 +779,7 @@ already gone." (delete-region (point) (1+ (point-at-eol))) (setq beg (point)) (insert txt) - (setq end (point))) + (setq end (point)))) (goto-char beg) (if (re-search-forward "%\\?" end t) (replace-match "")) (org-table-align))) @@ -889,7 +920,8 @@ Lisp programs can force the template by setting KEYS to a string." (org-mks org-capture-templates "Select a capture template\n=========================" "Template key: " - '(("C" "Customize org-capture-templates")))))) + '(("C" "Customize org-capture-templates") + ("q" "Abort")))))) (defun org-capture-fill-template (&optional template initial annotation) "Fill a template and return the filled template as a string. From 92d69c7cf74519b3130bb2b293533d4a19e20644 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Wed, 23 Jun 2010 17:41:24 +0200 Subject: [PATCH 101/138] Keep byte compiler happy --- lisp/org-capture.el | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/lisp/org-capture.el b/lisp/org-capture.el index baeab6e7b..27e629090 100644 --- a/lisp/org-capture.el +++ b/lisp/org-capture.el @@ -55,8 +55,10 @@ (declare-function org-datetree-find-date-create "org-datetree" (DATE &optional KEEP-RESTRICTION)) +(declare-function org-table-get-specials "org-table" ()) (defvar org-remember-default-headline) (defvar org-remember-templates) +(defvar org-table-hlines) (defvar org-capture-clock-was-started nil "Internal flag, noting if the clock was started.") @@ -714,14 +716,17 @@ already gone." (defun org-capture-place-table-line () "Place the template as a table line." + (require 'org-table) (let* ((txt (org-capture-get :template)) (target-entry-p (org-capture-get :target-entry-p)) (table-line-pos (org-capture-get :table-line-pos)) ind beg end) (cond ((not target-entry-p) + ;; Table is not necessarily under a heading (setq beg (point-min) end (point-max))) (t + ;; WE are at a heading, limit search to the body (setq beg (1+ (point-at-eol)) end (save-excursion (outline-next-heading) (point))))) (if (re-search-forward org-table-dataline-regexp end t) @@ -741,6 +746,7 @@ already gone." (cond ((and table-line-pos (string-match "\\(I+\\)\\([-+][0-9]\\)" table-line-pos)) + ;; we have a complex line specification (goto-char (point-min)) (let ((nh (- (match-end 1) (match-beginning 1))) (delta (string-to-number (match-string 2 table-line-pos))) From 6da29f151915fd86f40b51cbb999d3b2792aff0e Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Wed, 23 Jun 2010 11:24:33 -0700 Subject: [PATCH 102/138] integrating org-babel into org.el --- Makefile | 9 +++-- lisp/babel/ob-init.el | 20 ----------- lisp/babel/ob-keys.el | 7 +--- lisp/babel/ob-lob.el | 5 +-- lisp/babel/ob-ref.el | 4 +++ lisp/babel/ob-tangle.el | 7 ++++ lisp/babel/ob.el | 78 +++++++++++++++++++++++------------------ lisp/org-exp.el | 1 + lisp/org.el | 40 +++++++++++++++++++-- 9 files changed, 103 insertions(+), 68 deletions(-) delete mode 100644 lisp/babel/ob-init.el diff --git a/Makefile b/Makefile index 7d7181a3d..c767cbdb8 100644 --- a/Makefile +++ b/Makefile @@ -30,9 +30,10 @@ infodir = $(prefix)/share/info BATCH=$(EMACS) -batch -q -no-site-file -eval \ "(setq load-path (cons (expand-file-name\ - \"babel\"\ - (expand-file-name \"./lisp/\"))\ - (cons (expand-file-name \"./lisp/\") (cons \"$(lispdir)\" load-path))))" + \"langs\"\ + (expand-file-name \"babel\" (expand-file-name \"./lisp/\")))\ + (cons (expand-file-name \"babel\" (expand-file-name \"./lisp/\"))\ + (cons (expand-file-name \"./lisp/\") (cons \"$(lispdir)\" load-path)))))" # Specify the byte-compiler for compiling org-mode files ELC= $(BATCH) -f batch-byte-compile @@ -195,6 +196,8 @@ lisp/org-install.el: $(LISPFILES0) Makefile --eval '(find-file "org-install.el")' \ --eval '(erase-buffer)' \ --eval '(mapc (lambda (x) (generate-file-autoloads (symbol-name x))) (quote ($(LISPFILES0))))' \ + --eval "(insert \"(add-to-list 'load-path (expand-file-name \\\"babel\\\" (file-name-directory (or (buffer-file-name) load-file-name))))\")" \ + --eval "(insert \"\n(add-to-list 'load-path (expand-file-name \\\"langs\\\" (expand-file-name \\\"babel\\\" (file-name-directory (or (buffer-file-name) load-file-name)))))\")\n" \ --eval '(insert "\n(provide (quote org-install))\n")' \ --eval '(save-buffer)' mv org-install.el lisp diff --git a/lisp/babel/ob-init.el b/lisp/babel/ob-init.el deleted file mode 100644 index a229dea38..000000000 --- a/lisp/babel/ob-init.el +++ /dev/null @@ -1,20 +0,0 @@ -;;; ob-init.el --- working with code blocks in org-mode -(require 'ob) -(require 'ob-table) -(require 'ob-lob) -(require 'ob-ref) -(require 'ob-exp) -(require 'ob-tangle) -(require 'ob-comint) -(require 'ob-keys) - -;; add the langs/ directory to the load path -(add-to-list - 'load-path (expand-file-name - "langs" - (file-name-directory (or (buffer-file-name) - load-file-name)))) -(require 'ob-emacs-lisp) - -(provide 'ob-init) -;;; ob-init.el ends here \ No newline at end of file diff --git a/lisp/babel/ob-keys.el b/lisp/babel/ob-keys.el index 233c4c5da..b98a069d9 100644 --- a/lisp/babel/ob-keys.el +++ b/lisp/babel/ob-keys.el @@ -45,8 +45,7 @@ functions which are assigned key bindings, and see "The keymap holding key bindings for interactive org-babel functions.") -(define-key org-mode-map org-babel-key-prefix org-babel-map) - +;;;###autoload (defun org-babel-describe-bindings () "Describe all key binding placed behind the `org-babel-key-prefix' prefix." @@ -78,9 +77,5 @@ 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'.") -(mapc (lambda (pair) - (define-key org-babel-map (car pair) (cdr pair))) - org-babel-key-bindings) - (provide 'ob-keys) ;;; ob-keys.el ends here diff --git a/lisp/babel/ob-lob.el b/lisp/babel/ob-lob.el index 064c51228..25eb7bda4 100644 --- a/lisp/babel/ob-lob.el +++ b/lisp/babel/ob-lob.el @@ -31,7 +31,6 @@ ;;; Code: (require 'ob) (require 'ob-table) -(require 'ob-exp) (defvar org-babel-library-of-babel nil "Library of source-code blocks. This is an association list. @@ -43,6 +42,7 @@ add files to this list use the `org-babel-lob-ingest' command." :group 'org-babel :type 'list) +;;;###autoload (defun org-babel-lob-ingest (&optional file) "Add all source-blocks defined in FILE to `org-babel-library-of-babel'." (interactive "f") @@ -67,7 +67,7 @@ add files to this list use the `org-babel-lob-ingest' command." "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 @@ -78,6 +78,7 @@ the Library." (add-hook 'org-ctrl-c-ctrl-c-hook 'org-babel-lob-execute-maybe) +;;;###autoload (defun org-babel-lob-get-info () "Return the function call supplied on the current Library of Babel line as a string. diff --git a/lisp/babel/ob-ref.el b/lisp/babel/ob-ref.el index c75930e33..36bbcbd21 100644 --- a/lisp/babel/ob-ref.el +++ b/lisp/babel/ob-ref.el @@ -56,6 +56,9 @@ (eval-when-compile (require 'cl)) +(declare-function org-remove-if-not "org" (predicate seq)) +(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." @@ -214,6 +217,7 @@ which case the entire range is returned." ((or (string= holder ")") (string= holder "]")) (setq depth (- depth 1))))) (mapcar #'org-babel-trim (reverse (cons buffer return))))) +(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 diff --git a/lisp/babel/ob-tangle.el b/lisp/babel/ob-tangle.el index 30a962307..64171b7e3 100644 --- a/lisp/babel/ob-tangle.el +++ b/lisp/babel/ob-tangle.el @@ -30,9 +30,12 @@ ;;; Code: (require 'ob) +(require 'org-src) (eval-when-compile (require 'cl)) +(declare-function org-link-escape "org" (text &optional table)) + (defcustom org-babel-tangle-w-comments nil "Control the insertion of comments into tangled code. Non-nil value will result in the insertion of comments for those @@ -53,6 +56,7 @@ then the name of the language is used." (string "Language name") (string "File Extension")))) +;;;###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 @@ -72,6 +76,7 @@ file using `load-file'." (load-file exported-file) (message "loaded %s" exported-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 @@ -92,6 +97,7 @@ blocks by language." "Tangle FILENAME and place the results in PUB-DIR." (mapc (lambda (el) (copy-file el pub-dir t)) (org-babel-tangle-file filename))) +;;;###autoload (defun org-babel-tangle (&optional target-file lang) "Extract the bodies of all source code blocks from the current file into their own source-specific files. Optional argument @@ -178,6 +184,7 @@ references." (delete-region (save-excursion (beginning-of-line 1) (point)) (save-excursion (end-of-line 1) (forward-char 1) (point))))) +(defvar org-stored-links) (defun org-babel-tangle-collect-blocks (&optional lang) "Collect all source blocks in the current org-mode file. Return an association list of source-code block specifications of diff --git a/lisp/babel/ob.el b/lisp/babel/ob.el index 56eb0c83a..aad0ab6ff 100644 --- a/lisp/babel/ob.el +++ b/lisp/babel/ob.el @@ -30,22 +30,35 @@ ;;; Code: (eval-when-compile (require 'cl)) -(require 'org) (defvar org-babel-call-process-region-original) -(declare-function orgtbl-to-generic "org-table" (table params)) -(declare-function org-babel-ref-split-args "ob-ref" (arg-string)) -(declare-function org-babel-ref-variables "ob-ref" (params)) -(declare-function org-babel-lob-get-info "ob-lob" nil) -(declare-function orgtbl-to-orgtbl "org-table" (table params)) -(declare-function org-babel-ref-resolve-reference - "ob-ref" (ref &optional params)) -(declare-function tramp-compat-make-temp-file - "tramp" (filename &optional dir-flag)) -(declare-function tramp-dissect-file-name - "tramp" (name &optional nodefault)) +(declare-function show-all "outline" ()) +(declare-function tramp-compat-make-temp-file "tramp" (filename &optional dir-flag)) +(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-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)) +(declare-function org-narrow-to-subtree "org" ()) +(declare-function org-entry-get "org" (pom property &optional inherit)) +(declare-function org-make-options-regexp "org" (kwds &optional extra)) +(declare-function org-match-string-no-properties "org" (num &optional string)) +(declare-function org-do-remove-indentation "org" (&optional n)) +(declare-function org-show-context "org" (&optional key)) +(declare-function org-at-table-p "org" (&optional table-type)) +(declare-function org-cycle "org" (&optional arg)) +(declare-function org-uniquify "org" (list)) +(declare-function org-table-import "org" (file arg)) +(declare-function org-add-hook "org-compat" (hook function &optional append local)) +(declare-function org-table-align "org-table" ()) +(declare-function org-table-end "org-table" (&optional table-type)) +(declare-function orgtbl-to-generic "org-table" (table params)) +(declare-function orgtbl-to-orgtbl "org-table" (table params)) +(declare-function org-babel-lob-get-info "ob-lob" nil) +(declare-function org-babel-ref-split-args "ob-ref" (arg-string)) +(declare-function org-babel-ref-variables "ob-ref" (params)) +(declare-function org-babel-ref-resolve-reference "ob-ref" (ref &optional params)) (defvar org-babel-source-name-regexp "^[ \t]*#\\+\\(srcname\\|source\\|function\\):[ \t]*" @@ -120,6 +133,7 @@ added to the header-arguments-alist." (org-babel-parse-inline-src-block-match) nil)))) +;;;###autoload (defun org-babel-execute-src-block-maybe () "Detect if this is context for a org-babel src-block and if so then run `org-babel-execute-src-block'." @@ -130,6 +144,7 @@ then run `org-babel-execute-src-block'." (add-hook 'org-ctrl-c-ctrl-c-hook 'org-babel-execute-src-block-maybe) +;;;###autoload (defun org-babel-expand-src-block-maybe () "Detect if this is context for a org-babel src-block and if so then run `org-babel-expand-src-block'." @@ -139,28 +154,7 @@ then run `org-babel-expand-src-block'." (progn (org-babel-expand-src-block current-prefix-arg info) t) nil))) -(defadvice org-edit-special (around org-babel-prep-session-for-edit activate) - "Prepare the current source block's session according to it's -header arguments before editing in an org-src buffer. This -function is called when `org-edit-special' is called with a -prefix argument from inside of a source-code block." - (when current-prefix-arg - (let* ((info (org-babel-get-src-block-info)) - (lang (nth 0 info)) - (params (nth 2 info)) - (session (cdr (assoc :session params)))) - (when (and info session) ;; we are in a source-code block with a session - (funcall - (intern (concat "org-babel-prep-session:" lang)) session params)))) - ad-do-it) - -(defadvice org-open-at-point (around org-babel-open-at-point activate) - "If `point' is on a source code block, then open that block's -results with `org-babel-open-src-block-results', otherwise defer -to `org-open-at-point'." - (interactive "P") - (or (call-interactively #'org-babel-open-src-block-result) ad-do-it)) - +;;;###autoload (defun org-babel-load-in-session-maybe () "Detect if this is context for a org-babel src-block and if so then run `org-babel-load-in-session'." @@ -172,6 +166,7 @@ then run `org-babel-load-in-session'." (add-hook 'org-metaup-hook 'org-babel-load-in-session-maybe) +;;;###autoload (defun org-babel-pop-to-session-maybe () "Detect if this is context for a org-babel src-block and if so then run `org-babel-pop-to-session'." @@ -230,6 +225,7 @@ can not be resolved.") ;;; 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 @@ -303,6 +299,7 @@ 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." @@ -323,6 +320,7 @@ arguments, and pop open the results in a preview buffer." (org-edit-src-code nil expanded (concat "*Org-Babel Preview " (buffer-name) "[ " lang " ]*")))) +;;;###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 @@ -339,6 +337,7 @@ session. After loading the body this pops open the session." (pop-to-buffer (funcall cmd session body params)) (end-of-line 1))) +;;;###autoload (defun org-babel-switch-to-session (&optional arg info) "Switch to the session of the current source-code block. If called with a prefix argument then evaluate the header arguments @@ -370,6 +369,8 @@ of the source block to the kill ring." (defalias 'org-babel-pop-to-session 'org-babel-switch-to-session) +(defvar org-bracket-link-regexp) +;;;###autoload (defun org-babel-open-src-block-result (&optional re-run) "If `point' is on a src block then open the results of the source code block, otherwise return nil. With optional prefix @@ -400,6 +401,7 @@ results already exist." (insert (echo-res results)))))) t))) +;;;###autoload (defun org-babel-execute-buffer (&optional arg) "Call `org-babel-execute-src-block' on every source block in the current buffer." @@ -414,6 +416,7 @@ the current buffer." (org-babel-execute-src-block arg) (goto-char pos-end)))))) +;;;###autoload (defun org-babel-execute-subtree (&optional arg) "Call `org-babel-execute-src-block' on every source block in the current subtree." @@ -424,6 +427,7 @@ the current subtree." (org-babel-execute-buffer) (widen)))) +;;;###autoload (defun org-babel-sha1-hash (&optional info) "Generate an sha1 hash based on the value of info." (interactive) @@ -504,6 +508,7 @@ portions of results lines." (mapc 'delete-overlay org-babel-hide-result-overlays) (setq org-babel-hide-result-overlays nil)) +;;;###autoload (defun org-babel-hide-result-toggle-maybe () "Toggle visibility of result at point." (interactive) @@ -575,6 +580,7 @@ portions of results lines." (unless visited-p (kill-buffer to-be-removed)))) +(defvar org-file-properties) (defun org-babel-params-from-properties (&optional lang) "Return an association list of any source block params which may be specified in the properties of the current outline entry." @@ -612,6 +618,7 @@ may be specified at the top of the current buffer." (org-babel-parse-header-arguments (org-match-string-no-properties 2))))))))) +(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'." @@ -805,6 +812,7 @@ If the point is not on a source block then return nil." (looking-at org-babel-src-block-regexp)) (point)))))) +;;;###autoload (defun org-babel-goto-named-source-block (&optional name) "Go to a named source-code block." (interactive "ssource-block name: ") @@ -883,6 +891,7 @@ following the source block." (if hash (org-babel-hide-hash)) t))) (point)))))) +(defvar org-block-regexp) (defun org-babel-read-result () "Read the result at `point' into emacs-lisp." (let ((case-fold-search t) result-string) @@ -913,6 +922,7 @@ following the source block." (mapcar #'org-babel-read row))) (org-table-to-lisp))) +(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'." diff --git a/lisp/org-exp.el b/lisp/org-exp.el index 029e4d795..704c0b7ac 100644 --- a/lisp/org-exp.el +++ b/lisp/org-exp.el @@ -30,6 +30,7 @@ (require 'org-macs) (require 'org-agenda) (require 'org-exp-blocks) +(require 'ob-exp) (require 'org-src) (eval-when-compile (require 'cl)) diff --git a/lisp/org.el b/lisp/org.el index 26281520a..a721b0e68 100644 --- a/lisp/org.el +++ b/lisp/org.el @@ -104,6 +104,23 @@ (require 'org-src) (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) +(require 'ob-ref) +(require 'ob-tangle) +(require 'ob-comint) +(require 'ob-keys) +(require 'ob-emacs-lisp) + ;;;; Customization variables (defcustom org-clone-delete-id nil "Remove ID property of clones of a subtree. @@ -8887,6 +8904,8 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file. With a double prefix argument, try to open outside of Emacs, in the application the system uses for this file type." (interactive "P") + ;; if in a code block, then open the block's results + (unless (call-interactively #'org-babel-open-src-block-result) (org-load-modules-maybe) (move-marker org-open-link-marker (point)) (setq org-window-config-before-follow-link (current-window-configuration)) @@ -9068,7 +9087,7 @@ application the system uses for this file type." (t (browse-url-at-point))))))) (move-marker org-open-link-marker nil) - (run-hook-with-args 'org-follow-link-hook)) + (run-hook-with-args 'org-follow-link-hook))) (defun org-offer-links-in-entry (&optional nth zero) "Offer links in the current entry and follow the selected link. @@ -16010,6 +16029,12 @@ BEG and END default to the buffer boundaries." (org-defkey org-mode-map [(control shift right)] 'org-shiftcontrolright) (org-defkey org-mode-map [(control shift left)] 'org-shiftcontrolleft) +;; Babel keys +(define-key org-mode-map org-babel-key-prefix org-babel-map) +(mapc (lambda (pair) + (define-key org-babel-map (car pair) (cdr pair))) + org-babel-key-bindings) + ;;; Extra keys for tty access. ;; We only set them when really needed because otherwise the ;; menus don't show the simple keys @@ -16872,14 +16897,23 @@ See the individual commands for more information." (org-table-paste-rectangle) (org-paste-subtree arg))) -(defun org-edit-special () +(defun org-edit-special (&optional arg) "Call a special editor for the stuff at point. When at a table, call the formula editor with `org-table-edit-formulas'. When at the first line of an src example, call `org-edit-src-code'. When in an #+include line, visit the include file. Otherwise call `ffap' to visit the file at point." (interactive) - (cond + ;; possibly prep session before editing source + (when arg + (let* ((info (org-babel-get-src-block-info)) + (lang (nth 0 info)) + (params (nth 2 info)) + (session (cdr (assoc :session params)))) + (when (and info session) ;; we are in a source-code block with a session + (funcall + (intern (concat "org-babel-prep-session:" lang)) session params)))) + (cond ;; proceed with `org-edit-special' ((save-excursion (beginning-of-line 1) (looking-at "\\(?:#\\+\\(?:setupfile\\|include\\):?[ \t]+\"?\\|[ \t]*.*?file=\"\\)\\([^\"\n>]+\\)")) From b6e9c6a996f848d85e14fd910c6d1d4bec7b8c63 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Wed, 23 Jun 2010 15:57:38 -0700 Subject: [PATCH 103/138] babel: variables can now accept null literal values * lisp/babel/ob-exp.el (org-babel-exp-results): now checking to see if return value of `org-babel-ref-literal' is equal to the null indicator flag -- meaning it's now possible to accept a value of null * lisp/babel/ob-ref.el (org-babel-ref-parse): now checking to see if return value of `org-babel-ref-literal' is equal to the null indicator flag -- meaning it's now possible to accept a value of null (org-babel-ref-literal): now returning a null indicator flag when the value is *not* a literal value, meaning it is possible to pass in a literal value of null --- lisp/babel/ob-exp.el | 3 ++- lisp/babel/ob-ref.el | 9 ++++++--- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/lisp/babel/ob-exp.el b/lisp/babel/ob-exp.el index a12f2795f..c6a4f4936 100644 --- a/lisp/babel/ob-exp.el +++ b/lisp/babel/ob-exp.el @@ -245,7 +245,8 @@ results into the buffer." (if (and org-current-export-file (eq (car pair) :var) (string-match org-babel-ref-split-regexp (cdr pair)) - (null (org-babel-ref-literal (match-string 2 (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)))) diff --git a/lisp/babel/ob-ref.el b/lisp/babel/ob-ref.el index 36bbcbd21..df8a0338e 100644 --- a/lisp/babel/ob-ref.el +++ b/lisp/babel/ob-ref.el @@ -83,8 +83,10 @@ emacs-lisp representation of the value of the variable." (let ((var (match-string 1 assignment)) (ref (match-string 2 assignment))) (cons (intern var) - (or (org-babel-ref-literal ref) - (org-babel-ref-resolve-reference ref params)))))) + ((lambda (val) + (if (equal :ob-must-be-reference val) + (org-babel-ref-resolve-reference ref params) + val)) (org-babel-ref-literal ref)))))) (defun org-babel-ref-literal (ref) "Determine if the right side of a header argument variable @@ -95,7 +97,8 @@ return nil." (let ((out (org-babel-read ref))) (if (equal out ref) (if (string-match "^\".+\"$" ref) - (read ref)) + (read ref) + :ob-must-be-reference) out))) (defvar org-babel-library-of-babel) From ec8edda16594125e159e45206447fe25499ac68f Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Wed, 23 Jun 2010 16:40:48 -0700 Subject: [PATCH 104/138] babel: ob-oz is now up to date with the new naming schema * contrib/babel/langs/ob-oz.el (ob-oz): brought ob-oz up to date with new naming schema --- contrib/babel/langs/ob-oz.el | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/contrib/babel/langs/ob-oz.el b/contrib/babel/langs/ob-oz.el index b8c416f4e..e1e6e35bb 100644 --- a/contrib/babel/langs/ob-oz.el +++ b/contrib/babel/langs/ob-oz.el @@ -1,4 +1,4 @@ -;;; org-babel-oz.el --- org-babel functions for Oz evaluation +;;; ob-oz.el --- org-babel functions for Oz evaluation ;; Copyright (C) 2009 Torsten Anders and Eric Schulte @@ -88,7 +88,7 @@ ;; -(require 'org-babel) +(require 'ob) ;;; major mode for editing Oz programs (require 'mozart) @@ -302,5 +302,5 @@ Emacs-lisp table, otherwise return the results as a string." (error "org-babel-oz-table-or-string unimplemented")) -(provide 'org-babel-oz) +(provide 'ob-oz) ;;; org-babel-oz.el ends here From 024974299c58edccf68cf7c5e9b057d794a14930 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Wed, 23 Jun 2010 17:27:23 -0700 Subject: [PATCH 105/138] babel: updating documentation for new babel 'ob* require syntax Thanks to Bernt Hansen for pointing this out * doc/org.texi (Languages): updating require statements for the next org-babel syntax (Batch execution): updating require statements for the next org-babel syntax --- doc/org.texi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 19ee7b0e5..1f8b4206d 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -11175,7 +11175,7 @@ the following to your Emacs configuration, (replace ``identifier'' with one of the language names from the above table). @example -(require 'org-babel-identifier) +(require 'ob-identifier) @end example @@ -12060,7 +12060,7 @@ emacsclient \ --eval "(progn (add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\")) (add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\")) -(require 'org)(require 'org-exp)(require 'org-babel) +(require 'org)(require 'org-exp)(require 'ob)(require 'ob-tangle) (mapc (lambda (file) (find-file (expand-file-name file \"$DIR\")) (org-babel-tangle) From e6182995d9f31fb0265abef8d9eb6c377dc1bf2b Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Thu, 24 Jun 2010 07:17:54 +0200 Subject: [PATCH 106/138] Skip template selection if there is only a single template --- lisp/org-capture.el | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/lisp/org-capture.el b/lisp/org-capture.el index 27e629090..decf50a77 100644 --- a/lisp/org-capture.el +++ b/lisp/org-capture.el @@ -356,8 +356,7 @@ bypassed." ((equal goto '(4)) (org-capture-goto-target)) ((equal goto '(16)) (org-capture-goto-last-stored)) (t - ;; set temporary variables that will be needed in - ;; `org-select-remember-template' + ;; FIXME: Are these needed? (let* ((orig-buf (current-buffer)) (annotation (if org-capture-link-is-already-stored (plist-get org-store-link-plist :annotation) @@ -923,11 +922,13 @@ Lisp programs can force the template by setting KEYS to a string." (if keys (or (assoc keys org-capture-templates) (error "No capture template referred to by \"%s\" keys" keys)) - (org-mks org-capture-templates - "Select a capture template\n=========================" - "Template key: " - '(("C" "Customize org-capture-templates") - ("q" "Abort")))))) + (if (= 1 (length org-capture-templates)) + (car org-capture-templates) + (org-mks org-capture-templates + "Select a capture template\n=========================" + "Template key: " + '(("C" "Customize org-capture-templates") + ("q" "Abort"))))))) (defun org-capture-fill-template (&optional template initial annotation) "Fill a template and return the filled template as a string. From 1fc1dc389b1d04ca989516b1bb41cfde46e6a964 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Thu, 24 Jun 2010 07:36:13 +0200 Subject: [PATCH 107/138] Make sure the clock history only points to base buffers --- lisp/org-clock.el | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/lisp/org-clock.el b/lisp/org-clock.el index 8477b2cdb..6bd1d3989 100644 --- a/lisp/org-clock.el +++ b/lisp/org-clock.el @@ -314,7 +314,10 @@ of a different task.") (defun org-clock-history-push (&optional pos buffer) "Push a marker to the clock history." (setq org-clock-history-length (max 1 (min 35 org-clock-history-length))) - (let ((m (move-marker (make-marker) (or pos (point)) buffer)) n l) + (let ((m (move-marker (make-marker) + (or pos (point)) (org-base-buffer + (or buffer (current-buffer))))) + n l) (while (setq n (member m org-clock-history)) (move-marker (car n) nil)) (setq org-clock-history From 08f8875ecdb6cdddc872e5474c87c1bfb5b6adc3 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Thu, 24 Jun 2010 08:53:34 +0200 Subject: [PATCH 108/138] Catch agenda error when there is a tie stamp before the first headline * lisp/org-agenda.el (org-agenda-get-timestamps): No errors while getting TODO state. (org-agenda-highlight-todo): No error when no keyword has been matched. Eric Arneson writes: > I've discovered a bug in `org-agenda-get-timestamps' wherein an active > timestamp before the first headline causes it to fail. I realize that > this is probably an error in my use of active timestamps, but there was > no really handy error message and this bugged me for weeks. > > I'm not familiar enough with org-mode to know what the correct behavior > should be here (it'd be nice to get an error message saying "Don't use > active timestamps that way!"), but here's an example .org file that will > trigger the bug: > > --8<---------------cut here---------------start------------->8--- > #+BEGIN: clocktable :maxlevel 3 :scope today > Clock summary at [2010-06-20 Sun 13:09] > > | L | Headline | Time | > |---+---------------------------------------+--------| > | | *Total time* | *0:13* | > |---+---------------------------------------+--------| > | 1 | Track down funky bug <2010-06-20 Sun> | 0:13 | > #+END: > > * Track down funky bug <2010-06-20 Sun> > :LOGBOOK: > CLOCK: [2010-06-20 Sun 12:43] > CLOCK: [2010-06-20 Sun 12:30]--[2010-06-20 Sun 12:43] => 0:13 > :END: > --8<---------------cut here---------------end--------------->8--- > > I hope this can help somebody else track down the right place to fix > this bug. --- lisp/org-agenda.el | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el index bdb852649..8035addb7 100644 --- a/lisp/org-agenda.el +++ b/lisp/org-agenda.el @@ -4344,7 +4344,7 @@ the documentation of `org-diary'." clockp (and org-agenda-include-inactive-timestamps (or (string-match org-clock-string tmp) (string-match "]-+\\'" tmp))) - todo-state (org-get-todo-state) + todo-state (ignore-errors (org-get-todo-state)) donep (member todo-state org-done-keywords)) (if (or scheduledp deadlinep closedp clockp (and donep org-agenda-skip-timestamp-if-done)) @@ -5162,11 +5162,12 @@ HH:MM." (or (match-end 1) (match-end 0)) (match-end 0) (list 'face (org-get-todo-face (match-string 2 x))) x) - (setq x (concat (substring x 0 (match-end 1)) - (format org-agenda-todo-keyword-format - (match-string 2 x)) - (org-add-props " " (text-properties-at 0 x)) - (substring x (match-end 3))))) + (when (match-end 1) + (setq x (concat (substring x 0 (match-end 1)) + (format org-agenda-todo-keyword-format + (match-string 2 x)) + (org-add-props " " (text-properties-at 0 x)) + (substring x (match-end 3)))))) x))) (defsubst org-cmp-priority (a b) From a969714755e9831f2762068bd48c18e2d9087946 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Thu, 24 Jun 2010 14:05:34 -0700 Subject: [PATCH 109/138] babel: emacs-lisp no longer evaluates header argument references multiple times * lisp/babel/langs/ob-emacs-lisp.el (org-babel-expand-body:emacs-lisp): removed extra call to `org-babel-process-params' which was causing referenced code blocks to be run multiple times (org-babel-execute:emacs-lisp): now passing processed-params through to `org-babel-expand-body:emacs-lisp' which keeps references from being evaluated multiple times --- lisp/babel/langs/ob-emacs-lisp.el | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lisp/babel/langs/ob-emacs-lisp.el b/lisp/babel/langs/ob-emacs-lisp.el index c1c9da2c3..724838a0c 100644 --- a/lisp/babel/langs/ob-emacs-lisp.el +++ b/lisp/babel/langs/ob-emacs-lisp.el @@ -45,7 +45,6 @@ "Expand BODY according to PARAMS, return the expanded body." (let* ((processed-params (or processed-params (org-babel-process-params params))) (vars (nth 1 processed-params)) - (processed-params (org-babel-process-params params)) (result-params (nth 2 processed-params)) (print-level nil) (print-length nil) (body (if (> (length vars) 0) @@ -66,7 +65,8 @@ (let ((processed-params (org-babel-process-params params))) (org-babel-reassemble-table (eval (read (format "(progn %s)" - (org-babel-expand-body:emacs-lisp body params)))) + (org-babel-expand-body:emacs-lisp + body params processed-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))))))) From ae20361475ae80550ac228838784da14d8ac841e Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Fri, 25 Jun 2010 07:29:13 +0200 Subject: [PATCH 110/138] Fix the clock target for org-capture --- lisp/org-capture.el | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/lisp/org-capture.el b/lisp/org-capture.el index decf50a77..879dd25ea 100644 --- a/lisp/org-capture.el +++ b/lisp/org-capture.el @@ -584,8 +584,7 @@ already gone." ((eq (car target) 'clock) (if (and (markerp org-clock-hd-marker) (marker-buffer org-clock-hd-marker)) - (progn (set-buffer (org-capture-target-buffer - (marker-buffer org-clock-hd-marker))) + (progn (set-buffer (marker-buffer org-clock-hd-marker)) (goto-char org-clock-hd-marker)) (error "No running clock that could be used as capture target"))) From 732884dbeb1a0f939b6f436a9d2bab9dcc9e3f8e Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Fri, 25 Jun 2010 08:23:25 +0200 Subject: [PATCH 111/138] Fix the behavior of C-a when visible-mode is active * lisp/org.el (org-truely-invisible-p): New function. (org-beginning-of-line): Use `org-truely-invisible-p'. Sebastien Vauban writes: > I'm reporting some movement problem I've observed. When on any line, let's say > the last clock one: > > - `C-e' moves the cursor to the end of it > - `C-a' moves the cursor at the level of `LOGBOOK'. > > --8<---------------cut here---------------start------------->8--- > **** Emails and News > :PROPERTIES: > :ID: 62849012-ae7a-4885-a552-b34516d3fd06 > :Effort: 1:00 > :END: > :LOGBOOK: > CLOCK: [2010-06-01 Tue 08:35]--[2010-06-01 Tue 09:20] => 0:45 > CLOCK: [2010-06-02 Wed 09:10]--[2010-06-02 Wed 10:20] => 1:10 > CLOCK: [2010-06-03 Thu 09:25]--[2010-06-03 Thu 10:20] => 0:55 > CLOCK: [2010-06-04 Fri 09:00]--[2010-06-04 Fri 10:00] => 1:00 > CLOCK: [2010-06-07 Mon 09:05]--[2010-06-07 Mon 10:25] => 1:20 > CLOCK: [2010-06-08 Tue 09:05]--[2010-06-08 Tue 10:30] => 1:25 > CLOCK: [2010-06-09 Wed 09:05]--[2010-06-09 Wed 10:20] => 1:15 > CLOCK: [2010-06-10 Thu 09:05]--[2010-06-10 Thu 10:20] => 1:15 > CLOCK: [2010-06-11 Fri 09:15]--[2010-06-11 Fri 10:00] => 0:45 > CLOCK: [2010-06-14 Mon 09:15]--[2010-06-14 Mon 10:10] => 0:55 > :END: > --8<---------------cut here---------------end--------------->8--- > > This is -- at least -- true whenever `M-x visible-mode' is enabled. --- lisp/org.el | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/lisp/org.el b/lisp/org.el index a721b0e68..21a14678d 100644 --- a/lisp/org.el +++ b/lisp/org.el @@ -18560,8 +18560,8 @@ beyond the end of the headline." (if (bobp) nil (backward-char 1) - (if (org-invisible-p) - (while (and (not (bobp)) (org-invisible-p)) + (if (org-truely-invisible-p) + (while (and (not (bobp)) (org-truely-invisible-p)) (backward-char 1) (beginning-of-line 1)) (forward-char 1)))) @@ -18779,6 +18779,17 @@ interactive command with similar behavior." (outline-invisible-p) (get-char-property (point) 'invisible))) +(defun org-truely-invisible-p () + "Check if point is at a character currently not visible. +This version does not only check the character property, but also +`visible-mode'." + ;; Early versions of noutline don't have `outline-invisible-p'. + (if (org-bound-and-true-p visible-mode) + nil + (if (fboundp 'outline-invisible-p) + (outline-invisible-p) + (get-char-property (point) 'invisible)))) + (defun org-invisible-p2 () "Check if point is at a character currently not visible." (save-excursion From a547c1048b6a195fb4d3ae79697753b3e69e3398 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Fri, 25 Jun 2010 09:00:19 +0200 Subject: [PATCH 112/138] Fix issue with turning off ORDERED property * lisp/org-macs.el (org-not-nil): New function. * lisp/org.el (org-block-todo-from-children-or-siblings-or-parent): Use `org-not-nil' to interpret a property value of nil. Robert Goldman writes: > I have found what I believe to be a bug in handling ordered subtasks. > Here is the behavior: > > I have a top level set of tasks that is ordered. > > One of the outline items below the top level set is a grab bag of tasks > that will be performed in parallel. So this task is NOT ordered > (ORDERED: nil). > > The problem is that the blocking behavior from ordered tasks seems to be > inherited from the top level task list into the second level of the > outline, even though the ORDERED property at the second level is > explicitly overridden. > > I am attaching an org file that displays this issue. To see the > problem, put your cursor on the "Bar" task and attempt to change its > status to DONE. The problem was here that the value of the property is the string "nil", which is of course not nil. This patches introduces a special case to interpret "nil" as nil. --- lisp/org-macs.el | 4 ++++ lisp/org.el | 4 ++-- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/lisp/org-macs.el b/lisp/org-macs.el index 65a864758..ad1fab50b 100644 --- a/lisp/org-macs.el +++ b/lisp/org-macs.el @@ -43,6 +43,10 @@ "Return the value of symbol VAR if it is bound, else nil." `(and (boundp (quote ,var)) ,var)) +(defun org-not-nil (v) + "Is V not nil, and also not the string \"nil\"?" + (and v (not (equal v "nil")))) + (defmacro org-unmodified (&rest body) "Execute body without changing `buffer-modified-p'. Also, do not record undo information." diff --git a/lisp/org.el b/lisp/org.el index 21a14678d..7bb4f45d7 100644 --- a/lisp/org.el +++ b/lisp/org.el @@ -10881,7 +10881,7 @@ changes. Such blocking occurs when: (let* ((pos (point)) (parent-pos (and (org-up-heading-safe) (point)))) (if (not parent-pos) (throw 'dont-block t)) ; no parent - (when (and (org-entry-get (point) "ORDERED") + (when (and (org-not-nil (org-entry-get (point) "ORDERED")) (forward-line 1) (re-search-forward org-not-done-heading-regexp pos t)) (throw 'dont-block nil)) ; block, there is an older sibling not done. @@ -10893,7 +10893,7 @@ changes. Such blocking occurs when: (setq pos (point)) (setq parent-pos (and (org-up-heading-safe) (point))) (if (not parent-pos) (throw 'dont-block t)) ; no parent - (when (and (org-entry-get (point) "ORDERED") + (when (and (org-not-nil (org-entry-get (point) "ORDERED")) (forward-line 1) (re-search-forward org-not-done-heading-regexp pos t)) (throw 'dont-block nil)))))))) ; block, older sibling not done. From 6724bcfa94c7af51dade0cf93e07df19875a6e70 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Fri, 25 Jun 2010 09:09:34 +0200 Subject: [PATCH 113/138] Clean up org-babel documentation Patch by Thomas S. Dye --- doc/org.texi | 629 ++++++++++++++++++++++++++++----------------------- 1 file changed, 345 insertions(+), 284 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 1f8b4206d..775648060 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -108,7 +108,7 @@ license to the document, as described in section 6 of the license. * Markup:: Prepare text for rich export * Exporting:: Sharing and publishing of notes * Publishing:: Create a web site of linked Org files -* Working With Source Code:: Export, evaluate, and tangle code blocks +* Working With Source Code:: Export, evaluate, and tangle code blocks * Miscellaneous:: All the rest which did not fit elsewhere * Hacking:: How to hack your way around * MobileOrg:: Viewing and capture on a mobile device @@ -306,7 +306,7 @@ Markup for rich export * Images and tables:: Tables and Images will be included * Literal examples:: Source code examples with special formatting * Include files:: Include additional files into a document -* Index entries:: +* Index entries:: Making an index * Macro replacement:: Use macros to create complex output * Embedded LaTeX:: LaTeX can be freely used inside Org documents @@ -380,13 +380,6 @@ Publishing * Uploading files:: How to get files up on the server * Sample configuration:: Example projects * Triggering publication:: Publication commands -* Library of Babel:: -* Languages:: -* Header arguments:: -* Results:: -* Noweb reference syntax:: -* Key bindings & useful functions:: -* Batch execution:: Configuration @@ -406,47 +399,47 @@ Sample configuration Working With Source Code -* Structure of code blocks:: -* Editing source code:: -* Exporting code blocks:: -* Extracting source code:: -* Evaluating code blocks:: -* Library of Babel:: -* Languages:: -* Header arguments:: -* Results:: -* Noweb reference syntax:: -* Key bindings & useful functions:: -* Batch execution:: +* Structure of code blocks:: Code block syntax described +* Editing source code:: Language major-mode editing +* Exporting code blocks:: Export contents and/or results +* Extracting source code:: Create pure source code files +* Evaluating code blocks:: Place results of evaluation in the Org-mode buffer +* Library of Babel:: Use and contribute to a library of useful code blocks +* Languages:: List of supported code block languages +* Header arguments:: Configure code block functionality +* Results of evaluation:: How evaluation results are handled +* Noweb reference syntax:: Literate programming in Org-mode +* Key bindings and useful functions:: Work quickly with code blocks +* Batch execution:: Call functions from the command line Header arguments -* Using header arguments:: -* Specific header arguments:: +* Using header arguments:: Different ways to set header arguments +* Specific header arguments:: List of header arguments Using header arguments -* System-wide header arguments:: -* Language-specific header arguments:: -* Buffer-wide header arguments:: -* Header arguments in Org-mode properties:: -* Code block specific header arguments:: +* System-wide header arguments:: Set global default values +* Language-specific header arguments:: Set default values by language +* Buffer-wide header arguments:: Set default values for a specific buffer +* Header arguments in Org-mode properties:: Set default values for a buffer or heading +* Code block specific header arguments:: The most common way to set values Specific header arguments -* var argument:: -* results argument:: -* file argument:: -* dir and remote execution:: -* exports argument:: -* tangle argument:: -* no-expand argument:: -* session argument:: -* noweb argument:: -* cache argument:: -* hlines argument:: -* colnames argument:: -* rownames argument:: +* var:: Pass arguments to code blocks +* results:: Specify the type of results and how they will be collectd 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 +* tangle:: Toggle tangling and specify file name +* no-expand:: Turn off variable assignment and noweb expansion during tangling +* session:: Preserve the state of code evaluation +* noweb:: Toggle expansion of noweb references +* cache:: Avoid re-evaluating unchanged code blocks +* hlines:: Handle horizontal lines in tables +* colnames:: Handle column names in tables +* rownames:: Handle row names in tables Miscellaneous @@ -8310,13 +8303,13 @@ Org mode has rules on how to prepare text for rich export. This section summarizes the markup rules used in an Org-mode buffer. @menu -* Structural markup elements:: The basic structure as seen by the exporter -* Images and tables:: Tables and Images will be included -* Literal examples:: Source code examples with special formatting -* Include files:: Include additional files into a document -* Index entries:: Making an index -* Macro replacement:: Use macros to create complex output -* Embedded LaTeX:: LaTeX can be freely used inside Org documents +* Structural markup elements:: The basic structure as seen by the exporter +* Images and tables:: Tables and Images will be included +* Literal examples:: Source code examples with special formatting +* Include files:: Include additional files into a document +* Index entries:: Making an index +* Macro replacement:: Use macros to create complex output +* Embedded LaTeX:: LaTeX can be freely used inside Org documents @end menu @node Structural markup elements, Images and tables, Markup, Markup @@ -10407,13 +10400,6 @@ Publishing has been contributed to Org by David O'Toole. * Uploading files:: How to get files up on the server * Sample configuration:: Example projects * Triggering publication:: Publication commands -* Library of Babel:: -* Languages:: -* Header arguments:: -* Results:: -* Noweb reference syntax:: -* Key bindings & useful functions:: -* Batch execution:: @end menu @node Configuration, Uploading files, Publishing, Publishing @@ -10927,30 +10913,33 @@ e.g. Org-mode provides a number of features for working with live source code, including editing of code blocks in their native major-mode, evaluation of -code blocks, tangling of code blocks, and exportation of code blocks and -their results to a number of formats. The following sections describe -Org-mode's code block handling facilities. +code blocks, tangling of code blocks, and exporting code blocks and +their results in several formats. + +The following sections describe Org-mode's code block handling facilities. @menu -* Structure of code blocks:: -* Editing source code:: -* Exporting code blocks:: -* Extracting source code:: -* Evaluating code blocks:: -* Library of Babel:: -* Languages:: -* Header arguments:: -* Results:: -* Noweb reference syntax:: -* Key bindings & useful functions:: -* Batch execution:: +* Structure of code blocks:: Code block syntax described +* Editing source code:: Language major-mode editing +* Exporting code blocks:: Export contents and/or results +* Extracting source code:: Create pure source code files +* Evaluating code blocks:: Place results of evaluation in the Org-mode buffer +* Library of Babel:: Use and contribute to a library of useful code blocks +* Languages:: List of supported code block languages +* Header arguments:: Configure code block functionality +* Results of evaluation:: How evaluation results are handled +* Noweb reference syntax:: Literate programming in Org-mode +* Key bindings and useful functions:: Work quickly with code blocks +* Batch execution:: Call functions from the command line @end menu - -@node Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code @comment node-name, next, previous, up @comment Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code + +@node Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code @section Structure of code blocks +@cindex code block, structure +@cindex source code, block structure The structure of code blocks is as follows: @@ -10975,22 +10964,26 @@ Switches controling exportation of the code block (see switches discussion in @ref{Literal examples}) @item
Optional header arguments control many aspects of evaluation, export and -tangling of source code blocks. See the @ref{Header arguments} +tangling of code blocks. See the @ref{Header arguments} section. Header arguments can also be set on a per-buffer or per-subtree basis using properties. @item The source code. @end table -@node Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code @comment node-name, next, previous, up @comment Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code -@section Editing source code -Use @kbd{C-c '} to edit the current code block. This brings up a language -major-mode edit buffer containing the body of the code block. Saving this -buffer will write the new contents back to the Org buffer. Use @kbd{C-c '} -again to exit. +@node Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code +@section Editing source code +@cindex code block, editing +@cindex source code, editing + +@kindex C-c ' +Use @kbd{C-c '} to edit the current code block. This brings up +a language major-mode edit buffer containing the body of the code +block. Saving this buffer will write the new contents back to the Org +buffer. Use @kbd{C-c '} again to exit. The @code{org-src-mode} minor mode will be active in the edit buffer. The following variables can be used to configure the behavior of the edit @@ -11013,10 +11006,13 @@ By default, Org will ask before returning to an open edit buffer. Set this variable to nil to switch without asking. @end table -@node Exporting code blocks, Extracting source code, Editing source code, Working With Source Code @comment node-name, next, previous, up @comment Exporting code blocks, Extracting source code, Editing source code, Working With Source Code + +@node Exporting code blocks, Extracting source code, Editing source code, Working With Source Code @section Exporting code blocks +@cindex code block, exporting +@cindex source code, exporting It is possible to export the @emph{contents} of code blocks, the @emph{results} of code block evaluation, @emph{neither}, or @emph{both}. For @@ -11049,6 +11045,8 @@ Neither the code block nor its results will be exported. @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 @section Extracting source code +@cindex source code, extracting +@cindex code block, extracting source code Creating pure source code files by extracting code from source blocks is referred to as ``tangling''---a term adopted from the literate programming @@ -11056,7 +11054,7 @@ community. During ``tangling'' of code blocks their bodies are expanded using @code{org-babel-expand-src-block} which can expand both variable and ``noweb'' style references (see @ref{Noweb reference syntax}). -@subsubheading header arguments: +@subsubheading Header arguments @table @code @item :tangle no The default. The code block is not included in the tangled output. @@ -11068,9 +11066,10 @@ for the block language. Include the code block in the tangled output to file @samp{filename}. @end table -@subsubheading functions: +@kindex C-c C-v t +@subsubheading Functions @table @code -@item org-babel-tangle @key{C-c C-v t} +@item org-babel-tangle @kbd{C-c C-v t} Tangle the current file. @item org-babel-tangle-file Choose a file to tangle. @@ -11081,15 +11080,18 @@ Choose a file to tangle. @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 Code blocks can be evaluated and the results placed in the Org-mode buffer. -Check the value of the variable @code{org-babel-interpreters} for a list of languages -that can be evaluated on your system. See also @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. +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 @key{C-c C-c} with the point on a code block. This will call the +press @kbd{C-c C-c} 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. @@ -11107,7 +11109,7 @@ blocks located in the current Org-mode buffer or in the ``Library of Babel'' @table @code @item -The name of the source code block to be evaluated. +The name of the code block to be evaluated. @item Arguments specified in this section will be passed to the code block. @item
@@ -11118,6 +11120,10 @@ Header arguments can be placed after the function invocation. See @node Library of Babel, Languages, Evaluating code blocks, Working With Source Code @section Library of Babel +@cindex babel, library of +@cindex source code, library +@cindex code block, library + The ``Library of Babel'' is a library of code blocks that can be called from any Org-mode file. The library is housed in an Org-mode file located in the @samp{contrib} directory of Org-mode. @@ -11128,67 +11134,68 @@ Code blocks defined in the ``Library of Babel'' can be called remotely as if they were in the current Org-mode buffer (see @ref{Evaluating code blocks} for information on the syntax of remote code block evaluation). +@kindex C-c C-v l Code blocks located in any Org-mode file can be loaded into the ``Library of -Babel'' with the @code{org-babel-lob-ingest} function, bound to @key{C-c C-v +Babel'' with the @code{org-babel-lob-ingest} function, bound to @kbd{C-c C-v l}. @node Languages, Header arguments, Library of Babel, Working With Source Code @section Languages +@cindex babel, languages +@cindex source code, languages +@cindex code block, languages + Code blocks in the following languages are supported. -@multitable @columnfractions 0.583 0.417 -@item Language @tab Identifier -@item Asymptote @tab asymptote -@item C @tab C -@item C @tab C++ -@item Clojure @tab clojure -@item css @tab css -@item ditaa @tab ditaa -@item Graphviz @tab dot -@item Emacs Lisp @tab emacs-lisp -@item gnuplot @tab gnuplot -@item Haskell @tab haskell -@item Matlab @tab matlab -@item LaTeX @tab latex -@item Objective Caml @tab ocaml -@item Octave @tab octave -@item OZ @tab oz -@item Perl @tab perl -@item Python @tab python -@item R @tab R -@item Ruby @tab ruby -@item Sass @tab sass -@item GNU Screen @tab screen -@item shell @tab sh -@item SQL @tab sql -@item Sqlite @tab sqlite +@multitable @columnfractions 0.28 0.3 0.22 0.2 +@item Language @tab Identifier @tab Language @tab Identifier +@item Asymptote @tab asymptote @tab C @tab C +@item C @tab C++ @tab Clojure @tab clojure +@item css @tab css @tab ditaa @tab ditaa +@item Graphviz @tab dot @tab Emacs Lisp @tab emacs-lisp +@item gnuplot @tab gnuplot @tab Haskell @tab haskell +@item Matlab @tab matlab @tab LaTeX @tab latex +@item Objective Caml @tab ocaml @tab Octave @tab octave +@item OZ @tab oz @tab Perl @tab perl +@item Python @tab python @tab R @tab R +@item Ruby @tab ruby @tab Sass @tab sass +@item GNU Screen @tab screen @tab shell @tab sh +@item SQL @tab sql @tab Sqlite @tab sqlite @end multitable - See the language specific documentation and an up to date list of languages -that is available at -@uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}. +Language specific documentation is available for some languages. If +available, it can be found at +@uref{http://orgmode.org/worg/org-contrib/babel/languages}. -To add support for a particular language to your installation, first -make sure that the requirements of the language are met, then add a line like -the following to your Emacs configuration, (replace ``identifier'' with one -of the language names from the above table). +To add support for a particular language to your installation: +@enumerate +@item +ensure that the language-specific requirements are met, then +@item +add a line to your Emacs configuration like @example (require 'ob-identifier) @end example +where ``identifier'' is taken from the table above, e.g., +@example +(require 'ob-sass) +@end example +@end enumerate - -@node Header arguments, Results, Languages, Working With Source Code +@node Header arguments, Results of evaluation, Languages, Working With Source Code @section Header arguments +@cindex code block, header arguments +@cindex source code, block header arguments Code block functionality can be configured with header arguments. This section provides an overview of the use of header arguments, and then describes each header argument in detail. @menu -* Using header arguments:: -* Specific header arguments:: +* Using header arguments:: Different ways to set header arguments +* Specific header arguments:: List of header arguments @end menu @node Using header arguments, Specific header arguments, Header arguments, Header arguments @@ -11197,15 +11204,17 @@ describes each header argument in detail. The values of header arguments can be set in five different ways, each more specific (and having higher priority) than the last. @menu -* System-wide header arguments:: -* Language-specific header arguments:: -* Buffer-wide header arguments:: -* Header arguments in Org-mode properties:: -* Code block specific header arguments:: +* System-wide header arguments:: Set global default values +* Language-specific header arguments:: Set default values by language +* Buffer-wide header arguments:: Set default values for a specific buffer +* Header arguments in Org-mode properties:: Set default values for a buffer or heading +* Code block specific header arguments:: The most common way to set values @end menu + @node System-wide header arguments, Language-specific header arguments, Using header arguments, Using header arguments @subsubheading System-wide header arguments +@vindex org-babel-default-header-args System-wide values of header arguments can be specified by customizing the @code{org-babel-default-header-args} variable: @@ -11269,7 +11278,7 @@ of setting a header argument for all code blocks in a buffer is When properties are used to set default header arguments, they are looked up with inheritance, so the value of the @code{:cache} header argument will default -to @code{yes} in all source code blocks in the subtree rooted at the following +to @code{yes} in all code blocks in the subtree rooted at the following heading: @example @@ -11279,9 +11288,11 @@ heading: :END: @end example +@kindex C-c C-x p +@vindex org-babel-default-header-args Properties defined in this way override the properties set in @code{org-babel-default-header-args}. It is convenient to use the -@code{org-set-property} function bound to @key{C-c C-x p} to set properties +@code{org-set-property} function bound to @kbd{C-c C-x p} to set properties in Org-mode documents. @node Code block specific header arguments, , Header arguments in Org-mode properties, Using header arguments @@ -11291,11 +11302,11 @@ The most common way to assign values to header arguments is at the code block level. This can be done by listing a sequence of header arguments and their values as part of the @code{#+begin_src} line. Properties set in this way override both the values of -@code{org-babel-default-header-args} and header argument specified as +@code{org-babel-default-header-args} and header arguments specified as properties. In the following example, the @code{:results} header argument is set to @code{silent}, meaning the results of execution will not be inserted in the buffer, and the @code{:exports} header argument is set to -@code{code}, meaning only the body of the source code block will be +@code{code}, meaning only the body of the code block will be preserved on export to HTML or LaTeX. @example @@ -11323,23 +11334,23 @@ Header arguments for ``Library of Babel'' or function call lines can be set as s The following header arguments are defined: @menu -* var argument:: -* results argument:: -* file argument:: -* dir and remote execution:: -* exports argument:: -* tangle argument:: -* no-expand argument:: -* session argument:: -* noweb argument:: -* cache argument:: -* hlines argument:: -* colnames argument:: -* rownames argument:: +* var:: Pass arguments to code blocks +* results:: Specify the type of results and how they will be collectd 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 +* tangle:: Toggle tangling and specify file name +* no-expand:: Turn off variable assignment and noweb expansion during tangling +* session:: Preserve the state of code evaluation +* noweb:: Toggle expansion of noweb references +* cache:: Avoid re-evaluating unchanged code blocks +* hlines:: Handle horizontal lines in tables +* colnames:: Handle column names in tables +* rownames:: Handle row names in tables @end menu -@node var argument, results argument, Specific header arguments, Specific header arguments -@subsubsection var argument +@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 @@ -11349,7 +11360,7 @@ languages. The values passed to arguments can be @itemize @bullet @item literal values @item values from org-mode tables -@item the results of other source code blocks +@item the results of other code blocks @end itemize These values can be indexed in a manner similar to arrays---see the argument @@ -11386,7 +11397,7 @@ a table name: : 4 @end example -a source code block name, as assigned by @code{#+srcname:}, followed by +a code block name, as assigned by @code{#+srcname:}, followed by parentheses: @example @@ -11400,7 +11411,7 @@ parentheses: In addition, an argument can be passed to the code block referenced by @code{:var}. The argument is passed within the parentheses following the -source code block name: +code block name: @example #+source: double @@ -11423,7 +11434,7 @@ source code block name: @subsubheading Alternate argument syntax It is also possible to specify arguments in a potentially more natural way -using the @code{#+source:} line of a source code block. As in the following +using the @code{#+source:} line of a code block. As in the following example arguments can be packed inside of parenthesis, separated by commas, following the source name. @@ -11473,39 +11484,39 @@ For more information on indexing behavior see the documentation for the which case the entire range is returned. @end example -@node results argument, file argument, var argument, Specific header arguments -@subsubsection results argument +@node results, file, var, Specific header arguments +@subsubsection @code{:results} -There are three types of results header argument. Only one option of each -type may be supplied per code block. +There are three classes of @code{:results} header argument. Only one option of +each type may be supplied per code block. @itemize @bullet -@item collection -arguments specify how the results should be collected from the source code -block -@item type -header arguments specify what type of result the source code block will +@item +@b{collection} header arguments specify how the results should be collected +from the code block +@item +@b{type} header arguments specify what type of result the code block will return---which has implications for how they will be inserted into the Org-mode buffer -@item handling -header arguments specify how the results of evaluating the source code block -should be handled. +@item +@b{handling} header arguments specify how the results of evaluating the code +block should be handled. @end itemize @subsubheading collection The following options are mutually exclusive, and specify how the results -should be collected from the source code block. +should be collected from the code block. @itemize @bullet -@item value +@item @code{value} This is the default. The result is the value of the last statement in the -source code block. This header argument places the evaluation in functional +code block. This header argument places the evaluation in functional mode. Note that in some languages, e.g., python, use of this result type requires that a @code{return} statement be included in the body of the source code block. E.g., @code{:results value}. -@item output +@item @code{output} The result is the collection of everything printed to STDOUT during the -execution of the source code block. This header argument places the +execution of the code block. This header argument places the evaluation in scripting mode. E.g., @code{:results output}. @end itemize @@ -11516,64 +11527,65 @@ the code block will return. By default, results are inserted as either a table or scalar depending on their value. @itemize @bullet -@item table, vector +@item @code{table}, @code{vector} The results should be interpreted as an Org-mode table. If a single value is returned, it will be converted into a table with one row and one column. E.g., @code{:results value table}. -@item scalar, verbatim +@item @code{scalar}, @code{verbatim} The results should be interpreted literally---they will not be converted into a table. The results will be inserted into the Org-mode buffer as quoted text. E.g., @code{:results value verbatim}. -@item file +@item @code{file} The results will be interpreted as the path to a file, and will be inserted into the Org-mode buffer as a file link. E.g., @code{:results value file}. -@item raw, org +@item @code{raw}, @code{org} The results are interpreted as raw Org-mode code and are inserted directly into the buffer. If the results look like a table they will be aligned as such by Org-mode. E.g., @code{:results value raw}. -@item html +@item @code{html} Results are assumed to be HTML and will be enclosed in a @code{begin_html} block. E.g., @code{:results value html}. -@item latex +@item @code{latex} Results assumed to be LaTeX and are enclosed in a @code{begin_latex} block. E.g., @code{:results value latex}. -@item code +@item @code{code} Result are assumed to be parseable code and are enclosed in a code block. E.g., @code{:results value code}. -@item pp +@item @code{pp} The result is converted to pretty-printed code and is enclosed in a code block. This option currently supports Emacs Lisp, python, and ruby. E.g., @code{:results value pp}. @end itemize @subsubheading handling -The following results options indicate what Org-babel should do with the +The following results options indicate what happens with the results once they are collected. @itemize @bullet -@item silent +@item @code{silent} The results will be echoed in the minibuffer but will not be inserted into the Org-mode buffer. E.g., @code{:results output silent}. -@item replace +@item @code{replace} The default value. Any existing results will be removed, and the new results will be inserted into the Org-mode buffer in their place. E.g., @code{:results output replace}. -@item append +@item @code{append} If there are pre-existing results of the code block then the new results will be appended to the existing results. Otherwise the new results will be inserted as with @code{replace}. -@item prepend +@item @code{prepend} If there are pre-existing results of the code block then the new results will be prepended to the existing results. Otherwise the new results will be inserted as with @code{replace}. @end itemize -@node file argument, dir and remote execution, results argument, Specific header arguments -@subsubsection file argument -@code{:file} is used to specify a path for file output in which case an -Org-mode style link (see @ref{Link format}) @code{file:} link is inserted -into the buffer as the result. Common examples are graphical output from R, -gnuplot, ditaa and LaTeX blocks. +@node file, dir and remote execution, results, Specific header arguments +@subsubsection @code{:file} + +The header argument @code{:file} is used to specify a path for file output. +An Org-mode style @code{file:} link is inserted into the buffer as the result +(see @ref{Link format}). Common examples are graphical output from R, +gnuplot, ditaa and LaTeX code blocks. Note that for some languages, including R, gnuplot, LaTeX and ditaa, graphical output is sent to the specified file without the file being @@ -11583,13 +11595,14 @@ as python and ruby require that the code explicitly create output corresponding to the path indicated by @code{:file}. -@node dir and remote execution, exports argument, file argument, Specific header arguments -@subsubsection dir and remote execution +@node dir and remote execution, exports, file, Specific header arguments +@subsubsection @code{:dir} and remote execution + While the @code{:file} header argument can be used to specify the path to the output file, @code{:dir} specifies the default directory during code block execution. If it is absent, then the directory associated with the current buffer is used. In other words, supplying @code{:dir path} temporarily has -the same effect as changing the current directory with @key{M-x cd path}, and +the same effect as changing the current directory with @kbd{M-x cd path}, and then not supplying @code{:dir}. Under the surface, @code{:dir} simply sets the value of the Emacs variable @code{default-directory}. @@ -11650,37 +11663,39 @@ directory}. Therefore, if @code{default-directory} is altered using which the link does not point. @end itemize -@node exports argument, tangle argument, dir and remote execution, Specific header arguments -@subsubsection exports argument -Specify what should be included in HTML or LaTeX exports of the Org-mode -file. +@node exports, tangle, dir and remote execution, Specific header arguments +@subsubsection @code{:exports} + +The @code{:exports} header argument specifies what should be included in HTML +or LaTeX exports of the Org-mode file. @itemize @bullet -@item code -the default. The body of code is included into the exported file. E.g., +@item @code{code} +The default. The body of code is included into the exported file. E.g., @code{:exports code}. -@item results -the result of evaluating the code is included in the exported file. E.g., +@item @code{results} +The result of evaluating the code is included in the exported file. E.g., @code{:exports results}. -@item both -both the code and results are included in the exported file. E.g., +@item @code{both} +Both the code and results are included in the exported file. E.g., @code{:exports both}. -@item none -nothing is included in the exported file. E.g., @code{:exports none}. +@item @code{none} +Nothing is included in the exported file. E.g., @code{:exports none}. @end itemize -@node tangle argument, no-expand argument, exports argument, Specific header arguments -@subsubsection tangle argument -Specify whether or not the source code block should be included in tangled -extraction of source code files. +@node tangle, no-expand, exports, Specific header arguments +@subsubsection @code{:tangle} + +The @code{:tangle} header argument specifies whether or not the code +block should be included in tangled extraction of source code files. @itemize @bullet -@item yes -the source code block is exported to a source code file named after the +@item @code{yes} +The code block is exported to a source code file named after the basename (name w/o extension) of the Org-mode file. E.g., @code{:tangle yes}. -@item no -the default. The source code block is not exported to a source code file. +@item @code{no} +The default. The code block is not exported to a source code file. E.g., @code{:tangle no}. @item other Any other string passed to the @code{:tangle} header argument is interpreted @@ -11688,18 +11703,21 @@ as a file basename to which the block will be exported. E.g., @code{:tangle basename}. @end itemize -@node no-expand argument, session argument, tangle argument, Specific header arguments -@subsubsection no-expand argument +@node no-expand, session, tangle, Specific header arguments +@subsubsection @code{:no-expand} + By default, code blocks are expanded with @code{org-babel-expand-src-block} during tangling. This has the effect of assigning values to variables -specified with @code{:var} (see @ref{var argument}), and of replacing ``noweb'' +specified with @code{:var} (see @ref{var}), and of replacing ``noweb'' references (see @ref{Noweb reference syntax}) with their targets. The @code{:no-expand} header argument can be used to turn off this behavior. -@node session argument, noweb argument, no-expand argument, Specific header arguments -@subsubsection session argument -Start a session for an interpreted language where state is preserved. This -applies particularly to the supported languages python, R and ruby. +@node session, noweb, no-expand, Specific header arguments +@subsubsection @code{:session} + +The @code{:session} header argument starts a session for an interpreted +language where state is preserved. This applies particularly to the +supported languages python, R and ruby. By default, a session is not started. @@ -11707,19 +11725,20 @@ A string passed to the @code{:session} header argument will give the session a name. This makes it possible to run concurrent sessions for each interpreted language. -@node noweb argument, cache argument, session argument, Specific header arguments -@subsubsection noweb argument -Controls the expansion of ``noweb'' style (see @ref{Noweb reference syntax}) -references in a source code block. This header argument can have one of two -values: @code{yes} or @code{no}. +@node noweb, cache, session, Specific header arguments +@subsubsection @code{:noweb} + +The @code{:noweb} header argument controls expansion of ``noweb'' style (see +@ref{Noweb reference syntax}) references in a code block. This header +argument can have one of two values: @code{yes} or @code{no}. @itemize @bullet @item @code{no} -the default. No ``noweb'' syntax specific action is taken on evaluating -source code blocks, However, noweb references will still be expanded during +The default. No ``noweb'' syntax specific action is taken on evaluating +code blocks, However, noweb references will still be expanded during tangling. @item @code{yes} -all ``noweb'' syntax references in the body of the source code block will be +All ``noweb'' syntax references in the body of the code block will be expanded before the block is evaluated. @end itemize @@ -11730,7 +11749,7 @@ This behavior is illustrated in the following example. Because the @code{<>} noweb reference appears behind the SQL comment syntax, each line of the expanded noweb reference will be commented. -This source code block: +This code block: @example -- <> @@ -11748,26 +11767,29 @@ Note that noweb replacement text that does not contain any newlines will not be affected by this change, so it is still possible to use inline noweb references. -@node cache argument, hlines argument, noweb argument, Specific header arguments -@subsubsection cache argument -Controls the use of in-buffer caching of source code block results to avoid -re-running unchanged source code blocks. This header argument can have one -of two values: @code{yes} or @code{no}. +@node cache, hlines, noweb, Specific header arguments +@subsubsection @code{:cache} + +The @code{:cache} header argument controls the use of in-buffer caching of +the results of evaluating code blocks. It can be used to avoid re-evaluating +unchanged code blocks. This header argument can have one of two +values: @code{yes} or @code{no}. @itemize @bullet @item @code{no} -The default. No caching takes place and the source code block will be run -every time it is evaluated. +The default. No caching takes place, and the code block will be evaluated +every time it is called. @item @code{yes} -every time the source code block is run a sha1 hash of the code and arguments +Every time the code block is run a sha1 hash of the code and arguments passed to the block will be generated. This hash is packed into the -@code{#+results:} line of the results and will be checked on subsequent -executions of the source code block. If the source code block has not +@code{#+results:} line and will be checked on subsequent +executions of the code block. If the code block has not changed since the last time it was evaluated, it will not be re-evaluated. @end itemize -@node hlines argument, colnames argument, cache argument, Specific header arguments -@subsubsection hlines argument +@node hlines, colnames, cache, Specific header arguments +@subsubsection @code{:hlines} + Tables are frequently represented with one or more horizontal lines, or hlines. The @code{:hlines} argument to a code block accepts the values @code{yes} or @code{no}, with a default value of @code{no}. @@ -11823,8 +11845,9 @@ Leaves hlines in the table. Setting @code{:hlines yes} has this effect. @end example @end itemize -@node colnames argument, rownames argument, hlines argument, Specific header arguments -@subsubsection colnames argument +@node colnames, rownames, hlines, Specific header arguments +@subsubsection @code{:colnames} + The @code{:colnames} header argument accepts the values @code{yes}, @code{no}, or @code{nil} for unassigned. The default value is @code{nil}. @@ -11863,8 +11886,9 @@ does not ``look like'' it has column names (i.e. the second row is not an hline) @end itemize -@node rownames argument, , colnames argument, Specific header arguments -@subsubsection rownames argument +@node rownames, , colnames, Specific header arguments +@subsubsection @code{:rownames} + The @code{:rownames} header argument can take on the values @code{yes} or @code{no}, with a default value of @code{no}. @@ -11892,8 +11916,11 @@ and is then reapplied to the results. @end example @end itemize -@node Results, Noweb reference syntax, Header arguments, Working With Source Code -@section Results +@node Results of evaluation, Noweb reference syntax, Header arguments, Working With Source Code +@section Results of evaluation +@cindex code block, results of evaluation +@cindex source code, results of evaluation + The way in which results are handled depends on whether a session is invoked, as well as on whether @code{:results value} or @code{:results output} is used. The following table shows the possibilities: @@ -11972,8 +11999,12 @@ But in @code{:session} mode, the interactive interpreter receives input '2' and prints out its value, '2'. (Indeed, the other print statements are unnecessary here). -@node Noweb reference syntax, Key bindings & useful functions, Results, Working With Source Code +@node Noweb reference syntax, Key bindings and useful functions, Results of evaluation, Working With Source Code @section Noweb reference syntax +@cindex code block, noweb reference +@cindex syntax, noweb +@cindex source code, noweb reference + The ``noweb'' (see @uref{http://www.cs.tufts.edu/~nr/noweb/}) Literate Programming system allows named blocks of code to be referenced by using the familiar Noweb syntax: @@ -11982,61 +12013,91 @@ familiar Noweb syntax: <> @end example -When a source code block is tangled or evaluated, whether or not ``noweb'' +When a code block is tangled or evaluated, whether or not ``noweb'' references are expanded depends upon the value of the @code{:noweb} header argument. If @code{:noweb yes}, then a Noweb reference is expanded before evaluation. If @code{:noweb no}, the default, then the reference is not expanded before evaluation. Note: the default value, @code{:noweb no}, was chosen to ensure that -Org-babel does not break correct code in a language, such as Ruby, where +correct code is not broken in a language, such as Ruby, where @code{<>} is a syntactically valid construct. If @code{<>} is not syntactically valid in languages that you use, then please consider setting the default value. -@node Key bindings & useful functions, Batch execution, Noweb reference syntax, Working With Source Code -@section Key bindings & useful functions +@node Key bindings and useful functions, Batch execution, Noweb reference syntax, Working With Source Code +@section Key bindings and useful functions +@cindex code block, key bindings Many common Org-mode key sequences are re-bound depending on -the context. Within a code block the following sequences -are rebound: +the context. + +Within a code block, the following key bindings +are active: @multitable @columnfractions 0.25 0.75 -@item @key{C-c C-c} @tab org-babel-execute-src-block -@item @key{C-c C-o} @tab org-babel-open-src-block-result -@item @key{C-up} @tab org-babel-load-in-session -@item @key{M-down} @tab org-babel-pop-to-session +@kindex C-c C-c +@item @kbd{C-c C-c} @tab org-babel-execute-src-block +@kindex C-c C-o +@item @kbd{C-c C-o} @tab org-babel-open-src-block-result +@kindex C-up +@item @kbd{C-@key{up}} @tab org-babel-load-in-session +@kindex M-down +@item @kbd{M-@key{down}} @tab org-babel-pop-to-session @end multitable -@multitable @columnfractions 0.25 0.75 -@item @key{C-c C-v a} @tab org-babel-sha1-hash -@item @key{C-c C-v b} @tab org-babel-execute-buffer -@item @key{C-c C-v f} @tab org-babel-tangle-file -@item @key{C-c C-v g} @tab org-babel-goto-named-source-block -@item @key{C-c C-v h} @tab org-babel-describe-bindings -@item @key{C-c C-v l} @tab org-babel-lob-ingest -@item @key{C-c C-v p} @tab org-babel-expand-src-block -@item @key{C-c C-v s} @tab org-babel-execute-subtree -@item @key{C-c C-v t} @tab org-babel-tangle -@item @key{C-c C-v z} @tab org-babel-switch-to-session +In an Org-mode buffer, the following key bindings are active: + +@multitable @columnfractions 0.45 0.55 +@kindex C-c C-v a +@kindex C-c C-v C-a +@item @kbd{C-c C-v a} @r{or} @kbd{C-c C-v C-a} @tab org-babel-sha1-hash +@kindex C-c C-v b +@kindex C-c C-v C-b +@item @kbd{C-c C-v b} @r{or} @kbd{C-c C-v C-b} @tab org-babel-execute-buffer +@kindex C-c C-v f +@kindex C-c C-v C-f +@item @kbd{C-c C-v f} @r{or} @kbd{C-c C-v C-f} @tab org-babel-tangle-file +@kindex C-c C-v g +@item @kbd{C-c C-v g} @tab org-babel-goto-named-source-block +@kindex C-c C-v h +@item @kbd{C-c C-v h} @tab org-babel-describe-bindings +@kindex C-c C-v l +@kindex C-c C-v C-l +@item @kbd{C-c C-v l} @r{or} @kbd{C-c C-v C-l} @tab org-babel-lob-ingest +@kindex C-c C-v p +@kindex C-c C-v C-p +@item @kbd{C-c C-v p} @r{or} @kbd{C-c C-v C-p} @tab org-babel-expand-src-block +@kindex C-c C-v s +@kindex C-c C-v C-s +@item @kbd{C-c C-v s} @r{or} @kbd{C-c C-v C-s} @tab org-babel-execute-subtree +@kindex C-c C-v t +@kindex C-c C-v C-t +@item @kbd{C-c C-v t} @r{or} @kbd{C-c C-v C-t} @tab org-babel-tangle +@kindex C-c C-v z +@kindex C-c C-v C-z +@item @kbd{C-c C-v z} @r{or} @kbd{C-c C-v C-z} @tab org-babel-switch-to-session @end multitable -When possible these keybindings were extended to work when the control key is -kept pressed, resulting in the following additional keybindings. +@c When possible these keybindings were extended to work when the control key is +@c kept pressed, resulting in the following additional keybindings. -@multitable @columnfractions 0.25 0.75 -@item @key{C-c C-v C-a} @tab org-babel-sha1-hash -@item @key{C-c C-v C-b} @tab org-babel-execute-buffer -@item @key{C-c C-v C-f} @tab org-babel-tangle-file -@item @key{C-c C-v C-l} @tab org-babel-lob-ingest -@item @key{C-c C-v C-p} @tab org-babel-expand-src-block -@item @key{C-c C-v C-s} @tab org-babel-execute-subtree -@item @key{C-c C-v C-t} @tab org-babel-tangle -@item @key{C-c C-v C-z} @tab org-babel-switch-to-session -@end multitable +@c @multitable @columnfractions 0.25 0.75 +@c @item @kbd{C-c C-v C-a} @tab org-babel-sha1-hash +@c @item @kbd{C-c C-v C-b} @tab org-babel-execute-buffer +@c @item @kbd{C-c C-v C-f} @tab org-babel-tangle-file +@c @item @kbd{C-c C-v C-l} @tab org-babel-lob-ingest +@c @item @kbd{C-c C-v C-p} @tab org-babel-expand-src-block +@c @item @kbd{C-c C-v C-s} @tab org-babel-execute-subtree +@c @item @kbd{C-c C-v C-t} @tab org-babel-tangle +@c @item @kbd{C-c C-v C-z} @tab org-babel-switch-to-session +@c @end multitable -@node Batch execution, , Key bindings & useful functions, Working With Source Code +@node Batch execution, , Key bindings and useful functions, Working With Source Code @section Batch execution +@cindex code block, batch execution +@cindex source code, batch execution + It is possible to call functions from the command line. This shell script calls @code{org-babel-tangle} on every one of its arguments. @@ -12046,7 +12107,7 @@ Be sure to adjust the paths to fit your system. #!/bin/sh # -*- mode: shell-script -*- # -# tangle a file with org-babel +# tangle a file with org-mode # DIR=`pwd` FILES="" From eae7ccd5b0e16014bd77e7d042fc28efb5c2f5c7 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Fri, 25 Jun 2010 09:51:57 +0200 Subject: [PATCH 114/138] Augment the acknowledgements to reflect the addition of Org Babel --- doc/org.texi | 93 ++++++++++++++++++++++++++++------------------------ 1 file changed, 50 insertions(+), 43 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 775648060..f8270fc0f 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -77,6 +77,7 @@ license to the document, as described in section 6 of the license. @subtitle Release @value{VERSION} @author by Carsten Dominik +with contributions by David O'Toole, Dan Davison, Eric Schulte and Thomas Dye @c The following two commands start the copyright page. @page @@ -13992,27 +13993,21 @@ the view, only the current agenda files will be searched. @cindex history @cindex thanks -Org was born in 2003, out of frustration over the user interface -of the Emacs Outline mode. I was trying to organize my notes and -projects, and using Emacs seemed to be the natural way to go. However, -having to remember eleven different commands with two or three keys per -command, only to hide and show parts of the outline tree, that seemed -entirely unacceptable to me. Also, when using outlines to take notes, I -constantly wanted to restructure the tree, organizing it parallel to my -thoughts and plans. @emph{Visibility cycling} and @emph{structure -editing} were originally implemented in the package -@file{outline-magic.el}, but quickly moved to the more general -@file{org.el}. As this environment became comfortable for project -planning, the next step was adding @emph{TODO entries}, basic -@emph{timestamps}, and @emph{table support}. These areas highlighted the two main -goals that Org still has today: to be a new, outline-based, -plain text mode with innovative and intuitive editing features, and to -incorporate project planning functionality directly into a notes file. - -A special thanks goes to @i{Bastien Guerry} who has not only written a large -number of extensions to Org (most of them integrated into the core by now), -but who has also helped in the development and maintenance of Org so much that he -should be considered the main co-contributor to this package. +Org was born in 2003, out of frustration over the user interface of the Emacs +Outline mode. I was trying to organize my notes and projects, and using +Emacs seemed to be the natural way to go. However, having to remember eleven +different commands with two or three keys per command, only to hide and show +parts of the outline tree, that seemed entirely unacceptable to me. Also, +when using outlines to take notes, I constantly wanted to restructure the +tree, organizing it parallel to my thoughts and plans. @emph{Visibility +cycling} and @emph{structure editing} were originally implemented in the +package @file{outline-magic.el}, but quickly moved to the more general +@file{org.el}. As this environment became comfortable for project planning, +the next step was adding @emph{TODO entries}, basic @emph{timestamps}, and +@emph{table support}. These areas highlighted the two main goals that Org +still has today: to be a new, outline-based, plain text mode with innovative +and intuitive editing features, and to incorporate project planning +functionality directly into a notes file. Since the first release, literally thousands of emails to me or to @email{emacs-orgmode@@gnu.org} have provided a constant stream of bug @@ -14023,6 +14018,38 @@ in shaping one or more aspects of Org. The list may not be complete, if I have forgotten someone, please accept my apologies and let me know. +Before I get to this list, a few special mentions are in order: + +@table @i +@item Bastien Guerry +Bastien has written a large number of extensions to Org (most of them +integrated into the core by now), including the LaTeX exporter and the plain +list parser. More importantly, maybe, was his help and support when Org got +first started, he was very important during this phase. Also, he invented +Worg, helped establishing the Web presence of Org, and sponsors hosting costs +for the orgmode.org website. +@item Eric Schulte and Dan Davison +Eric and Dan are jointly responsible for the Org-babel system, which turns +Org into a multi-language environment for evaluating code and doing literate +programming and reproducible research. +@item John Wiegley +John has also contributed a number of great ideas and patches +directly to Org, including the attachment system (@file{org-attach.el}), +integration with Apple Mail (@file{org-mac-message.el}), hierarchical +dependencies of TODO items, habit tracking (@file{org-habits.el}), and +encryption (@file{org-crypt.el}). Also, the capture system is really an +extended copy of his great @file{remember.el}. +@item Sebastian Rose +Without Sebastian, the HTML/XHTML publishing of Org would be the pitiful work +of an ignorant amateur. Sebastian has pushed this part of Org onto a much +higher level. He also wrote @file{org-info.js}, a Java script for displaying +webpages derived from Org using an Info-like or a folding interface with +single-key navigation. +@end table + +@noindent OK, now to the full list of contributions! Again, please let me +know what I am missing here! + @itemize @bullet @item @@ -14055,8 +14082,6 @@ calculations and improved XEmacs compatibility, in particular by porting @item @i{Baoqiu Cui} contributed the DocBook exporter. @item -@i{Dan Davison} wrote (together with @i{Eric Schulte}) Org Babel. -@item @i{Eddward DeVilla} proposed and tested checkbox statistics. He also came up with the idea of properties, and that there should be an API for them. @@ -14066,6 +14091,8 @@ them. @i{Kees Dullemond} used to edit projects lists directly in HTML and so inspired some of the early development, including HTML export. He also asked for a way to narrow wide table columns. +@i{Thomas S. Dye} contributed documentation on Worg and helped integrating +the Org-Babel documentation into the manual. @item @i{Christian Egli} converted the documentation into Texinfo format, patched CSS formatting into the HTML exporter, and inspired the agenda. @@ -14088,9 +14115,6 @@ around a match in a hidden outline tree. @item @i{Niels Giesen} had the idea to automatically archive DONE trees. @item -@i{Bastien Guerry} wrote the La@TeX{} exporter and @file{org-bibtex.el}, and -has been prolific with patches, ideas, and bug reports. -@item @i{Kai Grossjohann} pointed out key-binding conflicts with other packages. @item @i{Bernt Hansen} has driven much of the support for auto-repeating tasks, @@ -14164,10 +14188,6 @@ also acted as mailing list moderator for some time. @item @i{Kevin Rogers} contributed code to access VM files on remote hosts. @item -@i{Sebastian Rose} wrote @file{org-info.js}, a Java script for displaying -webpages derived from Org using an Info-like or a folding interface with -single-key navigation, and make lots of improvements to the HTML exporter. -@item @i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a conflict with @file{allout.el}. @item @@ -14180,9 +14200,6 @@ of feedback, developed and applied standards to the Org documentation. @i{Christian Schlauer} proposed angular brackets around links, among other things. @item -@i{Eric Schulte} wrote @file{org-plot.el} and (together with @i{Dan Davison}) -Org Babel, and contributed various patches, small features and modules. -@item @i{Paul Sexton} wrote @file{org-ctags.el}. @item Linking to VM/BBDB/Gnus was first inspired by @i{Tom Shannon}'s @@ -14229,16 +14246,6 @@ keyword. @i{David Wainberg} suggested archiving, and improvements to the linking system. @item -@i{John Wiegley} wrote @file{emacs-wiki.el}, @file{planner.el}, and -@file{muse.el}, which have some overlap with Org. Initially the development -of Org was fully independent because I was not aware of the existence of -these packages. But with time I have occasionally looked at John's code and -learned a lot from it. John has also contributed a number of great ideas and -patches directly to Org, including the attachment system -(@file{org-attach.el}), integration with Apple Mail -(@file{org-mac-message.el}), hierarchical dependencies of TODO items, habit -tracking (@file{org-habits.el}). -@item @i{Carsten Wimmer} suggested some changes and helped fix a bug in linking to Gnus. @item From 7f21f76d5efe1a54e62b4baa115675d4bd08e0b5 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Fri, 25 Jun 2010 10:01:23 +0200 Subject: [PATCH 115/138] fix typo --- lisp/org-table.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lisp/org-table.el b/lisp/org-table.el index 46efc28e6..f6b77aa08 100644 --- a/lisp/org-table.el +++ b/lisp/org-table.el @@ -4226,7 +4226,7 @@ this function is called." (orgtbl-to-generic table (org-combine-plists params2 params)))) (defun orgtbl-to-html (table params) - "Convert the orgtbl-mode TABLE to LaTeX. + "Convert the orgtbl-mode TABLE to HTML. TABLE is a list, each entry either the symbol `hline' for a horizontal separator line, or a list of fields for that line. PARAMS is a property list of parameters that can influence the conversion. From 8f83ac51ee6b4be9ecdaebabdcc693d6a414ed85 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Fri, 25 Jun 2010 16:40:47 +0200 Subject: [PATCH 116/138] Add documentation for capture --- doc/org.texi | 453 +++++++++++++++++++++++++++------------------------ 1 file changed, 242 insertions(+), 211 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index f8270fc0f..b4696a55c 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -251,18 +251,23 @@ Deadlines and scheduling Capture - Refile - Archive -* Remember:: Capture new tasks/ideas with little interruption -* Attachments:: Add files to tasks. +* Capture:: Capturing new stuff +* Attachments:: Add files to tasks * RSS Feeds:: Getting input from RSS feeds * Protocols:: External (e.g. Browser) access to Emacs and Org * Refiling notes:: Moving a tree from one place to another * Archiving:: What to do with finished projects -Remember +Capture -* Setting up Remember for Org:: Some code for .emacs to get things going -* Remember templates:: Define the outline of different note types -* Storing notes:: Directly get the note to where it belongs +* Setting up a capture location:: Where notes will be stored +* Using capture:: Commands to invoke and terminate capture +* Capture templates:: Define the outline of different note types + +Capture templates + +* Template elements:: What is needed for a complete template entry +* Template expansion:: Filling in information about time and context Archiving @@ -4373,26 +4378,6 @@ C-c}). If you set the variable to the value @code{expert}, the special window is not even shown for single-key tag selection, it comes up only when you press an extra @kbd{C-c}. -@vindex org-complete-tags-always-offer-all-agenda-tags -As said before, when setting tags and @code{org-tag-alist} is nil, then the -list of tags in the current buffer is used. Normally, this behavior is very -convenient, except in org remember buffers (@pxref{Remember}), because there -are no tags that can be calculated dynamically. Here, you most probably want -to have completion for all tags in all agenda files. This can be done by -setting @code{org-complete-tags-always-offer-all-agenda-tags} to non-nil in -those buffers. - -@lisp -(add-hook 'org-remember-mode-hook - (lambda () - (set (make-local-variable - 'org-complete-tags-always-offer-all-agenda-tags) - t))) -@end lisp - -Of course, you can also set it to @code{t} globally if you always want to -have completion of all tags in all agenda files. - @node Tag searches, , Setting tags, Tags @section Tag searches @cindex tag searches @@ -5898,155 +5883,268 @@ not started at exactly the right moment. An important part of any organization system is the ability to quickly capture new ideas and tasks, and to associate reference material with them. -Org uses the @file{remember.el} package to create tasks, and stores files +Org does this using a process called @i{capture}. It also can store files related to a task (@i{attachments}) in a special directory. Once in the system, tasks and projects need to be moved around. Moving completed project trees to an archive file keeps the system compact and fast. @menu -* Remember:: Capture new tasks/ideas with little interruption -* Attachments:: Add files to tasks. +* Capture:: Capturing new stuff +* Attachments:: Add files to tasks * RSS Feeds:: Getting input from RSS feeds * Protocols:: External (e.g. Browser) access to Emacs and Org * Refiling notes:: Moving a tree from one place to another * Archiving:: What to do with finished projects @end menu -@node Remember, Attachments, Capture - Refile - Archive, Capture - Refile - Archive -@section Remember -@cindex @file{remember.el} +@node Capture, Attachments, Capture - Refile - Archive, Capture - Refile - Archive +@section Capture +@cindex capture -The Remember package by John Wiegley lets you store quick notes with little -interruption of your work flow. It is an excellent way to add new notes and -tasks to Org files. The @code{remember.el} package is part of Emacs 23, not -Emacs 22. See @uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for -more information. - -Org significantly expands the possibilities of Remember: you may define -templates for different note types, and associate target files and headlines -with specific templates. It also allows you to select the location where a -note should be stored interactively, on the fly. +Org's method for capturing new items is heavily inspired by John Wiegley +excellent remember package@footnote{Up to version 6.36 Org actually did use a +special setup for @file{remember.el}. @file{org-remember.el} is still part +of Org-mode for backward compatibility with existing setups. But the new +capturing setup described here is preferred and should be used by new users.} +which lets you store quick notes with little interruption of your work flow. +The basic process of capturing is very similar to remember, but Org does +enhance it with templates and more. @menu -* Setting up Remember for Org:: Some code for .emacs to get things going -* Remember templates:: Define the outline of different note types -* Storing notes:: Directly get the note to where it belongs +* Setting up a capture location:: Where notes will be stored +* Using capture:: Commands to invoke and terminate capture +* Capture templates:: Define the outline of different note types @end menu -@node Setting up Remember for Org, Remember templates, Remember, Remember -@subsection Setting up Remember for Org +@node Setting up a capture location, Using capture, Capture, Capture +@subsection Setting up a capture location -The following customization will tell Remember to use Org files as -target, and to create annotations compatible with Org links. +The following customization sets a default target@footnote{Using capture +templates, you can define more fine-grained capture locations, see +@ref{Capture templates}.} file for notes, and defines a global +key@footnote{Please select your own key, @kbd{C-c c} is only a suggestion.} +for capturing new stuff. @example -(org-remember-insinuate) -(setq org-directory "~/path/to/my/orgfiles/") (setq org-default-notes-file (concat org-directory "/notes.org")) -(define-key global-map "\C-cr" 'org-remember) +(define-key global-map "\C-cc" 'org-capture) @end example -@noindent -The last line binds the command @code{org-remember} to a global -key@footnote{Please select your own key, @kbd{C-c r} is only a -suggestion.}. @code{org-remember} basically just calls Remember, -but it makes a few things easier: if there is an active region, it will -automatically copy the region into the Remember buffer. It also allows -to jump to the buffer and location where Remember notes are being -stored: just call @code{org-remember} with a prefix argument. If you -use two prefix arguments, Org jumps to the location where the last -remember note was stored. +@node Using capture, Capture templates, Setting up a capture location, Capture +@subsection Using capture -The Remember buffer will actually use @code{org-mode} as its major mode, so -that all editing features of Org mode are available. In addition to this, a -minor mode @code{org-remember-mode} is turned on, for the single purpose that -you can use its keymap @code{org-remember-mode-map} to override some of -Org mode's key bindings. +@table @kbd +@kindex C-c c +@item C-c c +Call the command @code{org-capture}. If you have templates defined +@pxref{Capture templates}, it will offer these templates for selection or use +a new Org outline node as the default template. It will insert the template +into the target file and switch to an indirect buffer narrowed to this new +node. You may then insert the information you want. -You can also call @code{org-remember} in a special way from the agenda, -using the @kbd{k r} key combination. With this access, any timestamps -inserted by the selected Remember template (see below) will default to +@kindex C-c C-c +@item C-c C-c +Once you are done entering information into the capture buffer, +@kbd{C-c C-c} will return you to the window configuration before the capture +process, so that you can resume your work without further distraction. + +@kindex C-c C-w +@item C-c C-w +When this command is used in the capture buffer, it will finalize the capture +process by refiling (@pxref{Refiling notes}) the note to a different place. + +@kindex C-c C-k +@item C-c C-k +Abort the capture process and return to the previous state. +@end table + +You can also call @code{org-capture} in a special way from the agenda, +using the @kbd{k c} key combination. With this access, any timestamps +inserted by the selected capture template (see below) will default to the cursor date in the agenda, rather than to the current date. -@node Remember templates, Storing notes, Setting up Remember for Org, Remember -@subsection Remember templates -@cindex templates, for Remember +@node Capture templates, , Using capture, Capture +@subsection Capture templates +@cindex templates, for Capture -In combination with Org, you can use templates to generate -different types of Remember notes. For example, if you would like -to use one template to create general TODO entries, another one for -journal entries, and a third one for collecting random ideas, you could -use: +You can use templates to arrange for different types of capture items, and +for different target locations. The easiest way to set up such templates is +through the customize interface. + +@table @kbd +@kindex C-c c C +@item C-c c C +Customize the variable @code{org-capture-templates}. +@end table + +Before we give the formal description of template definitions, let's look at +an example. Say you would like to use one template to create general TODO +entries, and you want to put these entries under the heading @samp{Tasks} in +your file @file{~/org/gtd.org}. Also, a date tree in the file +@file{journal.org} should capture journal entries. A possible configuration +would then look like this: @example -(setq org-remember-templates - '(("Todo" ?t "* TODO %?\n %i\n %a" "~/org/TODO.org" "Tasks") - ("Journal" ?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org") - ("Idea" ?i "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas"))) +(setq org-capture-templates + '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks") + "* TODO %?\n %i\n %a") + ("j" "Journal" entry (file+datetree "~/org/journal.org") + "* %?\nEntered on %U\n %i\n %a"))) @end example -@vindex org-remember-default-headline -@vindex org-directory -@noindent In these entries, the first string is just a name, and the -character specifies how to select the template. It is useful if the -character is also the first letter of the name. The next string specifies -the template. Two more (optional) strings give the file in which, and the -headline under which, the new note should be stored. The file (if not -present or @code{nil}) defaults to @code{org-default-notes-file}, the heading -to @code{org-remember-default-headline}. If the file name is not an absolute -path, it will be interpreted relative to @code{org-directory}. - -The heading can also be the symbols @code{top} or @code{bottom} to send notes -as level 1 entries to the beginning or end of the file, respectively. It may -also be the symbol @code{date-tree}. Then, a tree with year on level 1, -month on level 2 and day on level three will be built in the file, and the -entry will be filed into the tree under the current date@footnote{If the file -contains an entry with a @code{DATE_TREE} property (arbitrary value), the -entire date tree will be built under that entry.} - -An optional sixth element specifies the contexts in which the user can select -the template. This element can be a list of major modes or a function. -@code{org-remember} will first check whether the function returns @code{t} or -if we are in any of the listed major modes, and exclude templates for which -this condition is not fulfilled. Templates that do not specify this element -at all, or that use @code{nil} or @code{t} as a value will always be -selectable. - -So for example: - -@example -(setq org-remember-templates - '(("Bug" ?b "* BUG %?\n %i\n %a" "~/org/BUGS.org" "Bugs" (emacs-lisp-mode)) - ("Journal" ?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org" "X" my-check) - ("Idea" ?i "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas"))) -@end example - -@noindent -The first template will only be available when invoking @code{org-remember} -from a buffer in @code{emacs-lisp-mode}. The second template will only be -available when the function @code{my-check} returns @code{t}. The third -template will be proposed in any context. - -When you call @kbd{M-x org-remember} (or @kbd{M-x remember}) to remember -something, Org will prompt for a key to select the template (if you have -more than one template) and then prepare the buffer like +@noindent If you then press @kbd{C-c c t}, Org will prepare the template +for you like this: @example * TODO - [[file:@var{link to where you called remember}]] + [[file:@var{link to where you initiated capture}]] @end example @noindent -During expansion of the template, special @kbd{%}-escapes@footnote{If you -need one of these sequences literally, escape the @kbd{%} with a backslash.} -allow dynamic insertion of content: +During expansion of the template, @code{%a} has been replaced by a link to +the location from where you called the capture command. This can be +extremely useful for deriving tasks from emails, for example. You fill in +the task definition, press @code{C-c C-c} and Org puts you back into the same +place where you started the capture process. + + +@menu +* Template elements:: What is needed for a complete template entry +* Template expansion:: Filling in information about time and context +@end menu + +@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 +@code{org-capture-templates} is a list with the following items: + +@table @var +@item keys +The keys that will select the template, as a string, characters +only, for example @code{"a"} for a template to be selected with a +single key, or @code{"bt"} for selection with two keys. When using +several keys, keys using the same prefix key must be sequential +in the list and preceded by a 2-element entry explaining the +prefix key, for example @example + ("b" "Templates for marking stuff to buy") +@end example +@noindent If you do not define a template for the @kbd{C} key, this key will +be used to open the customize buffer for this complex variable. + +@item description +A short string describing the template, which will be shown during +selection. + +@item type +The type of entry, a symbol. Valid values are: +@table @code +@item entry +An Org-mode node, with a headline. Will be filed as the child of the +target entry or as a top-level entry. The target file should be an Org-mode +file. +@item item +A plain list item, placed in the first plain list a the target +location. Again the target file should be an Org file. +@item checkitem +A checkbox item. This only differs from the plain lis item by the +default template. +@item table-line +a new line in the first table at target location. Where exactly the +line will be inserted depends on the properties @code{:prepend} and +@code{:table-line-pos} (see below) +@item plain +Text to be inserted as it is. +@end table + +@item target +Specification of where the captured item should be placed. +In Org-mode files, targets usually define a node. Entries will become +children of this node, other types will be added to the table or list in the +body of this node. + +Valid values are: +@table @code +@item (file "path/to/file") +Text will be placed at the beginning or end of that file + +@item (id "id of existing org entry") +Filing as child of this entry, or in the body of the entry + +@item (file+headline "path/to/file" "node headline") +Fast configuration if the target heading is unique in the file + +@item (file+olp "path/to/file" "Level 1 heading" "Level 2" ...) +For non-unique headings, the full path is safer. + +@item (file+regexp "path/to/file" "regexp to find location") + +@item (file+datetree "path/to/file") +Will create a heading in a date tree. + +@item (file+function "path/to/file" function-finding-location) +A function to find the right location in the file. + +@item (clock) +File to the entry that is currently being clocked. + +@item (function function-finding-location) +Most general way, write your own function to find both +file and location. +@end table + +@item template +The template for creating the capture item. If you leave this +empty, an appropriate default template will be used. Otherwise this is a +string with a number of escape code, which will be replaced depending on time +and context of the capture call. See below for more details. + +@item properties +The rest of the entry is a property list of additional options. +Recognized properties are: +@table @code +@item :prepend +Normally new captured information will be appended at +the target location (last child, last table line, last list item...). +Setting this property will change that. + +@item :immediate-finish +When set, do not offer to edit the information, just +file it away immediately. This makes sense if the template only needs +information that can be added automatically. + +@item :empty-lines +Set this to the number of lines the should be inserted +before and after the new item. Default 0, only common other value is 1. + +@item :clock-in +Start the clock in this item. + +@item :clock-resume +If Starting the capture interrupted a clock, restart that clock when done +with the capture. + +@item :unnarrowed +Do not narrow the target buffer, simply show the full buffer. Default is to +narrow it so that you only see the new stuff. +@end table +@end table + +@node Template expansion, , Template elements, Capture templates +@subsubsection Template expansion + +In the template itself, special @kbd{%}-escapes@footnote{If you need one of +these sequences literally, escape the @kbd{%} with a backslash.} allow +dynamic insertion of content: +@smallexample %^@{@var{prompt}@} @r{prompt the user for a string and replace this sequence with it.} @r{You may specify a default value and a completion table with} @r{%^@{prompt|default|completion2|completion3...@}} @r{The arrow keys access a prompt-specific history.} %a @r{annotation, normally the link created with @code{org-store-link}} %A @r{like @code{%a}, but prompt for the description part} -%i @r{initial content, the region when remember is called with C-u.} +%i @r{initial content, the region when capture is called while the} + @r{region is active.} @r{The entire text will be indented like @code{%i} itself.} %t @r{timestamp, date only} %T @r{timestamp with date and time} @@ -6069,17 +6167,17 @@ allow dynamic insertion of content: %! @r{immediately store note after completing the template} @r{(skipping the @kbd{C-c C-c} that normally triggers storing)} %& @r{jump to target location immediately after storing note} -@end example +@end smallexample @noindent For specific link types, the following keywords will be defined@footnote{If you define your own link types (@pxref{Adding hyperlink types}), any property you store with -@code{org-store-link-props} can be accessed in remember templates in a +@code{org-store-link-props} can be accessed in capture templates in a similar way.}: @vindex org-from-is-user-regexp -@example +@smallexample Link type | Available keywords -------------------+---------------------------------------------- bbdb | %:name %:company @@ -6092,83 +6190,17 @@ gnus | %:group, @r{for messages also all email fields} w3, w3m | %:url info | %:file %:node calendar | %:date" -@end example +@end smallexample @noindent To place the cursor after template expansion use: -@example +@smallexample %? @r{After completing the template, position cursor here.} -@end example - -@noindent -If you change your mind about which template to use, call -@code{org-remember} in the remember buffer. You may then select a new -template that will be filled with the previous context information. - -@node Storing notes, , Remember templates, Remember -@subsection Storing notes - -@vindex org-remember-clock-out-on-exit -When you are finished preparing a note with Remember, you have to press -@kbd{C-c C-c} to file the note away. If you have started the clock in the -Remember buffer, you will first be asked if you want to clock out -now@footnote{To avoid this query, configure the variable -@code{org-remember-clock-out-on-exit}.}. If you answer @kbd{n}, the clock -will continue to run after the note was filed away. - -The handler will then store the note in the file and under the headline -specified in the template, or it will use the default file and headline. The -window configuration will be restored, sending you back to the working -context before the call to Remember. To re-use the location found during the -last call to Remember, exit the Remember buffer with @kbd{C-0 C-c C-c}, -i.e. specify a zero prefix argument to @kbd{C-c C-c}. Another special case -is @kbd{C-2 C-c C-c} which files the note as a child of the currently clocked -item, and @kbd{C-3 C-c C-c} files as a sibling of the currently clocked item. - -@vindex org-remember-store-without-prompt -If you want to store the note directly to a different place, use -@kbd{C-1 C-c C-c} instead to exit Remember@footnote{Configure the -variable @code{org-remember-store-without-prompt} to make this behavior -the default.}. The handler will then first prompt for a target file---if -you press @key{RET}, the value specified for the template is used. -Then the command offers the headings tree of the selected file, with the -cursor position at the default headline (if you specified one in the -template). You can either immediately press @key{RET} to get the note -placed there. Or you can use the following keys to find a different -location: -@example -@key{TAB} @r{Cycle visibility.} -@key{down} / @key{up} @r{Next/previous visible headline.} -n / p @r{Next/previous visible headline.} -f / b @r{Next/previous headline same level.} -u @r{One level up.} -@c 0-9 @r{Digit argument.} -@end example -@noindent -Pressing @key{RET} or @key{left} or @key{right} -then leads to the following result. - -@vindex org-reverse-note-order -@multitable @columnfractions 0.2 0.15 0.65 -@item @b{Cursor position} @tab @b{Key} @tab @b{Note gets inserted} -@item on headline @tab @key{RET} @tab as sublevel of the heading at cursor, first or last -@item @tab @tab depending on @code{org-reverse-note-order}. -@item @tab @key{left}/@key{right} @tab as same level, before/after current heading -@item buffer-start @tab @key{RET} @tab as level 2 heading at end of file or level 1 at beginning -@item @tab @tab depending on @code{org-reverse-note-order}. -@item not on headline @tab @key{RET} - @tab at cursor position, level taken from context. -@end multitable - -Before inserting the text into a tree, the function ensures that the text has -a headline, i.e. a first line that starts with a @samp{*}. If not, a -headline is constructed from the current date. If you have indented the text -of the note below the headline, the indentation will be adapted if inserting -the note into the tree requires demotion from level 1. +@end smallexample -@node Attachments, RSS Feeds, Remember, Capture - Refile - Archive +@node Attachments, RSS Feeds, Capture, Capture - Refile - Archive @section Attachments @cindex attachments @@ -6320,7 +6352,7 @@ For more information, see @file{org-feed.el} and the docstring of You can set up Org for handling protocol calls from outside applications that are passed to Emacs through the @file{emacsserver}. For example, you can configure bookmarks in your web browser to send a link to the current page to -Org and create a note from it using Remember (@pxref{Remember}). Or you +Org and create a note from it using capture (@pxref{Capture}). Or you could create a bookmark that will tell Emacs to open the local source file of a remote website you are looking at with the browser. See @uref{http://orgmode.org/worg/org-contrib/org-protocol.php} for detailed @@ -7742,7 +7774,7 @@ m @r{Mark the entry at point for action. You can also make entries} @r{in Org files with @kbd{C-c C-x C-k}.} d @r{Set the deadline of the marked entry to the date at point.} s @r{Schedule the marked entry at the date at point.} -r @r{Call @code{org-remember} with the cursor date as default date.} +r @r{Call @code{org-capture} with the cursor date as default date.} @end example @noindent Press @kbd{r} afterward to refresh the agenda and see the effect of the @@ -12518,7 +12550,7 @@ works even if the automatic table editor has been turned off. If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to the entire table. @item -If the current buffer is a Remember buffer, close the note and file it. +If the current buffer is a capture buffer, close the note and file it. With a prefix argument, file it, without further interaction, to the default location. @item @@ -12766,8 +12798,7 @@ the option @code{org-imenu-depth}. @item @file{remember.el} by John Wiegley @cindex @file{remember.el} @cindex Wiegley, John -Org cooperates with remember, see @ref{Remember}. -As of Emacs 23, @file{Remember.el} is part of the Emacs distribution. +Org used to use this package for capture, but no longer does. @item @file{speedbar.el} by Eric M. Ludlam @cindex @file{speedbar.el} @cindex Ludlam, Eric M. @@ -14069,7 +14100,7 @@ Org-mode website. @i{Tom Breton} wrote @file{org-choose.el}. @item @i{Charles Cave}'s suggestion sparked the implementation of templates -for Remember. +for Remember, which are now templates for capture. @item @i{Pavel Chalmoviansky} influenced the agenda treatment of items with specified time. From 9bf78c7db463a583efb27f5c0e80b70bd1605b88 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Fri, 25 Jun 2010 17:32:29 +0200 Subject: [PATCH 117/138] Point to a PDF copy of the old org-remember documentation --- doc/org.texi | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/org.texi b/doc/org.texi index b4696a55c..5a417747a 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -5905,7 +5905,9 @@ Org's method for capturing new items is heavily inspired by John Wiegley excellent remember package@footnote{Up to version 6.36 Org actually did use a special setup for @file{remember.el}. @file{org-remember.el} is still part of Org-mode for backward compatibility with existing setups. But the new -capturing setup described here is preferred and should be used by new users.} +capturing setup described here is preferred and should be used by new users. +You can find the documentation for org-remember at +@url{http://orgmode.org/org-remember.pdf}.} which lets you store quick notes with little interruption of your work flow. The basic process of capturing is very similar to remember, but Org does enhance it with templates and more. From 808115a4cf65a655f9091695116e6c441e9758b8 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Fri, 25 Jun 2010 17:54:48 +0200 Subject: [PATCH 118/138] Document org-capture in the guide --- doc/orgguide.texi | 142 +++++++++++++++++++++------------------------- 1 file changed, 65 insertions(+), 77 deletions(-) diff --git a/doc/orgguide.texi b/doc/orgguide.texi index b2f132bc7..fd999a8a2 100644 --- a/doc/orgguide.texi +++ b/doc/orgguide.texi @@ -169,15 +169,15 @@ Dates and Times Capture - Refile - Archive -* Remember:: Capture new tasks/ideas with little interruption +* Capture:: * Refiling notes:: Moving a tree from one place to another * Archiving:: What to do with finished projects -Remember +Capture -* Setting up Remember for Org:: Some code for .emacs to get things going -* Remember templates:: Define the outline of different note types -* Storing notes:: Directly get the note to where it belongs +* Setting up a capture location:: Where notes will be stored +* Using capture:: Commands to invoke and terminate capture +* Capture templates:: Define the outline of different note types Agenda Views @@ -1525,89 +1525,90 @@ Cave's Date and Time tutorial}@* An important part of any organization system is the ability to quickly capture new ideas and tasks, and to associate reference material with them. -Org uses the @file{remember.el} package to create tasks, and stores files -related to a task (@i{attachments}) in a special directory. Once in the -system, tasks and projects need to be moved around. Moving completed project -trees to an archive file keeps the system compact and fast. +Org defines a capture process to create tasks. It stores files related to a +task (@i{attachments}) in a special directory. Once in the system, tasks and +projects need to be moved around. Moving completed project trees to an +archive file keeps the system compact and fast. @menu -* Remember:: Capture new tasks/ideas with little interruption +* Capture:: * Refiling notes:: Moving a tree from one place to another * Archiving:: What to do with finished projects @end menu -@node Remember, Refiling notes, Capture - Refile - Archive, Capture - Refile - Archive -@section Remember +@node Capture, Refiling notes, Capture - Refile - Archive, Capture - Refile - Archive +@section Capture -The Remember package by John Wiegley lets you store quick notes with little -interruption of your work flow. It is an excellent way to add new notes and -tasks to Org files. The @code{remember.el} package is part of Emacs 23, not -Emacs 22. See @uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for -more information. - -Org significantly expands the possibilities of Remember: you may define -templates for different note types, and associate target files and headlines -with specific templates. It also allows you to select the location where a -note should be stored interactively, on the fly. +Org's method for capturing new items is heavily inspired by John Wiegley +excellent remember package. It lets you store quick notes with little +interruption of your work flow. Org lets you define templates for new +entries and associate them with different targets for storing notes. @menu -* Setting up Remember for Org:: Some code for .emacs to get things going -* Remember templates:: Define the outline of different note types -* Storing notes:: Directly get the note to where it belongs +* Setting up a capture location:: Where notes will be stored +* Using capture:: Commands to invoke and terminate capture +* Capture templates:: Define the outline of different note types @end menu -@node Setting up Remember for Org, Remember templates, Remember, Remember -@unnumberedsubsec Setting up Remember for Org +@node Setting up a capture location, Using capture, Capture, Capture +@unnumberedsubsec Setting up a capture location -The following customization will tell Remember to use Org files as -target, and to create annotations compatible with Org links. +The following customization sets a default target@footnote{Using capture +templates, you can define more fine-grained capture locations, see +@ref{Capture templates}.} file for notes, and defines a global +key@footnote{Please select your own key, @kbd{C-c c} is only a suggestion.} +for capturing new stuff. -@smallexample -(org-remember-insinuate) -(setq org-directory "~/path/to/my/orgfiles/") +@example (setq org-default-notes-file (concat org-directory "/notes.org")) -(define-key global-map "\C-cr" 'org-remember) -@end smallexample +(define-key global-map "\C-cc" 'org-capture) +@end example -@noindent -The last line binds the command @code{org-remember} to a global -key@footnote{Please select your own key, @kbd{C-c r} is only a -suggestion.}. @code{org-remember} basically just calls Remember, -but it makes a few things easier: if there is an active region, it will -automatically copy the region into the Remember buffer. It also allows -to jump to the buffer and location where Remember notes are being -stored: just call @code{org-remember} with a prefix argument. If you -use two prefix arguments, Org jumps to the location where the last -remember note was stored. +@node Using capture, Capture templates, Setting up a capture location, Capture +@unnumberedsubsec Using capture -@node Remember templates, Storing notes, Setting up Remember for Org, Remember -@unnumberedsubsec Remember templates +@table @kbd +@item C-c c +Start a capture process. You will be placed into a narrowed indirect buffer +to edit the item. +@item C-c C-c +Once you are done entering information into the capture buffer, +@kbd{C-c C-c} will return you to the window configuration before the capture +process, so that you can resume your work without further distraction. +@item C-c C-w +Finalize by moving the entry to a refile location (@pxref{Refiling notes}). +@item C-c C-k +Abort the capture process and return to the previous state. +@end table -In combination with Org, you can use templates to generate -different types of Remember notes. For example, if you would like -to use one template to create general TODO entries, another one for -journal entries, and a third one for collecting random ideas, you could +@node Capture templates, , Using capture, Capture +@unnumberedsubsec Capture templates + +You can use templates to generate different types of capture notes, and to +store them in different places. For example, if you would like +to store new tasks under a heading @samp{Tasks} in file @file{TODO.org}, and +journal entries in a date tree in @file{journal.org} you could use: @smallexample -(setq org-remember-templates - '(("Todo" ?t "* TODO %?\n %i\n %a" "~/org/TODO.org" "Tasks") - ("Journal" ?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org") - ("Idea" ?i "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas"))) +(setq org-capture-templates + '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks") + "* TODO %?\n %i\n %a") + ("j" "Journal" entry (file+datetree "~/org/journal.org") + "* %?\nEntered on %U\n %i\n %a"))) @end smallexample -@noindent In these entries, the first string is just a name, and the -character specifies how to select the template. It is useful if the -character is also the first letter of the name. The next string specifies -the template. Two more (optional) strings give the file in which, and the -headline under which, the new note should be stored. +@noindent In these entries, the first string is the key to reach the +template, the second is a short description. Then follows the type of the +entry and a definition of the target location for storing the note. Finally, +the template itself, a string with %-escapes to fill in information based on +time and context. -When you call @kbd{M-x org-remember} (or @kbd{M-x remember}) to remember -something, Org will prompt for a key to select the template (if you have -more than one template) and then prepare the buffer like +When you call @kbd{M-x org-capture}, Org will prompt for a key to select the +template (if you have more than one template) and then prepare the buffer like @smallexample * TODO - [[file:@var{link to where you called remember}]] + [[file:@var{link to where you were when initiating capture}]] @end smallexample @noindent @@ -1623,18 +1624,7 @@ possibilities, consult the manual for more. %u, %U @r{like the above, but inactive timestamps} @end smallexample -@node Storing notes, , Remember templates, Remember -@unnumberedsubsec Storing notes - -When you are finished preparing a note with Remember, you have to press -@kbd{C-c C-c} to file the note away. - -The handler will store the note in the file and under the headline -specified in the template, or it will use the default file and headline. The -window configuration will be restored, sending you back to the working -context before the call to Remember. - -@node Refiling notes, Archiving, Remember, Capture - Refile - Archive +@node Refiling notes, Archiving, Capture, Capture - Refile - Archive @section Refiling notes When reviewing the captured data, you may want to refile some of the entries @@ -2432,10 +2422,8 @@ code. @section iCalendar export @table @kbd -@kindex C-c C-e i @item C-c C-e i Create iCalendar entries for the current file in a @file{.ics} file. -@kindex C-c C-e c @item C-c C-e c Create a single large iCalendar file from all files in @code{org-agenda-files} and write it to the file given by From ae98b23ab979fb1c2f802a2edaedcd5ce337b43a Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Fri, 25 Jun 2010 09:20:39 -0700 Subject: [PATCH 119/138] babel: assigning copyright to the FSF for core babel files --- lisp/babel/ob-comint.el | 25 +++++++++++++------------ lisp/babel/ob-exp.el | 27 +++++++++++++++------------ lisp/babel/ob-keys.el | 31 ++++++++++++++++--------------- lisp/babel/ob-lob.el | 29 ++++++++++++++++------------- lisp/babel/ob-ref.el | 38 +++++++++++++++++++------------------- lisp/babel/ob-table.el | 33 +++++++++++++++++---------------- lisp/babel/ob-tangle.el | 25 +++++++++++++------------ lisp/babel/ob.el | 27 +++++++++++++++------------ 8 files changed, 124 insertions(+), 111 deletions(-) diff --git a/lisp/babel/ob-comint.el b/lisp/babel/ob-comint.el index e847bc44f..b60e8f12b 100644 --- a/lisp/babel/ob-comint.el +++ b/lisp/babel/ob-comint.el @@ -1,34 +1,32 @@ ;;; ob-comint.el --- org-babel functions for interaction with comint buffers -;; Copyright (C) 2009 Eric Schulte +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research, comint ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: ;; These functions build on comint to ease the sending and receiving ;; of commands and results from comint buffers. -;; + ;; Note that the buffers in this file are analogous to sessions in ;; org-babel at large. @@ -135,4 +133,7 @@ blocks of code)." (accept-process-output (get-buffer-process buffer))))) (provide 'ob-comint) + +;; arch-tag: 9adddce6-0864-4be3-b0b5-6c5157dc7889 + ;;; ob-comint.el ends here diff --git a/lisp/babel/ob-exp.el b/lisp/babel/ob-exp.el index c6a4f4936..59ad4af72 100644 --- a/lisp/babel/ob-exp.el +++ b/lisp/babel/ob-exp.el @@ -1,32 +1,32 @@ ;;; ob-exp.el --- Exportation of org-babel source blocks -;; Copyright (C) 2009 Eric Schulte, Dan Davison +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc. ;; Author: Eric Schulte, Dan Davison ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: -;; for more information see the comments in org-babel.el +;; See the online documentation for more information +;; +;; http://orgmode.org/worg/org-contrib/babel/ ;;; Code: (require 'ob) @@ -286,4 +286,7 @@ results into the buffer." "")))))) (provide 'ob-exp) + +;; arch-tag: 523abf4c-76d1-44ed-9f27-e3bddf34bf0f + ;;; ob-exp.el ends here diff --git a/lisp/babel/ob-keys.el b/lisp/babel/ob-keys.el index b98a069d9..dc459902f 100644 --- a/lisp/babel/ob-keys.el +++ b/lisp/babel/ob-keys.el @@ -1,35 +1,33 @@ ;;; ob-keys.el --- key bindings for org-babel -;; Copyright (C) 2009 Eric Schulte +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: -;; Add some org-babel keybindings to the org-mode keymap for exposing -;; org-babel functions. These will all share the common C-c M-b -;; prefix. See the value of `org-babel-key-bindings' for a list of -;; interactive functions and their associated keys. +;; Add org-babel keybindings to the org-mode keymap for exposing +;; org-babel functions. These will all share a common prefix. See +;; the value of `org-babel-key-bindings' for a list of interactive +;; functions and their associated keys. ;;; Code: (require 'ob) @@ -78,4 +76,7 @@ with keys. Each element of this list will add an entry to the a-list placed behind the generic `org-babel-key-prefix'.") (provide 'ob-keys) + +;; arch-tag: 01e348ee-4906-46fa-839a-6b7b6f989048 + ;;; ob-keys.el ends here diff --git a/lisp/babel/ob-lob.el b/lisp/babel/ob-lob.el index 25eb7bda4..cc7596c2a 100644 --- a/lisp/babel/ob-lob.el +++ b/lisp/babel/ob-lob.el @@ -1,32 +1,32 @@ -;;; ob-lob.el --- The Library of Babel: off-the-shelf functions for data analysis and plotting using org-babel +;;; ob-lob.el --- functions supporting the Library of Babel -;; Copyright (C) 2009 Eric Schulte, Dan Davison +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc. ;; Author: Eric Schulte, Dan Davison ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: -;; See org-babel.org in the parent directory for more information +;; See the online documentation for more information +;; +;; http://orgmode.org/worg/org-contrib/babel/ ;;; Code: (require 'ob) @@ -111,4 +111,7 @@ the word 'call'." nil (list "emacs-lisp" "results" params nil nil (nth 2 info))))) (provide 'ob-lob) + +;; arch-tag: ce0712c9-2147-4019-ba3f-42341b8b474b + ;;; ob-lob.el ends here diff --git a/lisp/babel/ob-ref.el b/lisp/babel/ob-ref.el index df8a0338e..85a29a216 100644 --- a/lisp/babel/ob-ref.el +++ b/lisp/babel/ob-ref.el @@ -1,55 +1,52 @@ ;;; ob-ref.el --- org-babel functions for referencing external data -;; Copyright (C) 2009 Eric Schulte, Dan Davison +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc. ;; Author: Eric Schulte, Dan Davison ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: ;; Functions for referencing data from the header arguments of a ;; org-babel block. The syntax of such a reference should be -;; + ;; #+VAR: variable-name=file:resource-id -;; + ;; - variable-name :: the name of the variable to which the value ;; will be assigned -;; + ;; - file :: path to the file containing the resource, or omitted if ;; resource is in the current file -;; + ;; - resource-id :: the id or name of the resource -;; + ;; So an example of a simple src block referencing table data in the ;; same file would be -;; + ;; #+TBLNAME: sandbox ;; | 1 | 2 | 3 | ;; | 4 | org-babel | 6 | ;; ;; #+begin_src emacs-lisp :var table=sandbox -;; (message table) +;; (message table) ;; #+end_src -;; ;;; Code: (require 'ob) @@ -231,4 +228,7 @@ types are tables and source blocks." ((looking-at org-babel-result-regexp) 'results-line))) (provide 'ob-ref) + +;; arch-tag: ace4a4f4-ea38-4dac-8fe6-6f52fcc43b6d + ;;; ob-ref.el ends here diff --git a/lisp/babel/ob-table.el b/lisp/babel/ob-table.el index 22aa4ca0e..37ee327ba 100644 --- a/lisp/babel/ob-table.el +++ b/lisp/babel/ob-table.el @@ -1,43 +1,41 @@ -;;; ob-table.el --- integration for calling org-babel functions from tables +;;; ob-table.el --- support for calling org-babel functions from tables -;; Copyright (C) 2009 Eric Schulte +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: ;; Should allow calling functions from org-mode tables using the ;; function `sbe' as so... -;; + ;; #+begin_src emacs-lisp :results silent -;; (defun fibbd (n) (if (< n 2) 1 (+ (fibbd (- n 1)) (fibbd (- n 2))))) +;; (defun fibbd (n) (if (< n 2) 1 (+ (fibbd (- n 1)) (fibbd (- n 2))))) ;; #+end_src -;; + ;; #+srcname: fibbd ;; #+begin_src emacs-lisp :var n=2 :results silent ;; (fibbd n) ;; #+end_src -;; + ;; | original | fibbd | ;; |----------+--------| ;; | 0 | | @@ -104,4 +102,7 @@ example above." "")))) (provide 'ob-table) + +;; arch-tag: 4234cc7c-4fc8-4e92-abb0-2892de1a493b + ;;; ob-table.el ends here diff --git a/lisp/babel/ob-tangle.el b/lisp/babel/ob-tangle.el index 64171b7e3..00e1faa63 100644 --- a/lisp/babel/ob-tangle.el +++ b/lisp/babel/ob-tangle.el @@ -1,28 +1,26 @@ -;;; ob-tangle.el --- Extract source code from org-mode files +;;; ob-tangle.el --- extract source code from org-mode files -;; Copyright (C) 2009 Eric Schulte +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -262,4 +260,7 @@ form (insert-comment (format "%s ends here" source-name))))) (provide 'ob-tangle) + +;; arch-tag: 413ced93-48f5-4216-86e4-3fc5df8c8f24 + ;;; ob-tangle.el ends here diff --git a/lisp/babel/ob.el b/lisp/babel/ob.el index aad0ab6ff..c6aa7d24a 100644 --- a/lisp/babel/ob.el +++ b/lisp/babel/ob.el @@ -1,32 +1,32 @@ ;;; ob.el --- working with code blocks in org-mode -;; Copyright (C) 2009 Eric Schulte, Dan Davison +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc. ;; Author: Eric Schulte, Dan Davison ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: -;; See org-babel.org in the parent directory for more information +;; See the online documentation for more information +;; +;; http://orgmode.org/worg/org-contrib/babel/ ;;; Code: (eval-when-compile (require 'cl)) @@ -1605,4 +1605,7 @@ specifies the value of ERROR-BUFFER." exit-status)) (provide 'ob) + +;; arch-tag: 01a7ebee-06c5-4ee4-a709-e660d28c0af1 + ;;; ob.el ends here From 312081b3760fcb076835d4db6167fa4f1ece93f4 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Fri, 25 Jun 2010 18:28:04 +0200 Subject: [PATCH 120/138] More tweaks at the capture documentation --- doc/org.texi | 43 ++++++++++++++++++++++++++----------------- 1 file changed, 26 insertions(+), 17 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 5a417747a..0bf2f2b73 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -5902,15 +5902,25 @@ trees to an archive file keeps the system compact and fast. @cindex capture Org's method for capturing new items is heavily inspired by John Wiegley -excellent remember package@footnote{Up to version 6.36 Org actually did use a +excellent remember package. Up to version 6.36 Org did actually use a special setup for @file{remember.el}. @file{org-remember.el} is still part -of Org-mode for backward compatibility with existing setups. But the new -capturing setup described here is preferred and should be used by new users. -You can find the documentation for org-remember at -@url{http://orgmode.org/org-remember.pdf}.} -which lets you store quick notes with little interruption of your work flow. -The basic process of capturing is very similar to remember, but Org does -enhance it with templates and more. +of Org-mode for backward compatibility with existing setups. You can find +the documentation for org-remember at +@url{http://orgmode.org/org-remember.pdf}. + +The new capturing setup described here is preferred and should be used by new +users. To convert your @code{org-remember-templates}, run the command +@example +@kbd M-x org-capture-import-remember-templates RET +@end example +@noindent and then customize the new variable with @kbd{M-x +customize-variable org-capture-templates}, check the result, and save the +customization. You will then be able to use both remember and capture until +you have gotten used to the new mechanism. + +Capture lets you store quick notes with little interruption of your work +flow. The basic process of capturing is very similar to remember, but Org +does enhance it with templates and more. @menu * Setting up a capture location:: Where notes will be stored @@ -5921,11 +5931,9 @@ enhance it with templates and more. @node Setting up a capture location, Using capture, Capture, Capture @subsection Setting up a capture location -The following customization sets a default target@footnote{Using capture -templates, you can define more fine-grained capture locations, see -@ref{Capture templates}.} file for notes, and defines a global -key@footnote{Please select your own key, @kbd{C-c c} is only a suggestion.} -for capturing new stuff. +The following customization sets a default target file for notes, and defines +a global key@footnote{Please select your own key, @kbd{C-c c} is only a +suggestion.} for capturing new stuff. @example (setq org-default-notes-file (concat org-directory "/notes.org")) @@ -5960,10 +5968,10 @@ process by refiling (@pxref{Refiling notes}) the note to a different place. Abort the capture process and return to the previous state. @end table -You can also call @code{org-capture} in a special way from the agenda, -using the @kbd{k c} key combination. With this access, any timestamps -inserted by the selected capture template (see below) will default to -the cursor date in the agenda, rather than to the current date. +You can also call @code{org-capture} in a special way from the agenda, using +the @kbd{k c} key combination. With this access, any timestamps inserted by +the selected capture template will default to the cursor date in the agenda, +rather than to the current date. @node Capture templates, , Using capture, Capture @subsection Capture templates @@ -6080,6 +6088,7 @@ Fast configuration if the target heading is unique in the file For non-unique headings, the full path is safer. @item (file+regexp "path/to/file" "regexp to find location") +Use a regular expression to position the cursor. @item (file+datetree "path/to/file") Will create a heading in a date tree. From 670b9899b9c5e52a4c848987d522b074e50ad8a4 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Fri, 25 Jun 2010 09:32:35 -0700 Subject: [PATCH 121/138] babel: assigning copyright to the FSF for babel language files --- lisp/babel/langs/ob-C.el | 23 ++++++++++++----------- lisp/babel/langs/ob-R.el | 25 +++++++++++++------------ lisp/babel/langs/ob-asymptote.el | 23 ++++++++++++----------- lisp/babel/langs/ob-clojure.el | 23 ++++++++++++----------- lisp/babel/langs/ob-css.el | 23 ++++++++++++----------- lisp/babel/langs/ob-ditaa.el | 23 ++++++++++++----------- lisp/babel/langs/ob-dot.el | 23 ++++++++++++----------- lisp/babel/langs/ob-emacs-lisp.el | 23 ++++++++++++----------- lisp/babel/langs/ob-gnuplot.el | 23 ++++++++++++----------- lisp/babel/langs/ob-haskell.el | 23 ++++++++++++----------- lisp/babel/langs/ob-latex.el | 23 ++++++++++++----------- lisp/babel/langs/ob-matlab.el | 23 ++++++++++++----------- lisp/babel/langs/ob-ocaml.el | 23 ++++++++++++----------- lisp/babel/langs/ob-octave.el | 23 ++++++++++++----------- lisp/babel/langs/ob-perl.el | 23 ++++++++++++----------- lisp/babel/langs/ob-python.el | 25 +++++++++++++------------ lisp/babel/langs/ob-ruby.el | 23 ++++++++++++----------- lisp/babel/langs/ob-sass.el | 23 ++++++++++++----------- lisp/babel/langs/ob-screen.el | 23 ++++++++++++----------- lisp/babel/langs/ob-sql.el | 23 ++++++++++++----------- lisp/babel/langs/ob-sqlite.el | 23 ++++++++++++----------- 21 files changed, 254 insertions(+), 233 deletions(-) diff --git a/lisp/babel/langs/ob-C.el b/lisp/babel/langs/ob-C.el index 75f7b0b72..1d61a59ad 100644 --- a/lisp/babel/langs/ob-C.el +++ b/lisp/babel/langs/ob-C.el @@ -1,28 +1,26 @@ ;;; ob-C.el --- org-babel functions for C and similar languages -;; Copyright (C) 2010 Eric Schulte +;; Copyright (C) 2010 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -191,4 +189,7 @@ of the same value." (provide 'ob-C) + +;; arch-tag: 8f49e462-54e3-417b-9a8d-423864893b37 + ;;; ob-C.el ends here diff --git a/lisp/babel/langs/ob-R.el b/lisp/babel/langs/ob-R.el index c3e63d421..f315cb3ac 100644 --- a/lisp/babel/langs/ob-R.el +++ b/lisp/babel/langs/ob-R.el @@ -1,28 +1,26 @@ ;;; ob-R.el --- org-babel functions for R code evaluation -;; Copyright (C) 2009 Eric Schulte +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc. -;; Author: Eric Schulte +;; Author: Eric Schulte, Dan Davison ;; Keywords: literate programming, reproducible research, R, statistics ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -249,4 +247,7 @@ requested." (provide 'ob-R) + +;; arch-tag: cd4c7298-503b-450f-a3c2-f3e74b630237 + ;;; ob-R.el ends here diff --git a/lisp/babel/langs/ob-asymptote.el b/lisp/babel/langs/ob-asymptote.el index ecc062953..933c18da5 100644 --- a/lisp/babel/langs/ob-asymptote.el +++ b/lisp/babel/langs/ob-asymptote.el @@ -1,28 +1,26 @@ ;;; ob-asymptote.el --- org-babel functions for asymptote evaluation -;; Copyright (C) 2009 Eric Schulte +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -152,4 +150,7 @@ be of int type." (or (anything-but-int data) 'int))) (provide 'ob-asymptote) + +;; arch-tag: f2f5bd0d-78e8-412b-8e6c-6dadc94cc06b + ;;; ob-asymptote.el ends here diff --git a/lisp/babel/langs/ob-clojure.el b/lisp/babel/langs/ob-clojure.el index 029090148..311e0f095 100644 --- a/lisp/babel/langs/ob-clojure.el +++ b/lisp/babel/langs/ob-clojure.el @@ -1,28 +1,26 @@ ;;; ob-clojure.el --- org-babel functions for clojure evaluation -;; Copyright (C) 2009 Joel Boehland +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc. ;; Author: Joel Boehland ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -283,4 +281,7 @@ last statement in BODY, as elisp." (org-babel-pick-name (nth 5 processed-params) (cdr (assoc :rownames params)))))) (provide 'ob-clojure) + +;; arch-tag: a43b33f2-653e-46b1-ac56-2805cf05b7d1 + ;;; ob-clojure.el ends here diff --git a/lisp/babel/langs/ob-css.el b/lisp/babel/langs/ob-css.el index 525215dc8..cba682b5d 100644 --- a/lisp/babel/langs/ob-css.el +++ b/lisp/babel/langs/ob-css.el @@ -1,28 +1,26 @@ ;;; ob-css.el --- org-babel functions for css evaluation -;; Copyright (C) 2009 Eric Schulte +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -46,4 +44,7 @@ called by `org-babel-execute-src-block'." (error "CSS sessions are nonsensical")) (provide 'ob-css) + +;; arch-tag: f4447e8c-50ab-41f9-b322-b7b9574d9fbe + ;;; ob-css.el ends here diff --git a/lisp/babel/langs/ob-ditaa.el b/lisp/babel/langs/ob-ditaa.el index e7c04750b..6d0a584f6 100644 --- a/lisp/babel/langs/ob-ditaa.el +++ b/lisp/babel/langs/ob-ditaa.el @@ -1,28 +1,26 @@ ;;; ob-ditaa.el --- org-babel functions for ditaa evaluation -;; Copyright (C) 2009 Eric Schulte +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -69,4 +67,7 @@ sessions." (error "Ditaa does not support sessions")) (provide 'ob-ditaa) + +;; arch-tag: 492cd006-07d9-4fac-bef6-5bb60b48842e + ;;; ob-ditaa.el ends here diff --git a/lisp/babel/langs/ob-dot.el b/lisp/babel/langs/ob-dot.el index 0a8376796..e22defd8e 100644 --- a/lisp/babel/langs/ob-dot.el +++ b/lisp/babel/langs/ob-dot.el @@ -1,28 +1,26 @@ ;;; ob-dot.el --- org-babel functions for dot evaluation -;; Copyright (C) 2009 Eric Schulte +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -68,4 +66,7 @@ called by `org-babel-execute-src-block'." (error "Dot does not support sessions")) (provide 'ob-dot) + +;; arch-tag: 817d0516-7b47-4f77-a8b2-2aadd8e4d0e2 + ;;; ob-dot.el ends here diff --git a/lisp/babel/langs/ob-emacs-lisp.el b/lisp/babel/langs/ob-emacs-lisp.el index 724838a0c..81ee22e04 100644 --- a/lisp/babel/langs/ob-emacs-lisp.el +++ b/lisp/babel/langs/ob-emacs-lisp.el @@ -1,28 +1,26 @@ ;;; ob-emacs-lisp.el --- org-babel functions for emacs-lisp code evaluation -;; Copyright (C) 2009 Eric Schulte +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -71,4 +69,7 @@ (org-babel-pick-name (nth 5 processed-params) (cdr (assoc :rownames params))))))) (provide 'ob-emacs-lisp) + +;; arch-tag: e9a3acca-dc84-472a-9f5a-23c35befbcd6 + ;;; ob-emacs-lisp.el ends here diff --git a/lisp/babel/langs/ob-gnuplot.el b/lisp/babel/langs/ob-gnuplot.el index e11466377..5060d66db 100644 --- a/lisp/babel/langs/ob-gnuplot.el +++ b/lisp/babel/langs/ob-gnuplot.el @@ -1,28 +1,26 @@ ;;; ob-gnuplot.el --- org-babel functions for gnuplot evaluation -;; Copyright (C) 2009 Eric Schulte +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -209,4 +207,7 @@ Pass PARAMS through to `orgtbl-to-generic' when exporting TABLE." data-file) (provide 'ob-gnuplot) + +;; arch-tag: 50490ace-a9e1-4b29-a6e5-0db9f16c610b + ;;; ob-gnuplot.el ends here diff --git a/lisp/babel/langs/ob-haskell.el b/lisp/babel/langs/ob-haskell.el index 959073df2..aed816a06 100644 --- a/lisp/babel/langs/ob-haskell.el +++ b/lisp/babel/langs/ob-haskell.el @@ -1,28 +1,26 @@ ;;; ob-haskell.el --- org-babel functions for haskell evaluation -;; Copyright (C) 2009 Eric Schulte +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -202,4 +200,7 @@ constructs (header arguments, no-web syntax etc...) are ignored." (message "running %s" command) (shell-command command) (find-file tex-file)))) (provide 'ob-haskell) + +;; arch-tag: b53f75f3-ba1a-4b05-82d9-a2a0d4e70804 + ;;; ob-haskell.el ends here diff --git a/lisp/babel/langs/ob-latex.el b/lisp/babel/langs/ob-latex.el index 3526d86d2..d06254ffd 100644 --- a/lisp/babel/langs/ob-latex.el +++ b/lisp/babel/langs/ob-latex.el @@ -1,28 +1,26 @@ ;;; ob-latex.el --- org-babel functions for latex "evaluation" -;; Copyright (C) 2009 Eric Schulte +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -139,4 +137,7 @@ from `org-export-as-pdf' in org-latex.el." (error "Latex does not support sessions")) (provide 'ob-latex) + +;; arch-tag: 1f13f7e2-26de-4c24-9274-9f331d4c6ff3 + ;;; ob-latex.el ends here diff --git a/lisp/babel/langs/ob-matlab.el b/lisp/babel/langs/ob-matlab.el index fff035f60..398217aa9 100644 --- a/lisp/babel/langs/ob-matlab.el +++ b/lisp/babel/langs/ob-matlab.el @@ -1,28 +1,26 @@ ;;; ob-matlab.el --- org-babel support for matlab evaluation -;; Copyright (C) Dan Davison +;; Copyright (C) 2010 Free Software Foundation, Inc. ;; Author: Dan Davison ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -75,4 +73,7 @@ the initialized session." (org-babel-octave-initiate-session session params 'matlab)) (provide 'ob-matlab) + +;; arch-tag: 6b234299-c1f7-4eb1-ace8-7b93344065ac + ;;; ob-matlab.el ends here diff --git a/lisp/babel/langs/ob-ocaml.el b/lisp/babel/langs/ob-ocaml.el index 6ed8457a8..f3eed0592 100644 --- a/lisp/babel/langs/ob-ocaml.el +++ b/lisp/babel/langs/ob-ocaml.el @@ -1,28 +1,26 @@ ;;; ob-ocaml.el --- org-babel functions for ocaml evaluation -;; Copyright (C) 2009 Eric Schulte +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -125,4 +123,7 @@ Emacs-lisp table, otherwise return the results as a string." results))) (provide 'ob-ocaml) + +;; arch-tag: 2e815f4d-365e-4d69-b1df-dd17fdd7b7b7 + ;;; ob-ocaml.el ends here diff --git a/lisp/babel/langs/ob-octave.el b/lisp/babel/langs/ob-octave.el index f01337243..a60871187 100644 --- a/lisp/babel/langs/ob-octave.el +++ b/lisp/babel/langs/ob-octave.el @@ -1,28 +1,26 @@ ;;; ob-octave.el --- org-babel functions for octave and matlab evaluation -;; Copyright (C) Dan Davison +;; Copyright (C) 2010 Free Software Foundation, Inc. ;; Author: Dan Davison ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -218,4 +216,7 @@ comment lines and then calls `org-babel-import-elisp-from-file'." string)) (provide 'ob-octave) + +;; arch-tag: d8e5f68b-ba13-440a-a495-b653e989e704 + ;;; ob-octave.el ends here diff --git a/lisp/babel/langs/ob-perl.el b/lisp/babel/langs/ob-perl.el index fcb84f392..fc06155a7 100644 --- a/lisp/babel/langs/ob-perl.el +++ b/lisp/babel/langs/ob-perl.el @@ -1,28 +1,26 @@ ;;; ob-perl.el --- org-babel functions for perl evaluation -;; Copyright (C) 2009 Dan Davison, Eric Schulte +;; Copyright (C) 2009, 2010 Free Software Foundation ;; Author: Dan Davison, Eric Schulte ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -126,4 +124,7 @@ last statement in BODY, as elisp." (error "Sessions are not supported for Perl."))) (provide 'ob-perl) + +;; arch-tag: 88ef9396-d857-4dc3-8946-5a72bdfa2337 + ;;; ob-perl.el ends here diff --git a/lisp/babel/langs/ob-python.el b/lisp/babel/langs/ob-python.el index 48953adf9..e7ea0d651 100644 --- a/lisp/babel/langs/ob-python.el +++ b/lisp/babel/langs/ob-python.el @@ -1,28 +1,26 @@ ;;; ob-python.el --- org-babel functions for python evaluation -;; Copyright (C) 2009 Eric Schulte +;; Copyright (C) 2009, 2010 Free Software Foundation -;; Author: Eric Schulte +;; Author: Eric Schulte, Dan Davison ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -252,4 +250,7 @@ last statement in BODY, as elisp." string)) (provide 'ob-python) + +;; arch-tag: f19b6c3d-dfcb-4a1a-9ce0-45ade1ebc212 + ;;; ob-python.el ends here diff --git a/lisp/babel/langs/ob-ruby.el b/lisp/babel/langs/ob-ruby.el index c7ff56f92..b42dc7c3b 100644 --- a/lisp/babel/langs/ob-ruby.el +++ b/lisp/babel/langs/ob-ruby.el @@ -1,28 +1,26 @@ ;;; ob-ruby.el --- org-babel functions for ruby evaluation -;; Copyright (C) 2009 Eric Schulte +;; Copyright (C) 2009, 2010 Free Software Foundation ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -232,4 +230,7 @@ last statement in BODY, as elisp." string)) (provide 'ob-ruby) + +;; arch-tag: 3e9726db-4520-49e2-b263-e8f571ac88f5 + ;;; ob-ruby.el ends here diff --git a/lisp/babel/langs/ob-sass.el b/lisp/babel/langs/ob-sass.el index 58ece16e1..7c06e52c1 100644 --- a/lisp/babel/langs/ob-sass.el +++ b/lisp/babel/langs/ob-sass.el @@ -1,28 +1,26 @@ ;;; ob-sass.el --- org-babel functions for the sass css generation language -;; Copyright (C) 2009 Eric Schulte +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -66,4 +64,7 @@ called by `org-babel-execute-src-block'." (error "Sass does not support sessions")) (provide 'ob-sass) + +;; arch-tag: 2954b169-eef4-45ce-a8e5-3e619f0f07ac + ;;; ob-sass.el ends here diff --git a/lisp/babel/langs/ob-screen.el b/lisp/babel/langs/ob-screen.el index 8c690e89d..132476d7a 100644 --- a/lisp/babel/langs/ob-screen.el +++ b/lisp/babel/langs/ob-screen.el @@ -1,28 +1,26 @@ ;;; ob-screen.el --- org-babel support for interactive terminal -;; Copyright (C) 2009 Benjamin Andresen +;; Copyright (C) 2009, 2010 Free Software Foundation ;; Author: Benjamin Andresen ;; Keywords: literate programming, interactive shell ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -141,4 +139,7 @@ flicker." "DOESN'T work."))))) (provide 'ob-screen) + +;; arch-tag: 908e5afe-89a0-4f27-b982-23f1f2e3bac9 + ;;; ob-screen.el ends here diff --git a/lisp/babel/langs/ob-sql.el b/lisp/babel/langs/ob-sql.el index f48f1a577..c680a6bd5 100644 --- a/lisp/babel/langs/ob-sql.el +++ b/lisp/babel/langs/ob-sql.el @@ -1,28 +1,26 @@ ;;; ob-sql.el --- org-babel functions for sql evaluation -;; Copyright (C) 2009 Eric Schulte +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -81,4 +79,7 @@ called by `org-babel-execute-src-block'." (error "sql sessions not yet implemented")) (provide 'ob-sql) + +;; arch-tag: a43ff944-6de1-4566-a83c-626814e3dad2 + ;;; ob-sql.el ends here diff --git a/lisp/babel/langs/ob-sqlite.el b/lisp/babel/langs/ob-sqlite.el index d2331e710..a4f883da6 100644 --- a/lisp/babel/langs/ob-sqlite.el +++ b/lisp/babel/langs/ob-sqlite.el @@ -1,28 +1,26 @@ ;;; ob-sqlite.el --- org-babel functions for sqlite database interaction -;; Copyright (C) 2009 Eric Schulte +;; Copyright (C) 2010 Free Software Foundation ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -88,4 +86,7 @@ called by `org-babel-execute-src-block'." (error "sqlite sessions not yet implemented")) (provide 'ob-sqlite) + +;; arch-tag: 5c03d7f2-0f72-48b8-bbd1-35aafea248ac + ;;; ob-sqlite.el ends here From 05ac8eb8a8858162e096f57f1652dd5df8b0f975 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Fri, 25 Jun 2010 10:12:54 -0700 Subject: [PATCH 122/138] babel: ensuring each language defined (possibly empty) default header arguments this makes customization easier when users can assume that org-babel-default-header-args:foo will exist for every language --- lisp/babel/langs/ob-C.el | 2 ++ lisp/babel/langs/ob-R.el | 2 ++ lisp/babel/langs/ob-clojure.el | 2 ++ lisp/babel/langs/ob-css.el | 2 ++ lisp/babel/langs/ob-haskell.el | 2 ++ lisp/babel/langs/ob-matlab.el | 2 ++ lisp/babel/langs/ob-ocaml.el | 2 ++ lisp/babel/langs/ob-octave.el | 2 ++ lisp/babel/langs/ob-perl.el | 2 ++ lisp/babel/langs/ob-python.el | 2 ++ lisp/babel/langs/ob-ruby.el | 2 ++ lisp/babel/langs/ob-sass.el | 2 ++ lisp/babel/langs/ob-sh.el | 2 ++ lisp/babel/langs/ob-sql.el | 2 ++ lisp/babel/langs/ob-sqlite.el | 2 ++ 15 files changed, 30 insertions(+) diff --git a/lisp/babel/langs/ob-C.el b/lisp/babel/langs/ob-C.el index 1d61a59ad..42514ead4 100644 --- a/lisp/babel/langs/ob-C.el +++ b/lisp/babel/langs/ob-C.el @@ -36,6 +36,8 @@ (add-to-list 'org-babel-tangle-lang-exts '("c++" . "cpp")) +(defvar org-babel-default-header-args:C '()) + (defvar org-babel-C-compiler "gcc" "Command used to compile a C source code file into an executable.") diff --git a/lisp/babel/langs/ob-R.el b/lisp/babel/langs/ob-R.el index f315cb3ac..a8dba35e1 100644 --- a/lisp/babel/langs/ob-R.el +++ b/lisp/babel/langs/ob-R.el @@ -35,6 +35,8 @@ pagecentre colormodel useDingbats horizontal) "R-specific header arguments.") +(defvar org-babel-default-header-args:R '()) + (defun org-babel-expand-body:R (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." (let* ((processed-params (or processed-params diff --git a/lisp/babel/langs/ob-clojure.el b/lisp/babel/langs/ob-clojure.el index 311e0f095..51f040efa 100644 --- a/lisp/babel/langs/ob-clojure.el +++ b/lisp/babel/langs/ob-clojure.el @@ -45,6 +45,8 @@ (add-to-list 'org-babel-tangle-lang-exts '("clojure" . "clj")) +(defvar org-babel-default-header-args:clojure '()) + (defvar org-babel-clojure-wrapper-method " (defn spit diff --git a/lisp/babel/langs/ob-css.el b/lisp/babel/langs/ob-css.el index cba682b5d..578562292 100644 --- a/lisp/babel/langs/ob-css.el +++ b/lisp/babel/langs/ob-css.el @@ -30,6 +30,8 @@ ;;; Code: (require 'ob) +(defvar org-babel-default-header-args:css '()) + (defun org-babel-expand-body:css (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." body) diff --git a/lisp/babel/langs/ob-haskell.el b/lisp/babel/langs/ob-haskell.el index aed816a06..f364fec7d 100644 --- a/lisp/babel/langs/ob-haskell.el +++ b/lisp/babel/langs/ob-haskell.el @@ -46,6 +46,8 @@ (add-to-list 'org-babel-tangle-lang-exts '("haskell" . "hs")) +(defvar org-babel-default-header-args:haskell '()) + (defvar org-babel-haskell-lhs2tex-command "lhs2tex") (defvar org-babel-haskell-eoe "\"org-babel-haskell-eoe\"") diff --git a/lisp/babel/langs/ob-matlab.el b/lisp/babel/langs/ob-matlab.el index 398217aa9..63858bc92 100644 --- a/lisp/babel/langs/ob-matlab.el +++ b/lisp/babel/langs/ob-matlab.el @@ -39,6 +39,8 @@ (require 'matlab) (require 'ob-octave) +(defvar org-babel-default-header-args:matlab '()) + (defvar org-babel-matlab-shell-command "matlab -nosplash" "Shell command to use to run matlab as an external process.") diff --git a/lisp/babel/langs/ob-ocaml.el b/lisp/babel/langs/ob-ocaml.el index f3eed0592..9bfade32e 100644 --- a/lisp/babel/langs/ob-ocaml.el +++ b/lisp/babel/langs/ob-ocaml.el @@ -41,6 +41,8 @@ (add-to-list 'org-babel-tangle-lang-exts '("ocaml" . "ml")) +(defvar org-babel-default-header-args:ocaml '()) + (defvar org-babel-ocaml-eoe-indicator "\"org-babel-ocaml-eoe\";;") (defvar org-babel-ocaml-eoe-output "org-babel-ocaml-eoe") diff --git a/lisp/babel/langs/ob-octave.el b/lisp/babel/langs/ob-octave.el index a60871187..f1205d075 100644 --- a/lisp/babel/langs/ob-octave.el +++ b/lisp/babel/langs/ob-octave.el @@ -33,6 +33,8 @@ (require 'ob) (require 'octave-inf) +(defvar org-babel-default-header-args:octave '()) + (defvar org-babel-octave-shell-command "octave -q" "Shell command to use to run octave as an external process.") diff --git a/lisp/babel/langs/ob-perl.el b/lisp/babel/langs/ob-perl.el index fc06155a7..0e1f778e1 100644 --- a/lisp/babel/langs/ob-perl.el +++ b/lisp/babel/langs/ob-perl.el @@ -31,6 +31,8 @@ (add-to-list 'org-babel-tangle-lang-exts '("perl" . "pl")) +(defvar org-babel-default-header-args:perl '()) + (defun org-babel-expand-body:perl (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." (let ((vars (second (or processed-params (org-babel-process-params params))))) diff --git a/lisp/babel/langs/ob-python.el b/lisp/babel/langs/ob-python.el index e7ea0d651..5b1fff92b 100644 --- a/lisp/babel/langs/ob-python.el +++ b/lisp/babel/langs/ob-python.el @@ -34,6 +34,8 @@ (add-to-list 'org-babel-tangle-lang-exts '("python" . "py")) +(defvar org-babel-default-header-args:python '()) + (defun org-babel-expand-body:python (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." (concat diff --git a/lisp/babel/langs/ob-ruby.el b/lisp/babel/langs/ob-ruby.el index b42dc7c3b..3dcdd1fe0 100644 --- a/lisp/babel/langs/ob-ruby.el +++ b/lisp/babel/langs/ob-ruby.el @@ -42,6 +42,8 @@ (add-to-list 'org-babel-tangle-lang-exts '("ruby" . "rb")) +(defvar org-babel-default-header-args:ruby '()) + (defun org-babel-expand-body:ruby (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." (let ((vars (second (or processed-params (org-babel-process-params params))))) diff --git a/lisp/babel/langs/ob-sass.el b/lisp/babel/langs/ob-sass.el index 7c06e52c1..7cf7015ef 100644 --- a/lisp/babel/langs/ob-sass.el +++ b/lisp/babel/langs/ob-sass.el @@ -42,6 +42,8 @@ (require 'ob) (require 'sass-mode) +(defvar org-babel-default-header-args:sass '()) + (defun org-babel-expand-body:sass (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." body) diff --git a/lisp/babel/langs/ob-sh.el b/lisp/babel/langs/ob-sh.el index 4b18ad14c..f6c265e0e 100644 --- a/lisp/babel/langs/ob-sh.el +++ b/lisp/babel/langs/ob-sh.el @@ -41,6 +41,8 @@ (declare-function org-babel-comint-with-output "ob-comint" (meta &rest body)) (declare-function orgtbl-to-generic "org-table" (table params)) +(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'") diff --git a/lisp/babel/langs/ob-sql.el b/lisp/babel/langs/ob-sql.el index c680a6bd5..9429ce042 100644 --- a/lisp/babel/langs/ob-sql.el +++ b/lisp/babel/langs/ob-sql.el @@ -45,6 +45,8 @@ ;;; Code: (require 'ob) +(defvar org-babel-default-header-args:sql '()) + (defun org-babel-expand-body:sql (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." body) diff --git a/lisp/babel/langs/ob-sqlite.el b/lisp/babel/langs/ob-sqlite.el index a4f883da6..a8180fce5 100644 --- a/lisp/babel/langs/ob-sqlite.el +++ b/lisp/babel/langs/ob-sqlite.el @@ -29,6 +29,8 @@ ;;; Code: (require 'ob) +(defvar org-babel-default-header-args:sqlite '()) + (defun org-babel-expand-body:sqlite (body params &optional processed-params) body) From 7f7602e65b5c43d63eecc68db05ec002eaed5bcb Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Fri, 25 Jun 2010 10:17:50 -0700 Subject: [PATCH 123/138] babel: assign copyright to FSF on ob-sh.el --- lisp/babel/langs/ob-sh.el | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/lisp/babel/langs/ob-sh.el b/lisp/babel/langs/ob-sh.el index f6c265e0e..284164b1e 100644 --- a/lisp/babel/langs/ob-sh.el +++ b/lisp/babel/langs/ob-sh.el @@ -1,28 +1,26 @@ ;;; ob-sh.el --- org-babel functions for shell evaluation -;; Copyright (C) 2009 Eric Schulte +;; Copyright (C) 2009, 2010 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org ;; Version: 0.01 -;;; License: +;; This file is part of GNU Emacs. -;; This program is free software; you can redistribute it and/or modify +;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation; either version 3, or (at your option) -;; any later version. -;; -;; This program is distributed in the hope that it will be useful, +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. -;; + ;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -;; Boston, MA 02110-1301, USA. +;; along with GNU Emacs. If not, see . ;;; Commentary: @@ -198,4 +196,7 @@ last statement in BODY." string) (provide 'ob-sh) + +;; arch-tag: 416dd531-c230-4b0a-a5bf-8d948f990f2d + ;;; ob-sh.el ends here From 940b6f90afaeb244bc7e4948c72f69f5ed1d095c Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Fri, 25 Jun 2010 10:26:48 -0700 Subject: [PATCH 124/138] babel: bringing languages closer to compilability removing un-needed 'cl functions from language files, and generally cleaning them up as if they were going to be compiled. --- lisp/babel/langs/ob-C.el | 29 ++++++++++++++++++----------- lisp/babel/langs/ob-R.el | 14 +++++++------- lisp/babel/langs/ob-asymptote.el | 3 ++- lisp/babel/langs/ob-clojure.el | 4 ++-- lisp/babel/langs/ob-haskell.el | 6 +++--- lisp/babel/langs/ob-latex.el | 2 +- lisp/babel/langs/ob-ocaml.el | 4 ++-- lisp/babel/langs/ob-octave.el | 8 ++++---- lisp/babel/langs/ob-perl.el | 8 ++++---- lisp/babel/langs/ob-python.el | 6 +++--- lisp/babel/langs/ob-ruby.el | 6 +++--- lisp/babel/langs/ob-screen.el | 2 +- 12 files changed, 50 insertions(+), 42 deletions(-) diff --git a/lisp/babel/langs/ob-C.el b/lisp/babel/langs/ob-C.el index 42514ead4..8930fa1dd 100644 --- a/lisp/babel/langs/ob-C.el +++ b/lisp/babel/langs/ob-C.el @@ -32,8 +32,11 @@ ;;; Code: (require 'ob) +(require 'org) (require 'cc-mode) +(declare-function org-entry-get "org" (&optional inherit)) + (add-to-list 'org-babel-tangle-lang-exts '("c++" . "cpp")) (defvar org-babel-default-header-args:C '()) @@ -46,6 +49,10 @@ "Command used to compile a c++ source code file into an executable.") +(defvar org-babel-c-variant nil + "Internal variable used to hold which type of C (e.g. C or C++) +is currently being evaluated.") + (defun org-babel-execute:cpp (body params) "Execute BODY according to PARAMS. This function calls `org-babel-execute:C'." @@ -54,22 +61,22 @@ (defun org-babel-execute:c++ (body params) "Execute a block of C++ code with org-babel. This function is called by `org-babel-execute-src-block'." - (let ((c-variant 'cpp)) (org-babel-C-execute body params))) + (let ((org-babel-c-variant 'cpp)) (org-babel-C-execute body params))) (defun org-babel-expand-body:c++ (body params &optional processed-params) "Expand a block of C++ code with org-babel according to it's header arguments (calls `org-babel-C-expand')." - (let ((c-variant 'cpp)) (org-babel-C-expand body params processed-params))) + (let ((org-babel-c-variant 'cpp)) (org-babel-C-expand body params processed-params))) (defun org-babel-execute:C (body params) "Execute a block of C code with org-babel. This function is called by `org-babel-execute-src-block'." - (let ((c-variant 'c)) (org-babel-C-execute body params))) + (let ((org-babel-c-variant 'c)) (org-babel-C-execute body params))) (defun org-babel-expand-body:c (body params &optional processed-params) "Expand a block of C code with org-babel according to it's header arguments (calls `org-babel-C-expand')." - (let ((c-variant 'c)) (org-babel-C-expand body params processed-params))) + (let ((org-babel-c-variant 'c)) (org-babel-C-expand body params processed-params))) (defun org-babel-C-execute (body params) "This function should only be called by `org-babel-execute:C' @@ -77,9 +84,9 @@ 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 - (case c-variant - ('c ".c") - ('cpp ".cpp")))) + (cond + ((equal org-babel-c-variant 'c) ".c") + ((equal org-babel-c-variant 'cpp) ".cpp")))) (tmp-bin-file (make-temp-file "org-babel-C-bin")) (tmp-out-file (make-temp-file "org-babel-C-out")) (cmdline (cdr (assoc :cmdline params))) @@ -93,9 +100,9 @@ or `org-babel-execute:c++'." (org-babel-shell-command-on-region (point-min) (point-max) (format "%s -o %s %s %s" - (case c-variant - ('c org-babel-C-compiler) - ('cpp org-babel-c++-compiler)) + (cond + ((equal org-babel-c-variant 'c) org-babel-C-compiler) + ((equal org-babel-c-variant 'cpp) org-babel-c++-compiler)) tmp-bin-file (mapconcat 'identity (if (listp flags) flags (list flags)) " ") @@ -123,7 +130,7 @@ or `org-babel-execute:c++'." (defun org-babel-C-expand (body params &optional processed-params) "Expand a block of C or C++ code with org-babel according to it's header arguments." - (let ((vars (second (or processed-params + (let ((vars (nth 1 (or processed-params (org-babel-process-params params)))) (main-p (not (string= (cdr (assoc :main params)) "no"))) (includes (or (cdr (assoc :includes params)) diff --git a/lisp/babel/langs/ob-R.el b/lisp/babel/langs/ob-R.el index a8dba35e1..6a711e868 100644 --- a/lisp/babel/langs/ob-R.el +++ b/lisp/babel/langs/ob-R.el @@ -41,12 +41,12 @@ "Expand BODY according to PARAMS, return the expanded body." (let* ((processed-params (or processed-params (org-babel-process-params params))) - (vars (mapcar (lambda (i) (cons (car (nth i (second processed-params))) + (vars (mapcar (lambda (i) (cons (car (nth i (nth 1 processed-params))) (org-babel-reassemble-table - (cdr (nth i (second processed-params))) - (cdr (nth i (fifth processed-params))) - (cdr (nth i (sixth processed-params)))))) - (number-sequence 0 (1- (length (second processed-params)))))) + (cdr (nth i (nth 1 processed-params))) + (cdr (nth i (nth 4 processed-params))) + (cdr (nth i (nth 5 processed-params)))))) + (number-sequence 0 (1- (length (nth 1 processed-params)))))) (out-file (cdr (assoc :file params)))) (concat (if out-file (concat (org-babel-R-construct-graphics-device-call out-file params) "\n") "") @@ -64,7 +64,7 @@ called by `org-babel-execute-src-block'." (message "executing R source code block...") (save-excursion (let* ((processed-params (org-babel-process-params params)) - (result-type (fourth processed-params)) + (result-type (nth 3 processed-params)) (session (org-babel-R-initiate-session (first processed-params) params)) (colnames-p (cdr (assoc :colnames params))) (rownames-p (cdr (assoc :rownames params))) @@ -124,7 +124,7 @@ called by `org-babel-execute-src-block'." (insert "\n")) (format "%s <- read.table(\"%s\", header=%s, row.names=%s, sep=\"\\t\", as.is=TRUE)" name transition-file - (if (or (eq (second value) 'hline) colnames-p) "TRUE" "FALSE") + (if (or (eq (nth 1 value) 'hline) colnames-p) "TRUE" "FALSE") (if rownames-p "1" "NULL"))) (format "%s <- %s" name (org-babel-R-quote-tsv-field value)))) diff --git a/lisp/babel/langs/ob-asymptote.el b/lisp/babel/langs/ob-asymptote.el index 933c18da5..1415730ce 100644 --- a/lisp/babel/langs/ob-asymptote.el +++ b/lisp/babel/langs/ob-asymptote.el @@ -44,6 +44,7 @@ ;;; Code: (require 'ob) +(eval-when-compile (require 'cl)) (add-to-list 'org-babel-tangle-lang-exts '("asymptote" . "asy")) @@ -53,7 +54,7 @@ (defun org-babel-expand-body:asymptote (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." - (let ((vars (second (or processed-params + (let ((vars (nth 1 (or processed-params (org-babel-process-params params))))) (concat (mapconcat 'org-babel-asymptote-var-to-asymptote vars "\n") "\n" body "\n"))) diff --git a/lisp/babel/langs/ob-clojure.el b/lisp/babel/langs/ob-clojure.el index 51f040efa..491a4ac1d 100644 --- a/lisp/babel/langs/ob-clojure.el +++ b/lisp/babel/langs/ob-clojure.el @@ -270,7 +270,7 @@ last statement in BODY, as elisp." (defun org-babel-expand-body:clojure (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." (org-babel-clojure-build-full-form - body (second (or processed-params (org-babel-process-params params))))) + 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." @@ -278,7 +278,7 @@ last statement in BODY, as elisp." (body (org-babel-expand-body:clojure body params processed-params)) (session (org-babel-clojure-initiate-session (first processed-params)))) (org-babel-reassemble-table - (org-babel-clojure-evaluate session body (fourth processed-params)) + (org-babel-clojure-evaluate session body (nth 3 processed-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)))))) diff --git a/lisp/babel/langs/ob-haskell.el b/lisp/babel/langs/ob-haskell.el index f364fec7d..79704c1d8 100644 --- a/lisp/babel/langs/ob-haskell.el +++ b/lisp/babel/langs/ob-haskell.el @@ -54,7 +54,7 @@ (defun org-babel-expand-body:haskell (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." - (let (vars (second (or processed-params (org-babel-process-params params)))) + (let (vars (nth 1 (or processed-params (org-babel-process-params params)))) (concat (mapconcat (lambda (pair) (format "let %s = %s;" (car pair) (cdr pair))) @@ -65,8 +65,8 @@ (message "executing haskell source code block") (let* ((processed-params (org-babel-process-params params)) (session (first processed-params)) - (vars (second processed-params)) - (result-type (fourth processed-params)) + (vars (nth 1 processed-params)) + (result-type (nth 3 processed-params)) (full-body (org-babel-expand-body:haskell body params processed-params)) (session (org-babel-prep-session:haskell session params)) (raw (org-babel-comint-with-output diff --git a/lisp/babel/langs/ob-latex.el b/lisp/babel/langs/ob-latex.el index d06254ffd..3c7b7cfa8 100644 --- a/lisp/babel/langs/ob-latex.el +++ b/lisp/babel/langs/ob-latex.el @@ -47,7 +47,7 @@ (regexp-quote (format "%S" (car pair))) (if (stringp (cdr pair)) (cdr pair) (format "%S" (cdr pair))) - body))) (second (org-babel-process-params params))) + body))) (nth 1 (org-babel-process-params params))) body) (defun org-babel-execute:latex (body params) diff --git a/lisp/babel/langs/ob-ocaml.el b/lisp/babel/langs/ob-ocaml.el index 9bfade32e..66d285bd9 100644 --- a/lisp/babel/langs/ob-ocaml.el +++ b/lisp/babel/langs/ob-ocaml.el @@ -48,7 +48,7 @@ (defun org-babel-expand-body:ocaml (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." - (let ((vars (second (or processed-params (org-babel-process-params params))))) + (let ((vars (nth 1 (or processed-params (org-babel-process-params params))))) (concat (mapconcat (lambda (pair) (format "let %s = %s;" (car pair) (cdr pair))) @@ -58,7 +58,7 @@ "Execute a block of Ocaml code with org-babel." (message "executing ocaml source code block") (let* ((processed-params (org-babel-process-params params)) - (vars (second processed-params)) + (vars (nth 1 processed-params)) (full-body (org-babel-expand-body:ocaml body params processed-params)) (session (org-babel-prep-session:ocaml session params)) (raw (org-babel-comint-with-output diff --git a/lisp/babel/langs/ob-octave.el b/lisp/babel/langs/ob-octave.el index f1205d075..8797b2317 100644 --- a/lisp/babel/langs/ob-octave.el +++ b/lisp/babel/langs/ob-octave.el @@ -40,7 +40,7 @@ (defun org-babel-expand-body:octave (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." - (let ((vars (second (or processed-params (org-babel-process-params params))))) + (let ((vars (nth 1 (or processed-params (org-babel-process-params params))))) (concat ;; prepend code to define all arguments passed to the code block ;; (may not be appropriate for all languages) @@ -58,9 +58,9 @@ ;; set the session if the session variable is non-nil (session (funcall (intern (format "org-babel-%s-initiate-session" lang)) (first processed-params) params)) - (vars (second processed-params)) - (result-params (third processed-params)) - (result-type (fourth processed-params)) + (vars (nth 1 processed-params)) + (result-params (nth 2 processed-params)) + (result-type (nth 3 processed-params)) (out-file (cdr (assoc :file params))) (augmented-body (org-babel-expand-body:octave body params processed-params)) (result (org-babel-octave-evaluate session augmented-body result-type matlabp))) diff --git a/lisp/babel/langs/ob-perl.el b/lisp/babel/langs/ob-perl.el index 0e1f778e1..f34a88c0d 100644 --- a/lisp/babel/langs/ob-perl.el +++ b/lisp/babel/langs/ob-perl.el @@ -35,7 +35,7 @@ (defun org-babel-expand-body:perl (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." - (let ((vars (second (or processed-params (org-babel-process-params params))))) + (let ((vars (nth 1 (or processed-params (org-babel-process-params params))))) (concat (mapconcat ;; define any variables (lambda (pair) @@ -50,9 +50,9 @@ called by `org-babel-execute-src-block'." (message "executing Perl source code block") (let* ((processed-params (org-babel-process-params params)) (session (first processed-params)) - (vars (second processed-params)) - (result-params (third processed-params)) - (result-type (fourth processed-params)) + (vars (nth 1 processed-params)) + (result-params (nth 2 processed-params)) + (result-type (nth 3 processed-params)) (full-body (org-babel-expand-body:perl body params processed-params)) ;; then the source block body (session (org-babel-perl-initiate-session session))) diff --git a/lisp/babel/langs/ob-python.el b/lisp/babel/langs/ob-python.el index 5b1fff92b..2ce9e1d3d 100644 --- a/lisp/babel/langs/ob-python.el +++ b/lisp/babel/langs/ob-python.el @@ -44,7 +44,7 @@ (format "%s=%s" (car pair) (org-babel-python-var-to-python (cdr pair)))) - (second (or processed-params (org-babel-process-params params))) "\n") + (nth 1 (or processed-params (org-babel-process-params params))) "\n") "\n" (org-babel-trim body) "\n")) (defun org-babel-execute:python (body params) @@ -53,8 +53,8 @@ called by `org-babel-execute-src-block'." (message "executing Python source code block") (let* ((processed-params (org-babel-process-params params)) (session (org-babel-python-initiate-session (first processed-params))) - (result-params (third processed-params)) - (result-type (fourth processed-params)) + (result-params (nth 2 processed-params)) + (result-type (nth 3 processed-params)) (full-body (org-babel-expand-body:python body params processed-params)) ;; then the source block body (result (org-babel-python-evaluate session full-body result-type))) diff --git a/lisp/babel/langs/ob-ruby.el b/lisp/babel/langs/ob-ruby.el index 3dcdd1fe0..d525bbe47 100644 --- a/lisp/babel/langs/ob-ruby.el +++ b/lisp/babel/langs/ob-ruby.el @@ -46,7 +46,7 @@ (defun org-babel-expand-body:ruby (body params &optional processed-params) "Expand BODY according to PARAMS, return the expanded body." - (let ((vars (second (or processed-params (org-babel-process-params params))))) + (let ((vars (nth 1 (or processed-params (org-babel-process-params params))))) (concat (mapconcat ;; define any variables (lambda (pair) @@ -61,8 +61,8 @@ called by `org-babel-execute-src-block'." (message "executing Ruby source code block") (let* ((processed-params (org-babel-process-params params)) (session (org-babel-ruby-initiate-session (first processed-params))) - (result-params (third processed-params)) - (result-type (fourth processed-params)) + (result-params (nth 2 processed-params)) + (result-type (nth 3 processed-params)) (full-body (org-babel-expand-body:ruby body params processed-params)) (result (org-babel-ruby-evaluate session full-body result-type))) diff --git a/lisp/babel/langs/ob-screen.el b/lisp/babel/langs/ob-screen.el index 132476d7a..c7843565e 100644 --- a/lisp/babel/langs/ob-screen.el +++ b/lisp/babel/langs/ob-screen.el @@ -63,7 +63,7 @@ In case you want to use a different screen than one selected by your $PATH") "Prepare SESSION according to the header arguments specified in PARAMS." (let* ((processed-params (org-babel-process-params params)) (session (first processed-params)) - (vars (second processed-params)) + (vars (nth 1 processed-params)) (socket (org-babel-screen-session-socketname session)) (vars (org-babel-ref-variables params)) (cmd (cdr (assoc :cmd params))) From 41c832ef6ff7436a589195503349737b32dd0a27 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Fri, 25 Jun 2010 20:49:55 +0200 Subject: [PATCH 125/138] Fix typo --- doc/org.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/org.texi b/doc/org.texi index 0bf2f2b73..f3e88b8cf 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -5911,7 +5911,7 @@ the documentation for org-remember at The new capturing setup described here is preferred and should be used by new users. To convert your @code{org-remember-templates}, run the command @example -@kbd M-x org-capture-import-remember-templates RET +@kbd{M-x org-capture-import-remember-templates RET} @end example @noindent and then customize the new variable with @kbd{M-x customize-variable org-capture-templates}, check the result, and save the From 2b26cb4e4ec9b857c2b67ae865d1bc2967b8f3f2 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Fri, 25 Jun 2010 20:53:15 +0200 Subject: [PATCH 126/138] Fix bug with regexp target definition Patch by Juan Pechiar --- lisp/org-capture.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lisp/org-capture.el b/lisp/org-capture.el index 879dd25ea..03387c0ae 100644 --- a/lisp/org-capture.el +++ b/lisp/org-capture.el @@ -556,7 +556,7 @@ already gone." ((eq (car target) 'file+regexp) (set-buffer (org-capture-target-buffer (nth 1 target))) (goto-char (point-min)) - (if (re-search-forward (nth 1 target) nil t) + (if (re-search-forward (nth 2 target) nil t) (progn (goto-char (match-beginning 0)) (setq target-entry-p (and (org-mode-p) (org-at-heading-p)))) From 548b6f61050ff8b71b5dba2adab7648b2e541eef Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Fri, 25 Jun 2010 16:15:06 +0200 Subject: [PATCH 127/138] Add new utilities --- UTILITIES/git-changelog | 70 ++++++ UTILITIES/pw | 527 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 597 insertions(+) create mode 100755 UTILITIES/git-changelog create mode 100755 UTILITIES/pw diff --git a/UTILITIES/git-changelog b/UTILITIES/git-changelog new file mode 100755 index 000000000..e15374a50 --- /dev/null +++ b/UTILITIES/git-changelog @@ -0,0 +1,70 @@ +#!/usr/bin/env python + +# git-changelog +# +# version 2.0, by John Wiegley +# +# The purpose of this code is to turn "git log" output into a complete +# ChangeLog, for projects who wish to begin using a ChangeLog, but haven't +# been. +# +# This version of git-changelog depends on GitPython: +# git://gitorious.org/git-python/mainline.git + +import time +import string +import sys +import re +import os + +from git import * # GitPython +from subprocess import * + +repo = Repo(os.getcwd()) +ref = 'origin/master..' +path = '' + +# Usage: git changelog [COMMITISH] [-- [PATH]] + +saw_dashdash = False +if len(sys.argv) > 1: + for arg in sys.argv[1:]: + if arg == "--": + saw_dashdash = True + elif saw_dashdash: + path = arg + else: + ref = arg + +for commit in repo.iter_commits(ref, paths=path): + hash_id = commit.sha + author = commit.author + date = commit.committed_date + log_text = commit.message.split('\n')[0] + + log_text_remainder = commit.message.split('\n\n')[1:] + while len(log_text_remainder) > 0 and not log_text_remainder[0]: + log_text_remainder = log_text_remainder[1:] + log_text_remainder = string.join(log_text_remainder, '\n\t') + if log_text_remainder: + log_text_remainder = '\n\t' + log_text_remainder + + diff = commit.diff(commit.parents[0]) + files = [] + for f in diff: + p = f.a_blob.path or f.b_blob.path + 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)) + fp.stdin.close() + log_text = fp.stdout.read() + del fp + + print "%s %s <%s>\n\n%s%s" % \ + (time.strftime("%Y-%m-%d", time.gmtime(date)), + author.name, author.email, log_text, log_text_remainder) + +# git-changelog ends here diff --git a/UTILITIES/pw b/UTILITIES/pw new file mode 100755 index 000000000..890c72b82 --- /dev/null +++ b/UTILITIES/pw @@ -0,0 +1,527 @@ +#!/usr/bin/env python +# +# Patchwork command line client +# Copyright (C) 2008 Nate Case +# +# This file is part of the Patchwork package. +# +# Patchwork is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# Patchwork is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with Patchwork; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + +import os +import sys +import xmlrpclib +import getopt +import string +import tempfile +import subprocess +import base64 +import ConfigParser +import datetime +import re + +# Default Patchwork remote XML-RPC server URL +# This script will check the PW_XMLRPC_URL environment variable +# for the URL to access. If that is unspecified, it will fallback to +# the hardcoded default value specified here. +DEFAULT_URL = "http://patchwork/xmlrpc/" +CONFIG_FILES = [os.path.expanduser('~/.pwclientrc')] + +class Filter: + """Filter for selecting patches.""" + def __init__(self): + # These fields refer to specific objects, so they are special + # because we have to resolve them to IDs before passing the + # filter to the server + self.state = "" + self.project = "" + + # The dictionary that gets passed to via XML-RPC + self.d = {} + + def add(self, field, value): + if field == 'state': + self.state = value + elif field == 'project': + self.project = value + else: + # OK to add directly + self.d[field] = value + + def resolve_ids(self, rpc): + """Resolve State, Project, and Person IDs based on filter strings.""" + if self.state != "": + id = state_id_by_name(rpc, self.state) + if id == 0: + sys.stderr.write("Note: No State found matching %s*, " \ + "ignoring filter\n" % self.state) + else: + self.d['state_id'] = id + + if self.project != "": + id = project_id_by_name(rpc, self.project) + if id == 0: + sys.stderr.write("Note: No Project found matching %s, " \ + "ignoring filter\n" % self.project) + else: + self.d['project_id'] = id + + def __str__(self): + """Return human-readable description of the filter.""" + return str(self.d) + +class BasicHTTPAuthTransport(xmlrpclib.SafeTransport): + + def __init__(self, username = None, password = None, use_https = False): + self.username = username + self.password = password + self.use_https = use_https + xmlrpclib.SafeTransport.__init__(self) + + def authenticated(self): + return self.username != None and self.password != None + + def send_host(self, connection, host): + xmlrpclib.Transport.send_host(self, connection, host) + if not self.authenticated(): + return + credentials = '%s:%s' % (self.username, self.password) + auth = 'Basic ' + base64.encodestring(credentials).strip() + connection.putheader('Authorization', auth) + + def make_connection(self, host): + if self.use_https: + fn = xmlrpclib.SafeTransport.make_connection + else: + fn = xmlrpclib.Transport.make_connection + return fn(self, host) + +def usage(): + sys.stderr.write("Usage: %s [options]\n\n" % \ + (os.path.basename(sys.argv[0]))) + sys.stderr.write("Where is one of:\n") + sys.stderr.write( +""" apply : Apply a patch (in the current dir, using -p1) + get : Download a patch and save it locally + projects : List all projects + states : Show list of potential patch states + list [str] : List patches, using the optional filters specified + below and an optional substring to search for patches + by name + search [str] : Same as 'list' + view : View a patch + update [-s state] [-c commit-ref] + : Update patch\n""") + sys.stderr.write("""\nFilter options for 'list' and 'search': + -s : Filter by patch state (e.g., 'New', 'Accepted', etc.) + -p : Filter by project name (see 'projects' for list) + -w : Filter by submitter (name, e-mail substring search) + -d : Filter by delegate (name, e-mail substring search) + -n : Restrict number of results\n""") + sys.stderr.write("""\nActions that take an ID argument can also be \ +invoked with: + -h : Lookup by patch hash\n""") + sys.exit(1) + +def project_id_by_name(rpc, linkname): + """Given a project short name, look up the Project ID.""" + if len(linkname) == 0: + return 0 + projects = rpc.project_list(linkname, 0) + for project in projects: + if project['linkname'] == linkname: + return project['id'] + return 0 + +def state_id_by_name(rpc, name): + """Given a partial state name, look up the state ID.""" + if len(name) == 0: + return 0 + states = rpc.state_list(name, 0) + for state in states: + if state['name'].lower().startswith(name.lower()): + return state['id'] + return 0 + +def person_ids_by_name(rpc, name): + """Given a partial name or email address, return a list of the + person IDs that match.""" + if len(name) == 0: + return [] + people = rpc.person_list(name, 0) + return map(lambda x: x['id'], people) + +def list_patches(patches): + """Dump a list of patches to stdout.""" + print("%-5s %-12s %s" % ("ID", "State", "Name")) + print("%-5s %-12s %s" % ("--", "-----", "----")) + for patch in patches: + print("%-5d %-12s %s" % (patch['id'], patch['state'], patch['name'])) + +def action_list(rpc, filter, submitter_str, delegate_str): + filter.resolve_ids(rpc) + + if submitter_str != "": + ids = person_ids_by_name(rpc, submitter_str) + if len(ids) == 0: + sys.stderr.write("Note: Nobody found matching *%s*\n", \ + submitter_str) + else: + for id in ids: + person = rpc.person_get(id) + print "Patches submitted by %s <%s>:" % \ + (person['name'], person['email']) + f = filter + f.add("submitter_id", id) + patches = rpc.patch_list(f.d) + list_patches(patches) + return + + if delegate_str != "": + ids = person_ids_by_name(rpc, delegate_str) + if len(ids) == 0: + sys.stderr.write("Note: Nobody found matching *%s*\n", \ + delegate_str) + else: + for id in ids: + person = rpc.person_get(id) + print "Patches delegated to %s <%s>:" % \ + (person['name'], person['email']) + f = filter + f.add("delegate_id", id) + patches = rpc.patch_list(f.d) + list_patches(patches) + return + + patches = rpc.patch_list(filter.d) + list_patches(patches) + +def action_projects(rpc): + projects = rpc.project_list("", 0) + print("%-5s %-24s %s" % ("ID", "Name", "Description")) + print("%-5s %-24s %s" % ("--", "----", "-----------")) + for project in projects: + print("%-5d %-24s %s" % (project['id'], \ + project['linkname'], \ + project['name'])) + +def action_states(rpc): + states = rpc.state_list("", 0) + print("%-5s %s" % ("ID", "Name")) + print("%-5s %s" % ("--", "----")) + for state in states: + print("%-5d %s" % (state['id'], state['name'])) + +def action_get(rpc, patch_id): + patch = rpc.patch_get(patch_id) + s = rpc.patch_get_mbox(patch_id) + + if patch == {} or len(s) == 0: + sys.stderr.write("Unable to get patch %d\n" % patch_id) + sys.exit(1) + + base_fname = fname = os.path.basename(patch['filename']) + i = 0 + while os.path.exists(fname): + fname = "%s.%d" % (base_fname, i) + i += 1 + + try: + f = open(fname, "w") + except: + sys.stderr.write("Unable to open %s for writing\n" % fname) + sys.exit(1) + + try: + f.write(unicode(s).encode("utf-8")) + f.close() + print "Saved patch to %s" % fname + except: + sys.stderr.write("Failed to write to %s\n" % fname) + sys.exit(1) + +def action_apply(rpc, patch_id): + patch = rpc.patch_get(patch_id) + if patch == {}: + sys.stderr.write("Error getting information on patch ID %d\n" % \ + patch_id) + sys.exit(1) + print "Applying patch #%d to current directory" % patch_id + print "Description: %s" % patch['name'] + s = rpc.patch_get_mbox(patch_id) + if len(s) > 0: + proc = subprocess.Popen(['patch', '-p1'], stdin = subprocess.PIPE) + proc.communicate(s) + else: + sys.stderr.write("Error: No patch content found\n") + sys.exit(1) + +def action_update_patch(rpc, patch_id, state = None, commit = None): + patch = rpc.patch_get(patch_id) + if patch == {}: + sys.stderr.write("Error getting information on patch ID %d\n" % \ + patch_id) + sys.exit(1) + + params = {} + + if state: + state_id = state_id_by_name(rpc, state) + if state_id == 0: + sys.stderr.write("Error: No State found matching %s*\n" % state) + sys.exit(1) + params['state'] = state_id + + if commit: + params['commit_ref'] = commit + + success = False + try: + success = rpc.patch_set(patch_id, params) + except xmlrpclib.Fault, f: + sys.stderr.write("Error updating patch: %s\n" % f.faultString) + + if not success: + sys.stderr.write("Patch not updated\n") + +def patch_id_from_hash(rpc, project, hash): + try: + patch = rpc.patch_get_by_project_hash(project, hash) + except xmlrpclib.Fault: + # the server may not have the newer patch_get_by_project_hash function, + # so fall back to hash-only. + patch = rpc.patch_get_by_hash(hash) + + if patch == {}: + return None + + return patch['id'] + +def branch_with(patch_id, rpc): + s = rpc.patch_get_mbox(patch_id) + if len(s) > 0: + print unicode(s).encode("utf-8") + + patch = rpc.patch_get(patch_id) + + # Find the latest commit from the day before the patch + proc = subprocess.Popen(['git', 'log', '--until=' + patch['date'], + '-1', '--format=%H', 'master'], + stdout = subprocess.PIPE) + sha = proc.stdout.read()[:-1] + + # Create a topic branch named after this commit + proc = subprocess.Popen(['git', 'checkout', '-b', 't/patch%s' % + patch_id, sha]) + sts = os.waitpid(proc.pid, 0) + if sts[1] != 0: + sys.stderr.write("Could not create branch for patch\n") + return + + # Apply the patch to the branch + fname = '/tmp/patch' + try: + f = open(fname, "w") + except: + sys.stderr.write("Unable to open %s for writing\n" % fname) + sys.exit(1) + + try: + f.write(unicode(s).encode("utf-8")) + f.close() + print "Saved patch to %s" % fname + except: + sys.stderr.write("Failed to write to %s\n" % fname) + sys.exit(1) + + proc = subprocess.Popen(['git', 'am', '/tmp/patch']) + sts = os.waitpid(proc.pid, 0) + if sts[1] != 0: + sys.stderr.write("Failed to apply patch to branch\n") + proc = subprocess.Popen(['git', 'checkout', 'master']) + os.waitpid(proc.pid, 0) + proc = subprocess.Popen(['git', 'branch', '-D', 't/patch%s' % + patch_id, sha]) + os.waitpid(proc.pid, 0) + return + + proc = subprocess.Popen(['git', 'rebase', 'master']) + sts = os.waitpid(proc.pid, 0) + + print sha + +auth_actions = ['update'] + +def main(): + try: + opts, args = getopt.getopt(sys.argv[2:], 's:p:w:d:n:c:h:') + except getopt.GetoptError, err: + print str(err) + usage() + + if len(sys.argv) < 2: + usage() + + action = sys.argv[1].lower() + + # set defaults + filt = Filter() + submitter_str = "" + delegate_str = "" + project_str = "" + commit_str = "" + state_str = "New" + hash_str = "" + url = DEFAULT_URL + + config = ConfigParser.ConfigParser() + config.read(CONFIG_FILES) + + # grab settings from config files + if config.has_option('base', 'url'): + url = config.get('base', 'url') + + if config.has_option('base', 'project'): + project_str = config.get('base', 'project') + + for name, value in opts: + if name == '-s': + state_str = value + elif name == '-p': + project_str = value + elif name == '-w': + submitter_str = value + elif name == '-d': + delegate_str = value + elif name == '-c': + commit_str = value + elif name == '-h': + hash_str = value + elif name == '-n': + try: + filt.add("max_count", int(value)) + except: + sys.stderr.write("Invalid maximum count '%s'\n" % value) + usage() + else: + sys.stderr.write("Unknown option '%s'\n" % name) + usage() + + if len(args) > 1: + sys.stderr.write("Too many arguments specified\n") + usage() + + (username, password) = (None, None) + transport = None + if action in auth_actions: + if config.has_option('auth', 'username') and \ + config.has_option('auth', 'password'): + + use_https = url.startswith('https') + + transport = BasicHTTPAuthTransport( \ + config.get('auth', 'username'), + config.get('auth', 'password'), + use_https) + + else: + sys.stderr.write(("The %s action requires authentication, " + "but no username or password\nis configured\n") % action) + sys.exit(1) + + if project_str: + filt.add("project", project_str) + + if state_str: + filt.add("state", state_str) + + try: + rpc = xmlrpclib.Server(url, transport = transport) + except: + sys.stderr.write("Unable to connect to %s\n" % url) + sys.exit(1) + + patch_id = None + if hash_str: + patch_id = patch_id_from_hash(rpc, project_str, hash_str) + if patch_id is None: + sys.stderr.write("No patch has the hash provided\n") + sys.exit(1) + + + if action == 'list' or action == 'search': + if len(args) > 0: + filt.add("name__icontains", args[0]) + action_list(rpc, filt, submitter_str, delegate_str) + + elif action.startswith('project'): + action_projects(rpc) + + elif action.startswith('state'): + action_states(rpc) + + elif action == 'branch': + try: + patch_id = patch_id or int(args[0]) + except: + sys.stderr.write("Invalid patch ID given\n") + sys.exit(1) + + branch_with(patch_id, rpc) + + elif action == 'view': + try: + patch_id = patch_id or int(args[0]) + except: + sys.stderr.write("Invalid patch ID given\n") + sys.exit(1) + + s = rpc.patch_get_mbox(patch_id) + if len(s) > 0: + print unicode(s).encode("utf-8") + + elif action == 'get' or action == 'save': + try: + patch_id = patch_id or int(args[0]) + except: + sys.stderr.write("Invalid patch ID given\n") + sys.exit(1) + + action_get(rpc, patch_id) + + elif action == 'apply': + try: + patch_id = patch_id or int(args[0]) + except: + sys.stderr.write("Invalid patch ID given\n") + sys.exit(1) + + action_apply(rpc, patch_id) + + elif action == 'update': + try: + patch_id = patch_id or int(args[0]) + except: + sys.stderr.write("Invalid patch ID given\n") + sys.exit(1) + + action_update_patch(rpc, patch_id, state = state_str, + commit = commit_str) + + else: + sys.stderr.write("Unknown action '%s'\n" % action) + usage() + +if __name__ == "__main__": + main() From 8c17c53002cbe6a582092735cccf20695e0f2896 Mon Sep 17 00:00:00 2001 From: Julien Danjou Date: Mon, 21 Jun 2010 17:29:20 +0000 Subject: [PATCH 128/138] Fix missing : in documentation Signed-off-by: Julien Danjou --- doc/org.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/org.texi b/doc/org.texi index 1f8b4206d..c7d510e47 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -6825,7 +6825,7 @@ following to one your your agenda files: * Anniversaries :PROPERTIES: :CATEGORY: Anniv - :END + :END: %%(org-bbdb-anniversaries) @end example From bbfca4a0e43fdc843375e5073a7cb10cf919d18e Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Sat, 26 Jun 2010 07:17:57 +0200 Subject: [PATCH 129/138] Clean up when aborting capture template selection * lisp/org.el (org-switch-to-buffer-other-window): Return the buffer. Patch by Sebastian Rose. --- lisp/org-mks.el | 16 ++++++++-------- lisp/org.el | 3 ++- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/lisp/org-mks.el b/lisp/org-mks.el index abf5e799e..4a49a2b61 100644 --- a/lisp/org-mks.el +++ b/lisp/org-mks.el @@ -48,15 +48,13 @@ under this key will be shown and offered for selection. TITLE will be placed over the selection in the temporary buffer, PROMPT will be used when prompting for a key. SPECIAL is an alist with -also (\"key\" \"description\") entries. When they are selected, - - -" +also (\"key\" \"description\") entries. When one of these is selection, +only the bare key is returned." (setq prompt (or prompt "Select: ")) (let (tbl orig-table dkey ddesc des-keys allowed-keys - current prefix rtn re pressed) + current prefix rtn re pressed buffer (inhibit-quit t)) (save-window-excursion - (org-switch-to-buffer-other-window "*Org Select*") + (setq buffer (org-switch-to-buffer-other-window "*Org Select*")) (setq orig-table table) (catch 'exit (while t @@ -104,7 +102,9 @@ also (\"key\" \"description\") entries. When they are selected, (message "Invalid key `%s'" pressed) (sit-for 1) (message prompt) (setq pressed (char-to-string (read-char-exclusive)))) - (if (equal pressed "\C-g") (error "Abort")) + (when (equal pressed "\C-g") + (kill-buffer buffer) + (error "Abort")) (when (and (not (assoc pressed table)) (not (member pressed des-keys)) (assoc pressed specials)) @@ -121,7 +121,7 @@ also (\"key\" \"description\") entries. When they are selected, nil)) table)) (setq table (remove nil table))))) - (kill-buffer "*Org Select*") + (when buffer (kill-buffer buffer)) rtn)) (provide 'org-mks) diff --git a/lisp/org.el b/lisp/org.el index 7bb4f45d7..517f7823d 100644 --- a/lisp/org.el +++ b/lisp/org.el @@ -18143,7 +18143,8 @@ return nil." (defun org-switch-to-buffer-other-window (&rest args) "Switch to buffer in a second window on the current frame. -In particular, do not allow pop-up frames." +In particular, do not allow pop-up frames. +Returns the newly created buffer." (let (pop-up-frames special-display-buffer-names special-display-regexps special-display-function) (apply 'switch-to-buffer-other-window args))) From bcb7f7f1ef0d3e6bf1123d65537c5d177307e87e Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Sat, 26 Jun 2010 07:54:07 +0200 Subject: [PATCH 130/138] Introduce a way to set a property to undefined. * lisp/org-macs.el (org-not-nil): Return the value if not interpreted as nil. * lisp/org.el (org-entry-get): (org-entry-get-with-inheritance): Interpret the value "nil" as nil for properties. Bernt Hansen writes: > Carsten Dominik writes: > > > On Jun 25, 2010, at 3:23 PM, Robert Goldman wrote: > > > > > Question: what is the proper way to get a NIL into a property? Are > > > we > > > to use () instead of "nil"? Or are property values always interpreted > > > as strings? > > > > > > Apologies in advance if this is a stupid question! > > > > Not a stupid question at all. > > > > There is no way, currently. Property values are string - the only > > way to make > > org-entry-get return nil is to not have the property defined at all. > > I've wanted a similar thing in the past for the LOGGING property where > the parent task has special logging set via the LOGGING property but I > want to undo that for some of the child tasks so they use the default > logging setup. > > Having a way to undefine a property would be good in general I think. -Bernt --- lisp/org-macs.el | 5 +++-- lisp/org.el | 23 +++++++++++++++-------- 2 files changed, 18 insertions(+), 10 deletions(-) diff --git a/lisp/org-macs.el b/lisp/org-macs.el index ad1fab50b..20430458b 100644 --- a/lisp/org-macs.el +++ b/lisp/org-macs.el @@ -44,8 +44,9 @@ `(and (boundp (quote ,var)) ,var)) (defun org-not-nil (v) - "Is V not nil, and also not the string \"nil\"?" - (and v (not (equal v "nil")))) + "If V not nil, and also not the string \"nil\", then return V. +Otherwise return nil." + (and v (not (equal v "nil")) v)) (defmacro org-unmodified (&rest body) "Execute body without changing `buffer-modified-p'. diff --git a/lisp/org.el b/lisp/org.el index 517f7823d..31cc94cf6 100644 --- a/lisp/org.el +++ b/lisp/org.el @@ -13352,14 +13352,18 @@ things up because then unnecessary parsing is avoided." (push (cons "CATEGORY" value) props)) (append sum-props (nreverse props))))))) -(defun org-entry-get (pom property &optional inherit) +(defun org-entry-get (pom property &optional inherit literal-nil) "Get value of PROPERTY for entry at point-or-marker POM. If INHERIT is non-nil and the entry does not have the property, then also check higher levels of the hierarchy. If INHERIT is the symbol `selective', use inheritance only if the setting in `org-use-property-inheritance' selects PROPERTY for inheritance. If the property is present but empty, the return value is the empty string. -If the property is not present at all, nil is returned." +If the property is not present at all, nil is returned. + +If LITERAL-NIL is set, return the string value \"nil\" as a string, +do not interpret it as the list atom nil. This is used for inheritance +when a \"nil\" value can supercede a non-nil value higher up the hierarchy." (org-with-point-at pom (if (and inherit (if (eq inherit 'selective) (org-property-inherit-p property) @@ -13377,7 +13381,9 @@ If the property is not present at all, nil is returned." (cdr range) t)) ;; Found the property, return it. (if (match-end 1) - (org-match-string-no-properties 1) + (if literal-nil + (org-match-string-no-properties 1) + (org-not-nil (org-match-string-no-properties 1))) ""))))))) (defun org-property-or-variable-value (var &optional inherit) @@ -13481,15 +13487,16 @@ is set.") (widen) (catch 'ex (while t - (when (setq tmp (org-entry-get nil property)) + (when (setq tmp (org-entry-get nil property nil 'literal-nil)) (org-back-to-heading t) (move-marker org-entry-property-inherited-from (point)) (throw 'ex tmp)) (or (org-up-heading-safe) (throw 'ex nil))))) - (or tmp - (cdr (assoc property org-file-properties)) - (cdr (assoc property org-global-properties)) - (cdr (assoc property org-global-properties-fixed)))))) + (org-not-nil + (or tmp + (cdr (assoc property org-file-properties)) + (cdr (assoc property org-global-properties)) + (cdr (assoc property org-global-properties-fixed))))))) (defvar org-property-changed-functions nil "Hook called when the value of a property has changed. From d3e3a3ce0aa8bcd08b15aded7b93d9ab51c49a9b Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Sat, 26 Jun 2010 07:59:00 +0200 Subject: [PATCH 131/138] Document nil as a special property value --- doc/org.texi | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/org.texi b/doc/org.texi index 0f321bfe4..bc1be059b 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -4629,7 +4629,9 @@ useful, you can turn it on by setting the variable @code{org-use-property-inheritance}. It may be set to @code{t} to make all properties inherited from the parent, to a list of properties that should be inherited, or to a regular expression that matches -inherited properties. +inherited properties. If a property has the value @samp{nil}, this is +interpreted as an explicit undefine of he property, so that inheritance +search will stop at this value and return @code{nil}. Org mode has a few properties for which inheritance is hard-coded, at least for the special applications for which they are used: From d325d0c255f02250e17ee3fbe066205c852b86ec Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Sat, 26 Jun 2010 13:13:14 +0200 Subject: [PATCH 132/138] Implement patch by Stefan Monnier --- lisp/org.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lisp/org.el b/lisp/org.el index 31cc94cf6..679804565 100644 --- a/lisp/org.el +++ b/lisp/org.el @@ -8635,7 +8635,7 @@ Use TAB to complete link prefixes, then RET for type-specific completion support (save-match-data (if (string-match (concat "^" (regexp-quote (file-name-as-directory - (expand-file-name ".")))) + default-directory))) (expand-file-name path)) ;; We are linking a file with relative path name. (setq path (substring (expand-file-name path) From ec51d1fee3f201b9b560869ed3f2467477bcb42a Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Sun, 27 Jun 2010 00:23:08 +0200 Subject: [PATCH 133/138] Clean up capitalization of headings in the manual Patch by Thomas S Dye. --- doc/org.texi | 470 +++++++++++++++++++++++++++------------------------ 1 file changed, 245 insertions(+), 225 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index bc1be059b..05ec6c4b8 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -129,7 +129,7 @@ Introduction * Feedback:: Bug reports, ideas, patches etc. * Conventions:: Type-setting conventions in the manual -Document Structure +Document structure * Outlines:: Org is based on Outline mode * Headlines:: How to typeset Org tree headlines @@ -178,7 +178,7 @@ Internal links * Radio targets:: Make targets trigger links in plain text -TODO Items +TODO items * TODO basics:: Marking and displaying TODO entries * TODO extensions:: Workflow and assignments @@ -209,10 +209,10 @@ Tags * Setting tags:: How to assign tags to a headline * Tag searches:: Searching for combinations of tags -Properties and Columns +Properties and columns * Property syntax:: How properties are spelled out -* Special properties:: Access to other Org mode features +* Special properties:: Access to other Org-mode features * Property searches:: Matching property values * Property inheritance:: Passing values down the tree * Column view:: Tabular viewing and editing @@ -229,7 +229,7 @@ Defining columns * Scope of column definitions:: Where defined, where valid? * Column attributes:: Appearance and content of a column -Dates and Times +Dates and times * Timestamps:: Assigning a time to a tree entry * Creating timestamps:: Commands which insert timestamps @@ -241,7 +241,7 @@ Dates and Times Creating timestamps -* The date/time prompt:: How Org mode helps you entering date and time +* The date/time prompt:: How Org-mode helps you entering date and time * Custom time format:: Making dates look different Deadlines and scheduling @@ -274,7 +274,7 @@ Archiving * Moving subtrees:: Moving a tree to an archive file * Internal archiving:: Switch off a tree but keep it in the file -Agenda Views +Agenda views * Agenda files:: Files being searched for agenda information * Agenda dispatcher:: Keyboard access to agenda views @@ -354,7 +354,7 @@ Exporting HTML export * HTML Export commands:: How to invoke HTML export -* Quoting HTML tags:: Using direct HTML in Org mode +* Quoting HTML tags:: Using direct HTML in Org-mode * Links in HTML export:: How links will be interpreted and formatted * Tables in HTML export:: How to modify the formatting of tables * Images in HTML export:: How to insert figures into HTML output @@ -403,7 +403,7 @@ Sample configuration * Simple example:: One-component publishing * Complex example:: A multi-component publishing example -Working With Source Code +Working with source code * Structure of code blocks:: Code block syntax described * Editing source code:: Language major-mode editing @@ -446,6 +446,7 @@ Specific header arguments * hlines:: Handle horizontal lines in tables * colnames:: Handle column names in tables * rownames:: Handle row names in tables +* shebang:: Make tangled files executable Miscellaneous @@ -687,9 +688,9 @@ active. You can do this with either one of the following two lines (add-hook 'org-mode-hook 'turn-on-font-lock) ; Org buffers only @end lisp -@cindex Org mode, turning on +@cindex Org-mode, turning on With this setup, all files with extension @samp{.org} will be put -into Org mode. As an alternative, make the first line of a file look +into Org-mode. As an alternative, make the first line of a file look like this: @example @@ -697,7 +698,7 @@ MY PROJECTS -*- mode: org; -*- @end example @vindex org-insert-mode-line-in-empty-file -@noindent which will select Org mode for this buffer no matter what +@noindent which will select Org-mode for this buffer no matter what the file's name is. See also the variable @code{org-insert-mode-line-in-empty-file}. @@ -800,7 +801,7 @@ special meaning are written with all capitals. @end table @node Document Structure, Tables, Introduction, Top -@chapter Document Structure +@chapter Document structure @cindex document structure @cindex structure of document @@ -1198,7 +1199,7 @@ functionality. @vindex org-show-following-heading @vindex org-show-siblings @vindex org-show-entry-below -An important feature of Org mode is the ability to construct @emph{sparse +An important feature of Org-mode is the ability to construct @emph{sparse trees} for selected information in an outline tree, so that the entire document is folded as much as possible, but the selected information is made visible along with the headline structure above it@footnote{See also the @@ -1207,7 +1208,7 @@ variables @code{org-show-hierarchy-above}, @code{org-show-following-heading}, control on how much context is shown around each match.}. Just try it out and you will see immediately how it works. -Org mode contains several commands creating such trees, all these +Org-mode contains several commands creating such trees, all these commands can be accessed through a dispatcher: @table @kbd @@ -1443,7 +1444,7 @@ numerically, alphabetically, by time, or by custom function. @vindex org-drawers Sometimes you want to keep information associated with an entry, but you -normally don't want to see it. For this, Org mode has @emph{drawers}. +normally don't want to see it. For this, Org-mode has @emph{drawers}. Drawers need to be configured with the variable @code{org-drawers}@footnote{You can define drawers on a per-file basis with a line like @code{#+DRAWERS: HIDDEN PROPERTIES STATE}}. Drawers @@ -1461,7 +1462,7 @@ look like this: Visibility cycling (@pxref{Visibility cycling}) on the headline will hide and show the entry, but keep the drawer collapsed to a single line. In order to look inside the drawer, you need to move the cursor to the drawer line and -press @key{TAB} there. Org mode uses the @code{PROPERTIES} drawer for +press @key{TAB} there. Org-mode uses the @code{PROPERTIES} drawer for storing properties (@pxref{Properties and Columns}), and you can also arrange for state change notes (@pxref{Tracking TODO state changes}) and clock times (@pxref{Clocking work time}) to be stored in a drawer @code{LOGBOOK}. If you @@ -1497,8 +1498,8 @@ or on a per-file basis by using @section Footnotes @cindex footnotes -Org mode supports the creation of footnotes. In contrast to the -@file{footnote.el} package, Org mode's footnotes are designed for work on a +Org-mode supports the creation of footnotes. In contrast to the +@file{footnote.el} package, Org-mode's footnotes are designed for work on a larger document, not only for one-off documents like emails. The basic syntax is similar to the one used by @file{footnote.el}, i.e. a footnote is defined in a paragraph that is started by a footnote marker in square @@ -1512,7 +1513,7 @@ The Org homepage[fn:1] now looks a lot better than it used to. [fn:1] The link is: http://orgmode.org @end example -Org mode extends the number-based syntax to @emph{named} footnotes and +Org-mode extends the number-based syntax to @emph{named} footnotes and optional inline definition. Using plain numbers as markers (as @file{footnote.el} does) is supported for backward compatibility, but not encouraged because of possible conflicts with La@TeX{} snippets (@pxref{Embedded @@ -1606,7 +1607,7 @@ you can use the usual commands to follow these links. @cindex Orgstruct mode @cindex minor mode for structure editing -If you like the intuitive way the Org mode structure editing and list +If you like the intuitive way the Org-mode structure editing and list formatting works, you might want to use these commands in other modes like Text mode or Mail mode as well. The minor mode @code{orgstruct-mode} makes this possible. Toggle the mode with @kbd{M-x orgstruct-mode}, or @@ -2816,7 +2817,7 @@ headlines@footnote{To insert a link targeting a headline, in-buffer completion can be used. Just type a star followed by a few optional letters into the buffer and press @kbd{M-@key{TAB}}. All headlines in the current buffer will be offered as completions. @xref{Handling links}, for more -commands creating links.}. When searching, Org mode will first try an +commands creating links.}. When searching, Org-mode will first try an exact match, but then move on to more and more lenient searches. For example, the link @samp{[[*My Targets]]} will find any of the following: @@ -3236,7 +3237,7 @@ Link to a heading with a @code{CUSTOM_ID} property @item /regexp/ Do a regular expression search for @code{regexp}. This uses the Emacs command @code{occur} to list all matches in a separate window. If the -target file is in Org mode, @code{org-occur} is used to create a +target file is in Org-mode, @code{org-occur} is used to create a sparse tree with the matches. @c If the target file is a directory, @c @code{grep} will be used to search all files in the directory. @@ -3272,10 +3273,10 @@ for Bib@TeX{} database files, and you can use the corresponding code as an implementation example. See the file @file{org-bibtex.el}. @node TODO Items, Tags, Hyperlinks, Top -@chapter TODO Items +@chapter TODO items @cindex TODO items -Org mode does not maintain TODO lists as separate documents@footnote{Of +Org-mode does not maintain TODO lists as separate documents@footnote{Of course, you can make a document that contains only long lists of TODO items, but this is not required.}. Instead, TODO items are an integral part of the notes file, because TODO items usually come up while taking notes! With Org @@ -3284,7 +3285,7 @@ information is not duplicated, and the entire context from which the TODO item emerged is always present. Of course, this technique for managing TODO items scatters them -throughout your notes file. Org mode compensates for this by providing +throughout your notes file. Org-mode compensates for this by providing methods to give you an overview of all the things that you have to do. @menu @@ -3376,7 +3377,7 @@ option @code{org-todo-state-tags-triggers} for details. @vindex org-todo-keywords By default, marked TODO entries have one of only two states: TODO and -DONE. Org mode allows you to classify TODO items in more complex ways +DONE. Org-mode allows you to classify TODO items in more complex ways with @emph{TODO keywords} (stored in @code{org-todo-keywords}). With special setup, the TODO keyword system can work differently in different files. @@ -3401,7 +3402,7 @@ TODO items in particular (@pxref{Tags}). You can use TODO keywords to indicate different @emph{sequential} states in the process of working on an item, for example@footnote{Changing -this variable only becomes effective after restarting Org mode in a +this variable only becomes effective after restarting Org-mode in a buffer.}: @lisp @@ -3444,7 +3445,7 @@ be set up like this: In this case, different keywords do not indicate a sequence, but rather different types. So the normal work flow would be to assign a task to a -person, and later to mark it DONE. Org mode supports this style by adapting +person, and later to mark it DONE. Org-mode supports this style by adapting the workings of the command @kbd{C-c C-t}@footnote{This is also true for the @kbd{t} command in the timeline and agenda buffers.}. When used several times in succession, it will still cycle through all names, in order to first @@ -3475,7 +3476,7 @@ like this: (sequence "|" "CANCELED"))) @end lisp -The keywords should all be different, this helps Org mode to keep track +The keywords should all be different, this helps Org-mode to keep track of which subsequence should be used for a given entry. In this setup, @kbd{C-c C-t} only operates within a subsequence, so it switches from @code{DONE} to (nothing) to @code{TODO}, and from @code{FIXED} to @@ -3572,9 +3573,9 @@ Remember that the keywords after the vertical bar (or the last keyword if no bar is there) must always mean that the item is DONE (although you may use a different word). After changing one of these lines, use @kbd{C-c C-c} with the cursor still in the line to make the changes -known to Org mode@footnote{Org mode parses these lines only when -Org mode is activated after visiting a file. @kbd{C-c C-c} with the -cursor in a line starting with @samp{#+} is simply restarting Org mode +known to Org-mode@footnote{Org-mode parses these lines only when +Org-mode is activated after visiting a file. @kbd{C-c C-c} with the +cursor in a line starting with @samp{#+} is simply restarting Org-mode for the current buffer.}. @node Faces for TODO keywords, TODO dependencies, Per-file keywords, TODO extensions @@ -3584,7 +3585,7 @@ for the current buffer.}. @vindex org-todo @r{(face)} @vindex org-done @r{(face)} @vindex org-todo-keyword-faces -Org mode highlights TODO keywords with special faces: @code{org-todo} +Org-mode highlights TODO keywords with special faces: @code{org-todo} for keywords indicating that an item still has to be acted upon, and @code{org-done} for keywords indicating that an item is finished. If you are using more than 2 different states, you might want to use @@ -3674,7 +3675,7 @@ module @file{org-depend.el}. @cindex progress logging @cindex logging, of progress -Org mode can automatically record a timestamp and possibly a note when +Org-mode can automatically record a timestamp and possibly a note when you mark a TODO item as DONE, or even each time you change the state of a TODO item. This system is highly configurable, settings can be on a per-keyword basis and can be localized to a file or even a subtree. For @@ -3738,7 +3739,7 @@ behavior---the recommended drawer for this is called @code{LOGBOOK}. You can also overrule the setting of this variable for a subtree by setting a @code{LOG_INTO_DRAWER} property. -Since it is normally too much to record a note for every state, Org mode +Since it is normally too much to record a note for every state, Org-mode expects configuration on a per-keyword basis for this. This is achieved by adding special markers @samp{!} (for a timestamp) and @samp{@@} (for a note) in parentheses after each keyword. For example, with the setting @@ -3752,7 +3753,7 @@ in parentheses after each keyword. For example, with the setting @vindex org-log-done you not only define global TODO keywords and fast access keys, but also request that a time is recorded when the entry is set to -DONE@footnote{It is possible that Org mode will record two timestamps +DONE@footnote{It is possible that Org-mode will record two timestamps when you are using both @code{org-log-done} and state change logging. However, it will never prompt for two notes---if you have configured both, the state change recording note will take precedence and cancel @@ -3898,7 +3899,7 @@ which should only be done in certain contexts, for example. @section Priorities @cindex priorities -If you use Org mode extensively, you may end up with enough TODO items that +If you use Org-mode extensively, you may end up with enough TODO items that it starts to make sense to prioritize them. Prioritizing can be done by placing a @emph{priority cookie} into the headline of a TODO item, like this @@ -3908,11 +3909,11 @@ placing a @emph{priority cookie} into the headline of a TODO item, like this @noindent @vindex org-priority-faces -By default, Org mode supports three priorities: @samp{A}, @samp{B}, and +By default, Org-mode supports three priorities: @samp{A}, @samp{B}, and @samp{C}. @samp{A} is the highest priority. An entry without a cookie is treated as priority @samp{B}. Priorities make a difference only in the agenda (@pxref{Weekly/daily agenda}); outside the agenda, they have no -inherent meaning to Org mode. The cookies can be highlighted with special +inherent meaning to Org-mode. The cookies can be highlighted with special faces by customizing the variable @code{org-priority-faces}. Priorities can be attached to any outline tree entries; they do not need @@ -4132,7 +4133,7 @@ entry twice (checkboxes with @kbd{C-c C-c}). @cindex sparse tree, tag based An excellent way to implement labels and contexts for cross-correlating -information is to assign @i{tags} to headlines. Org mode has extensive +information is to assign @i{tags} to headlines. Org-mode has extensive support for tags. @vindex org-tag-faces @@ -4212,7 +4213,7 @@ also a special command for inserting tags: @item C-c C-q @cindex completion, of tags @vindex org-tags-column -Enter new tags for the current headline. Org mode will either offer +Enter new tags for the current headline. Org-mode will either offer completion or a special single-key interface for setting tags, see below. After pressing @key{RET}, the tags will be inserted and aligned to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all @@ -4256,7 +4257,7 @@ by adding a STARTUP option line to that file: #+STARTUP: noptag @end example -By default Org mode uses the standard minibuffer completion facilities for +By default Org-mode uses the standard minibuffer completion facilities for entering tags. However, it also implements another, quicker, tag selection method called @emph{fast tag selection}. This allows you to select and deselect tags with just a single key press. For this to work well you should @@ -4415,11 +4416,11 @@ and properties. For a complete description with many examples, see @node Properties and Columns, Dates and Times, Tags, Top -@chapter Properties and Columns +@chapter Properties and columns @cindex properties Properties are a set of key-value pairs associated with an entry. There -are two main applications for properties in Org mode. First, properties +are two main applications for properties in Org-mode. First, properties are like tags, but with a value. Second, you can use properties to implement (very basic) database capabilities in an Org buffer. For an example of the first application, imagine maintaining a file where @@ -4436,7 +4437,7 @@ Properties can be conveniently edited and viewed in column view @menu * Property syntax:: How properties are spelled out -* Special properties:: Access to other Org mode features +* Special properties:: Access to other Org-mode features * Property searches:: Matching property values * Property inheritance:: Passing values down the tree * Column view:: Tabular viewing and editing @@ -4534,7 +4535,7 @@ nearest column format definition. @section Special properties @cindex properties, special -Special properties provide an alternative access method to Org mode +Special properties provide an alternative access method to Org-mode features, like the TODO state or the priority of an entry, discussed in the previous chapters. This interface exists so that you can include these states in a column view (@pxref{Column view}), or to use them in @@ -4622,7 +4623,7 @@ a regular expression and matched against the property values. @vindex org-use-property-inheritance The outline structure of Org-mode documents lends itself for an inheritance model of properties: if the parent in a tree has a certain -property, the children can inherit this property. Org mode does not +property, the children can inherit this property. Org-mode does not turn this on by default, because it can slow down property searches significantly and is often not needed. However, if you find inheritance useful, you can turn it on by setting the variable @@ -4633,7 +4634,7 @@ inherited properties. If a property has the value @samp{nil}, this is interpreted as an explicit undefine of he property, so that inheritance search will stop at this value and return @code{nil}. -Org mode has a few properties for which inheritance is hard-coded, at +Org-mode has a few properties for which inheritance is hard-coded, at least for the special applications for which they are used: @cindex property, COLUMNS @@ -4664,7 +4665,7 @@ subtree (@pxref{Tracking TODO state changes}). A great way to view and edit properties in an outline tree is @emph{column view}. In column view, each outline node is turned into a table row. Columns in this table provide access to properties of the -entries. Org mode implements columns by overlaying a tabular structure +entries. Org-mode implements columns by overlaying a tabular structure over the headline of each item. While the headlines have been turned into a table row, you can still change the visibility of the outline tree. For example, you get a compact table by switching to CONTENTS @@ -4959,7 +4960,7 @@ features based on them. For more information see @ref{Using the property API}. @node Dates and Times, Capture - Refile - Archive, Properties and Columns, Top -@chapter Dates and Times +@chapter Dates and times @cindex dates @cindex times @cindex timestamp @@ -4967,9 +4968,9 @@ property API}. To assist project planning, TODO items can be labeled with a date and/or a time. The specially formatted string carrying the date and time -information is called a @emph{timestamp} in Org mode. This may be a +information is called a @emph{timestamp} in Org-mode. This may be a little confusing because timestamp is often used as indicating when -something was created or last changed. However, in Org mode this term +something was created or last changed. However, in Org-mode this term is used in a much wider sense. @menu @@ -5025,7 +5026,7 @@ following will show up in the agenda every Wednesday: @end example @item Diary-style sexp entries -For more complex date specifications, Org mode supports using the +For more complex date specifications, Org-mode supports using the special sexp diary entries implemented in the Emacs calendar/diary package. For example @@ -5064,7 +5065,7 @@ angular ones. These timestamps are inactive in the sense that they do @cindex creating timestamps @cindex timestamps, creating -For Org mode to recognize timestamps, they need to be in the specific +For Org-mode to recognize timestamps, they need to be in the specific format. All commands listed below produce timestamps in the correct format. @@ -5135,7 +5136,7 @@ the following column). @menu -* The date/time prompt:: How Org mode helps you entering date and time +* The date/time prompt:: How Org-mode helps you entering date and time * Custom time format:: Making dates look different @end menu @@ -5145,17 +5146,17 @@ the following column). @cindex time, reading in minibuffer @vindex org-read-date-prefer-future -When Org mode prompts for a date/time, the default is shown in default +When Org-mode prompts for a date/time, the default is shown in default date/time format, and the prompt therefore seems to ask for a specific format. But it will in fact accept any string containing some date and/or time information, and it is really smart about interpreting your input. You can, for example, use @kbd{C-y} to paste a (possibly multi-line) string -copied from an email message. Org mode will find whatever information is in +copied from an email message. Org-mode will find whatever information is in there and derive anything you have not specified from the @emph{default date and time}. The default is usually the current date and time, but when modifying an existing timestamp, or when entering the second stamp of a range, it is taken from the stamp in the buffer. When filling in -information, Org mode assumes that most of the time you will want to enter a +information, Org-mode assumes that most of the time you will want to enter a date in the future: if you omit the month/year and the given day/month is @i{before} today, it will assume that you mean a future date@footnote{See the variable @code{org-read-date-prefer-future}. You may set that variable to @@ -5164,7 +5165,7 @@ tomorrow.}. If the date has been automatically shifted into the future, the time prompt will show this with @samp{(=>F).} For example, let's assume that today is @b{June 13, 2006}. Here is how -various inputs will be interpreted, the items filled in by Org mode are +various inputs will be interpreted, the items filled in by Org-mode are in @b{bold}. @example @@ -5256,7 +5257,7 @@ minibuffer@footnote{If you find this distracting, turn the display of with @vindex org-display-custom-times @vindex org-time-stamp-custom-formats -Org mode uses the standard ISO notation for dates and times as it is +Org-mode uses the standard ISO notation for dates and times as it is defined in ISO 8601. If you cannot get used to this and require another representation of date and time to keep you happy, you can get it by customizing the variables @code{org-display-custom-times} and @@ -5269,7 +5270,7 @@ Toggle the display of custom formats for dates and times. @end table @noindent -Org mode needs the default format for scanning, so the custom date/time +Org-mode needs the default format for scanning, so the custom date/time format does not @emph{replace} the default format---instead it is put @emph{over} the default format using text properties. This has the following consequences: @@ -5346,23 +5347,23 @@ I.e. the task will automatically be forwarded until completed. @end example @noindent -@b{Important:} Scheduling an item in Org mode should @i{not} be +@b{Important:} Scheduling an item in Org-mode should @i{not} be understood in the same way that we understand @i{scheduling a meeting}. Setting a date for a meeting is just a simple appointment, you should mark this entry with a simple plain timestamp, to get this item shown on the date where it applies. This is a frequent misunderstanding by -Org users. In Org mode, @i{scheduling} means setting a date when you +Org users. In Org-mode, @i{scheduling} means setting a date when you want to start working on an action item. @end table You may use timestamps with repeaters in scheduling and deadline -entries. Org mode will issue early and late warnings based on the +entries. Org-mode will issue early and late warnings based on the assumption that the timestamp represents the @i{nearest instance} of the repeater. However, the use of diary sexp entries like @c @code{<%%(diary-float t 42)>} @c -in scheduling and deadline timestamps is limited. Org mode does not +in scheduling and deadline timestamps is limited. Org-mode does not know enough about the internals of each sexp function to issue early and late warnings. However, it will show the item on each day where the sexp entry matches. @@ -5435,7 +5436,7 @@ Sparse tree for deadlines and scheduled items after a given date. @cindex tasks, repeated @cindex repeated tasks -Some tasks need to be repeated again and again. Org mode helps to +Some tasks need to be repeated again and again. Org-mode helps to organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED, or plain timestamp. In the following example @example @@ -5455,7 +5456,7 @@ over-due, so it is important to be able to mark such an entry as completed once you have done so. When you mark a DEADLINE or a SCHEDULE with the TODO keyword DONE, it will no longer produce entries in the agenda. The problem with this is, however, that then also the @emph{next} instance of the -repeated entry will not be active. Org mode deals with this in the following +repeated entry will not be active. Org-mode deals with this in the following way: When you try to mark such an entry DONE (using @kbd{C-c C-t}), it will shift the base date of the repeating timestamp by the repeater interval, and immediately set the entry state back to TODO@footnote{In fact, the target @@ -5488,7 +5489,7 @@ task, this may not be the best way to handle it. For example, if you forgot to call you father for 3 weeks, it does not make sense to call him 3 times in a single day to make up for it. Finally, there are tasks like changing batteries which should always repeat a certain time -@i{after} the last time you did it. For these tasks, Org mode has +@i{after} the last time you did it. For these tasks, Org-mode has special repeaters markers with @samp{++} and @samp{.+}. For example: @example @@ -5515,7 +5516,7 @@ created for this purpose, it is described in @ref{Structure editing}. @node Clocking work time, Resolving idle time, Deadlines and scheduling, Dates and Times @section Clocking work time -Org mode allows you to clock the time you spend on specific tasks in a +Org-mode allows you to clock the time you spend on specific tasks in a project. When you start working on an item, you can start the clock. When you stop working on that task, or when you mark the task done, the clock is stopped and the corresponding time interval is recorded. It @@ -5913,7 +5914,7 @@ the documentation for org-remember at The new capturing setup described here is preferred and should be used by new users. To convert your @code{org-remember-templates}, run the command @example -@kbd{M-x org-capture-import-remember-templates RET} +@kbd{M-x org-capture-import-remember-templates @key{RET}} @end example @noindent and then customize the new variable with @kbd{M-x customize-variable org-capture-templates}, check the result, and save the @@ -6567,7 +6568,7 @@ outline. @node Agenda Views, Markup, Capture - Refile - Archive, Top -@chapter Agenda Views +@chapter Agenda views @cindex agenda views Due to the way Org works, TODO items, time-stamped items, and @@ -6814,7 +6815,7 @@ anniversaries, lunar phases, sunrise/set, recurrent appointments Org. It can be very useful to combine output from Org with the diary. -In order to include entries from the Emacs diary into Org mode's +In order to include entries from the Emacs diary into Org-mode's agenda, you only need to customize the variable @lisp @@ -6823,7 +6824,7 @@ agenda, you only need to customize the variable @noindent After that, everything will happen automatically. All diary entries including holidays, anniversaries, etc., will be included in the -agenda buffer created by Org mode. @key{SPC}, @key{TAB}, and +agenda buffer created by Org-mode. @key{SPC}, @key{TAB}, and @key{RET} can be used from the agenda buffer to jump to the diary file in order to edit existing diary entries. The @kbd{i} command to insert new entries for the current date works in the agenda buffer, as @@ -6834,7 +6835,7 @@ between calendar and agenda. If you are using the diary only for sexp entries and holidays, it is faster to not use the above setting, but instead to copy or even move -the entries into an Org file. Org mode evaluates diary-style sexp +the entries into an Org file. Org-mode evaluates diary-style sexp entries, and does it faster because there is no overhead for first creating the diary display. Note that the sexp entries must start at the left margin, no whitespace is allowed before them. For example, @@ -7094,7 +7095,7 @@ other properties will slow down the search. However, once you have paid the price by accessing one property, testing additional properties is cheap again. -You can configure Org mode to use property inheritance during a search, but +You can configure Org-mode to use property inheritance during a search, but beware that this can slow down searches considerably. See @ref{Property inheritance}, for details. @@ -7127,7 +7128,7 @@ Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or @cindex timeline, single file @cindex time-sorted view -The timeline summarizes all time-stamped items from a single Org mode +The timeline summarizes all time-stamped items from a single Org-mode file in a @emph{time-sorted view}. The main purpose of this command is to give an overview over events in a project. @@ -7149,7 +7150,7 @@ The commands available in the timeline buffer are listed in @cindex text search @cindex searching, for text -This agenda view is a general text search facility for Org mode entries. +This agenda view is a general text search facility for Org-mode entries. It is particularly useful to find notes. @table @kbd @@ -7181,7 +7182,7 @@ If you are following a system like David Allen's GTD to organize your work, one of the ``duties'' you have is a regular review to make sure that all projects move along. A @emph{stuck} project is a project that has no defined next actions, so it will never show up in the TODO lists -Org mode produces. During the review, you need to identify such +Org-mode produces. During the review, you need to identify such projects and define next actions for them. @table @kbd @@ -7200,7 +7201,7 @@ work for you. The built-in default assumes that all your projects are level-2 headlines, and that a project is not stuck if it has at least one entry marked with a TODO keyword TODO or NEXT or NEXTACTION. -Let's assume that you, in your own way of using Org mode, identify +Let's assume that you, in your own way of using Org-mode, identify projects with a tag PROJECT, and that you use a TODO keyword MAYBE to indicate a project that should not be considered yet. Let's further assume that the TODO keyword DONE marks finished projects, and that NEXT @@ -7227,7 +7228,7 @@ will still be searched for stuck projects. @cindex presentation, of agenda items @vindex org-agenda-prefix-format -Before displaying items in an agenda view, Org mode visually prepares +Before displaying items in an agenda view, Org-mode visually prepares the items and sorts them. Each item occupies a single line. The line starts with a @emph{prefix} that contains the @emph{category} (@pxref{Categories}) of the item and other important information. You can @@ -7274,7 +7275,7 @@ longer than 10 characters. @subsection Time-of-day specifications @cindex time-of-day specification -Org mode checks each agenda item for a time-of-day specification. The +Org-mode checks each agenda item for a time-of-day specification. The time can be part of the timestamp that triggered inclusion into the agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time ranges can be specified with two timestamps, like @@ -7286,7 +7287,7 @@ plain text (like @samp{12:45} or a @samp{8:30-1pm}). If the agenda integrates the Emacs diary (@pxref{Weekly/daily agenda}), time specifications in diary entries are recognized as well. -For agenda display, Org mode extracts the time and displays it in a +For agenda display, Org-mode extracts the time and displays it in a standard 24 hour format as part of the prefix. The example times in the previous paragraphs would end up in the agenda like this: @@ -7735,7 +7736,7 @@ agenda, change a tag for all headings in the region. @c @kindex , @item , -Set the priority for the current item. Org mode prompts for the +Set the priority for the current item. Org-mode prompts for the priority character. If you reply with @key{SPC}, the priority cookie is removed from the entry. @c @@ -7876,7 +7877,7 @@ d @r{Set deadline to a specific date.} Open the Emacs calendar and move to the date at the agenda cursor. @c @item c -When in the calendar, compute and show the Org mode agenda for the +When in the calendar, compute and show the Org-mode agenda for the date at the cursor. @c @cindex diary entries, creating from agenda @@ -8074,7 +8075,7 @@ command @kbd{C-c a o} provides a similar view for office tasks. @cindex options, for custom agenda views @vindex org-agenda-custom-commands -Org mode contains a number of variables regulating agenda construction +Org-mode contains a number of variables regulating agenda construction and display. The global variables define the behavior for all agenda commands, including the custom commands. However, if you want to change some settings just for a single custom view, you can do so. Setting @@ -8146,7 +8147,7 @@ yourself. @cindex agenda views, exporting If you are away from your computer, it can be very useful to have a printed -version of some agenda views to carry around. Org mode can export custom +version of some agenda views to carry around. Org-mode can export custom agenda views as plain text, HTML@footnote{You need to install Hrvoje Niksic's @file{htmlize.el}.}, Postscript, PDF@footnote{To create PDF output, the ghostscript @file{ps2pdf} utility must be installed on the system. Selecting @@ -8211,7 +8212,7 @@ or absolute. @end lisp The extension of the file name determines the type of export. If it is -@file{.html}, Org mode will use the @file{htmlize.el} package to convert +@file{.html}, Org-mode will use the @file{htmlize.el} package to convert the buffer to HTML and save it to this file name. If the extension is @file{.ps}, @code{ps-print-buffer-with-faces} is used to produce Postscript output. If the extension is @file{.ics}, iCalendar export is @@ -8345,7 +8346,7 @@ the agenda). When exporting Org-mode documents, the exporter tries to reflect the structure of the document as accurately as possible in the backend. Since export targets like HTML, La@TeX{}, or DocBook allow much richer formatting, -Org mode has rules on how to prepare text for rich export. This section +Org-mode has rules on how to prepare text for rich export. This section summarizes the markup rules used in an Org-mode buffer. @menu @@ -8438,7 +8439,7 @@ the table of contents entirely, by configuring the variable @cindex text before first headline, markup rules @cindex #+TEXT -Org mode normally exports the text before the first headline, and even uses +Org-mode normally exports the text before the first headline, and even uses the first line as the document title. The text will be fully marked up. If you need to include literal HTML, La@TeX{}, or DocBook code, use the special constructs described below in the sections for the individual exporters. @@ -8566,8 +8567,8 @@ Toggle the COMMENT keyword at the beginning of an entry. @cindex tables, markup rules @cindex #+CAPTION @cindex #+LABEL -Both the native Org mode tables (@pxref{Tables}) and tables formatted with -the @file{table.el} package will be exported properly. For Org mode tables, +Both the native Org-mode tables (@pxref{Tables}) and tables formatted with +the @file{table.el} package will be exported properly. For Org-mode tables, the lines before the first horizontal separator line will become table header lines. You can use the following lines somewhere before the table to assign a caption and a label for cross references, and in the text you can refer to @@ -8721,7 +8722,7 @@ include your @file{.emacs} file, you could use: The optional second and third parameter are the markup (e.g. @samp{quote}, @samp{example}, or @samp{src}), and, if the markup is @samp{src}, the language for formatting the contents. The markup is optional, if it is not -given, the text will be assumed to be in Org mode format and will be +given, the text will be assumed to be in Org-mode format and will be processed normally. The include line will also allow additional keyword parameters @code{:prefix1} and @code{:prefix} to specify prefixes for the first line and for each following line, as well as any options accepted by @@ -8791,12 +8792,12 @@ mathematical symbols and the occasional formula. La@TeX{}@footnote{La@TeX{} is a macro system based on Donald E. Knuth's @TeX{} system. Many of the features described here as ``La@TeX{}'' are really from @TeX{}, but for simplicity I am blurring this distinction.} is widely used to typeset -scientific documents. Org mode supports embedding La@TeX{} code into its +scientific documents. Org-mode supports embedding La@TeX{} code into its files, because many academics are used to reading La@TeX{} source code, and because it can be readily processed into images for HTML production. It is not necessary to mark La@TeX{} macros and code in any special way. -If you observe a few conventions, Org mode knows how to find it and what +If you observe a few conventions, Org-mode knows how to find it and what to do with it. @menu @@ -8820,7 +8821,7 @@ You can use La@TeX{} macros to insert special symbols like @samp{\alpha} to indicate the Greek letter, or @samp{\to} to indicate an arrow. Completion for these macros is available, just type @samp{\} and maybe a few letters, and press @kbd{M-@key{TAB}} to see possible completions. Unlike La@TeX{} -code, Org mode allows these macros to be present without surrounding math +code, Org-mode allows these macros to be present without surrounding math delimiters, for example: @example @@ -8900,7 +8901,7 @@ MathML, but that is not yet fully supported by many browsers, and there is no decent converter for turning La@TeX{} or ASCII representations of formulas into MathML. So for the time being, converting formulas into images seems the way to go.}. More complex expressions need a dedicated -formula processor. To this end, Org mode can contain arbitrary La@TeX{} +formula processor. To this end, Org-mode can contain arbitrary La@TeX{} fragments. It provides commands to preview the typeset result of these fragments, and upon export to HTML, all fragments will be converted to images and inlined into the HTML document@footnote{The La@TeX{} export @@ -8987,12 +8988,12 @@ setting is active: CDLa@TeX{} mode is a minor mode that is normally used in combination with a major La@TeX{} mode like AUC@TeX{} in order to speed-up insertion of -environments and math templates. Inside Org mode, you can make use of +environments and math templates. Inside Org-mode, you can make use of some of the features of CDLa@TeX{} mode. You need to install @file{cdlatex.el} and @file{texmathp.el} (the latter comes also with AUC@TeX{}) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}. -Don't use CDLa@TeX{} mode itself under Org mode, but use the light -version @code{org-cdlatex-mode} that comes as part of Org mode. Turn it +Don't use CDLa@TeX{} mode itself under Org-mode, but use the light +version @code{org-cdlatex-mode} that comes as part of Org-mode. Turn it on for the current buffer with @code{M-x org-cdlatex-mode}, or for all Org files with @@ -9009,7 +9010,7 @@ Environment templates can be inserted with @kbd{C-c @{}. @item @kindex @key{TAB} The @key{TAB} key will do template expansion if the cursor is inside a -La@TeX{} fragment@footnote{Org mode has a method to test if the cursor is +La@TeX{} fragment@footnote{Org-mode has a method to test if the cursor is inside such a fragment, see the documentation of the function @code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} will expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor @@ -9050,14 +9051,14 @@ Org-mode documents can be exported into a variety of other formats. For printing and sharing of notes, ASCII export produces a readable and simple version of an Org file. HTML export allows you to publish a notes file on the web, while the XOXO format provides a solid base for exchange with a -broad range of other applications. La@TeX{} export lets you use Org mode and +broad range of other applications. La@TeX{} export lets you use Org-mode and its structured editing functions to easily create La@TeX{} files. DocBook export makes it possible to convert Org files to many other formats using DocBook tools. For project management you can create gantt and resource charts by using TaskJuggler export. To incorporate entries with associated times like deadlines or appointments into a desktop calendar program like -iCal, Org mode can also produce extracts in the iCalendar format. Currently -Org mode only supports export, not import of these different formats. +iCal, Org-mode can also produce extracts in the iCalendar format. Currently +Org-mode only supports export, not import of these different formats. Org supports export of selected regions when @code{transient-mark-mode} is enabled (default in Emacs 23). @@ -9321,13 +9322,13 @@ the text and the link in a note before the next heading. See the variable @section HTML export @cindex HTML export -Org mode contains an HTML (XHTML 1.0 strict) exporter with extensive +Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive HTML formatting, in ways similar to John Gruber's @emph{markdown} language, but with additional support for tables. @menu * HTML Export commands:: How to invoke HTML export -* Quoting HTML tags:: Using direct HTML in Org mode +* Quoting HTML tags:: Using direct HTML in Org-mode * Links in HTML export:: How links will be interpreted and formatted * Tables in HTML export:: How to modify the formatting of tables * Images in HTML export:: How to insert figures into HTML output @@ -9669,7 +9670,7 @@ pages, configure the variable @code{org-export-html-use-infojs}. @cindex PDF export @cindex Guerry, Bastien -Org mode contains a La@TeX{} exporter written by Bastien Guerry. With +Org-mode contains a La@TeX{} exporter written by Bastien Guerry. With further processing@footnote{The default LaTeX output is designed for processing with pdftex or latex. It includes packages that are not compatible with xetex and possibly luatex. See the variables @@ -9715,11 +9716,11 @@ Export to a temporary buffer, do not create a file. @item C-c C-e v L Export only the visible part of the document. @item M-x org-export-region-as-latex -Convert the region to La@TeX{} under the assumption that it was Org mode +Convert the region to La@TeX{} under the assumption that it was Org-mode syntax before. This is a global command that can be invoked in any buffer. @item M-x org-replace-region-by-latex -Replace the active region (assumed to be in Org mode syntax) by La@TeX{} +Replace the active region (assumed to be in Org-mode syntax) by La@TeX{} code. @kindex C-c C-e p @item C-c C-e p @@ -10155,7 +10156,7 @@ set: @cindex #+LABEL @cindex #+ATTR_DOCBOOK @example -#+CAPTION: The logo of Org mode +#+CAPTION: The logo of Org-mode #+LABEL: unicorn-svg #+ATTR_DOCBOOK: scalefit="1" width="100%" depth="100%" [[./img/org-mode-unicorn.svg]] @@ -10343,7 +10344,7 @@ Export as Freemind mind map @file{myfile.mm}. @section XOXO export @cindex XOXO export -Org mode contains an exporter that produces XOXO-style output. +Org-mode contains an exporter that produces XOXO-style output. Currently, this exporter only handles the general outline structure and does not interpret any additional Org-mode features. @@ -10364,10 +10365,10 @@ Export only the visible part of the document. @vindex org-icalendar-use-deadline @vindex org-icalendar-use-scheduled @vindex org-icalendar-categories -Some people use Org mode for keeping track of projects, but still prefer a +Some people use Org-mode for keeping track of projects, but still prefer a standard calendar application for anniversaries and appointments. In this case it can be useful to show deadlines and other time-stamped items in Org -files in the calendar application. Org mode can export calendar information +files in the calendar application. Org-mode can export calendar information in the standard iCalendar format. If you also want to have TODO entries included in the export, configure the variable @code{org-icalendar-include-todo}. Plain timestamps are exported as VEVENT, @@ -10802,7 +10803,7 @@ a title, style information etc. For those people already utilizing third party sync tools such as @command{rsync} or @command{unison}, it might be preferable not to use the built in -@i{remote} publishing facilities of Org mode which rely heavily on +@i{remote} publishing facilities of Org-mode which rely heavily on Tramp. Tramp, while very useful and powerful, tends not to be so efficient for multiple file transfer and has been known to cause problems under heavy usage. @@ -10941,7 +10942,7 @@ This may be necessary in particular if files include other files via @comment Working With Source Code, Miscellaneous, Publishing, Top @node Working With Source Code, Miscellaneous, Publishing, Top -@chapter Working With Source Code +@chapter Working with source code @cindex Schulte, Eric @cindex Davison, Dan @cindex source code, working with @@ -10960,7 +10961,8 @@ e.g. Org-mode provides a number of features for working with live source code, including editing of code blocks in their native major-mode, evaluation of code blocks, tangling of code blocks, and exporting code blocks and -their results in several formats. +their results in several formats. This functionality was contributed by Dan +Davison and Eric Schulte, and was originally named Org-babel. The following sections describe Org-mode's code block handling facilities. @@ -11194,7 +11196,7 @@ l}. Code blocks in the following languages are supported. @multitable @columnfractions 0.28 0.3 0.22 0.2 -@item Language @tab Identifier @tab Language @tab Identifier +@item @b{Language} @tab @b{Identifier} @tab @b{Language} @tab @b{Identifier} @item Asymptote @tab asymptote @tab C @tab C @item C @tab C++ @tab Clojure @tab clojure @item css @tab css @tab ditaa @tab ditaa @@ -11221,13 +11223,13 @@ To add support for a particular language to your installation: ensure that the language-specific requirements are met, then @item add a line to your Emacs configuration like -@example +@lisp (require 'ob-identifier) -@end example +@end lisp where ``identifier'' is taken from the table above, e.g., -@example +@lisp (require 'ob-sass) -@end example +@end lisp @end enumerate @node Header arguments, Results of evaluation, Languages, Working With Source Code @@ -11265,29 +11267,37 @@ System-wide values of header arguments can be specified by customizing the @code{org-babel-default-header-args} variable: @example - org-babel-default-header-args is a variable defined in `org-babel.el'. - Its value is - ((:session . "none") - (:results . "replace") - (:exports . "code") - (:cache . "no") - (:noweb . "no")) - - - Documentation: - Default arguments to use when evaluating a code block. +:session => "none" +:results => "replace" +:exports => "code" +:cache => "no" +:noweb => "no" @end example +@c @example +@c org-babel-default-header-args is a variable defined in `org-babel.el'. +@c Its value is +@c ((:session . "none") +@c (:results . "replace") +@c (:exports . "code") +@c (:cache . "no") +@c (:noweb . "no")) + + +@c Documentation: +@c Default arguments to use when evaluating a code block. +@c @end example + For example, the following example could be used to set the default value of @code{:noweb} header arguments to @code{yes}. This would have the effect of expanding @code{:noweb} references by default when evaluating source code blocks. -@example - (setq org-babel-default-header-args - (cons '(:noweb . "yes") - (assq-delete-all :noweb org-babel-default-header-args))) -@end example +@lisp +(setq org-babel-default-header-args +(cons '(:noweb . "yes") +(assq-delete-all :noweb org-babel-default-header-args))) +@end lisp @node Language-specific header arguments, Buffer-wide header arguments, System-wide header arguments, Using header arguments @subsubheading Language-specific header arguments @@ -11328,10 +11338,10 @@ to @code{yes} in all code blocks in the subtree rooted at the following heading: @example - * outline header - :PROPERTIES: - :cache: yes - :END: +* outline header +:PROPERTIES: +:cache: yes +:END: @end example @kindex C-c C-x p @@ -11356,11 +11366,11 @@ inserted in the buffer, and the @code{:exports} header argument is set to preserved on export to HTML or LaTeX. @example - #+source: factorial - #+begin_src haskell :results silent :exports code :var n=0 - fac 0 = 1 - fac n = n * fac (n-1) - #+end_src +#+source: factorial +#+begin_src haskell :results silent :exports code :var n=0 +fac 0 = 1 +fac n = n * fac (n-1) +#+end_src @end example Similarly, it is possible to set header arguments for inline code blocks: @@ -11393,6 +11403,7 @@ The following header arguments are defined: * hlines:: Handle horizontal lines in tables * colnames:: Handle column names in tables * rownames:: Handle row names in tables +* shebang:: Make tangled files executable @end menu @node var, results, Specific header arguments, Specific header arguments @@ -11416,7 +11427,7 @@ The following syntax is used to pass arguments to code blocks using the @code{:var} header argument. @example - :var name=assign +:var name=assign @end example where @code{assign} can take one of the following forms @@ -11428,31 +11439,31 @@ either a string @code{"string"} or a number @code{9}. a table name: @example - #+tblname: example-table - | 1 | - | 2 | - | 3 | - | 4 | +#+tblname: example-table +| 1 | +| 2 | +| 3 | +| 4 | - #+source: table-length - #+begin_src emacs-lisp :var table=example-table - (length table) - #+end_src +#+source: table-length +#+begin_src emacs-lisp :var table=example-table +(length table) +#+end_src - #+results: table-length - : 4 +#+results: table-length +: 4 @end example a code block name, as assigned by @code{#+srcname:}, followed by parentheses: @example - #+begin_src emacs-lisp :var length=table-length() - (* 2 length) - #+end_src +#+begin_src emacs-lisp :var length=table-length() +(* 2 length) +#+end_src - #+results: - : 8 +#+results: +: 8 @end example In addition, an argument can be passed to the code block referenced @@ -11460,21 +11471,21 @@ by @code{:var}. The argument is passed within the parentheses following the code block name: @example - #+source: double - #+begin_src emacs-lisp :var input=8 - (* 2 input) - #+end_src +#+source: double +#+begin_src emacs-lisp :var input=8 +(* 2 input) +#+end_src - #+results: double - : 16 +#+results: double +: 16 - #+source: squared - #+begin_src emacs-lisp :var input=double(input=1) - (* input input) - #+end_src +#+source: squared +#+begin_src emacs-lisp :var input=double(input=1) +(* input input) +#+end_src - #+results: squared - : 4 +#+results: squared +: 4 @end example @end itemize @@ -11485,10 +11496,10 @@ example arguments can be packed inside of parenthesis, separated by commas, following the source name. @example - #+source: double(input=0, x=2) - #+begin_src emacs-lisp - (* 2 (+ input x)) - #+end_src +#+source: double(input=0, x=2) +#+begin_src emacs-lisp +(* 2 (+ input x)) +#+end_src @end example @subsubheading Indexable variable values @@ -11497,7 +11508,7 @@ block. The following example assigns the second and third rows of the table @code{example-table} to the variable @code{data}: @example - :var data=example-table[1:2] +:var data=example-table[1:2] @end example Note: ranges are indexed using the @code{:} operator. @@ -11508,7 +11519,7 @@ The following example assigns the second column of the first row of @code{example-table} to @code{data}: @example - :var data=example-table[0,1] +:var data=example-table[0,1] @end example It is possible to index into the results of code blocks as well as @@ -11518,17 +11529,17 @@ from one another by commas. For more information on indexing behavior see the documentation for the @code{org-babel-ref-index-list} function, provided below. -@example - org-babel-ref-index-list is a Lisp function in `org-babel-ref.el'. +@deffn +org-babel-ref-index-list is a Lisp function in `org-babel-ref.el'. - (org-babel-ref-index-list INDEX LIS) +(org-babel-ref-index-list index lis) - Return the subset of LIS indexed by INDEX. If INDEX is - separated by ,s then each PORTION is assumed to index into the - next deepest nesting or dimension. A valid PORTION can consist - of either an integer index, or two integers separated by a : in - which case the entire range is returned. -@end example +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 @node results, file, var, Specific header arguments @subsubsection @code{:results} @@ -11549,7 +11560,7 @@ Org-mode buffer block should be handled. @end itemize -@subsubheading collection +@subsubheading Collection The following options are mutually exclusive, and specify how the results should be collected from the code block. @@ -11566,7 +11577,7 @@ execution of the code block. This header argument places the evaluation in scripting mode. E.g., @code{:results output}. @end itemize -@subsubheading type +@subsubheading Type The following options are mutually exclusive and specify what type of results the code block will return. By default, results are inserted as either a @@ -11603,7 +11614,7 @@ block. This option currently supports Emacs Lisp, python, and ruby. E.g., @code{:results value pp}. @end itemize -@subsubheading handling +@subsubheading Handling The following results options indicate what happens with the results once they are collected. @@ -11660,9 +11671,9 @@ In other words, if you want your plot to go into a folder called Work in your home directory, you could use @example - #+begin_src R :file myplot.png :dir ~/Work - matplot(matrix(rnorm(100), 10), type="l") - #+end_src +#+begin_src R :file myplot.png :dir ~/Work +matplot(matrix(rnorm(100), 10), type="l") +#+end_src @end example @subsubheading Remote execution @@ -11671,7 +11682,7 @@ which case the code will be evaluated on the remote machine. An example is @example #+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu: - plot(1:10, main=system("hostname", intern=TRUE)) +plot(1:10, main=system("hostname", intern=TRUE)) #+end_src @end example @@ -11788,7 +11799,7 @@ All ``noweb'' syntax references in the body of the code block will be expanded before the block is evaluated. @end itemize -@subsubheading Noweb Prefix Lines +@subsubheading Noweb prefix lines Noweb insertions are now placed behind the line prefix of the @code{<>}. This behavior is illustrated in the following example. Because the @@ -11798,15 +11809,15 @@ each line of the expanded noweb reference will be commented. This code block: @example - -- <> +-- <> @end example expands to: @example - -- this is the - -- multi-line body of example +-- this is the +-- multi-line body of example @end example Note that noweb replacement text that does not contain any newlines will not @@ -11932,7 +11943,7 @@ does not ``look like'' it has column names (i.e. the second row is not an hline) @end itemize -@node rownames, , colnames, Specific header arguments +@node rownames, shebang, colnames, Specific header arguments @subsubsection @code{:rownames} The @code{:rownames} header argument can take on the values @code{yes} @@ -11962,6 +11973,14 @@ and is then reapplied to the results. @end example @end itemize +@node shebang, , rownames, Specific header arguments +@subsubsection @code{:shebang} + +Setting the @code{:shebang} header argument to a string value +(e.g. @code{:shebang "#!/bin/bash"}) causes the string to be inserted as the +first line of any tangled file holding the code block, and the file +permissions of the tangled file are set to make it executable. + @node Results of evaluation, Noweb reference syntax, Header arguments, Working With Source Code @section Results of evaluation @cindex code block, results of evaluation @@ -11971,10 +11990,10 @@ The way in which results are handled depends on whether a session is invoked, as well as on whether @code{:results value} or @code{:results output} is used. The following table shows the possibilities: -@multitable @columnfractions 0.32 0.32 0.32 -@item @tab non-session @tab session -@item @code{results :value} @tab value of last expression @tab value of last expression -@item @code{results :output} @tab contents of STDOUT @tab concatenation of interpreter output +@multitable @columnfractions 0.26 0.33 0.41 +@item @tab @b{Non-session} @tab @b{Session} +@item @code{:results value} @tab value of last expression @tab value of last expression +@item @code{:results output} @tab contents of STDOUT @tab concatenation of interpreter output @end multitable Note: With @code{:results value}, the result in both @code{:session} and @@ -12240,7 +12259,7 @@ buffer. After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}). @item After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or -@samp{OPTIONS} which set file-specific options for Org mode. When the +@samp{OPTIONS} which set file-specific options for Org-mode. When the option keyword is already complete, pressing @kbd{M-@key{TAB}} again will insert example settings for this keyword. @item @@ -12288,7 +12307,7 @@ lines into the buffer (@pxref{In-buffer settings}). @cindex in-buffer settings @cindex special keywords -Org mode uses special lines in the buffer to define settings on a +Org-mode uses special lines in the buffer to define settings on a per-file basis. These lines start with a @samp{#+} followed by a keyword, a colon, and then individual words defining a setting. Several setting words can be in the same line, but you can also have multiple @@ -12347,14 +12366,14 @@ buffer, most useful for specifying the allowed values of a property. @item #+SETUPFILE: file This line defines a file that holds more in-buffer setup. Normally this is entirely ignored. Only when the buffer is parsed for option-setting lines -(i.e. when starting Org mode for a file, when pressing @kbd{C-c C-c} in a +(i.e. when starting Org-mode for a file, when pressing @kbd{C-c C-c} in a settings line, or when exporting), then the contents of this file are parsed as if they had been included in the buffer. In particular, the file can be -any other Org mode file with internal setup. You can visit the file the +any other Org-mode file with internal setup. You can visit the file the cursor is in the line with @kbd{C-c '}. @item #+STARTUP: @cindex #+STARTUP: -This line sets options to be used at startup of Org mode, when an +This line sets options to be used at startup of Org-mode, when an Org file is being visited. The first set of options deals with the initial visibility of the outline @@ -12795,11 +12814,11 @@ setup. See the installation instructions in the file @item @file{cdlatex.el} by Carsten Dominik @cindex @file{cdlatex.el} @cindex Dominik, Carsten -Org mode can make use of the CDLa@TeX{} package to efficiently enter +Org-mode can make use of the CDLa@TeX{} package to efficiently enter La@TeX{} fragments into Org files. See @ref{CDLaTeX mode}. @item @file{imenu.el} by Ake Stenhoff and Lars Lindberg @cindex @file{imenu.el} -Imenu allows menu access to an index of items in a file. Org mode +Imenu allows menu access to an index of items in a file. Org-mode supports Imenu---all you need to do to get the index is the following: @lisp (add-hook 'org-mode-hook @@ -12816,7 +12835,7 @@ Org used to use this package for capture, but no longer does. @cindex @file{speedbar.el} @cindex Ludlam, Eric M. Speedbar is a package that creates a special frame displaying files and -index items in files. Org mode supports Speedbar and allows you to +index items in files. Org-mode supports Speedbar and allows you to drill into Org files directly from the Speedbar. It also allows you to restrict the scope of agenda commands to a file or a subtree by using the command @kbd{<} in the Speedbar frame. @@ -12852,13 +12871,13 @@ possible. @item @file{footnote.el} by Steven L. Baur @cindex @file{footnote.el} @cindex Baur, Steven L. -Org mode recognizes numerical footnotes as provided by this package. -However, Org mode also has its own footnote support (@pxref{Footnotes}), +Org-mode recognizes numerical footnotes as provided by this package. +However, Org-mode also has its own footnote support (@pxref{Footnotes}), which makes using @file{footnote.el} unnecessary. @end table @node Conflicts, , Cooperation, Interaction -@subsection Packages that lead to conflicts with Org mode +@subsection Packages that lead to conflicts with Org-mode @table @asis @@ -12870,7 +12889,7 @@ This conflicts with the use of @kbd{S-@key{cursor}} commands in Org to change timestamps, TODO keywords, priorities, and item bullet types if the cursor is at such a location. By default, @kbd{S-@key{cursor}} commands outside special contexts don't do anything, but you can customize the variable -@code{org-support-shift-select}. Org mode then tries to accommodate shift +@code{org-support-shift-select}. Org-mode then tries to accommodate shift selection by (i) using it outside of the special contexts where special commands apply, and by (ii) extending an existing active region even if the cursor moves across a special context. @@ -12885,7 +12904,7 @@ region. In fact, Emacs 23 has this built-in in the form of @code{shift-selection-mode}, see previous paragraph. If you are using Emacs 23, you probably don't want to use another package for this purpose. However, if you prefer to leave these keys to a different package while working in -Org mode, configure the variable @code{org-replace-disputed-keys}. When set, +Org-mode, configure the variable @code{org-replace-disputed-keys}. When set, Org will move the following key bindings in Org files, and in the agenda buffer (but not during date selection). @@ -12980,7 +12999,7 @@ maintained by the Worg project and can be found at A large number of add-on packages have been written by various authors. These packages are not part of Emacs, but they are distributed as contributed -packages with the separate release available at the Org mode home page at +packages with the separate release available at the Org-mode home page at @uref{http://orgmode.org}. The list of contributed packages, along with documentation about each package, is maintained by the Worg project at @uref{http://orgmode.org/worg/org-contrib/}. @@ -14026,13 +14045,13 @@ this flagged entry is finished. If you are not able to process all flagged entries directly, you can always return to this agenda view using @kbd{C-c a ?}. Note, however, that there is a subtle difference. The view created automatically by @kbd{M-x -org-mobile-pull RET} is guaranteed to search all files that have been +org-mobile-pull @key{RET}} is guaranteed to search all files that have been addressed by the last pull. This might include a file that is not currently in your list of agenda files. If you later use @kbd{C-c a ?} to regenerate the view, only the current agenda files will be searched. @node History and Acknowledgments, Main Index, MobileOrg, Top -@appendix History and Acknowledgments +@appendix History and acknowledgments @cindex acknowledgements @cindex history @cindex thanks @@ -14135,6 +14154,7 @@ them. @i{Kees Dullemond} used to edit projects lists directly in HTML and so inspired some of the early development, including HTML export. He also asked for a way to narrow wide table columns. +@item @i{Thomas S. Dye} contributed documentation on Worg and helped integrating the Org-Babel documentation into the manual. @item @@ -14302,17 +14322,17 @@ and contributed various ideas and code snippets. @node Main Index, Key Index, History and Acknowledgments, Top -@unnumbered Concept Index +@unnumbered Concept index @printindex cp @node Key Index, Variable Index, Main Index, Top -@unnumbered Key Index +@unnumbered Key index @printindex ky @node Variable Index, , Key Index, Top -@unnumbered Variable Index +@unnumbered Variable index This is not a complete index of variables and faces, only the ones that are mentioned in the manual. For a more complete list, use @kbd{M-x From a77dce0eacea8b7094d8106df9185adc94230b5b Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Sun, 27 Jun 2010 08:33:16 +0200 Subject: [PATCH 134/138] Do not set the file name of the temporary buffer during capture --- lisp/org-capture.el | 1 + 1 file changed, 1 insertion(+) diff --git a/lisp/org-capture.el b/lisp/org-capture.el index 03387c0ae..6a6707d54 100644 --- a/lisp/org-capture.el +++ b/lisp/org-capture.el @@ -1001,6 +1001,7 @@ The template may still contain \"%?\" for cursor positioning." (insert template) (goto-char (point-min)) (org-capture-steal-local-variables buffer) + (setq buffer-file-name nil) ;; Simple %-escapes (while (re-search-forward "%\\([tTuUaiAcxkKI]\\)" nil t) (unless (org-capture-escaped-%) From 1b2a21fdf777ee875ec9754ab7f4f265481cf396 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Sun, 27 Jun 2010 09:09:15 +0200 Subject: [PATCH 135/138] Fix bug when retrieving time properties with modified keywords * lisp/org.el (org-entry-properties): Make sure that standard property names are used even if the user has customized time keywords. --- lisp/org.el | 38 +++++++++++++++++++++++++------------- 1 file changed, 25 insertions(+), 13 deletions(-) diff --git a/lisp/org.el b/lisp/org.el index 679804565..1029fa14a 100644 --- a/lisp/org.el +++ b/lisp/org.el @@ -13278,7 +13278,7 @@ things up because then unnecessary parsing is avoided." (let ((clockstr (substring org-clock-string 0 -1)) (excluded '("TODO" "TAGS" "ALLTAGS" "PRIORITY" "BLOCKED")) (case-fold-search nil) - beg end range props sum-props key value string clocksum) + beg end range props sum-props key key1 value string clocksum) (save-excursion (when (condition-case nil (and (org-mode-p) (org-back-to-heading t)) @@ -13309,23 +13309,35 @@ things up because then unnecessary parsing is avoided." (when (or (not specific) (string= specific "BLOCKED")) (push (cons "BLOCKED" (if (org-entry-blocked-p) "t" "")) props)) (when (or (not specific) - (member specific org-all-time-keywords) - (member specific '("TIMESTAMP" "TIMESTAMP_IA"))) + (member specific + '("SCHEDULED" "DEADLINE" "CLOCK" "CLOSED" + "TIMESTAMP" "TIMESTAMP_IA"))) (while (re-search-forward org-maybe-keyword-time-regexp end t) - (setq key (if (match-end 1) (substring (org-match-string-no-properties 1) 0 -1)) + (setq key (if (match-end 1) + (substring (org-match-string-no-properties 1) + 0 -1)) string (if (equal key clockstr) (org-no-properties (org-trim - (buffer-substring - (match-beginning 3) (goto-char (point-at-eol))))) - (substring (org-match-string-no-properties 3) 1 -1))) - (unless key - (if (= (char-after (match-beginning 3)) ?\[) - (setq key "TIMESTAMP_IA") - (setq key "TIMESTAMP"))) - (when (or (equal key clockstr) (not (assoc key props))) + (buffer-substring + (match-beginning 3) (goto-char + (point-at-eol))))) + (substring (org-match-string-no-properties 3) + 1 -1))) + ;; Get the correct property name from the key. This is + ;; necessary if the user has configured time keywords. + (setq key1 (concat key ":")) + (cond + ((not key) + (setq key + (if (= (char-after (match-beginning 3)) ?\[) + "TIMESTAMP_IA" "TIMESTAMP"))) + ((equal key1 org-scheduled-string) (setq key "SCHEDULED")) + ((equal key1 org-deadline-string) (setq key "DEADLINE")) + ((equal key1 org-closed-string) (setq key "CLOSED")) + ((equal key1 org-clock-string) (setq key "CLOCK"))) + (when (or (equal key "CLOCK") (not (assoc key props))) (push (cons key string) props)))) - ) (when (memq which '(all standard)) From f63d977c8b914117d6f1b7a2b0cae24b4198e8cd Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Sun, 27 Jun 2010 12:26:08 +0200 Subject: [PATCH 136/138] Better capturing of error when aborting capture --- lisp/org-capture.el | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/lisp/org-capture.el b/lisp/org-capture.el index 6a6707d54..ea232cb56 100644 --- a/lisp/org-capture.el +++ b/lisp/org-capture.el @@ -377,7 +377,12 @@ bypassed." (or org-overriding-default-time (org-current-time))) (org-capture-set-target-location) - (org-capture-put :template (org-capture-fill-template)) + (condition-case error + (org-capture-put :template (org-capture-fill-template)) + ((error quit) + (if (get-buffer "*Capture*") (kill-buffer "*Capture*")) + (error "Capture abort: %s" error))) + (if (equal goto 0) ;;insert at point (org-capture-insert-template-here) @@ -998,6 +1003,7 @@ The template may still contain \"%?\" for cursor positioning." (save-window-excursion (delete-other-windows) (switch-to-buffer (get-buffer-create "*Capture*")) + (erase-buffer) (insert template) (goto-char (point-min)) (org-capture-steal-local-variables buffer) From 517837b3a167bf365be71186d13615f4f0c49dcf Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Sun, 27 Jun 2010 15:50:07 -0700 Subject: [PATCH 137/138] library of babel: added json function for accessing local or remote json objects A quick example of accessing remote json data from Babel code blocks. Evaluate the following to see a listing of parks in DC by ward. #+source: dc-parks #+begin_src emacs-lisp :var keys='(ward address) :var data=json(url="http://ogdi.cloudapp.net/v1/dc/RecreationParks?format=json") (append (list keys 'hline) (mapcar (lambda (lis) (mapcar (lambda (key) (cdr (assoc key lis))) keys)) (cdr (car data)))) #+end_src --- contrib/babel/library-of-babel.org | 37 ++++++++++++++++-------------- 1 file changed, 20 insertions(+), 17 deletions(-) diff --git a/contrib/babel/library-of-babel.org b/contrib/babel/library-of-babel.org index 807ada4d9..330734440 100644 --- a/contrib/babel/library-of-babel.org +++ b/contrib/babel/library-of-babel.org @@ -1,22 +1,6 @@ #+title: The Library of Babel -#+SEQ_TODO: TODO PROPOSED | DONE DEFERRED REJECTED -#+OPTIONS: H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc +#+author: Org-mode People #+STARTUP: odd hideblocks -#+STYLE: - -#+begin_html - -#+end_html * Introduction The Library of Babel is an extensible collection of ready-made and @@ -69,6 +53,25 @@ as a table in traditional Org-mode table syntax. nil #+end_src +** remote files + +Read local or remote file in [[http://www.json.org/][json]] format into emacs-lisp objects. +#+srcname: json +#+begin_src emacs-lisp :var file='() :var url='() + (require 'json) + (cond + (file + (with-temp-filebuffer file + (goto-char (point-min)) + (json-read))) + (url + (require 'w3m) + (with-temp-buffer + (w3m-retrieve url) + (goto-char (point-min)) + (json-read)))) +#+end_src + * Plotting code ** R From 2f0e2f1c5e2c0b29050bd25357fd40b58d50a702 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Sun, 27 Jun 2010 16:43:13 -0700 Subject: [PATCH 138/138] babel: python now treats 'hline lines in tables as "None"s Thanks to Christopher Webber (cwebb) for bringing this up. --- lisp/babel/langs/ob-python.el | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/lisp/babel/langs/ob-python.el b/lisp/babel/langs/ob-python.el index 2ce9e1d3d..29bb16676 100644 --- a/lisp/babel/langs/ob-python.el +++ b/lisp/babel/langs/ob-python.el @@ -96,7 +96,7 @@ called by `org-babel-execute-src-block'." specifying a var of the same value." (if (listp var) (concat "[" (mapconcat #'org-babel-python-var-to-python var ", ") "]") - (format "%S" var))) + (if (equal var 'hline) "None" (format "%S" var)))) (defun org-babel-python-table-or-string (results) "If the results look like a list or tuple, then convert them into an @@ -110,7 +110,9 @@ Emacs-lisp table, otherwise return the results as a string." "\\[" "(" (replace-regexp-in-string "\\]" ")" (replace-regexp-in-string ", " " " (replace-regexp-in-string - "'" "\"" results)))))) + "'" "\"" + (replace-regexp-in-string + "None" "hline" results t))))))) results))) (defvar org-babel-python-buffers '(:default . nil))