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

173
doc/org.texi
View File

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