From 93c6a663035b4b53b01234b43314a76bc8804db7 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 11:48:07 -0400 Subject: [PATCH 01/17] 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 34c152094..7d77bc7b1 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10595,6 +10595,8 @@ above, or by customizing the variable @code{org-publish-use-timestamps-flag}. This may be necessary in particular if files include other files via @code{#+SETUPFILE:} or @code{#+INCLUDE:}. +@include source-code-chapter.texi + @node Miscellaneous, Hacking, Publishing, Top @chapter Miscellaneous 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 7b0e07461f8b556883d45835fe888c33e154a6d5 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 12:00:44 -0400 Subject: [PATCH 02/17] 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 dbcd54f16f1e2d642f35254651e7c998047276bb Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 12:21:57 -0400 Subject: [PATCH 03/17] 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 3cba424a694c639a2d40e32e36e796ff4696c788 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 12:28:25 -0400 Subject: [PATCH 04/17] 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 2263127360362441a87d4727bdae90768bad32cb Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 12:35:17 -0400 Subject: [PATCH 05/17] 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 b056b2cd772fca90ad07a1ea317921cc8a57728f Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 12:42:43 -0400 Subject: [PATCH 06/17] 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 ba5e0f06a12b5da9578619ad3e42632661179b98 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 14:57:09 -0400 Subject: [PATCH 07/17] 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 52fd87ad3cf5a26b805060cd0dc1bca38028b698 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 15:54:14 -0400 Subject: [PATCH 08/17] 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 850bcdac6c0295dcb50fa71fc78794babb30ceb3 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 22:09:36 -0400 Subject: [PATCH 09/17] 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 58c3358a0e3032748e2d59daf7e32f025038f1dc Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 22:10:17 -0400 Subject: [PATCH 10/17] 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 a5821f649..6a62ef639 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -107,6 +107,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 @@ -10118,7 +10119,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 @@ -10619,7 +10620,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 fe6521b9b07d1f20d6e7349813c024227ee76708 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 22:12:41 -0400 Subject: [PATCH 11/17] 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 6a62ef639..322b2e9f1 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10618,7 +10618,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 c2a1f16556c2e7dfb21327dab2ae827ab3a9566c Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 22:13:18 -0400 Subject: [PATCH 12/17] 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 b5bbbc1be100196d4a5d1df594773eb53687b4ab Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 22:19:19 -0400 Subject: [PATCH 13/17] 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 322b2e9f1..c69f8dd7e 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10665,23 +10665,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 e72d8b71c86022e11ef536c783d5ff0a39e0095a Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 22:19:32 -0400 Subject: [PATCH 14/17] Minor edits --- doc/org.texi | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index c69f8dd7e..4d6d25588 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10690,27 +10690,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 c6af0f947958ef5fd2a403cdf941369bbabdf39d Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Wed, 14 Apr 2010 16:47:44 -0400 Subject: [PATCH 15/17] 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 4d6d25588..5944bc667 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -500,6 +500,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 020cfb0dfab5218a0d2518b2dbc843e91af25034 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sat, 17 Apr 2010 20:19:55 -0400 Subject: [PATCH 16/17] 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 5944bc667..330ef852f 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10634,7 +10634,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 @@ -10667,21 +10667,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 @@ -10722,11 +10722,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 @@ -10789,30 +10842,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 91a169177abdadfec58a30a62bb83f13ac4617e9 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sat, 17 Apr 2010 21:47:57 -0400 Subject: [PATCH 17/17] 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 330ef852f..9ded71487 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10663,7 +10663,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: @@ -10680,8 +10680,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 @@ -10723,10 +10725,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. @@ -10785,6 +10791,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 @@ -10840,39 +10851,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]] | @@ -10897,31 +10938,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: @@ -10955,10 +10999,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: