|
|
@@ -107,7 +107,6 @@ 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
|
|
|
@@ -500,7 +499,6 @@ 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
|
|
|
@@ -7942,7 +7940,7 @@ your agenda for the current week, all TODO items that carry the tag
|
|
|
@samp{home}, and also all lines tagged with @samp{garden}. Finally the
|
|
|
command @kbd{C-c a o} provides a similar view for office tasks.
|
|
|
|
|
|
-@node Setting Options, Block agenda, Custom agenda views
|
|
|
+@node Setting Options, , Block agenda, Custom agenda views
|
|
|
@subsection Setting options for custom commands
|
|
|
@cindex options, for custom agenda views
|
|
|
|
|
|
@@ -10136,7 +10134,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, Working With Source Code, Exporting, Top
|
|
|
+@node Publishing, Miscellaneous, Exporting, Top
|
|
|
@chapter Publishing
|
|
|
@cindex publishing
|
|
|
@cindex O'Toole, David
|
|
|
@@ -10648,1231 +10646,7 @@ above, or by customizing the variable @code{org-publish-use-timestamps-flag}.
|
|
|
This may be necessary in particular if files include other files via
|
|
|
@code{#+SETUPFILE:} or @code{#+INCLUDE:}.
|
|
|
|
|
|
-@node Working With Source Code, Miscellaneous, Publishing, Top
|
|
|
-@comment node-name, next, previous, up
|
|
|
-@comment Working With Source Code, Miscellaneous, Publishing, Top
|
|
|
-@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 blocks of code:
|
|
|
-
|
|
|
-@itemize @bullet
|
|
|
-@item
|
|
|
-Editing in the appropriate Emacs major-mode (@ref{Editing Source Code})
|
|
|
-@item
|
|
|
-Export with appropriate markup (@ref{Exporting Code Blocks})
|
|
|
-@item
|
|
|
-Extraction (``tangling'') into pure code files. (@ref{Extracting Source Code})
|
|
|
-@item
|
|
|
-Code execution, with results captured in the Org buffer (@ref{Evaluating Code Blocks})
|
|
|
-@item
|
|
|
-Using code blocks in table formulas
|
|
|
-@end itemize
|
|
|
-
|
|
|
-@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 structure of code blocks is as follows:
|
|
|
-
|
|
|
-@example
|
|
|
-#+srcname: <name>
|
|
|
-#+begin_src <language> <switches> <header arguments>
|
|
|
-<body>
|
|
|
-#+end_src
|
|
|
-@end example
|
|
|
-
|
|
|
-@table @code
|
|
|
-@item <name>
|
|
|
-An optional name for the block (see @ref{Evaluating Code Blocks})
|
|
|
-@item <language>
|
|
|
-The language of the code in the block.
|
|
|
-@item <switches>
|
|
|
-Optional links FIXME link/relocate switches discussion in @ref{Literal examples}
|
|
|
-@item <header arguments>
|
|
|
-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 <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 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.
|
|
|
-
|
|
|
-@table @code
|
|
|
-@item org-src-lang-modes
|
|
|
-If an emacs major-mode named @code{<lang>-mode} exists, where
|
|
|
-@code{<lang>} 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, in which whitespace indentation in the output is critical.
|
|
|
-@item org-src-ask-before-returning-to-edit-buffer
|
|
|
-By default, Org will ask before returning to an open edit buffer. Set
|
|
|
-to a non-nil value to switch without asking.
|
|
|
-@end table
|
|
|
-
|
|
|
-@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
|
|
|
-
|
|
|
-By default, code blocks export to HTML with the appearance of the fontified
|
|
|
-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.
|
|
|
-
|
|
|
-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
|
|
|
-@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
|
|
|
-#+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 can evaluate/execute/compile the following languages. See the
|
|
|
-language specific documentation on Worg for details.
|
|
|
-
|
|
|
-FIXME: How are we going to refer to the external documentation?
|
|
|
-
|
|
|
-@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
|
|
|
-
|
|
|
-@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 |
|
|
|
-
|
|
|
-
|
|
|
- | 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 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 four different ways, each
|
|
|
-more specific (and having higher priority) 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 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:
|
|
|
- :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
|
|
|
- =<<reference>>=.
|
|
|
-
|
|
|
- This behavior is illustrated in the following example. Because
|
|
|
- the =<<example>>= noweb reference appears behind the SQL
|
|
|
- comment syntax, each line of the expanded noweb reference will
|
|
|
- be commented.
|
|
|
-
|
|
|
- This source code block:
|
|
|
-
|
|
|
- @example
|
|
|
- -- <<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:
|
|
|
- : <<code-block-name>>
|
|
|
-
|
|
|
- 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 =<<arg>>= is a syntactically valid construct. If =<<arg>>= 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
|
|
|
+@node Miscellaneous, Hacking, Publishing, Top
|
|
|
@chapter Miscellaneous
|
|
|
|
|
|
@menu
|
Carsten Dominik