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