ndwarshuis
/
org-mode
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

First pass through babel documentation (on airplane)

This commit is contained in:
Tom Dye 2010-06-15 00:48:21 -04:00 committed by Eric Schulte
parent b329b7a736
commit cbd9bba834
1 changed files with 84 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

175
doc/org.texi
View File

@ -11050,13 +11050,13 @@ Header arguments can be placed after the function invocation. See
@node Library of Babel, Languages, Evaluating code blocks, Working With Source Code @node Library of Babel, Languages, Evaluating code blocks, Working With Source Code
@section Library of Babel @section Library of Babel
The ``Library of Babel'' is two things. First, it is a library of code blocks The ``Library of Babel'' is a library of code blocks
that can be called from any Org-mode file, and second it is an actual that can be called from any Org-mode file. The library is housed in an
Org-mode file located in the @samp{contrib} directory of Org-mode in which Org-mode file located in the @samp{contrib} directory of Org-mode.
Org-mode users may deposit functions they believe to be generally Org-mode users can deposit functions they believe to be generally
useful. useful in the library.
Code blocks defined in the``Library of Babel'' can be called remotely as if Code blocks defined in the ``Library of Babel'' can be called remotely as if
they were in the current Org-mode buffer (see @ref{Evaluating code blocks} they were in the current Org-mode buffer (see @ref{Evaluating code blocks}
for information on the syntax of remote code block evaluation). for information on the syntax of remote code block evaluation).
@ -11066,9 +11066,7 @@ l}.
@node Languages, Header arguments, Library of Babel, Working With Source Code @node Languages, Header arguments, Library of Babel, Working With Source Code
@section Languages @section Languages
Org-babel provides support for the following languages. See the language Code blocks in the following languages are supported.
specific documentation and an up to date list of languages is available at
@uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}.
@c BEGIN RECEIVE ORGTBL org-babel-lang-table @c BEGIN RECEIVE ORGTBL org-babel-lang-table
@multitable @columnfractions 0.583 0.417 @multitable @columnfractions 0.583 0.417
@ -11155,8 +11153,12 @@ The original table from reference.org is below; I'm just using the first column
@end ignore @end ignore
See the language specific documentation and an up to date list of languages
that is available at
@uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}.
To add support for a particular language to your Org-babel installation first
To add support for a particular language to your installation, first
make sure that the requirements of the language are met, then add a line like 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 the following to your Emacs configuration, (replace ``identifier'' with one
of the language names from the above table). of the language names from the above table).
@ -11185,10 +11187,10 @@ The values of header arguments can be set in five different ways, each more
specific (and having higher priority) than the last. specific (and having higher priority) than the last.
@menu @menu
* System-wide header arguments:: * System-wide header arguments::
* Language Specific header arguments:: * Language-specific header arguments::
* Buffer Wide header arguments:: * Buffer-wide header arguments::
* header arguments in Org-mode Properties:: * Header arguments in Org-mode properties::
* Source Code Block specific header arguments:: * Code block specific header arguments::
@end menu @end menu
@node System-wide header arguments, Language Specific header arguments, , Using Header arguments @node System-wide header arguments, Language Specific header arguments, , Using Header arguments
@ -11207,7 +11209,7 @@ System-wide values of header arguments can be specified by customizing the
Documentation: Documentation:
Default arguments to use when evaluating a source block. Default arguments to use when evaluating a code block.
@end example @end example
For example, the following example could be used to set the default value of For example, the following example could be used to set the default value of
@ -11222,14 +11224,14 @@ blocks.
@end example @end example
@node Language Specific header arguments, Buffer Wide header arguments, System-wide header arguments, Using Header arguments @node Language Specific header arguments, Buffer Wide header arguments, System-wide header arguments, Using Header arguments
@subsubheading Language Specific header arguments @subsubheading Language-specific header arguments
Each language can define it's own set of default header arguments. See the Each language can define its own set of default header arguments. See the
language-specific documentation available at language-specific documentation available at
@uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}. @uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}.
for information on language-specific header arguments. for information on language-specific header arguments.
@node Buffer Wide header arguments, header arguments in Org-mode Properties, Language Specific header arguments, Using Header arguments @node Buffer Wide header arguments, header arguments in Org-mode Properties, Language Specific header arguments, Using Header arguments
@subsubheading Buffer Wide header arguments @subsubheading Buffer-wide header arguments
FIXME FIXME
@node header arguments in Org-mode Properties, Source Code Block specific header arguments, Buffer Wide header arguments, Using Header arguments @node header arguments in Org-mode Properties, Source Code Block specific header arguments, Buffer Wide header arguments, Using Header arguments
@ -11244,8 +11246,8 @@ of setting a header argument for all code blocks in a buffer is
@end example @end example
When properties are used to set default header arguments, they are looked up 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 with inheritance, so the value of the @code{:cache} header argument will default
to true in all source code blocks in the subtree rooted at the following to @code{yes} in all source code blocks in the subtree rooted at the following
heading: heading:
@example @example
@ -11261,9 +11263,9 @@ Properties defined in this way override the properties set in
in Org-mode documents. in Org-mode documents.
@node Source Code Block specific header arguments, , header arguments in Org-mode Properties, Using Header arguments @node Source Code Block specific header arguments, , header arguments in Org-mode Properties, Using Header arguments
@subsubheading Source Code Block specific header arguments @subsubheading Code block specific header arguments
The most common way to assign values to header arguments is at the source The most common way to assign values to header arguments is at the
code block level. This can be done by listing a sequence of header code block level. This can be done by listing a sequence of header
arguments and their values as part of the @code{#+begin_src} line. arguments and their values as part of the @code{#+begin_src} line.
Properties set in this way override both the values of Properties set in this way override both the values of
@ -11282,14 +11284,13 @@ preserved on export to HTML or LaTeX.
#+end_src #+end_src
@end example @end example
Similarly it is possible to set header arguments for inline code blocks as Similarly, it is possible to set header arguments for inline code blocks:
shown,
@example @example
src_haskell[:exports both]@{fac 5@} src_haskell[:exports both]@{fac 5@}
@end example @end example
and for ``Library of Babel'' or function call lines as shown below. Header arguments for ``Library of Babel'' or function call lines can be set as shown below:
@example @example
#+call: factorial(n=5) :exports results #+call: factorial(n=5) :exports results
@ -11297,8 +11298,7 @@ and for ``Library of Babel'' or function call lines as shown below.
@node Specific Header arguments, , Using Header arguments, Header arguments @node Specific Header arguments, , Using Header arguments, Header arguments
@subsection Specific Header arguments @subsection Specific Header arguments
Description of every standard (non language-specific) Org-babel header The following header arguments are defined:
argument.
@menu @menu
* var:: * var::
@ -11319,22 +11319,22 @@ argument.
@node var, results, , Specific Header arguments @node var, results, , Specific Header arguments
@subsubsection var @subsubsection var
The @code{:var} header argument is used to pass arguments to The @code{:var} header argument is used to pass arguments to
source code blocks. The specifics of how arguments are included code blocks. The specifics of how arguments are included
in a source code block are language specific and are in a code block vary by language; these are
addressed in the language-specific documentation. However, the addressed in the language-specific documentation. However, the
syntax used to specify arguments is the same across all syntax used to specify arguments is the same across all
languages. The values passed to arguments can be or languages. The values passed to arguments can be
@itemize @bullet @itemize @bullet
@item literal values @item literal values
@item values from org-mode tables @item values from org-mode tables
@item the results of other source code blocks @item the results of other source code blocks
@end itemize @end itemize
These values can be indexed in a manner similar to arrays -- see the argument These values can be indexed in a manner similar to arrays---see the argument
``indexable variable values'' heading below. ``indexable variable values'' heading below.
The following syntax is used to pass arguments to source code The following syntax is used to pass arguments to code blocks using the
blocks using the @code{:var} header argument. @code{:var} header argument.
@example @example
:var name=assign :var name=assign
@ -11376,7 +11376,7 @@ parentheses:
: 8 : 8
@end example @end example
In addition, an argument can be passed to the source code block referenced In addition, an argument can be passed to the code block referenced
by @code{:var}. The argument is passed within the parentheses following the by @code{:var}. The argument is passed within the parentheses following the
source code block name: source code block name:
@ -11399,16 +11399,16 @@ source code block name:
@end example @end example
@end itemize @end itemize
@subsubheading alternate argument syntax @subsubheading Alternate argument syntax
It is also possible to specify arguments in a potentially more natural way It is also possible to specify arguments in a potentially more natural way
using the @code{#+source:} line of a source code block. As in the following using the @code{#+source:} line of a source code block. As in the following
example arguments can be packed inside of parenthesis following the source example arguments can be packed inside of parenthesis, separated by commas,
name. following the source name.
@example @example
#+source: double(input=0) #+source: double(input=0, x=2)
#+begin_src emacs-lisp #+begin_src emacs-lisp
(* 2 input) (* 2 (+ input x))
#+end_src #+end_src
@end example @end example
@ -11421,7 +11421,7 @@ block. The following example assigns the second and third rows of the table
:var data=example-table[1:2] :var data=example-table[1:2]
@end example @end example
Note: ranges are indexed using the =:= operator. Note: ranges are indexed using the @code{:} operator.
Note: indices are 0 based. Note: indices are 0 based.
@ -11432,12 +11432,12 @@ The following example assigns the second column of the first row of
:var data=example-table[0,1] :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 It is possible to index into the results of code blocks as well as
tables. Any number of dimensions can be indexed. Dimensions are separated tables. Any number of dimensions can be indexed. Dimensions are separated
from one another by commas. from one another by commas.
For more information on indexing behavior see the documentation for the For more information on indexing behavior see the documentation for the
@code{org-babel-ref-index-list} function -- provided below. @code{org-babel-ref-index-list} function, provided below.
@example @example
org-babel-ref-index-list is a Lisp function in `org-babel-ref.el'. org-babel-ref-index-list is a Lisp function in `org-babel-ref.el'.
@ -11451,16 +11451,11 @@ For more information on indexing behavior see the documentation for the
which case the entire range is returned. 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 @code{describe-function} (M-x describe function) and
@code{describe-variable} (M-x describe variable) functions, respectively.
@node results, file, var, Specific Header arguments @node results, file, var, Specific Header arguments
@subsubsection results @subsubsection results
There are three types of results header argument: There are three types of results header argument. Only one option of each
type may be supplied per code block.
Note: only one option from each type may be supplied per source code block.
@itemize @bullet @itemize @bullet
@item collection @item collection
@ -11468,7 +11463,7 @@ arguments specify how the results should be collected from the source code
block block
@item type @item type
header arguments specify what type of result the source code block will header arguments specify what type of result the source code block will
return -- which has implications for how they will be inserted into the return---which has implications for how they will be inserted into the
Org-mode buffer Org-mode buffer
@item handling @item handling
header arguments specify how the results of evaluating the source code block header arguments specify how the results of evaluating the source code block
@ -11482,14 +11477,14 @@ should be collected from the source code block.
@itemize @bullet @itemize @bullet
@item value @item value
This is the default. The result is the value of the last statement in the 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. source code block. This header argument places the evaluation in functional
Note that in some languages, e.g., python, use of this result type requires mode. Note that in some languages, e.g., python, use of this result type
that a @code{return} statement be included in the body of the source code requires that a @code{return} statement be included in the body of the source
block. E.g., @code{:results value}. code block. E.g., @code{:results value}.
@item output @item output
The result is the collection of everything printed to STDOUT during the 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 execution of the source code block. This header argument places the
scripting mode. E.g., @code{:results output}. evaluation in scripting mode. E.g., @code{:results output}.
@end itemize @end itemize
@subsubheading type @subsubheading type
@ -11501,10 +11496,10 @@ table or scalar depending on their value.
@itemize @bullet @itemize @bullet
@item table, vector @item table, vector
The results should be interpreted as an Org-mode table. If a single value is The results should be interpreted as an Org-mode table. If a single value is
returned, Org-babel will convert it into a table with one row and one column. returned, it will be converted into a table with one row and one column.
E.g., @code{:results value table}. E.g., @code{:results value table}.
@item scalar, verbatim @item scalar, verbatim
The results should be interpreted literally -- meaning they will not be The results should be interpreted literally---they will not be
converted into a table. The results will be inserted into the Org-mode converted into a table. The results will be inserted into the Org-mode
buffer as quoted text. E.g., @code{:results value verbatim}. buffer as quoted text. E.g., @code{:results value verbatim}.
@item file @item file
@ -11565,17 +11560,16 @@ individual languages for details. In contrast, general purpose languages such
as python and ruby require that the code explicitly create output as python and ruby require that the code explicitly create output
corresponding to the path indicated by @code{:file}. corresponding to the path indicated by @code{:file}.
While the @code{:file} header argument can be used to specify the path to the
output file,
@node dir and remote execution, exports, file, Specific Header arguments @node dir and remote execution, exports, file, Specific Header arguments
@subsubsection dir and remote execution @subsubsection dir and remote execution
@code{:dir} specifies the /default directory/ during code block execution. If While the @code{:file} header argument can be used to specify the path to the
it is absent, then the directory associated with the current buffer is output file, @code{:dir} specifies the default directory during code block
used. In other words, supplying @code{:dir path} temporarily has the same execution. If it is absent, then the directory associated with the current
effect as changing the current directory with @key{M-x cd path}, and then not buffer is used. In other words, supplying @code{:dir path} temporarily has
supplying @code{:dir}. Under the surface, @code{:dir} simply sets the value the same effect as changing the current directory with @key{M-x cd path}, and
of the Emacs variable @code{default-directory}. then not supplying @code{:dir}. Under the surface, @code{:dir} simply sets
the value of the Emacs variable @code{default-directory}.
When using @code{:dir}, you should supply a relative path for file output When using @code{:dir}, you should supply a relative path for file output
(e.g. @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in which (e.g. @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in which
@ -11600,12 +11594,12 @@ which case the code will be evaluated on the remote machine. An example is
#+end_src #+end_src
@end example @end example
Text results will be returned to the local org buffer as normal, and Text results will be returned to the local Org-mode buffer as usual, and file
file output will be created on the remote machine with relative paths output will be created on the remote machine with relative paths interpreted
interpreted relative to the remote directory. An org link to the relative to the remote directory. An Org-mode link to the remote file will be
remote file will be created. created.
So in the above example a plot will be created on the remote machine, So, in the above example a plot will be created on the remote machine,
and a link of the following form will be inserted in the org buffer: and a link of the following form will be inserted in the org buffer:
@example @example
@ -11615,7 +11609,7 @@ and a link of the following form will be inserted in the org buffer:
Most of this functionality follows immediately from the fact that @code{:dir} Most of this functionality follows immediately from the fact that @code{:dir}
sets the value of the Emacs variable @code{default-directory}, thanks to sets the value of the Emacs variable @code{default-directory}, thanks to
tramp. Those using XEmacs, or GNU Emacs prior to version 23 may need to tramp. Those using XEmacs, or GNU Emacs prior to version 23 may need to
install tramp separately in order for the above features to work correctly. install tramp separately in order for the these features to work correctly.
@subsubheading Further points @subsubheading Further points
@ -11627,11 +11621,11 @@ currently made to alter the directory associated with an existing session.
@item @item
@code{:dir} should typically not be used to create files during export with @code{:dir} should typically not be used to create files during export with
@code{:exports results} or @code{:exports both}. The reason is that, in order @code{:exports results} or @code{:exports both}. The reason is that, in order
to retain portability of exported material between machines, during export, to retain portability of exported material between machines, during export
links inserted into the buffer will *not* be expanded against default links inserted into the buffer will *not* be expanded against @code{default
directory. Therefore, if default-directory is altered using @code{:dir}, it directory}. Therefore, if @code{default-directory} is altered using
it probable that the file will be created in a location to which the link @code{:dir}, it is probable that the file will be created in a location to
does not point. which the link does not point.
@end itemize @end itemize
@node exports, tangle, dir and remote execution, Specific Header arguments @node exports, tangle, dir and remote execution, Specific Header arguments
@ -11753,7 +11747,7 @@ changed since the last time it was evaluated, it will not be re-evaluated.
@node hlines, colnames, cache, Specific Header arguments @node hlines, colnames, cache, Specific Header arguments
@subsubsection hlines @subsubsection hlines
Tables are frequently represented with one or more horizontal lines, or Tables are frequently represented with one or more horizontal lines, or
hlines. The @code{:hlines} argument to an Org-babel code block accepts the hlines. The @code{:hlines} argument to a code block accepts the
values @code{yes} or @code{no}, with a default value of @code{no}. values @code{yes} or @code{no}, with a default value of @code{no}.
@itemize @bullet @itemize @bullet
@ -11814,9 +11808,9 @@ The @code{:colnames} header argument accepts the values @code{yes},
@itemize @bullet @itemize @bullet
@item @code{nil} @item @code{nil}
If an input table /looks like/ it has column names If an input table looks like it has column names
(because its second row is an hline), then the column (because its second row is an hline), then the column
names will be removed from the table by Org-babel before names will be removed from the table before
processing, then reapplied to the results. processing, then reapplied to the results.
@example @example
@ -11857,9 +11851,8 @@ or @code{no}, with a default value of @code{no}.
No row name pre-processing will take place. No row name pre-processing will take place.
@item @code{yes} @item @code{yes}
The first column of the table is removed from the The first column of the table is removed from the table before processing,
table by Org-babel before processing, and is then reapplied and is then reapplied to the results.
to the results.
@example @example
#+tblname: with-rownames #+tblname: with-rownames
@ -11967,11 +11960,11 @@ familiar Noweb syntax:
<<code-block-name>> <<code-block-name>>
@end example @end example
When a source code block is tangled or evaluated, ``noweb'' references are When a source code block is tangled or evaluated, whether or not ``noweb''
expanded depends upon the value of the @code{:noweb} header argument. If references are expanded depends upon the value of the @code{:noweb} header
@code{:noweb yes}, then a Noweb reference is expanded before evaluation. If argument. If @code{:noweb yes}, then a Noweb reference is expanded before
@code{:noweb no}, the default, then the reference is not expanded before evaluation. If @code{:noweb no}, the default, then the reference is not
evaluation. expanded before evaluation.
Note: the default value, @code{:noweb no}, was chosen to ensure that Note: the default value, @code{:noweb no}, was chosen to ensure that
Org-babel does not break correct code in a language, such as Ruby, where Org-babel does not break correct code in a language, such as Ruby, where
@ -11982,8 +11975,8 @@ the default value.
@node Key bindings & useful functions, Batch execution, Noweb reference syntax, Working With Source Code @node Key bindings & useful functions, Batch execution, Noweb reference syntax, Working With Source Code
@section Key bindings & useful functions @section Key bindings & useful functions
Org-babel re-binds many common Org-mode key sequences depending on Many common Org-mode key sequences are re-bound depending on
the context. Within a source-code block the following sequences the context. Within a code block the following sequences
are rebound: are rebound:
@multitable @columnfractions 0.25 0.75 @multitable @columnfractions 0.25 0.75
@ -12022,7 +12015,7 @@ kept pressed, resulting in the following additional keybindings.
@node Batch execution, , Key bindings & useful functions, Working With Source Code @node Batch execution, , Key bindings & useful functions, Working With Source Code
@section Batch execution @section Batch execution
It is possible to call Org-babel functions from the command line. This shell It is possible to call functions from the command line. This shell
script calls @code{org-babel-tangle} on every one of its arguments. script calls @code{org-babel-tangle} on every one of its arguments.
Be sure to adjust the paths to fit your system. Be sure to adjust the paths to fit your system.