diff --git a/doc/org.texi b/doc/org.texi index 09183f6cf..bcc00d199 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -108,7 +108,7 @@ license to the document, as described in section 6 of the license. * Markup:: Prepare text for rich export * Exporting:: Sharing and publishing of notes * Publishing:: Create a web site of linked Org files -* Working With Source Code:: Using Org for literate programming, reproducible research and code evaluation. +* Working With Source Code:: Code evaluation inside Org-mode * Miscellaneous:: All the rest which did not fit elsewhere * Hacking:: How to hack your way around * MobileOrg:: Viewing and capture on a mobile device @@ -10849,7 +10849,8 @@ This may be necessary in particular if files include other files via @comment Working With Source Code, Miscellaneous, Publishing, Top @chapter Working With Source Code -Source code can be included in Org-mode documents using a @samp{src} block: +Source code can be included in Org-mode documents using a @samp{src} block, +e.g. @example #+BEGIN_SRC emacs-lisp @@ -10859,20 +10860,11 @@ Source code can be included in Org-mode documents using a @samp{src} block: #+END_SRC @end example -Org provides the following features for working with 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 +Org provides a number of features for working with live source code, +including editing of code blocks in their native major-mode, evaluation of +code blocks, tangling of code blocks, and exportation of code blocks and +their results to a number of formats. The following sections provide a +thorough tour of Org-mode's sophisticated code block handling facilities. @menu * Structure of Code Blocks:: @@ -10908,8 +10900,8 @@ The structure of code blocks is as follows: This name is associated with the source code block. This is similar to the @samp{#+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 from inside of Org-mode -tables. +block from other places in the file, other files, or from Org-mode table +formulas (see @ref{The spreadsheet}). @item The language of the code in the block. @item @@ -10929,7 +10921,7 @@ The code @comment Editing Source Code, Exporting Code Blocks, Structure of Code Blocks, Working With Source Code @section Editing Source Code -Use @kbd{C-c '} to edit the code block at point. This brings up a language +Use @kbd{C-c '} to edit the current code block. 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. @@ -10960,18 +10952,21 @@ to a non-nil value to switch without asking. @comment Exporting Code Blocks, Extracting Source Code, Editing Source Code, Working With Source Code @section Exporting Code Blocks -It is possible to export the contents of code blocks, the results of code -block evaluation, or neither or both. For most languages by default only -body of a code blocks will be exported, however some languages -(e.g. @code{ditaa}) default to exporting the results of the code block. For -information on the exportation of code blocks bodies see @ref{Literal -examples}. +It is possible to export the @emph{contents} of code blocks, the +@emph{results} of code block evaluation, or @emph{neither} or @emph{both}. +For most languages by default only body of a code blocks will be exported, +however some languages (e.g. @code{ditaa}) default to exporting the results +of the code block. For information on the exportation of code blocks bodies +see @ref{Literal examples}. The @code{:exports} header argument can be used to specify non-default export behavior: Header arguments: @table @code +@item :exports code +The default (in most languages). Only the body of the code block is exported +as described in @ref{Literal examples}. @item :exports results On export, the code block will be evaluated and the results will be placed in the org-mode buffer (either updating previous results of the code block @@ -10982,9 +10977,8 @@ block will not be exported. On export, the code block will be evaluated and the results inserted into the buffer as described above, however the body of the code block will be exported as well. -@item :exports code -The default (in most languages). Only the body of the code block is exported -as described in @ref{Literal examples}. +@item :exports none +No part of the code block or it's results will be exported. @end table @node Extracting Source Code, Evaluating Code Blocks, Exporting Code Blocks, Working With Source Code @@ -10998,7 +10992,8 @@ community. During ``tangling'' of code blocks their bodies are expanded using @code{org-babel-expand-src-block} which can expand both variable and ``noweb'' (see @ref{Noweb Reference Syntax}) style references. -Header arguments: +Relevant header arguments: + @table @code @item :tangle no The default. @@ -11010,7 +11005,8 @@ language. Include block in tangled output to file @samp{filename} @end table -Functions: +Relevant functions: + @table @code @item org-babel-tangle @key{C-c C-v t} Tangle the current file @@ -11018,22 +11014,15 @@ Tangle the current 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, Library of Babel, 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 language, blocks of code can be evaluated and the results -incorporated into the org-mode buffer. Check the value of the -@code{org-babel-interpreters} for a list of evaluable languages on your -system, also see @ref{Languages}. See @ref{Structure of Code Blocks} for +Blocks of code can be evaluated and the results incorporated into the +org-mode buffer. Check the value of the @code{org-babel-interpreters} for a +list of evaluable languages on your system, also see @ref{Languages} for a +list of supported languages. See @ref{Structure of Code Blocks} for information on the syntax used to define a code block. There are a number of ways of evaluating code blocks. The simplest is to @@ -11067,12 +11056,16 @@ Header arguments can be placed after the function invocation. See The ``Library of Babel'' is two things. First it is a library of code blocks which 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 contributed functions which they believe to be -generally useful. 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). +Org-mode users may deposit functions which they believe to be generally +useful. +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). + +Code blocks located in any Org-mode file can be loaded into the ``Library of +Babel'' with the @code{org-babel-lob-ingest} function, bound to @key{C-c C-v +l}. @node Languages, Header Arguments, Library of Babel, Working With Source Code @section Languages @@ -11103,7 +11096,7 @@ specific documentation and an up to date list of languages is available at @item Ruby @tab ruby @item Sass @tab sass @item GNU Screen @tab screen -@item shell @tab sh[fn:1] +@item shell @tab sh @item SQL @tab sql @end multitable @c END RECEIVE ORGTBL org-babel-lang-table @@ -11160,7 +11153,7 @@ The original table from reference.org is below; I'm just using the first column | 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 | + | shell | org-babel-doc-sh | sh | a shell | | SQL | org-babel-doc-sql | sql | none | @@ -11179,30 +11172,30 @@ of the language names from the above table). @node Header Arguments, Results, Languages, Working With Source Code @section Header Arguments -Definitions of all Org-babel header arguments are given (see @ref{Specific -Header Arguments}). In addition, some languages may add their own header -arguments. Please 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. +Most code block functionality is configurable using header arguments. This +section provides an overview of the use of header arguments, and then +exhaustively covers all header arguments. @menu * Using Header Arguments:: -* System-wide Header Arguments:: -* Language Specific Header Arguments:: -* Header Arguments in Org-mode Properties:: -* Header Arguments in Source Code Blocks:: * Specific Header Arguments:: -* Using Header Arguments:: @end menu -@node Using Header Arguments, System-wide Header Arguments, , Header Arguments +@node Using Header Arguments, Specific Header Arguments, , Header Arguments @subsection Using Header Arguments -The values of header arguments can be set in four different ways, each more +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:: +@end menu -@node System-wide Header Arguments, Language Specific Header Arguments, Using Header Arguments, Header Arguments -@subsubsection System-wide Header Arguments +@node System-wide header arguments, Language Specific header arguments, , Using Header Arguments +@subsubheading System-wide header arguments System-wide values of header arguments can be specified by customizing the @code{org-babel-default-header-args} variable: @@ -11221,7 +11214,7 @@ System-wide values of header arguments can be specified by customizing the @end example For example, the following example could be used to set the default value of -@code{:noweb} header arguments to =yes=. This would have the effect of +@code{:noweb} header arguments to @code{yes}. This would have the effect of expanding @code{:noweb} references by default when evaluating source code blocks. @@ -11231,13 +11224,19 @@ blocks. (assq-delete-all :noweb org-babel-default-header-args))) @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 +language-specific documentation available at +@uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}. +for information on language-specific header arguments. -@node Language Specific Header Arguments, Header Arguments in Org-mode Properties, System-wide Header Arguments, Header Arguments -@subsubsection Header Arguments in Org-mode Properties -Each language can define it's own set of default 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 +FIXME -@node Header Arguments in Org-mode Properties, Header Arguments in Source Code Blocks, Language Specific Header Arguments, Header Arguments -@subsubsection Header Arguments in Org-mode Properties +@node header arguments in Org-mode Properties, Source Code Block specific header arguments, Buffer Wide header arguments, Using Header Arguments +@subsubheading header arguments in Org-mode Properties Header arguments are also read from Org-mode properties (see @ref{Property syntax}), which can be set on a buffer-wide or per-heading basis. An example @@ -11256,7 +11255,6 @@ heading: * outline header :PROPERTIES: :cache: yes - :CUSTOM_ID: property-set-header-arguments :END: @end example @@ -11265,9 +11263,8 @@ Properties defined in this way override the properties set in @code{org-set-property} function bound to @key{C-c C-x p} to set properties in Org-mode documents. - -@node Header Arguments in Source Code Blocks, Specific Header Arguments, Header Arguments in Org-mode Properties, Header Arguments -@subsubsection Header Arguments in Source Code Block +@node Source Code Block specific header arguments, , header arguments in Org-mode Properties, Using Header Arguments +@subsubheading Source Code Block specific header arguments 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 @@ -11282,14 +11279,26 @@ preserved on export to HTML or LaTeX. @example #+source: factorial - #+begin_src haskell :results silent :exports code + #+begin_src haskell :results silent :exports code :var n=0 fac 0 = 1 fac n = n * fac (n-1) #+end_src @end example +Similarly it is possible to set header arguments for inline code blocks as +shown, -@node Specific Header Arguments, , Header Arguments in Source Code Blocks, Header Arguments +@example +src_haskell[:exports both]@{fac 5@} +@end example + +and for ``Library of Babel'' or function call lines as shown below. + +@example +#+call: factorial(n=5) :exports results +@end example + +@node Specific Header Arguments, , Using Header Arguments, Header Arguments @subsection Specific Header Arguments Description of every standard (non language-specific) Org-babel header argument. @@ -11307,19 +11316,21 @@ argument. @end menu @node var, results, , Specific Header Arguments -@subsubsection @code{var} +@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 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 +@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 argument -indexing FIXME/need section on argument indexing. +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. @@ -11330,64 +11341,68 @@ blocks using the @code{:var} header argument. where @code{assign} can take one of the following forms -- literal value :: either a string @code{"string"} or a number @code{9}. -- reference :: a table name: +@itemize @bullet +@item literal value +either a string @code{"string"} or a number @code{9}. +@item reference +a table name: - @example - #+tblname: example-table - | 1 | - | 2 | - | 3 | - | 4 | +@example + #+tblname: example-table + | 1 | + | 2 | + | 3 | + | 4 | - #+source: table-length - #+begin_src emacs-lisp :var table=example-table - (length table) - #+end_src + #+source: table-length + #+begin_src emacs-lisp :var table=example-table + (length table) + #+end_src - #+results: table-length - : 4 - @end example + #+results: table-length + : 4 +@end example - a source code block name, as assigned by =#+srcname:=, - followed by parentheses: +a source code block name, as assigned by @code{#+srcname:}, followed by +parentheses: - @example - #+begin_src emacs-lisp :var length=table-length() - (* 2 length) - #+end_src +@example + #+begin_src emacs-lisp :var length=table-length() + (* 2 length) + #+end_src - #+results: - : 8 - @end example + #+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: +In addition, an argument can be passed to the source code block referenced +by @code{: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 +@example + #+source: double + #+begin_src emacs-lisp :var input=8 + (* 2 input) + #+end_src - #+results: double - : 16 + #+results: double + : 16 - #+source: squared - #+begin_src emacs-lisp :var input=double(input=1) - (* input input) - #+end_src + #+source: squared + #+begin_src emacs-lisp :var input=double(input=1) + (* input input) + #+end_src - #+results: squared - : 4 - @end example + #+results: squared + : 4 +@end example +@end itemize @subsubheading alternate argument syntax -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. +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 #+source: double(input=0) @@ -11396,173 +11411,187 @@ parenthesis following the source name. #+end_src @end example -**** indexable variable values +@subsubheading indexable variable values +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 +@code{example-table} to the variable @code{data}: - 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 - @example - :var data=example-table[1:2] - @end example +Note: ranges are indexed using the =:= operator. - *Note:* ranges are indexed using the =:= operator. +Note: indices are 0 based. - *Note:* indices are 0 based. +The following example assigns the second column of the first row of +@code{example-table} to @code{data}: - 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 - @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. - 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 +@code{org-babel-ref-index-list} function -- provided below. - 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'. - @example - org-babel-ref-index-list is a Lisp function in `org-babel-ref.el'. + (org-babel-ref-index-list INDEX LIS) - (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 - 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. +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: - - *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. +There are three types of results header argument: - *Note:* only one option from each type may be supplied per source code - block. +Note: only one option from each type may be supplied per source code block. + +@itemize @bullet +@item collection +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 +Org-mode buffer +@item handling +header arguments specify how the results of evaluating the source code block +should be handled. +@end itemize @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. +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 @code{return} - statement be included in the body of the source code - block. E.g., @code{: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., @code{:results output}. +@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}. +@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}. +@end itemize @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., @code{: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., @code{: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., @code{: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., @code{:results value raw}. - - html :: Results are assumed to be HTML and will be enclosed in - a @code{begin_html} block. E.g., @code{:results value html}. - - latex :: Results assumed to be LaTeX and are enclosed in a - @code{begin_latex} block. E.g., @code{:results value latex}. - - code :: Result are assumed to be parseable code and are - enclosed in a code block. E.g., @code{: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., @code{:results value pp}. +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. + +@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. +E.g., @code{:results value table}. +@item 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., @code{:results value verbatim}. +@item 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., @code{:results value file}. +@item 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., @code{:results value raw}. +@item html +Results are assumed to be HTML and will be enclosed in a @code{begin_html} +block. E.g., @code{:results value html}. +@item latex +Results assumed to be LaTeX and are enclosed in a @code{begin_latex} block. +E.g., @code{:results value latex}. +@item code +Result are assumed to be parseable code and are enclosed in a code block. +E.g., @code{:results value code}. +@item 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., +@code{:results value pp}. +@end itemize @subsubheading handling - The following results options indicate what Org-babel should do - with the results once they are collected. +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., - @code{:results output silent}. - - replace :: The default value. The results will be inserted - into the Org-mode buffer. E.g., @code{:results output - replace}. +@itemize @bullet +@item silent +The results will be echoed in the minibuffer but will not be inserted into +the Org-mode buffer. E.g., @code{:results output silent}. +@item replace +The default value. Any existing results will be removed, and the new results +will be inserted into the Org-mode buffer in their place. E.g., +@code{:results output replace}. +@item append +If there are pre-existing results of the code block then the new results will +be appended to the existing results. Otherwise the new results will be +inserted as with @code{replace}. +@item prepend +If there are pre-existing results of the code block then the new results will +be prepended to the existing results. Otherwise the new results will be +inserted as with @code{replace}. +@end itemize @node file, dir and remote execution, results, Specific Header Arguments @subsubsection file - @code{:file} is used to specify a path for file output in which case an - Org-mode style link (see @ref{Link format}) @code{file:} link is inserted - into the buffer as the result. Common examples are graphical output from - R, gnuplot, ditaa and LaTeX blocks. +@code{:file} is used to specify a path for file output in which case an +Org-mode style link (see @ref{Link format}) @code{file:} link is inserted +into the buffer as the result. Common examples are graphical output from R, +gnuplot, ditaa and LaTeX blocks. - Note that for some languages, including R, gnuplot, 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 @code{:file}. +Note that for some languages, including R, gnuplot, 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 @code{:file}. - While the @code{:file} header argument can be used to specify the path to - the output 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}. +@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 case that path will be interpreted relative to the 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 +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 +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") + matplot(matrix(rnorm(100), 10), type="l") #+end_src @end example @subsubheading Remote execution - A directory on a remote machine can be specified using tramp file - syntax, in which case the code will be evaluated on the remote - machine. An example is +A directory on a remote machine can be specified using tramp file syntax, in +which case the code will be evaluated on the remote machine. An example is @example #+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu: @@ -11588,263 +11617,273 @@ 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 @code{:dir} is used in conjunction with @code{: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. - - @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. + +@itemize @bullet +@item +If @code{:dir} is used in conjunction with @code{: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. +@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. +@end itemize @node exports, tangle, dir and remote execution, Specific Header Arguments @subsubsection exports - Specify what should be included in HTML or LaTeX exports of the - Org-mode file. +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., @code{:exports code}. - - results :: the result of evaluating the code is included in the - exported file. E.g., @code{:exports results}. - - both :: both the code and results are included in the exported - file. E.g., @code{:exports both}. - - none :: nothing is included in the exported file. E.g., - @code{:exports none}. +@itemize @bullet +@item code +the default. The body of code is included into the exported file. E.g., +@code{:exports code}. +@item results +the result of evaluating the code is included in the exported file. E.g., +@code{:exports results}. +@item both +both the code and results are included in the exported file. E.g., +@code{:exports both}. +@item none +nothing is included in the exported file. E.g., @code{:exports none}. +@end itemize @node tangle, session, exports, Specific Header Arguments @subsubsection tangle - Specify whether or not the source code block should be included - in tangled extraction of source code files. +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., @code{:tangle yes}. - - no :: the default. The source code block is not - exported to a source code file. E.g., @code{:tangle no}. - - other :: Any other string passed to the @code{:tangle} header argument - is interpreted as a file basename to which the block will - be exported. E.g., @code{:tangle basename}. +@itemize @bullet +@item 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., @code{:tangle +yes}. +@item no +the default. The source code block is not exported to a source code file. +E.g., @code{:tangle no}. +@item other +Any other string passed to the @code{:tangle} header argument is interpreted +as a file basename to which the block will be exported. E.g., @code{:tangle +basename}. +@end itemize @node session, noweb, tangle, Specific Header Arguments @subsubsection session - Start a session for an interpreted language where state is - preserved. This applies particularly to the supported languages - python, R and ruby. +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. +By default, a session is not started. - A string passed to the @code{:session} header argument will give the - session a name. This makes it possible to run concurrent - sessions for each interpreted language. +A string passed to the @code{:session} header argument will give the session +a name. This makes it possible to run concurrent sessions for each +interpreted language. @node noweb, cache, session, Specific Header Arguments @subsubsection noweb - Controls the expansion of [[noweb-reference-syntax][noweb syntax]] references in a - source code block. This header argument can have one of two - values: @code{yes} or @code{no}. - - @code{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. - - @code{yes} :: all [[noweb-reference-syntax][noweb syntax]] references in the body of the source - code block will be expanded before the block is evaluated. +Controls the expansion of ``noweb'' style (see @ref{Noweb Reference Syntax}) +references in a source code block. This header argument can have one of two +values: @code{yes} or @code{no}. + +@itemize @bullet +@item @code{no} +the default. No ``noweb'' syntax specific action is taken on evaluating +source code blocks, However, noweb references will still be expanded during +tangling. +@item @code{yes} +all ``noweb'' syntax references in the body of the source code block will be +expanded before the block is evaluated. +@end itemize @subsubheading Noweb Prefix Lines - Noweb insertions are now placed behind the line prefix of the - @code{<>}. +Noweb insertions are now placed behind the line prefix of the +@code{<>}. +This behavior is illustrated in the following example. Because the +@code{<>} noweb reference appears behind the SQL comment syntax, +each line of the expanded noweb reference will be commented. - This behavior is illustrated in the following example. Because - the @code{<>} noweb reference appears behind the SQL - comment syntax, each line of the expanded noweb reference will - be commented. +This source code block: - This source code block: - - @example - -- <> - @end example +@example + -- <> +@end example - expands to: +expands to: - @example - -- this is the - -- multi-line body of example - @end example +@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. +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. @node cache, , noweb, Specific Header Arguments @subsubsection cache - 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: @code{yes} or @code{no}. - - @code{no} :: The default. No caching takes place and the source - code block will be run every time it is evaluated. - - @code{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 @code{#+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. +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: @code{yes} or @code{no}. + +@itemize @bullet +@item @code{no} +The default. No caching takes place and the source code block will be run +every time it is evaluated. +@item @code{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 +@code{#+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. +@end itemize @node Results, Noweb Reference Syntax, Header Arguments, Working With Source Code @section Results - The way in which results are handled depends on whether a - [[header-argument-session][session]] is invoked, as well as on whether - @code{:results value} or @code{:results output} is used. The following - table shows the possibilities: +The way in which results are handled depends on whether a session is invoked, +as well as on whether @code{:results value} or @code{: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 | +@multitable @columnfractions 0.32 0.32 0.32 +@item @tab non-session @tab session +@item @code{results :value} @tab value of last expression @tab value of last expression +@item @code{results :output} @tab contents of STDOUT @tab concatenation of interpreter output +@end multitable - *Note:* With @code{:results value}, the result in both @code{:session} and - non-session is returned to Org-mode as a table (a one- or - two-dimensional vector of strings or numbers) when appropriate. +Note: With @code{:results value}, the result in both @code{: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 @code{: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 @code{return} statement is present, and so a - 'return' statement will usually be required in python. +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 @code{return} statement is present, and so a +@samp{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. +This is the only one of the four evaluation contexts in which the code is +automatically wrapped in a function definition. @subsubsection @code{: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.) +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 @code{:session} @subsubsection @code{: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 @code{_} in python - and ruby, and the value of @code{.Last.value} in R). +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 @code{_} in python and ruby, and the value +of @code{.Last.value} in R). @subsubsection @code{: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 - @code{STDOUT} if the same code were passed to a non-interactive - interpreter running as an external process. For example, compare the - following two blocks: +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 @code{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" + print "hello" + 2 + print "bye" #+end_src #+resname: - : hello - : bye +: hello +: bye @end example - In non-session mode, the '2' is not printed and does not appear. +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" + print "hello" + 2 + print "bye" #+end_src #+resname: - : hello - : 2 - : bye +: 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). - +But in @code{:session} mode, the interactive interpreter receives input '2' +and prints out its value, '2'. (Indeed, the other print statements are +unnecessary here). @node Noweb Reference Syntax, Key Bindings & Useful Functions, Results, Working With Source Code @section Noweb Reference Syntax - 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: - : <> +The ``noweb'' (see @uref{http://www.cs.tufts.edu/~nr/noweb/}) Literate +Programming system allows named blocks of code to be referenced by using the +familiar Noweb syntax: - Noweb references are handled differently during evaluation and - tangling. +@example +<> +@end example - When a document is tangled, Noweb references are replaced with the - named source code block. - - When a source code block is evaluated, the action depends upon the - value of the =:noweb= header argument. If =:noweb yes=, then a - Noweb reference is expanded before evaluation. If =:noweb no=, - the default, then the reference is not expanded before - evaluation. - - *Note:* the default value, =:noweb no=, was chosen to ensure that - Org-babel does not break correct code in a language, such as Ruby, - where =<>= is a syntactically valid construct. If =<>= is - not syntactically valid in languages that you use, then please - consider [[*System%20wide][setting the default value]]. - - An example that uses the Noweb reference syntax is provided in the - [[literate programming example]]. +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. +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 +@code{<>} is a syntactically valid construct. If @code{<>} is not +syntactically valid in languages that you use, then please consider setting +the default value. @node Key Bindings & Useful Functions, , 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 - 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 re-binds many common Org-mode key sequences depending on +the context. Within a source-code block the following sequences +are rebound: - Org-babel also exposes a number of functions behind the common - =org-babel-key-prefix= of =C-c C-v=: +@multitable @columnfractions 0.25 0.75 +@item @key{C-c C-c} @tab org-babel-execute-src-block +@item @key{C-c C-o} @tab org-babel-open-src-block-result +@item @key{C-up} @tab org-babel-load-in-session +@item @key{M-down} @tab org-babel-pop-to-session +@end multitable + +Org-babel also exposes a number of functions behind the common +=org-babel-key-prefix= of =C-c C-v=: @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 +#+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 C-v t= | [[function-org-babel-tangle][org-babel-tangle]] | - | =C-c C-v T= | [[function-org-babel-tangle-file][org-babel-tangle-file]] | - | =C-c C-v e= | [[function-org-babel-execute-src-block][org-babel-execute-src-block]] | - | =C-c C-v s= | [[function-org-babel-execute-subtree][org-babel-execute-subtree]] | - | =C-c C-v b= | [[function-org-babel-execute-buffer][org-babel-execute-buffer]] | - | =C-c C-v h= | [[function-org-babel-sha1-hash][org-babel-sha1-hash]] | - | =C-c C-v g= | [[function-org-babel-goto-named-source-block][org-babel-goto-named-source-block]] | - | =C-c C-v l= | [[function-org-babel-lob-ingest][org-babel-lob-ingest]] | +@multitable @columnfractions 0.25 0.75 +@item @key{C-c C-v t} @tab org-babel-tangle +@item @key{C-c C-v T} @tab org-babel-tangle-file +@item @key{C-c C-v e} @tab org-babel-execute-src-block +@item @key{C-c C-v s} @tab org-babel-execute-subtree +@item @key{C-c C-v b} @tab org-babel-execute-buffer +@item @key{C-c C-v h} @tab org-babel-sha1-hash +@item @key{C-c C-v g} @tab org-babel-goto-named-source-block +@item @key{C-c C-v l} @tab org-babel-lob-ingest +@end multitable @subsection Functions -@subsubsection org-babel-execute-src-block - :PROPERTIES: - :CUSTOM_ID: function-org-babel-execute-src-block - :END: +@itemize @bullet +@item org-babel-execute-src-block @example org-babel-execute-src-block is an interactive Lisp function in @@ -11865,10 +11904,7 @@ install tramp separately in order for the above features to work correctly. block. @end example -@subsubsection org-babel-open-src-block-result - :PROPERTIES: - :CUSTOM_ID: function-org-babel-open-src-block-result - :END: +@item org-babel-open-src-block-result @example org-babel-open-src-block-result is an interactive Lisp function in @@ -11882,10 +11918,7 @@ install tramp separately in order for the above features to work correctly. results already exist. @end example -@subsubsection org-babel-load-in-session - :PROPERTIES: - :CUSTOM_ID: function-org-babel-load-in-session - :END: +@item org-babel-load-in-session @example org-babel-load-in-session is an interactive Lisp function in @@ -11900,10 +11933,7 @@ install tramp separately in order for the above features to work correctly. [back] @end example -@subsubsection org-babel-pop-to-session - :PROPERTIES: - :CUSTOM_ID: function-org-babel-pop-to-session - :END: +@item org-babel-pop-to-session @example org-babel-pop-to-session is an interactive Lisp function in @@ -11919,10 +11949,7 @@ install tramp separately in order for the above features to work correctly. [back] @end example -@subsubsection org-babel-tangle - :PROPERTIES: - :CUSTOM_ID: function-org-babel-tangle - :END: +@item org-babel-tangle @example org-babel-tangle is an interactive Lisp function in @@ -11939,10 +11966,7 @@ install tramp separately in order for the above features to work correctly. exported source code blocks by language. @end example -@subsubsection org-babel-execute-subtree - :PROPERTIES: - :CUSTOM_ID: function-org-babel-execute-subtree - :END: +@item org-babel-execute-subtree @example org-babel-execute-subtree is an interactive Lisp function in @@ -11955,10 +11979,7 @@ install tramp separately in order for the above features to work correctly. Replace EVAL snippets in the entire subtree. @end example -@subsubsection org-babel-execute-buffer - :PROPERTIES: - :CUSTOM_ID: function-org-babel-execute-buffer - :END: +@item org-babel-execute-buffer @example org-babel-execute-buffer is an interactive Lisp function in @@ -11971,10 +11992,7 @@ install tramp separately in order for the above features to work correctly. Replace EVAL snippets in the entire buffer. @end example -@subsubsection org-babel-sha1-hash - :PROPERTIES: - :CUSTOM_ID: function-org-babel-sha1-hash - :END: +@item org-babel-sha1-hash @example org-babel-sha1-hash is an interactive Lisp function in `org-babel.el'. @@ -11986,10 +12004,7 @@ install tramp separately in order for the above features to work correctly. Not documented. @end example -@subsubsection org-babel-goto-named-source-block - :PROPERTIES: - :CUSTOM_ID: function-org-babel-goto-named-source-block - :END: +@item org-babel-goto-named-source-block @example org-babel-goto-named-source-block is an interactive Lisp function in @@ -12002,10 +12017,7 @@ install tramp separately in order for the above features to work correctly. Go to a named source-code block. @end example -@subsubsection org-babel-lob-ingest - :PROPERTIES: - :CUSTOM_ID: function-org-babel-lob-ingest - :END: +@item org-babel-lob-ingest @example org-babel-lob-ingest is an interactive Lisp function in @@ -12017,11 +12029,11 @@ install tramp separately in order for the above features to work correctly. Add all source-blocks defined in FILE to `org-babel-library-of-babel'. @end example +@end itemize @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. +It is possible to call Org-babel 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. @example @@ -12049,13 +12061,6 @@ Be sure to adjust the paths to fit your system. (kill-buffer)) '($FILES)))" @end example -@section Footnotes - -[fn:1] The former use of the =shell= identifier is now deprecated. - -[fn:2] As long as the interpreter executable is found on the remote -machine: see the variable =tramp-remote-path= - @node Miscellaneous, Hacking, Working With Source Code, Top @chapter Miscellaneous