From 93c6a663035b4b53b01234b43314a76bc8804db7 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 11:48:07 -0400 Subject: [PATCH 01/34] Initialise new source code chapter with reference.org from Worg source-code-chapter.texi is just reference.org with level 1 headings replaced with @section, and level 2 headings replaced with @subsection, and with a top level @chapter node. This file is included in org.texi with an @include line for now. --- doc/org.texi | 2 + doc/source-code-chapter.texi | 1006 ++++++++++++++++++++++++++++++++++ 2 files changed, 1008 insertions(+) create mode 100644 doc/source-code-chapter.texi diff --git a/doc/org.texi b/doc/org.texi index 34c152094..7d77bc7b1 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10595,6 +10595,8 @@ 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:}. +@include source-code-chapter.texi + @node Miscellaneous, Hacking, Publishing, Top @chapter Miscellaneous diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi new file mode 100644 index 000000000..eafe02d7f --- /dev/null +++ b/doc/source-code-chapter.texi @@ -0,0 +1,1006 @@ +@chapter Working with source code or Embedded Source Code + +@section Syntax + :PROPERTIES: + :CUSTOM_ID: syntax + :END: + +@subsection Source Code Block +The basic syntax of source code blocks in Org-babel is as follows: + +: #+begin_src language header-arguments +: body +: #+end_src + +- language :: The language of the code in the source code block. Valid + values must be members of =org-babel-interpreters=. +- header-arguments :: Header arguments control many facets of the + evaluation and output of source code blocks. See the [[header-arguments][Header + Arguments]] section for a complete review of available header + arguments. +- body :: The source code to be evaluated. An important key-binding + is C-c '. This calls =org-edit-src-code=, a function that brings + up an edit buffer containing the code using the Emacs major mode + appropriate to the language. You can edit your source code block + as you regularly would in Emacs. + +This syntax can be expanded by naming the source code block. + +: #+source: name +: #+begin_src language header-arguments +: +: #+end_src + +- 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. + +: #+lob: R-plot(data=R-plot-example-data) + +@subsection Aliases + Keyword aliases are intended to make Org-babel feel natural to + programmers fluent in a variety of languages. For example, + #+begin_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=. + #+begin_example + ,#+lob: R-plot(data=R-plot-example-data) + #+end_example + +@section Languages + :PROPERTIES: + :CUSTOM_ID: languages + :END: + + Org-babel has support for the following languages. + + | 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 | + + 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). + #+begin_src emacs-lisp + (require 'org-babel-identifier) + #+end_src + +@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 three different ways, +each more specific than the last. + +*** 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: + #+begin_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. + #+begin_src emacs-lisp :results silent :exports code + (setq org-babel-default-header-args + (cons '(:noweb . "yes") + (assq-delete-all :noweb org-babel-default-header-args))) + #+end_src + +*** Org-mode Properties + + Header arguments are also read from [[http://orgmode.org/manual/Properties-and-Columns.html#Properties-and-Columns][Org-mode properties]], which + means they can be set on the outline header level. For example, the + value of the =:cache= header argument will default to true in all + source code blocks under the following example of an Org-mode outline header: + #+begin_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. + +*** 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. + #+begin_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: + +*** =: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. + + #+begin_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: + + #+begin_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: + + #+begin_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: + + #+begin_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 + +**** 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. + #+begin_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=: + + #+begin_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=: + + #+begin_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. + + #+begin_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. + +*** =: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. + +**** 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=. + +**** 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=. + +**** 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=. + +*** =: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, + +*** =: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 + +#+begin_example + ,#+begin_src R :file myplot.png :dir ~/Work + matplot(matrix(rnorm(100), 10), type="l") + ,#+end_src +#+end_example + +**** 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 + +#+begin_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: + +#+begin_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. + +**** 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. +*** =: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=. + +*** =: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=. + +*** =: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. + +*** =: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. + +**** Noweb Prefix Lines + + Noweb insertions are now placed behind the line prefix of the + =<>=. + + This behavior is illustrated in the following example. Because + the =<>= noweb reference appears behind the SQL + comment syntax, each line of the expanded noweb reference will + be commented. + + This source code block: + + #+begin_example + -- <> + #+end_example + + + expands to: + + #+begin_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. + +*** =: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. + +**** Non-session +***** =: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. + +***** =: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.) + +**** =:session= +***** =: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). + +***** =: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: + +#+begin_src python :results output + print "hello" + 2 + print "bye" +#+end_src + +#+resname: + : hello + : bye + + In non-session mode, the '2' is not printed and does not appear. + +#+begin_src python :results output :session + print "hello" + 2 + print "bye" +#+end_src + +#+resname: + : hello + : 2 + : bye + + 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: + : <> + + 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 =<>= 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]]. + +@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=: + #+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 + | =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 +*** org-babel-execute-src-block + :PROPERTIES: + :CUSTOM_ID: function-org-babel-execute-src-block + :END: + +#+begin_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 + +*** org-babel-open-src-block-result + :PROPERTIES: + :CUSTOM_ID: function-org-babel-open-src-block-result + :END: + +#+begin_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 + +*** org-babel-load-in-session + :PROPERTIES: + :CUSTOM_ID: function-org-babel-load-in-session + :END: + +#+begin_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 + +*** org-babel-pop-to-session + :PROPERTIES: + :CUSTOM_ID: function-org-babel-pop-to-session + :END: + +#+begin_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 + +*** org-babel-tangle + :PROPERTIES: + :CUSTOM_ID: function-org-babel-tangle + :END: + +#+begin_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 + +*** org-babel-execute-subtree + :PROPERTIES: + :CUSTOM_ID: function-org-babel-execute-subtree + :END: + +#+begin_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 + +*** org-babel-execute-buffer + :PROPERTIES: + :CUSTOM_ID: function-org-babel-execute-buffer + :END: + +#+begin_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 + +*** org-babel-sha1-hash + :PROPERTIES: + :CUSTOM_ID: function-org-babel-sha1-hash + :END: + +#+begin_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 + +*** org-babel-goto-named-source-block + :PROPERTIES: + :CUSTOM_ID: function-org-babel-goto-named-source-block + :END: + +#+begin_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 + +*** org-babel-lob-ingest + :PROPERTIES: + :CUSTOM_ID: function-org-babel-lob-ingest + :END: + +#+begin_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. +#+begin_src sh + #!/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_src + +@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= + + +@section HTML 1 :noexport: + +#+begin_html + +#+end_html + +@subsection Note + - HTML 1 was keeping the babelfish code from exporting. Not sure + why or if the code itself is necessary, but moving it here gets + the fish on the page. From 7b0e07461f8b556883d45835fe888c33e154a6d5 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 12:00:44 -0400 Subject: [PATCH 02/34] Quote some @ symbols and clean up. make info and make pdf work now. --- doc/source-code-chapter.texi | 25 +++---------------------- 1 file changed, 3 insertions(+), 22 deletions(-) diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi index eafe02d7f..b0d7ccc0a 100644 --- a/doc/source-code-chapter.texi +++ b/doc/source-code-chapter.texi @@ -480,7 +480,7 @@ each more specific than the last. remote machine[fn:2]. An example is #+begin_example -,#+begin_src R :file plot.png :dir /dand@yakuba.princeton.edu: +,#+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu: plot(1:10, main=system("hostname", intern=TRUE)) ,#+end_src #+end_example @@ -494,7 +494,7 @@ 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: #+begin_example -[[file:/scp:dand@yakuba.princeton.edu:/home/dand/plot.png][plot.png]] +[[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]] #+end_example Most of this functionality follows immediately from the fact that @@ -964,7 +964,7 @@ Be sure to adjust the paths to fit your system. FILES="" # wrap each argument in the code required to call tangle on it - for i in $@; do + for i in $@@; do FILES="$FILES \"$i\"" done @@ -985,22 +985,3 @@ Be sure to adjust the paths to fit your system. [fn:2] As long as the interpreter executable is found on the remote machine: see the variable =tramp-remote-path= - - -@section HTML 1 :noexport: - -#+begin_html - -#+end_html - -@subsection Note - - HTML 1 was keeping the babelfish code from exporting. Not sure - why or if the code itself is necessary, but moving it here gets - the fish on the page. From dbcd54f16f1e2d642f35254651e7c998047276bb Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 12:21:57 -0400 Subject: [PATCH 03/34] Wrap verbatim examples in @example ... @end example Note that there are some cases where the #+begin_src itself is part of the example, and others where only the body of the source block is the example. --- doc/source-code-chapter.texi | 216 ++++++++++++++++++----------------- 1 file changed, 112 insertions(+), 104 deletions(-) diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi index b0d7ccc0a..c2e93d742 100644 --- a/doc/source-code-chapter.texi +++ b/doc/source-code-chapter.texi @@ -8,10 +8,11 @@ @subsection Source Code Block The basic syntax of source code blocks in Org-babel is as follows: -: #+begin_src language header-arguments -: body -: #+end_src - +@example +#+begin_src language header-arguments +body +#+end_src +@end example - language :: The language of the code in the source code block. Valid values must be members of =org-babel-interpreters=. - header-arguments :: Header arguments control many facets of the @@ -26,10 +27,12 @@ The basic syntax of source code blocks in Org-babel is as follows: This syntax can be expanded by naming the source code block. -: #+source: name -: #+begin_src language header-arguments -: -: #+end_src +@example +#+sourcename +#+begin_src language header-arguments +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 @@ -42,33 +45,35 @@ This syntax can be expanded by naming the source code block. @subsection Library of Babel [[file:library-of-babel.org][Library of Babel]] functions can be called using the following syntax. -: #+lob: R-plot(data=R-plot-example-data) +@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, - #+begin_example - ,#+srcname: alias-example - ,#+begin_src emacs-lisp + @example + #+srcname: alias-example + #+begin_src emacs-lisp '((call lob) (source function srcname) (results resname)) - ,#+end_src + #+end_src - ,#+results: alias-example + #+results: alias-example | call | lob | | | source | function | srcname | | results | resname | | - #+end_example + @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=. - #+begin_example - ,#+lob: R-plot(data=R-plot-example-data) - #+end_example + @example + #+lob: R-plot(data=R-plot-example-data) + @end example @section Languages :PROPERTIES: @@ -107,9 +112,9 @@ This syntax can be expanded by naming the source code block. 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). - #+begin_src emacs-lisp + @example (require 'org-babel-identifier) - #+end_src + @end example @section Header Arguments :PROPERTIES: @@ -133,7 +138,7 @@ each more specific than the last. System-wide values of header arguments can be specified by customizing the =org-babel-default-header-args= variable: - #+begin_example + @example org-babel-default-header-args is a variable defined in `org-babel.el'. Its value is ((:session . "none") @@ -145,16 +150,16 @@ each more specific than the last. Documentation: Default arguments to use when evaluating a source block. - #+end_example + @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. - #+begin_src emacs-lisp :results silent :exports code + @example (setq org-babel-default-header-args (cons '(:noweb . "yes") (assq-delete-all :noweb org-babel-default-header-args))) - #+end_src + @end example *** Org-mode Properties @@ -162,13 +167,13 @@ each more specific than the last. means they can be set on the outline header level. For example, the value of the =:cache= header argument will default to true in all source code blocks under the following example of an Org-mode outline header: - #+begin_example - ,* outline header + @example + * outline header :PROPERTIES: :cache: yes :CUSTOM_ID: property-set-header-arguments :END: - #+end_example + @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 @@ -189,13 +194,13 @@ each more specific than the last. header argument is set to =code=, meaning only the body of the source code block will be preserved on export to HTML or LaTeX. - #+begin_example - ,#+source: factorial - ,#+begin_src haskell :results silent :exports code + @example + #+source: factorial + #+begin_src haskell :results silent :exports code fac 0 = 1 fac n = n * fac (n-1) - ,#+end_src - #+end_example + #+end_src + @end example @subsection Specific Header Arguments :PROPERTIES: @@ -223,64 +228,64 @@ each more specific than the last. The following syntax is used to pass arguments to source code blocks using the =:var= header argument. - #+begin_example + @example :var name=assign - #+end_example + @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: - #+begin_example - ,#+tblname: example-table + @example + #+tblname: example-table | 1 | | 2 | | 3 | | 4 | - ,#+source: table-length - ,#+begin_src emacs-lisp :var table=example-table + #+source: table-length + #+begin_src emacs-lisp :var table=example-table (length table) - ,#+end_src + #+end_src - ,#+results: table-length + #+results: table-length : 4 - #+end_example + @end example a source code block name, as assigned by =#+srcname:=, followed by parentheses: - #+begin_example - ,#+begin_src emacs-lisp :var length=table-length() + @example + #+begin_src emacs-lisp :var length=table-length() (* 2 length) - ,#+end_src + #+end_src - ,#+results: + #+results: : 8 - #+end_example + @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: - #+begin_example - ,#+source: double - ,#+begin_src emacs-lisp :var input=8 + @example + #+source: double + #+begin_src emacs-lisp :var input=8 (* 2 input) - ,#+end_src + #+end_src - ,#+results: double + #+results: double : 16 - ,#+source: squared - ,#+begin_src emacs-lisp :var input=double(input=1) + #+source: squared + #+begin_src emacs-lisp :var input=double(input=1) (* input input) - ,#+end_src + #+end_src - ,#+results: squared + #+results: squared : 4 - #+end_example + @end example **** alternate argument syntax :PROPERTIES: @@ -291,12 +296,12 @@ each more specific than the last. 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. - #+begin_example - ,#+source: double(input=0) - ,#+begin_src emacs-lisp + @example + #+source: double(input=0) + #+begin_src emacs-lisp (* 2 input) - ,#+end_src - #+end_example + #+end_src + @end example **** indexable variable values :PROPERTIES: @@ -308,9 +313,9 @@ each more specific than the last. assigns the second and third rows of the table =example-table= to the variable =data=: - #+begin_example + @example :var data=example-table[1:2] - #+end_example + @end example *Note:* ranges are indexed using the =:= operator. @@ -319,9 +324,9 @@ each more specific than the last. The following example assigns the second column of the first row of =example-table= to =data=: - #+begin_example + @example :var data=example-table[0,1] - #+end_example + @end example It is possible to index into the results of source code blocks as well as tables. Any number of dimensions can be indexed. @@ -330,7 +335,7 @@ each more specific than the last. For more information on indexing behavior see the documentation for the =org-babel-ref-index-list= function -- provided below. - #+begin_example + @example org-babel-ref-index-list is a Lisp function in `org-babel-ref.el'. (org-babel-ref-index-list INDEX LIS) @@ -340,7 +345,7 @@ each more specific than the last. 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 + @end example *Note:* In Emacs, the documentation for any function or variable can be read using the =describe-function= (M-x describe @@ -468,22 +473,22 @@ each more specific than the last. In other words, if you want your plot to go into a folder called Work in your home directory, you could use -#+begin_example - ,#+begin_src R :file myplot.png :dir ~/Work +@example + #+begin_src R :file myplot.png :dir ~/Work matplot(matrix(rnorm(100), 10), type="l") - ,#+end_src -#+end_example + #+end_src +@end example **** 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 -#+begin_example -,#+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu: +@example +#+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu: plot(1:10, main=system("hostname", intern=TRUE)) -,#+end_src -#+end_example +#+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 @@ -493,9 +498,9 @@ 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: -#+begin_example +@example [[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]] -#+end_example +@end example Most of this functionality follows immediately from the fact that =:dir= sets the value of the emacs variable =default-directory=, @@ -591,17 +596,17 @@ above features to work correctly. This source code block: - #+begin_example + @example -- <> - #+end_example + @end example expands to: - #+begin_example + @example -- this is the -- multi-line body of example - #+end_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 @@ -683,6 +688,7 @@ above features to work correctly. non-interactive interpreter running as an external process. For example, compare the following two blocks: +@example #+begin_src python :results output print "hello" 2 @@ -692,9 +698,10 @@ above features to work correctly. #+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 @@ -705,6 +712,7 @@ above features to work correctly. : 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 @@ -776,7 +784,7 @@ above features to work correctly. :CUSTOM_ID: function-org-babel-execute-src-block :END: -#+begin_example +@example org-babel-execute-src-block is an interactive Lisp function in `org-babel.el'. @@ -793,14 +801,14 @@ above features to work correctly. 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 +@end example *** org-babel-open-src-block-result :PROPERTIES: :CUSTOM_ID: function-org-babel-open-src-block-result :END: -#+begin_example +@example org-babel-open-src-block-result is an interactive Lisp function in `org-babel.el'. @@ -810,14 +818,14 @@ above features to work correctly. 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 +@end example *** org-babel-load-in-session :PROPERTIES: :CUSTOM_ID: function-org-babel-load-in-session :END: -#+begin_example +@example org-babel-load-in-session is an interactive Lisp function in `org-babel.el'. @@ -828,14 +836,14 @@ above features to work correctly. session. After loading the body this pops open the session. [back] -#+end_example +@end example *** org-babel-pop-to-session :PROPERTIES: :CUSTOM_ID: function-org-babel-pop-to-session :END: -#+begin_example +@example org-babel-pop-to-session is an interactive Lisp function in `org-babel.el'. @@ -847,14 +855,14 @@ above features to work correctly. of the source block to the kill ring. [back] -#+end_example +@end example *** org-babel-tangle :PROPERTIES: :CUSTOM_ID: function-org-babel-tangle :END: -#+begin_example +@example org-babel-tangle is an interactive Lisp function in `org-babel-tangle.el'. @@ -867,14 +875,14 @@ above features to work correctly. 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 +@end example *** org-babel-execute-subtree :PROPERTIES: :CUSTOM_ID: function-org-babel-execute-subtree :END: -#+begin_example +@example org-babel-execute-subtree is an interactive Lisp function in `org-babel.el'. @@ -883,14 +891,14 @@ above features to work correctly. (org-babel-execute-subtree &optional ARG) Replace EVAL snippets in the entire subtree. -#+end_example +@end example *** org-babel-execute-buffer :PROPERTIES: :CUSTOM_ID: function-org-babel-execute-buffer :END: -#+begin_example +@example org-babel-execute-buffer is an interactive Lisp function in `org-babel.el'. @@ -899,14 +907,14 @@ above features to work correctly. (org-babel-execute-buffer &optional ARG) Replace EVAL snippets in the entire buffer. -#+end_example +@end example *** org-babel-sha1-hash :PROPERTIES: :CUSTOM_ID: function-org-babel-sha1-hash :END: -#+begin_example +@example org-babel-sha1-hash is an interactive Lisp function in `org-babel.el'. It is bound to C-c M-b h. @@ -914,14 +922,14 @@ above features to work correctly. (org-babel-sha1-hash &optional INFO) Not documented. -#+end_example +@end example *** org-babel-goto-named-source-block :PROPERTIES: :CUSTOM_ID: function-org-babel-goto-named-source-block :END: -#+begin_example +@example org-babel-goto-named-source-block is an interactive Lisp function in `org-babel.el'. @@ -930,14 +938,14 @@ above features to work correctly. (org-babel-goto-named-source-block &optional NAME) Go to a named source-code block. -#+end_example +@end example *** org-babel-lob-ingest :PROPERTIES: :CUSTOM_ID: function-org-babel-lob-ingest :END: -#+begin_example +@example org-babel-lob-ingest is an interactive Lisp function in `org-babel-lob.el'. @@ -946,7 +954,7 @@ above features to work correctly. (org-babel-lob-ingest &optional FILE) Add all source-blocks defined in FILE to `org-babel-library-of-babel'. -#+end_example +@end example @section Batch Execution It is possible to call Org-babel functions from the command line. @@ -954,7 +962,7 @@ This shell script calls [[function-org-babel-tangle][org-babel-tangle]] on every arguments. Be sure to adjust the paths to fit your system. -#+begin_src sh +@example #!/bin/sh # -*- mode: shell-script -*- # @@ -977,7 +985,7 @@ Be sure to adjust the paths to fit your system. (find-file (expand-file-name file \"$DIR\")) (org-babel-tangle) (kill-buffer)) '($FILES)))" -#+end_src +@end example @section Footnotes From 3cba424a694c639a2d40e32e36e796ff4696c788 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 12:28:25 -0400 Subject: [PATCH 04/34] Convert level 3 headings to @subsubsections --- doc/source-code-chapter.texi | 44 ++++++++++++++++++------------------ 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi index c2e93d742..9b2be2c05 100644 --- a/doc/source-code-chapter.texi +++ b/doc/source-code-chapter.texi @@ -131,7 +131,7 @@ language-specific header arguments. The values of header arguments can be set in three different ways, each more specific than the last. -*** System-wide +@subsubsection System-wide :PROPERTIES: :CUSTOM_ID: system-wide-header-argument :END: @@ -161,7 +161,7 @@ each more specific than the last. (assq-delete-all :noweb org-babel-default-header-args))) @end example -*** Org-mode Properties +@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 means they can be set on the outline header level. For example, the @@ -179,7 +179,7 @@ each more specific than the last. =org-set-property= function bound to =C-c C-x p= to set properties in Org-mode documents. -*** Source Code Block +@subsubsection Source Code Block :PROPERTIES: :CUSTOM_ID: single-block-header-arguments :END: @@ -207,7 +207,7 @@ each more specific than the last. :CUSTOM_ID: header-argument-specific-documentation :END: -*** =:var= +@subsubsection =:var= :PROPERTIES: :CUSTOM_ID: header-argument-var :END: @@ -352,7 +352,7 @@ each more specific than the last. function) and =describe-variable= (M-x describe variable) functions, respectively. -*** =:results= +@subsubsection =:results= :PROPERTIES: :CUSTOM_ID: header-argument-results :END: @@ -430,7 +430,7 @@ each more specific than the last. into the Org-mode buffer. E.g., =:results output replace=. -*** =:file= +@subsubsection =:file= :PROPERTIES: :CUSTOM_ID: header-argument-file :END: @@ -453,7 +453,7 @@ each more specific than the last. While the =:file= header argument can be used to specify the path to the output file, -*** =:dir= and remote execution +@subsubsection =:dir= and remote execution :PROPERTIES: :CUSTOM_ID: header-argument-dir :END: @@ -521,7 +521,7 @@ above features to work correctly. 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. -*** =:exports= +@subsubsection =:exports= :PROPERTIES: :CUSTOM_ID: header-argument-exports :END: @@ -538,7 +538,7 @@ above features to work correctly. - none :: nothing is included in the exported file. E.g., =:exports none=. -*** =:tangle= +@subsubsection =:tangle= :PROPERTIES: :CUSTOM_ID: tangle-header-arguments :END: @@ -555,7 +555,7 @@ above features to work correctly. is interpreted as a file basename to which the block will be exported. E.g., =:tangle basename=. -*** =:session= +@subsubsection =:session= :PROPERTIES: :CUSTOM_ID: header-argument-session :END: @@ -570,7 +570,7 @@ above features to work correctly. session a name. This makes it possible to run concurrent sessions for each interpreted language. -*** =:noweb= +@subsubsection =:noweb= :PROPERTIES: :CUSTOM_ID: header-argument-noweb :END: @@ -614,7 +614,7 @@ above features to work correctly. Thanks to Sébastien Vauban for this idea. -*** =:cache= +@subsubsection =:cache= :PROPERTIES: :CUSTOM_ID: header-argument-cache :END: @@ -779,7 +779,7 @@ above features to work correctly. @subsection Functions -*** org-babel-execute-src-block +@subsubsection org-babel-execute-src-block :PROPERTIES: :CUSTOM_ID: function-org-babel-execute-src-block :END: @@ -803,7 +803,7 @@ above features to work correctly. block. @end example -*** org-babel-open-src-block-result +@subsubsection org-babel-open-src-block-result :PROPERTIES: :CUSTOM_ID: function-org-babel-open-src-block-result :END: @@ -820,7 +820,7 @@ above features to work correctly. results already exist. @end example -*** org-babel-load-in-session +@subsubsection org-babel-load-in-session :PROPERTIES: :CUSTOM_ID: function-org-babel-load-in-session :END: @@ -838,7 +838,7 @@ above features to work correctly. [back] @end example -*** org-babel-pop-to-session +@subsubsection org-babel-pop-to-session :PROPERTIES: :CUSTOM_ID: function-org-babel-pop-to-session :END: @@ -857,7 +857,7 @@ above features to work correctly. [back] @end example -*** org-babel-tangle +@subsubsection org-babel-tangle :PROPERTIES: :CUSTOM_ID: function-org-babel-tangle :END: @@ -877,7 +877,7 @@ above features to work correctly. exported source code blocks by language. @end example -*** org-babel-execute-subtree +@subsubsection org-babel-execute-subtree :PROPERTIES: :CUSTOM_ID: function-org-babel-execute-subtree :END: @@ -893,7 +893,7 @@ above features to work correctly. Replace EVAL snippets in the entire subtree. @end example -*** org-babel-execute-buffer +@subsubsection org-babel-execute-buffer :PROPERTIES: :CUSTOM_ID: function-org-babel-execute-buffer :END: @@ -909,7 +909,7 @@ above features to work correctly. Replace EVAL snippets in the entire buffer. @end example -*** org-babel-sha1-hash +@subsubsection org-babel-sha1-hash :PROPERTIES: :CUSTOM_ID: function-org-babel-sha1-hash :END: @@ -924,7 +924,7 @@ above features to work correctly. Not documented. @end example -*** org-babel-goto-named-source-block +@subsubsection org-babel-goto-named-source-block :PROPERTIES: :CUSTOM_ID: function-org-babel-goto-named-source-block :END: @@ -940,7 +940,7 @@ above features to work correctly. Go to a named source-code block. @end example -*** org-babel-lob-ingest +@subsubsection org-babel-lob-ingest :PROPERTIES: :CUSTOM_ID: function-org-babel-lob-ingest :END: From 2263127360362441a87d4727bdae90768bad32cb Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 12:35:17 -0400 Subject: [PATCH 05/34] Add an example block that was missed --- doc/source-code-chapter.texi | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi index 9b2be2c05..aeee0f545 100644 --- a/doc/source-code-chapter.texi +++ b/doc/source-code-chapter.texi @@ -760,6 +760,7 @@ above features to work correctly. 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" @@ -768,6 +769,8 @@ above features to work correctly. (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]] | @@ -777,7 +780,6 @@ above features to work correctly. | =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: From b056b2cd772fca90ad07a1ea317921cc8a57728f Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 12:42:43 -0400 Subject: [PATCH 06/34] Convert level 4 headings to subsubheadings. Also some promotion of some of the most deeply nested headings. --- doc/source-code-chapter.texi | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi index aeee0f545..90851c0aa 100644 --- a/doc/source-code-chapter.texi +++ b/doc/source-code-chapter.texi @@ -287,7 +287,7 @@ each more specific than the last. : 4 @end example -**** alternate argument syntax +@subsubheading alternate argument syntax :PROPERTIES: :CUSTOM_ID: alternate-argument-syntax :END: @@ -369,7 +369,7 @@ each more specific than the last. *Note:* only one option from each type may be supplied per source code block. -**** collection +@subsubheading collection :PROPERTIES: :CUSTOM_ID: header-argument-results-collection :END: @@ -388,7 +388,7 @@ each more specific than the last. block. This header argument places Org-babel in scripting mode. E.g., =:results output=. -**** type +@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 @@ -419,7 +419,7 @@ each more specific than the last. enclosed in a code block. This option currently supports Emacs Lisp, python, and ruby. E.g., =:results value pp=. -**** handling +@subsubheading handling The following results options indicate what Org-babel should do with the results once they are collected. @@ -479,7 +479,7 @@ each more specific than the last. #+end_src @end example -**** Remote execution +@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 @@ -508,7 +508,7 @@ thanks to [[http://www.gnu.org/software/tramp/][tramp]]. Those using XEmacs, or version 23 may need to install tramp separately in order for the above features to work correctly. -**** Further points +@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 @@ -584,7 +584,7 @@ above features to work correctly. - =yes= :: all [[noweb-reference-syntax][noweb syntax]] references in the body of the source code block will be expanded before the block is evaluated. -**** Noweb Prefix Lines +@subsubheading Noweb Prefix Lines Noweb insertions are now placed behind the line prefix of the =<>=. @@ -652,8 +652,8 @@ above features to work correctly. non-session is returned to Org-mode as a table (a one- or two-dimensional vector of strings or numbers) when appropriate. -**** Non-session -***** =:results value= +@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 @@ -665,21 +665,21 @@ above features to work correctly. This is the only one of the four evaluation contexts in which the code is automatically wrapped in a function definition. -***** =:results output= +@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.) -**** =:session= -***** =:results value= +@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). -***** =:results output= +@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 @@ -688,6 +688,7 @@ above features to work correctly. non-interactive interpreter running as an external process. For example, compare the following two blocks: + @example #+begin_src python :results output print "hello" From ba5e0f06a12b5da9578619ad3e42632661179b98 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 14:57:09 -0400 Subject: [PATCH 07/34] Add material to introduction of source code chapter --- doc/source-code-chapter.texi | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi index 90851c0aa..d0ad56092 100644 --- a/doc/source-code-chapter.texi +++ b/doc/source-code-chapter.texi @@ -1,4 +1,31 @@ -@chapter Working with source code or Embedded Source Code +@chapter Working With Source Code or Embedded Source Code + +Source code can be included in Org-mode documents using a @samp{src} block: + +FIXME: This example is also in the Literal Examples section. +@example +#+BEGIN_SRC emacs-lisp +(defun org-xor (a b) + "Exclusive or." + (if a (not b) b)) +#+END_SRC +@end example + +Org supports the following ways of working with such code blocks: + +@itemize @bullet +@item +Editing in the appropriate Emacs major-mode (@kbd{C-c '}) +@item +Export with appropriate markup +@item +Extraction (``tangling'') into pure code files. +@item +Execution, with results captured in the Org buffer +@item +Using code blocks in table formulas +@end itemize + @section Syntax :PROPERTIES: From 52fd87ad3cf5a26b805060cd0dc1bca38028b698 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 15:54:14 -0400 Subject: [PATCH 08/34] Working on syntax section --- doc/source-code-chapter.texi | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi index d0ad56092..b21fd7c02 100644 --- a/doc/source-code-chapter.texi +++ b/doc/source-code-chapter.texi @@ -36,27 +36,32 @@ Using code blocks in table formulas The basic syntax of source code blocks in Org-babel is as follows: @example -#+begin_src language header-arguments +#+begin_src language header-arguments switches body #+end_src @end example -- language :: The language of the code in the source code block. Valid - values must be members of =org-babel-interpreters=. -- header-arguments :: Header arguments control many facets of the - evaluation and output of source code blocks. See the [[header-arguments][Header - Arguments]] section for a complete review of available header - arguments. -- body :: The source code to be evaluated. An important key-binding - is C-c '. This calls =org-edit-src-code=, a function that brings - up an edit buffer containing the code using the Emacs major mode - appropriate to the language. You can edit your source code block - as you regularly would in Emacs. - +@table +@item language +The language of the code in the source code block. Valid values must +be members of =org-babel-interpreters=. +@item header-arguments +Header arguments control many facets of the evaluation and output of +source code blocks. See the [[header-arguments][Header Arguments]] +section for a complete review of available header arguments. +@item switches +FIXME link/relocate switches discussion in ``Literal examples'' section +@item body +The source code to be evaluated. An important key-binding is C-c '. +This calls =org-edit-src-code=, a function that brings up an edit +buffer containing the code using the Emacs major mode appropriate to +the language. You can edit your source code block as you regularly +would in Emacs. +@end table This syntax can be expanded by naming the source code block. @example #+sourcename -#+begin_src language header-arguments +#+begin_src language header-arguments switches body #+end_src @end example From 850bcdac6c0295dcb50fa71fc78794babb30ceb3 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 22:09:36 -0400 Subject: [PATCH 09/34] Edits to initial sections --- doc/source-code-chapter.texi | 79 ++++++++++++++++++++++++------------ 1 file changed, 54 insertions(+), 25 deletions(-) diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi index b21fd7c02..9cce3ccc3 100644 --- a/doc/source-code-chapter.texi +++ b/doc/source-code-chapter.texi @@ -1,8 +1,7 @@ -@chapter Working With Source Code or Embedded Source Code +@chapter ``Working With Source Code'' or ``Embedded Source Code'' Source code can be included in Org-mode documents using a @samp{src} block: -FIXME: This example is also in the Literal Examples section. @example #+BEGIN_SRC emacs-lisp (defun org-xor (a b) @@ -11,52 +10,82 @@ FIXME: This example is also in the Literal Examples section. #+END_SRC @end example -Org supports the following ways of working with such code blocks: +Org provides the following features for working with such code blocks: @itemize @bullet @item -Editing in the appropriate Emacs major-mode (@kbd{C-c '}) +Editing in the appropriate Emacs major-mode (@ref{Editing Source Code}) @item -Export with appropriate markup +Export with appropriate markup (@ref{Exporting Code Blocks}) @item -Extraction (``tangling'') into pure code files. +Extraction (``tangling'') into pure code files. (@ref{Extracting Source Code}) @item -Execution, with results captured in the Org buffer +Code execution, with results captured in the Org buffer (@ref{Evaluating Code Blocks}) @item Using code blocks in table formulas @end itemize -@section Syntax - :PROPERTIES: - :CUSTOM_ID: syntax - :END: -@subsection Source Code Block -The basic syntax of source code blocks in Org-babel is as follows: +@section Structure of Code Blocks + +The basic structure of code blocks is as follows: @example +#+srcname: name #+begin_src language header-arguments switches body #+end_src @end example -@table + +@table @code +@item name +The initial name line is optional. If present it is used during code evaluation. @item language -The language of the code in the source code block. Valid values must -be members of =org-babel-interpreters=. +The language of the code in the block. @item header-arguments -Header arguments control many facets of the evaluation and output of -source code blocks. See the [[header-arguments][Header Arguments]] -section for a complete review of available header arguments. +Header arguments control evaluation, export and tangling of source +code blocks. See the [[header-arguments][Header Arguments]] section. @item switches FIXME link/relocate switches discussion in ``Literal examples'' section @item body -The source code to be evaluated. An important key-binding is C-c '. -This calls =org-edit-src-code=, a function that brings up an edit -buffer containing the code using the Emacs major mode appropriate to -the language. You can edit your source code block as you regularly -would in Emacs. +The code @end table + +@section Editing Source Code + +Use @kbd{C-c '} to edit the code block at point. This brings up a +language major-mode 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{-mode} exists, where +@code{} is the language named in 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, where whitespace the 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 + +@section Exporting Code Blocks + +@section Extracting Source Code + +@section Evaluating Code Blocks + This syntax can be expanded by naming the source code block. @example @@ -107,7 +136,7 @@ body #+lob: R-plot(data=R-plot-example-data) @end example -@section Languages +@subsection Languages :PROPERTIES: :CUSTOM_ID: languages :END: From 58c3358a0e3032748e2d59daf7e32f025038f1dc Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 22:10:17 -0400 Subject: [PATCH 10/34] Create texinfo node structures for new chapter --- doc/org.texi | 5 +++-- doc/source-code-chapter.texi | 25 +++++++++++++++++++++++++ 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index a5821f649..6a62ef639 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -107,6 +107,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. * Miscellaneous:: All the rest which did not fit elsewhere * Hacking:: How to hack your way around * MobileOrg:: Viewing and capture on a mobile device @@ -10118,7 +10119,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, Miscellaneous, Exporting, Top +@node Publishing, Working With Source Code, Exporting, Top @chapter Publishing @cindex publishing @cindex O'Toole, David @@ -10619,7 +10620,7 @@ This may be necessary in particular if files include other files via @include source-code-chapter.texi -@node Miscellaneous, Hacking, Publishing, Top +@node Miscellaneous, Hacking, Working With Source Code, Top @chapter Miscellaneous @menu diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi index 9cce3ccc3..dafe4365c 100644 --- a/doc/source-code-chapter.texi +++ b/doc/source-code-chapter.texi @@ -1,3 +1,6 @@ +@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: @@ -25,8 +28,18 @@ Code execution, with results captured in the Org buffer (@ref{Evaluating Code Bl 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 basic structure of code blocks is as follows: @@ -52,6 +65,9 @@ FIXME link/relocate switches discussion in ``Literal examples'' section 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 @@ -80,10 +96,19 @@ 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 +@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 +@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 This syntax can be expanded by naming the source code block. From fe6521b9b07d1f20d6e7349813c024227ee76708 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 22:12:41 -0400 Subject: [PATCH 11/34] Move new chapter into main org.texi file It is currently impractical to work with it as an @included file, because the automatic node pointer updates do not work by default. --- doc/org.texi | 1085 +++++++++++++++++++++++++++++++++- doc/source-code-chapter.texi | 1084 --------------------------------- 2 files changed, 1084 insertions(+), 1085 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 6a62ef639..322b2e9f1 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10618,7 +10618,1090 @@ 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:}. -@include source-code-chapter.texi +@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 such code blocks: + +@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 basic structure of code blocks is as follows: + +@example +#+srcname: name +#+begin_src language header-arguments switches +body +#+end_src +@end example + +@table @code +@item name +The initial name line is optional. If present it is used during code evaluation. +@item language +The language of the code in the block. +@item header-arguments +Header arguments control evaluation, export and tangling of source +code blocks. See the [[header-arguments][Header Arguments]] section. +@item switches +FIXME link/relocate switches discussion in ``Literal examples'' section +@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 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{-mode} exists, where +@code{} is the language named in 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, where whitespace the 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 + +@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 + +@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 + +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 has support for the following languages. + + | 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 | + + 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 three different ways, +each more specific 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 + means they can be set on the outline header level. For example, the + value of the =:cache= header argument will default to true in all + source code blocks under the following example of an Org-mode outline header: + @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 + =<>=. + + This behavior is illustrated in the following example. Because + the =<>= noweb reference appears behind the SQL + comment syntax, each line of the expanded noweb reference will + be commented. + + This source code block: + + @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: + : <> + + 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 =<>= 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]]. + +@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 @chapter Miscellaneous diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi index dafe4365c..e69de29bb 100644 --- a/doc/source-code-chapter.texi +++ b/doc/source-code-chapter.texi @@ -1,1084 +0,0 @@ -@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 such code blocks: - -@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 basic structure of code blocks is as follows: - -@example -#+srcname: name -#+begin_src language header-arguments switches -body -#+end_src -@end example - -@table @code -@item name -The initial name line is optional. If present it is used during code evaluation. -@item language -The language of the code in the block. -@item header-arguments -Header arguments control evaluation, export and tangling of source -code blocks. See the [[header-arguments][Header Arguments]] section. -@item switches -FIXME link/relocate switches discussion in ``Literal examples'' section -@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 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{-mode} exists, where -@code{} is the language named in 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, where whitespace the 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 - -@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 - -@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 - -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 has support for the following languages. - - | 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 | - - 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 three different ways, -each more specific 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 - means they can be set on the outline header level. For example, the - value of the =:cache= header argument will default to true in all - source code blocks under the following example of an Org-mode outline header: - @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 - =<>=. - - This behavior is illustrated in the following example. Because - the =<>= noweb reference appears behind the SQL - comment syntax, each line of the expanded noweb reference will - be commented. - - This source code block: - - @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: - : <> - - 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 =<>= 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]]. - -@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= From c2a1f16556c2e7dfb21327dab2ae827ab3a9566c Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 22:13:18 -0400 Subject: [PATCH 12/34] Delete separate file for new chapter --- doc/source-code-chapter.texi | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 doc/source-code-chapter.texi diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi deleted file mode 100644 index e69de29bb..000000000 From b5bbbc1be100196d4a5d1df594773eb53687b4ab Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 22:19:19 -0400 Subject: [PATCH 13/34] Use angle bracket tags to refer to structural elements of code block --- doc/org.texi | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 322b2e9f1..c69f8dd7e 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10665,23 +10665,23 @@ Using code blocks in table formulas The basic structure of code blocks is as follows: @example -#+srcname: name -#+begin_src language header-arguments switches -body +#+srcname: +#+begin_src
+ #+end_src @end example @table @code -@item name +@item The initial name line is optional. If present it is used during code evaluation. -@item language +@item The language of the code in the block. -@item header-arguments +@item
Header arguments control evaluation, export and tangling of source code blocks. See the [[header-arguments][Header Arguments]] section. -@item switches +@item FIXME link/relocate switches discussion in ``Literal examples'' section -@item body +@item The code @end table From e72d8b71c86022e11ef536c783d5ff0a39e0095a Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 22:19:32 -0400 Subject: [PATCH 14/34] Minor edits --- doc/org.texi | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index c69f8dd7e..4d6d25588 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10690,27 +10690,27 @@ 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 major-mode 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. +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. +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{-mode} exists, where -@code{} is the language named in header line of the code block, +@code{} 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, where whitespace the indentation in the output is critical. +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. From c6af0f947958ef5fd2a403cdf941369bbabdf39d Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Wed, 14 Apr 2010 16:47:44 -0400 Subject: [PATCH 15/34] Add entry to main menu --- doc/org.texi | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/org.texi b/doc/org.texi index 4d6d25588..5944bc667 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -500,6 +500,7 @@ 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 From 020cfb0dfab5218a0d2518b2dbc843e91af25034 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sat, 17 Apr 2010 20:19:55 -0400 Subject: [PATCH 16/34] Work on initial sections. --- doc/org.texi | 147 ++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 116 insertions(+), 31 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 5944bc667..330ef852f 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10634,7 +10634,7 @@ 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 such code blocks: +Org provides the following features for working with blocks of code: @itemize @bullet @item @@ -10667,21 +10667,21 @@ The basic structure of code blocks is as follows: @example #+srcname: -#+begin_src
+#+begin_src
#+end_src @end example @table @code @item -The initial name line is optional. If present it is used during code evaluation. +An optional name for the block (see @ref{Evaluating Code Blocks}) @item The language of the code in the block. -@item
-Header arguments control evaluation, export and tangling of source -code blocks. See the [[header-arguments][Header Arguments]] section. @item -FIXME link/relocate switches discussion in ``Literal examples'' section +Optional links FIXME link/relocate switches discussion in @ref{Literal examples} +@item
+Optional header arguments control many aspects of evaluation, export and tangling of +source code blocks. See the [[header-arguments][Header Arguments]] section. @item The code @end table @@ -10722,11 +10722,64 @@ 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 +By default, code blocks export to HTML with the appearance of the fontified +language major-mode Emacs buffer. 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 @@ -10789,30 +10842,62 @@ body Org-babel has support for the following languages. - | 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 | +@c BEGIN RECEIVE ORGTBL org_babel_lang-table +@multitable @columnfractions 0.036 0.205 0.026 0.733 +@item Language @tab Documentation @tab Identifier @tab Requirements +@item Asymptote @tab org-babel-doc-asymptote @tab asymptote @tab [[http://asymptote.sourceforge.net/][asymptote]], [[http://asymptote.sourceforge.net/doc/Editing-modes.html][asy-mode]] +@item C @tab [[file:languages/org-babel-doc-C.org][org-babel-doc-C]] @tab C @tab none +@item Clojure @tab [[file:languages/org-babel-doc-clojure.org][org-babel-doc-clojure]] @tab clojure @tab [[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]] +@item css @tab org-babel-doc-css @tab css @tab none +@item ditaa @tab org-babel-doc-ditaa @tab ditaa @tab [[http://ditaa.org/ditaa/][ditaa]] (bundled with Org-mode) +@item Graphviz @tab org-babel-doc-dot @tab dot @tab [[http://www.graphviz.org/][dot]] +@item Emacs Lisp @tab org-babel-doc-emacs-lisp @tab emacs-lisp @tab none +@item gnuplot @tab org-babel-doc-gnuplot @tab gnuplot @tab [[http://www.gnuplot.info/][gnuplot]], [[http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html][gnuplot-mode]] +@item Haskell @tab org-babel-doc-haskell @tab haskell @tab [[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]] +@item Matlab @tab [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] @tab matlab @tab matlab, [[http://sourceforge.net/projects/matlab-emacs/][matlab.el]] +@item LaTeX @tab [[file:languages/org-babel-doc-LaTeX.org][org-babel-doc-latex]] @tab latex @tab [[http://www.latex-project.org/][latex]], [[http://www.gnu.org/software/auctex/][auctex]], [[http://www.gnu.org/software/auctex/reftex.html][reftex]] +@item Objective Caml @tab org-babel-doc-ocaml @tab ocaml @tab [[http://caml.inria.fr/][ocaml]], [[http://www-rocq.inria.fr/~acohen/tuareg/][tuareg-mode]] +@item Octave @tab [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] @tab octave @tab octave +@item OZ @tab [[file:languages/org-babel-doc-oz.org][org-babel-doc-oz]] @tab oz @tab [[http://www.mozart-oz.org/][Mozart]] which includes a major mode +@item Perl @tab org-babel-doc-perl @tab perl @tab [[http://www.perl.org/][perl]], [[http://www.emacswiki.org/emacs/CPerlMode][cperl-mode]] (optional) +@item Python @tab org-babel-doc-python @tab python @tab [[http://www.python.org/][python]], [[https://launchpad.net/python-mode][python-mode]] (optional) +@item R @tab [[file:languages/org-babel-doc-R.org][org-babel-doc-R]] @tab R @tab [[http://www.r-project.org/][R]], [[http://ess.r-project.org/][ess-mode]] +@item Ruby @tab org-babel-doc-ruby @tab ruby @tab [[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]] +@item Sass @tab org-babel-doc-sass @tab sass @tab [[http://sass-lang.com/][sass]], [[http://github.com/nex3/haml/blob/master/extra/sass-mode.el][sass-mode]] +@item GNU Screen @tab [[file:languages/org-babel-doc-screen.org][org-babel-doc-screen]] @tab screen @tab [[http://www.gnu.org/software/screen/][screen]], a terminal +@item shell @tab org-babel-doc-sh @tab sh[fn:1] @tab a shell +@item SQL @tab org-babel-doc-sql @tab sql @tab none +@end multitable +@c END RECEIVE ORGTBL org_babel_lang-table + +@ignore + +#+ORGTBL: SEND org-babel-lang-table orgtbl-to-texinfo :splice t :skip 2 + | 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 From 91a169177abdadfec58a30a62bb83f13ac4617e9 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sat, 17 Apr 2010 21:47:57 -0400 Subject: [PATCH 17/34] Edits, mainly to header args section --- doc/org.texi | 160 ++++++++++++++++++++++++++++++++++----------------- 1 file changed, 107 insertions(+), 53 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 330ef852f..9ded71487 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10663,7 +10663,7 @@ Using code blocks in table formulas @comment Structure of Code Blocks, Editing Source Code, Working With Source Code, Working With Source Code @section Structure of Code Blocks -The basic structure of code blocks is as follows: +The structure of code blocks is as follows: @example #+srcname: @@ -10680,8 +10680,10 @@ The language of the code in the block. @item Optional links FIXME link/relocate switches discussion in @ref{Literal examples} @item
-Optional header arguments control many aspects of evaluation, export and tangling of -source code blocks. See the [[header-arguments][Header Arguments]] section. +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 The code @end table @@ -10723,10 +10725,14 @@ to a non-nil value to switch without asking. @section Exporting Code Blocks By default, code blocks export to HTML with the appearance of the fontified -language major-mode Emacs buffer. 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. +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. @@ -10785,6 +10791,11 @@ FIXME: This variable may have been changed recently @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 @@ -10840,39 +10851,69 @@ body :CUSTOM_ID: languages :END: - Org-babel has support for the following languages. +Org-babel can evaluate/execute/compile the following languages. See the +language specific documentation on Worg for details. -@c BEGIN RECEIVE ORGTBL org_babel_lang-table -@multitable @columnfractions 0.036 0.205 0.026 0.733 -@item Language @tab Documentation @tab Identifier @tab Requirements -@item Asymptote @tab org-babel-doc-asymptote @tab asymptote @tab [[http://asymptote.sourceforge.net/][asymptote]], [[http://asymptote.sourceforge.net/doc/Editing-modes.html][asy-mode]] -@item C @tab [[file:languages/org-babel-doc-C.org][org-babel-doc-C]] @tab C @tab none -@item Clojure @tab [[file:languages/org-babel-doc-clojure.org][org-babel-doc-clojure]] @tab clojure @tab [[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]] -@item css @tab org-babel-doc-css @tab css @tab none -@item ditaa @tab org-babel-doc-ditaa @tab ditaa @tab [[http://ditaa.org/ditaa/][ditaa]] (bundled with Org-mode) -@item Graphviz @tab org-babel-doc-dot @tab dot @tab [[http://www.graphviz.org/][dot]] -@item Emacs Lisp @tab org-babel-doc-emacs-lisp @tab emacs-lisp @tab none -@item gnuplot @tab org-babel-doc-gnuplot @tab gnuplot @tab [[http://www.gnuplot.info/][gnuplot]], [[http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html][gnuplot-mode]] -@item Haskell @tab org-babel-doc-haskell @tab haskell @tab [[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]] -@item Matlab @tab [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] @tab matlab @tab matlab, [[http://sourceforge.net/projects/matlab-emacs/][matlab.el]] -@item LaTeX @tab [[file:languages/org-babel-doc-LaTeX.org][org-babel-doc-latex]] @tab latex @tab [[http://www.latex-project.org/][latex]], [[http://www.gnu.org/software/auctex/][auctex]], [[http://www.gnu.org/software/auctex/reftex.html][reftex]] -@item Objective Caml @tab org-babel-doc-ocaml @tab ocaml @tab [[http://caml.inria.fr/][ocaml]], [[http://www-rocq.inria.fr/~acohen/tuareg/][tuareg-mode]] -@item Octave @tab [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] @tab octave @tab octave -@item OZ @tab [[file:languages/org-babel-doc-oz.org][org-babel-doc-oz]] @tab oz @tab [[http://www.mozart-oz.org/][Mozart]] which includes a major mode -@item Perl @tab org-babel-doc-perl @tab perl @tab [[http://www.perl.org/][perl]], [[http://www.emacswiki.org/emacs/CPerlMode][cperl-mode]] (optional) -@item Python @tab org-babel-doc-python @tab python @tab [[http://www.python.org/][python]], [[https://launchpad.net/python-mode][python-mode]] (optional) -@item R @tab [[file:languages/org-babel-doc-R.org][org-babel-doc-R]] @tab R @tab [[http://www.r-project.org/][R]], [[http://ess.r-project.org/][ess-mode]] -@item Ruby @tab org-babel-doc-ruby @tab ruby @tab [[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]] -@item Sass @tab org-babel-doc-sass @tab sass @tab [[http://sass-lang.com/][sass]], [[http://github.com/nex3/haml/blob/master/extra/sass-mode.el][sass-mode]] -@item GNU Screen @tab [[file:languages/org-babel-doc-screen.org][org-babel-doc-screen]] @tab screen @tab [[http://www.gnu.org/software/screen/][screen]], a terminal -@item shell @tab org-babel-doc-sh @tab sh[fn:1] @tab a shell -@item SQL @tab org-babel-doc-sql @tab sql @tab none +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 +@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 | + -#+ORGTBL: SEND org-babel-lang-table orgtbl-to-texinfo :splice t :skip 2 | 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]] | @@ -10897,31 +10938,34 @@ body | 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 +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. +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 three different ways, -each more specific than the last. +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: @@ -10955,10 +10999,20 @@ each more specific than the last. @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 - means they can be set on the outline header level. For example, the - value of the =:cache= header argument will default to true in all - source code blocks under the following example of an Org-mode outline header: +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: From 6f399c20b66b617178a4f6a82d8f489ea5ebd4d3 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Thu, 18 Mar 2010 21:04:25 -0400 Subject: [PATCH 18/34] babel: Allow EmacsLink to be used for matlab session evaluation To use EmacsLink, the user will need to set org-babel-matlab-with-emacs-link to a non-nil value, and also arrange that (matlab-with-emacs-link) evaluates to a non-nil value. --- contrib/babel/lisp/langs/org-babel-matlab.el | 5 +++++ contrib/babel/lisp/langs/org-babel-octave.el | 15 ++++++++++++--- 2 files changed, 17 insertions(+), 3 deletions(-) diff --git a/contrib/babel/lisp/langs/org-babel-matlab.el b/contrib/babel/lisp/langs/org-babel-matlab.el index d40496e9d..4809b56f3 100644 --- a/contrib/babel/lisp/langs/org-babel-matlab.el +++ b/contrib/babel/lisp/langs/org-babel-matlab.el @@ -50,6 +50,11 @@ (defun org-babel-expand-body:matlab (body params &optional processed-params) body) +(defvar org-babel-matlab-with-emacs-link nil + "If non-nil use matlab-shell-run-region for session + evaluation. This will use EmacsLink if (matlab-with-emacs-link) + evaluates to a non-nil value.") + (defun org-babel-execute:matlab (body params) "Execute a block of matlab code with org-babel." (org-babel-execute:octave body params 'matlab)) diff --git a/contrib/babel/lisp/langs/org-babel-octave.el b/contrib/babel/lisp/langs/org-babel-octave.el index 72183a155..9a27d8f31 100644 --- a/contrib/babel/lisp/langs/org-babel-octave.el +++ b/contrib/babel/lisp/langs/org-babel-octave.el @@ -164,9 +164,18 @@ value of the last statement in BODY, as elisp." (mapconcat #'org-babel-chomp (list (format org-babel-octave-wrapper-method body tmp-file tmp-file) org-babel-octave-eoe-indicator) "\n")))) - (raw (org-babel-comint-with-output session - (if matlabp org-babel-octave-eoe-indicator org-babel-octave-eoe-output) t - (insert full-body) (comint-send-input nil t))) results) + (raw (if (and matlabp org-babel-matlab-with-emacs-link) + (save-window-excursion + (with-temp-buffer + (insert full-body) + (matlab-shell-run-region (point-min) (point-max)) + "")) ;; matlab-shell-run-region doesn't seem to + ;; make *matlab* buffer contents easily + ;; available, so :results output currently + ;; won't work + (org-babel-comint-with-output session + (if matlabp org-babel-octave-eoe-indicator org-babel-octave-eoe-output) t + (insert full-body) (comint-send-input nil t)))) results) (case result-type (value (org-babel-octave-import-elisp-from-file (org-babel-maybe-remote-file tmp-file))) From a61de7b13020af09091efd0ff9efce252aa341cb Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Fri, 30 Apr 2010 16:47:07 -0400 Subject: [PATCH 19/34] babel: matlab: don't try matlab-shell if using emacs link --- contrib/babel/lisp/langs/org-babel-octave.el | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/contrib/babel/lisp/langs/org-babel-octave.el b/contrib/babel/lisp/langs/org-babel-octave.el index 9a27d8f31..f20492ada 100644 --- a/contrib/babel/lisp/langs/org-babel-octave.el +++ b/contrib/babel/lisp/langs/org-babel-octave.el @@ -104,7 +104,8 @@ then create. Return the initialized session." (let ((session (or session (if matlabp "*Inferior Matlab*" "*Inferior Octave*")))) (if (org-babel-comint-buffer-livep session) session (save-window-excursion - (if matlabp (matlab-shell) (run-octave)) + (if matlabp (unless org-babel-matlab-with-emacs-link (matlab-shell)) + (run-octave)) (rename-buffer (if (bufferp session) (buffer-name session) (if (stringp session) session (buffer-name)))) (current-buffer)))))) From e873ef54b351887d7007cdf9db4c24fc8e9c3b0b Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Fri, 30 Apr 2010 22:35:50 -0400 Subject: [PATCH 20/34] Some docstring typos --- lisp/org-entities.el | 8 ++++---- lisp/org-faces.el | 4 ++-- lisp/org.el | 21 +++++++++++---------- 3 files changed, 17 insertions(+), 16 deletions(-) diff --git a/lisp/org-entities.el b/lisp/org-entities.el index 289b873e3..68802ee43 100644 --- a/lisp/org-entities.el +++ b/lisp/org-entities.el @@ -46,11 +46,11 @@ in backends where the corresponding character is not available." :type 'boolean) (defcustom org-entities-user nil - "User-defined entities used in Org-mode to preduce special characters. -Each entry in this list is a list of strings. It associate the name + "User-defined entities used in Org-mode to produce special characters. +Each entry in this list is a list of strings. It associates the name of the entity that can be inserted into an Org file as \\name with the appropriate replacements for the different export backends. The order -of the fields is he following +of the fields is the following name As a string, without the leading backslash LaTeX replacement In ready LaTeX, no further processing will take place @@ -62,7 +62,7 @@ ASCII replacement Plain ASCII, no extensions. Symbols that cannot be represented will be written out as an explanatory text. But see the variable `org-entities-ascii-keep-macro-form'. Latin1 replacement Use the special characters available in latin1. -utf-8 replacement Use special character available in utf-8. +utf-8 replacement Use the special characters available in utf-8. If you define new entities here that require specific LaTeX packages to be loaded, add these packages to `org-export-latex-packages-alist'." diff --git a/lisp/org-faces.el b/lisp/org-faces.el index d20d4df93..2f4307768 100644 --- a/lisp/org-faces.el +++ b/lisp/org-faces.el @@ -458,7 +458,7 @@ changes." (:foreground "green")) (((class color) (min-colors 8) (background dark)) (:foreground "yellow")))) - "Face for fixed-with text like code snippets." + "Face for fixed-width text like code snippets." :group 'org-faces :version "22.1") @@ -600,7 +600,7 @@ belong to the weekend." (defface org-agenda-dimmed-todo-face '((((background light)) (:foreground "grey50")) (((background dark)) (:foreground "grey50"))) - "Face used to dimm blocked tasks in the agenda." + "Face used to dim blocked tasks in the agenda." :group 'org-faces) (defface org-scheduled-previously diff --git a/lisp/org.el b/lisp/org.el index 0f6929624..0385383d2 100644 --- a/lisp/org.el +++ b/lisp/org.el @@ -3029,7 +3029,7 @@ compiling LaTeX snippets into images for inclusion into HTML." (string :tag "A line of LaTeX")))) (defcustom org-export-latex-packages-alist nil - "Alist of packages to be inserted in every LaTeX the header. + "Alist of packages to be inserted in every LaTeX header. These will be inserted after `org-export-latex-default-packages-alist'. Each cell is of the format \( \"options\" \"package\" snippet-flag \). SNIPPET-FLAG, when t, indicates that this package is also needed when @@ -4773,7 +4773,7 @@ will be prompted for." '(font-lock-fontified t face org-block)) t) ((and (match-end 4) (equal dc3 "begin")) - ;; Truely a block + ;; Truly a block (setq block-type (downcase (match-string 5)) quoting (member block-type org-protecting-blocks)) (when (re-search-forward @@ -7174,7 +7174,7 @@ Sorting can be alphabetically, numerically, by date/time as given by a time stamp, by a property or by priority. The command prompts for the sorting type unless it has been given to the -function through the SORTING-TYPE argument, which needs to a character, +function through the SORTING-TYPE argument, which needs to be a character, \(?n ?N ?a ?A ?t ?T ?s ?S ?d ?D ?p ?P ?r ?R ?f ?F). Here is the precise meaning of each character: @@ -7471,11 +7471,11 @@ If WITH-CASE is non-nil, the sorting will be case-sensitive." ;;;###autoload (define-minor-mode orgstruct-mode - "Toggle the minor more `orgstruct-mode'. -This mode is for using Org-mode structure commands in other modes. -The following key behave as if Org-mode was active, if the cursor -is on a headline, or on a plain list item (both in the definition -of Org-mode). + "Toggle the minor mode `orgstruct-mode'. +This mode is for using Org-mode structure commands in other +modes. The following keys behave as if Org-mode were active, if +the cursor is on a headline, or on a plain list item (both as +defined by Org-mode). M-up Move entry/item up M-down Move entry/item down @@ -15917,8 +15917,9 @@ See `org-ctrl-c-ctrl-c-hook' for more information. This hook runs as the first action when TAB is pressed, even before `org-cycle' messes around with the `outline-regexp' to cater for inline tasks and plain list item folding. -If any function in this hook returns t, not other actions like table -field motion visibility cycling will be done.") +If any function in this hook returns t, any other actions that +would have been caused by TAB (such as table field motion or visibility +cycling) will not occur.") (defvar org-tab-after-check-for-table-hook nil "Hook for functions to attach themselves to TAB. From b502a3d86226ac20912780d5174cc559a1274596 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Fri, 30 Apr 2010 22:36:01 -0400 Subject: [PATCH 21/34] Some manual typos --- doc/org.texi | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 5ee140130..51cdb928d 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -495,7 +495,7 @@ example as: @r{@bullet{} a TODO list editor} @r{@bullet{} a full agenda and planner with deadlines and work scheduling} @pindex GTD, Getting Things Done -@r{@bullet{} an environment to implement David Allen's GTD system} +@r{@bullet{} an environment in which to implement David Allen's GTD system} @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} @@ -7940,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 @@ -8559,7 +8559,7 @@ Edit the source code example at point in its native mode. This works by switching to a temporary buffer with the source code. You need to exit by pressing @kbd{C-c '} again@footnote{Upon exit, lines starting with @samp{*} or @samp{#} will get a comma prepended, to keep them from being interpreted -by Org as outline nodes or special comments. These commas will be striped +by Org as outline nodes or special comments. These commas will be stripped for editing with @kbd{C-c '}, and also for export.}, the edited version will then replace the old version in the Org buffer. Fixed-width regions (where each line starts with a colon followed by a space) will be edited @@ -9718,14 +9718,14 @@ If you need references to a label created in this way, write @node Beamer class export, , Images in LaTeX export, LaTeX and PDF export @subsection Beamer class export -The LaTeX class @file{beamer} allows to produce high quality presentations +The LaTeX class @file{beamer} allows production of high quality presentations using LaTeX and pdf processing. Org-mode has special support for turning an Org-mode file or tree into a @file{beamer} presentation. When the LaTeX class for the current buffer (as set with @code{#+LaTeX_CLASS: beamer}) or subtree (set with a @code{LaTeX_CLASS} property) is @code{beamer}, a special export mode will turn the file or tree into a beamer -presentation. Any tree with not-to-deep level nesting should in principle be +presentation. Any tree with not-too-deep level nesting should in principle be exportable as a beamer presentation. By default, the top-level entries (or the first level below the selected subtree heading) will be turned into frames, and the outline structure below this level will become itemize lists. @@ -9757,7 +9757,7 @@ set an options argument for the implied @code{columns} environment. @item BEAMER_col The width of a column that should start with this entry. If this property is set, the entry will also get a @code{:BMCOL:} property to make this visible. -Also this tag is only a visual aid. When his is a plain number, it will be +Also this tag is only a visual aid. When this is a plain number, it will be interpreted as a fraction of @code{\textwidth}. Otherwise it will be assumed that you have specified the units, like @samp{3cm}. The first such property in a frame will start a @code{columns} environment to surround the columns. @@ -9801,7 +9801,7 @@ environment or the @code{BEAMER_col} property. Column view provides a great way to set the environment of a node and other important parameters. Make sure you are using a COLUMN format that is geared toward this special purpose. The command @kbd{M-x -org-beamer-settings-template} does define such a format. +org-beamer-settings-template} defines such a format. Here is a simple example Org document that is intended for beamer export. From 182b107682d498ddff9f63c5dbdc3021d9843b01 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Fri, 30 Apr 2010 22:53:53 -0400 Subject: [PATCH 22/34] Correct coderef switch in docstring --- lisp/org-src.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lisp/org-src.el b/lisp/org-src.el index 2c067ff34..529413846 100644 --- a/lisp/org-src.el +++ b/lisp/org-src.el @@ -63,7 +63,7 @@ there are kept outside the narrowed region." "The default coderef format. This format string will be used to search for coderef labels in literal examples (EXAMPLE and SRC blocks). The format can be overwritten in -an individual literal example with the -f option, like +an individual literal example with the -l option, like #+BEGIN_SRC pascal +n -r -l \"((%s))\" ... From 23a1f40e3a0770d9e3184ad499bb5b117fff4a50 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Sat, 1 May 2010 06:30:02 +0200 Subject: [PATCH 23/34] Fix more typos --- doc/org.texi | 12 ++++++------ lisp/org-clock.el | 4 +++- lisp/org-entities.el | 4 ++-- 3 files changed, 11 insertions(+), 9 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index bf56c8438..781cc761c 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -8458,8 +8458,8 @@ Some backends (HTML, La@TeX{}, and DocBook) allow you to directly include images into the exported document. Org does this, if a link to an image files does not have a description part, for example @code{[[./img/a.jpg]]}. If you wish to define a caption for the image and maybe a label for internal -cross references, you sure that the link is on a line by itself precede it -with: +cross references, make sure that the link is on a line by itself and precede +it with @code{#+CAPTION} and @code{#+LABEL} as follows: @example #+CAPTION: This is the caption for the next figure link (or table) @@ -8700,7 +8700,7 @@ delimiters, for example: Angles are written as Greek letters \alpha, \beta and \gamma. @end example -@vindex org-html-entities +@vindex org-entities During export, these symbols will be transformed into the native format of the exporter backend. Strings like @code{\alpha} will be exported as @code{α} in the HTML output, and as @code{$\alpha$} in the La@TeX{} @@ -8709,7 +8709,7 @@ output. Similarly, @code{\nbsp} will become @code{ } in HTML and like this: @samp{\Aacute@{@}stor}. A large number of entities is provided, with names taken from both HTML and -La@TeX{}, see the variable @code{org-html-entities} for the complete list. +La@TeX{}, see the variable @code{org-entities} for the complete list. @samp{\-} is treated as a shy hyphen, and @samp{--}, @samp{---}, and @samp{...} are all converted into special commands creating hyphens of different lengths or a compact set of dots. @@ -10013,12 +10013,12 @@ more types to this list as long as DocBook supports them. @cindex Special characters in DocBook export @vindex org-export-docbook-doctype -@vindex org-html-entities +@vindex org-entities Special characters that are written in @TeX{}-like syntax, such as @code{\alpha}, @code{\Gamma}, and @code{\Zeta}, are supported by DocBook exporter. These characters are rewritten to XML entities, like @code{α}, @code{Γ}, and @code{Ζ}, based on the list saved in variable -@code{org-html-entities}. As long as the generated DocBook file includes the +@code{org-entities}. As long as the generated DocBook file includes the corresponding entities, these special characters are recognized. You can customize variable @code{org-export-docbook-doctype} to include the diff --git a/lisp/org-clock.el b/lisp/org-clock.el index 07c1083ce..027276b8a 100755 --- a/lisp/org-clock.el +++ b/lisp/org-clock.el @@ -496,11 +496,13 @@ the mode line." (if current (format ", prefix + to add to %s" org-clock-effort) ""))))) + (debug) (when (stringp value) ;; A string. See if it is a delta (setq sign (string-to-char value)) (if (member sign '(?- ?+)) - (setq current (org-hh:mm-string-to-minutes (substring current 1))) + (setq current (org-hh:mm-string-to-minutes current) + value (substring value 1)) (setq current 0)) (setq value (org-hh:mm-string-to-minutes value)) (if (equal ?- sign) diff --git a/lisp/org-entities.el b/lisp/org-entities.el index 68802ee43..95b759d86 100644 --- a/lisp/org-entities.el +++ b/lisp/org-entities.el @@ -59,8 +59,8 @@ LaTeX mathp A Boolean, either t or nil. t if this entity needs HTML replacement In ready HTML, no further processing will take place. Usually this will be an &...; entity. ASCII replacement Plain ASCII, no extensions. Symbols that cannot be - represented will be written out as an explanatory text. - But see the variable `org-entities-ascii-keep-macro-form'. + represented will be left as they are, but see the. + variable `org-entities-ascii-explanatory'. Latin1 replacement Use the special characters available in latin1. utf-8 replacement Use the special characters available in utf-8. From 110b175ef904b4bb8bcdf96224771b63d6223bb7 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Sat, 1 May 2010 06:35:23 +0200 Subject: [PATCH 24/34] Remove (debug) --- lisp/org-clock.el | 1 - 1 file changed, 1 deletion(-) diff --git a/lisp/org-clock.el b/lisp/org-clock.el index 027276b8a..c093a5db6 100755 --- a/lisp/org-clock.el +++ b/lisp/org-clock.el @@ -496,7 +496,6 @@ the mode line." (if current (format ", prefix + to add to %s" org-clock-effort) ""))))) - (debug) (when (stringp value) ;; A string. See if it is a delta (setq sign (string-to-char value)) From c38d101fff2f362d66db29153c6aa80ba9acab75 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Wed, 28 Apr 2010 08:53:17 +0200 Subject: [PATCH 25/34] New compact Org-mode guide --- Makefile | 23 +- ORGWEBPAGE/index.org | 6 +- UTILITIES/guidesplit.pl | 62 + doc/orgguide.texi | 2595 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 2681 insertions(+), 5 deletions(-) create mode 100755 UTILITIES/guidesplit.pl create mode 100644 doc/orgguide.texi diff --git a/Makefile b/Makefile index a7e14c05f..624e9631a 100644 --- a/Makefile +++ b/Makefile @@ -45,6 +45,7 @@ MAKEINFO = makeinfo # How to create the HTML file TEXI2HTML = makeinfo --html --number-sections +TEXI2HTMLNOPSLIT = makeinfo --html --no-split --number-sections # How to copy the lisp files and elc files to their distination. CP = cp -p @@ -116,7 +117,8 @@ LISPFILES0 = $(LISPF:%=lisp/%) LISPFILES = $(LISPFILES0) lisp/org-install.el ELCFILES0 = $(LISPFILES0:.el=.elc) ELCFILES = $(LISPFILES:.el=.elc) -DOCFILES = doc/org.texi doc/org.pdf doc/org doc/dir doc/.nosearch +DOCFILES = doc/org.texi doc/org.pdf doc/org doc/dir doc/.nosearch \ + doc/orgguide.texi doc/orgguide.pdf CARDFILES = doc/orgcard.tex doc/orgcard.pdf doc/orgcard_letter.pdf TEXIFILES = doc/org.texi INFOFILES = doc/org @@ -145,11 +147,14 @@ compile: $(ELCFILES0) install: install-lisp -doc: doc/org.html doc/org.pdf doc/orgcard.pdf doc/orgcard_letter.pdf +doc: doc/org.html doc/org.pdf doc/orgcard.pdf doc/orgcard_letter.pdf doc/orgguide.pdf p: ${MAKE} pdf && open doc/org.pdf +g: + ${MAKE} pdf && open doc/orgguide.pdf + install-lisp: $(LISPFILES) $(ELCFILES) if [ ! -d $(lispdir) ]; then $(MKDIR) $(lispdir); else true; fi ; $(CP) $(LISPFILES) $(lispdir) @@ -186,6 +191,9 @@ doc/org: doc/org.texi doc/org.pdf: doc/org.texi (cd doc; $(TEXI2PDF) org.texi) +doc/orgguide.pdf: doc/orgguide.texi + (cd doc; $(TEXI2PDF) orgguide.texi) + doc/org.html: doc/org.texi (cd doc; $(TEXI2HTML) --no-split -o org.html org.texi) UTILITIES/manfull.pl doc/org.html @@ -213,9 +221,15 @@ html_manual: doc/org.texi $(TEXI2HTML) -o doc/manual doc/org.texi UTILITIES/mansplit.pl doc/manual/*.html +html_guide: doc/orgguide.texi + rm -rf doc/guide + mkdir doc/guide + $(TEXI2HTML) -o doc/guide doc/orgguide.texi + UTILITIES/guidesplit.pl doc/guide/*.html + info: doc/org -pdf: doc/org.pdf +pdf: doc/org.pdf doc/orgguide.pdf card: doc/orgcard.pdf doc/orgcard_letter.pdf @@ -246,10 +260,12 @@ release: ${MAKE} doc UTILITIES/gplmanual.pl ${MAKE} html_manual + ${MAKE} html_guide rm -rf RELEASEDIR $(MKDIR) RELEASEDIR cp org-$(TAG).zip org-$(TAG).tar.gz RELEASEDIR cp doc/org.pdf doc/orgcard.pdf doc/org.texi doc/org.html RELEASEDIR + cp doc/orgguide.pdf RELEASEDIR cp RELEASEDIR/org-$(TAG).zip RELEASEDIR/org.zip cp RELEASEDIR/org-$(TAG).tar.gz RELEASEDIR/org.tar.gz @@ -258,6 +274,7 @@ upload_release: upload_manual: rsync -avuz --delete doc/manual/ cdominik@orgmode.org:orgmode.org/manual/ + rsync -avuz --delete doc/guide/ cdominik@orgmode.org:orgmode.org/guide/ relup0: ${MAKE} release diff --git a/ORGWEBPAGE/index.org b/ORGWEBPAGE/index.org index f8cc64160..3b56db51d 100644 --- a/ORGWEBPAGE/index.org +++ b/ORGWEBPAGE/index.org @@ -168,11 +168,13 @@ and corresponding to the latest git version. * Documentation ** The Org manual - - Read the [[file:manual/index.html][documentation online]]. + - Read the [[file:manual/index.html][manual online]]. - You can also have the entire manual in a [[file:org.html][single monolithic file]]. - - Download the documentation as a [[file:org.pdf][PDF document]]. + - Download the manual as a [[file:org.pdf][PDF document]]. - A [[http://hpcgi1.nifty.com/spen/index.cgi?OrgMode%2fManual][Japanese translation]] of the manual (version 4.60), by Takeshi Okano. + - The Org-mode Guide is a compact version of the manual, with all + basic information. Read the [[file:guide/index.html][guide online]] or as a [[file:orgguide.pdf][PDF document]] ** Reference card - Download the [[file:orgcard.pdf][Refcard]] for org-mode diff --git a/UTILITIES/guidesplit.pl b/UTILITIES/guidesplit.pl new file mode 100755 index 000000000..47152f157 --- /dev/null +++ b/UTILITIES/guidesplit.pl @@ -0,0 +1,62 @@ +#!/usr/bin/perl +# Work on the files that are created by makeinfo for html output +# split into many small files. + +# This will walk though the files listed on the command line, install +# Sebastian Rose's key reader and add a small top-level-only table +# of contents that will be placed into a special region and visible +# in all subfiles. The small contents is a constant and has to be updated +# by hand, currently. + +$contents = < +

Table of Contents

+
+ +
+ + +EOF + +$script = <<'EOF'; + + + +EOF + +while ($page = shift) { +system "mv $page $page.orig"; +open IN,"<$page.orig" or die "Cannot read from $page.orig\n"; +undef $/; +$all = ; +close IN; + +$all =~ s//$&\n$script/; +$all =~ s/^/\n$contents/m; + +open OUT,">$page" or die "Cannot write to $page\n"; +print OUT $all; +close OUT; +system "rm $page.orig"; +} diff --git a/doc/orgguide.texi b/doc/orgguide.texi new file mode 100644 index 000000000..e3e45bc21 --- /dev/null +++ b/doc/orgguide.texi @@ -0,0 +1,2595 @@ +\input texinfo +@c %**start of header +@setfilename ../../info/orgguide +@settitle The compact Org-mode Guide + +@set VERSION 0.92 +@set DATE April 2010 + +@c Version and Contact Info +@set MAINTAINERSITE @uref{http://orgmode.org,maintainers webpage} +@set AUTHOR Carsten Dominik +@set MAINTAINER Carsten Dominik +@set MAINTAINEREMAIL @email{carsten at orgmode dot org} +@set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer} +@c %**end of header +@finalout + +@c Macro definitions +@iftex +@c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed} +@end iftex +@macro Ie {} +I.e., +@end macro +@macro ie {} +i.e., +@end macro +@macro Eg {} +E.g., +@end macro +@macro eg {} +e.g., +@end macro + +@c Subheadings inside a table. +@macro tsubheading{text} +@ifinfo +@subsubheading \text\ +@end ifinfo +@ifnotinfo +@item @b{\text\} +@end ifnotinfo +@end macro + +@macro seealso{text} +@noindent @b{Further reading}@*@noindent \text\ +@end macro +@copying + +Copyright @copyright{} 2010 Free Software Foundation + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation License.'' + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual. Buying copies from the FSF supports it in +developing GNU and promoting software freedom.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory Emacs +@direntry +* Org Mode Guide: (orgguide). Abbreviated Org-mode Manual +@end direntry + +@titlepage +@title The compact Org-mode Guide + +@subtitle Release @value{VERSION} +@author by Carsten Dominik + +@c The following two commands start the copyright page. +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@c Output the table of contents at the beginning. +@shortcontents + +@ifnottex +@node Top, Introduction, (dir), (dir) +@top Org Mode Manual + +@insertcopying +@end ifnottex + +@menu +* Introduction:: Getting started +* Document Structure:: A tree works like your brain +* Tables:: Pure magic for quick formatting +* Hyperlinks:: Notes in context +* TODO Items:: Every tree branch can be a TODO item +* Tags:: Tagging headlines and matching sets of tags +* Properties:: +* Dates and Times:: Making items useful for planning +* Capture - Refile - Archive:: The ins and outs for projects +* Agenda Views:: Collecting information into views +* Markup:: Prepare text for rich export +* Exporting:: Sharing and publishing of notes +* Publishing:: Create a web site of linked Org files +* Miscellaneous:: All the rest which did not fit elsewhere + +@detailmenu + --- The Detailed Node Listing --- + +Introduction + +* Preface:: Welcome +* Installation:: How to install a downloaded version of Org +* Activation:: How to activate Org for certain buffers +* Feedback:: Bug reports, ideas, patches etc. + +Document Structure + +* Outlines:: Org is based on Outline mode +* Headlines:: How to typeset Org tree headlines +* Visibility cycling:: Show and hide, much simplified +* Motion:: Jumping to other headlines +* Structure editing:: Changing sequence and level of headlines +* Sparse trees:: Matches embedded in context +* Plain lists:: Additional structure within an entry +* Footnotes:: How footnotes are defined in Org's syntax + +Hyperlinks + +* Link format:: How links in Org are formatted +* Internal links:: Links to other places in the current file +* External links:: URL-like links to the world +* Handling links:: Creating, inserting and following +* Targeted links:: Point at a location in a file + +TODO Items + +* Using TODO states:: +* Multi-state workflows:: +* Progress logging:: Dates and notes for progress +* Priorities:: Some things are more important than others +* Breaking down tasks:: Splitting a task into manageable pieces +* Checkboxes:: Tick-off lists + +Progress logging + +* Closing items:: When was this entry marked DONE? +* Tracking TODO state changes:: When did the status change? + +Tags + +* Tag inheritance:: Tags use the tree structure of the outline +* Setting tags:: How to assign tags to a headline +* Tag searches:: Searching for combinations of tags + +Dates and Times + +* Timestamps:: Assigning a time to a tree entry +* Creating timestamps:: Commands which insert timestamps +* Deadlines and scheduling:: Planning your work +* Clocking work time:: Tracking how long you spend on a task + +Capture - Refile - Archive + +* Remember:: Capture new tasks/ideas with little interruption +* Refiling notes:: Moving a tree from one place to another +* Archiving:: What to do with finished projects + +Remember + +* Setting up Remember for Org:: Some code for .emacs to get things going +* Remember templates:: Define the outline of different note types +* Storing notes:: Directly get the note to where it belongs + +Agenda Views + +* Agenda files:: Files being searched for agenda information +* Agenda dispatcher:: Keyboard access to agenda views +* Built-in agenda views:: What is available out of the box? +* Agenda commands:: Remote editing of Org trees +* Custom agenda views:: Defining special searches and views + +The built-in agenda views + +* Weekly/daily agenda:: The calendar page with current tasks +* Global TODO list:: All unfinished action items +* Matching tags and properties:: Structured information with fine-tuned search +* Timeline:: Time-sorted view for single file +* Search view:: Find entries by searching for text + +Markup for rich export + +* Structural markup elements:: The basic structure as seen by the exporter +* Images and tables:: Tables and Images will be included +* Literal examples:: Source code examples with special formatting +* Include files:: Include additional files into a document +* Embedded LaTeX:: LaTeX can be freely used inside Org documents + +Structural markup elements + +* Document title:: Where the title is taken from +* Headings and sections:: The document structure as seen by the exporter +* Table of contents:: The if and where of the table of contents +* Paragraphs:: Paragraphs +* Emphasis and monospace:: Bold, italic, etc. +* Comment lines:: What will *not* be exported + +Exporting + +* Export options:: Per-file export settings +* The export dispatcher:: How to access exporter commands +* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding +* HTML export:: Exporting to HTML +* LaTeX and PDF export:: Exporting to La@TeX{}, and processing to PDF +* DocBook export:: Exporting to DocBook +* iCalendar export:: + +Miscellaneous + +* Completion:: M-TAB knows what you need +* Clean view:: Getting rid of leading stars in the outline +* MobileOrg:: Org-mode on the iPhone + +@end detailmenu +@end menu + +@node Introduction, Document Structure, Top, Top +@chapter Introduction + +@menu +* Preface:: Welcome +* Installation:: How to install a downloaded version of Org +* Activation:: How to activate Org for certain buffers +* Feedback:: Bug reports, ideas, patches etc. +@end menu + +@node Preface, Installation, Introduction, Introduction +@section Preface + +Org is a mode for keeping notes, maintaining TODO lists, and doing +project planning with a fast and effective plain-text system. + +@i{This document is an extract from the +@uref{http://orgmode.org/index.html#sec-4_1, comprehensive Org-mode manual}. +It contains all basic features and commands, along with important hints for +customization. It is intended for beginners who would shy back from a 200 +page manual because of sheer size.} + +@node Installation, Activation, Preface, Introduction +@section Installation + +@b{Important:} @i{If you are using a version of Org that is part of the Emacs +distribution or an XEmacs package, please skip this section and go directly +to @ref{Activation}.} + +If you have downloaded Org from the Web, either as a distribution @file{.zip} +or @file{.tar} file, or as a Git archive, it is best to run it directly from +the distribution directory. You need to add @file{lisp} subdirectory to the +Emacs load path. To do this, add the following line to @file{.emacs}: + +@smallexample +(setq load-path (cons "~/path/to/orgdir/lisp" load-path)) +(setq load-path (cons "~/path/to/orgdir/contrib/lisp" load-path)) +@end smallexample + +@noindent For speed you should byte-compile the Lisp files with the shell +command: + +@smallexample +make +@end smallexample + +Then add the following line to @file{.emacs}. It is needed so that +Emacs can autoload functions that are located in files not immediately loaded +when Org-mode starts. +@smalllisp +(require 'org-install) +@end smalllisp + +Do not forget to activate Org as described in the following section. + +@node Activation, Feedback, Installation, Introduction +@section Activation + +Add the following lines to your @file{.emacs} file. The last three lines +define @emph{global} keys for the commands @command{org-store-link}, +@command{org-agenda}, and @command{org-iswitchb}---please choose suitable +keys yourself. + +@smalllisp +;; The following lines are always needed. Choose your own keys. +(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode)) +(global-font-lock-mode 1) ; for all buffers +(global-set-key "\C-cl" 'org-store-link) +(global-set-key "\C-ca" 'org-agenda) +(global-set-key "\C-cb" 'org-iswitchb) +@end smalllisp + +With this setup, all files with extension @samp{.org} will be put +into Org mode. + +@node Feedback, , Activation, Introduction +@section Feedback + +If you find problems with Org, or if you have questions, remarks, or ideas +about it, please mail to the Org mailing list @email{emacs-orgmode@@gnu.org}. +If you are not a member of the mailing list, your mail will be passed to the +list after a moderator has approved it. For information on how to submit bug +reports, see the main manual. + +@node Document Structure, Tables, Introduction, Top +@chapter Document Structure + +Org is based on Outline mode and provides flexible commands to +edit the structure of the document. + +@menu +* Outlines:: Org is based on Outline mode +* Headlines:: How to typeset Org tree headlines +* Visibility cycling:: Show and hide, much simplified +* Motion:: Jumping to other headlines +* Structure editing:: Changing sequence and level of headlines +* Sparse trees:: Matches embedded in context +* Plain lists:: Additional structure within an entry +* Footnotes:: How footnotes are defined in Org's syntax +@end menu + +@node Outlines, Headlines, Document Structure, Document Structure +@section Outlines + +Org is implemented on top of Outline mode. Outlines allow a +document to be organized in a hierarchical structure, which (at least +for me) is the best representation of notes and thoughts. An overview +of this structure is achieved by folding (hiding) large parts of the +document to show only the general document structure and the parts +currently being worked on. Org greatly simplifies the use of +outlines by compressing the entire show/hide functionality into a single +command, @command{org-cycle}, which is bound to the @key{TAB} key. + +@node Headlines, Visibility cycling, Outlines, Document Structure +@section Headlines + +Headlines define the structure of an outline tree. The headlines in +Org start with one or more stars, on the left margin@footnote{See +the variable @code{org-special-ctrl-a/e} to configure special behavior +of @kbd{C-a} and @kbd{C-e} in headlines.}. For example: + +@smallexample +* Top level headline +** Second level +*** 3rd level + some text +*** 3rd level + more text + +* Another top level headline +@end smallexample + +@noindent Some people find the many stars too noisy and would prefer an +outline that has whitespace followed by a single star as headline +starters. @ref{Clean view}, describes a setup to realize this. + +@node Visibility cycling, Motion, Headlines, Document Structure +@section Visibility cycling + +Outlines make it possible to hide parts of the text in the buffer. +Org uses just two commands, bound to @key{TAB} and +@kbd{S-@key{TAB}} to change the visibility in the buffer. + +@table @kbd +@item @key{TAB} +@emph{Subtree cycling}: Rotate current subtree among the states + +@smallexample +,-> FOLDED -> CHILDREN -> SUBTREE --. +'-----------------------------------' +@end smallexample + +When called with a prefix argument (@kbd{C-u @key{TAB}}) or with the shift +key, global cycling is invoked. + +@item S-@key{TAB} @r{and} C-u @key{TAB} +@emph{Global cycling}: Rotate the entire buffer among the states + +@smallexample +,-> OVERVIEW -> CONTENTS -> SHOW ALL --. +'--------------------------------------' +@end smallexample + +@item C-u C-u C-u @key{TAB} +Show all, including drawers. +@end table + +When Emacs first visits an Org file, the global state is set to +OVERVIEW, i.e. only the top level headlines are visible. This can be +configured through the variable @code{org-startup-folded}, or on a +per-file basis by adding a startup keyword @code{overview}, @code{content}, +@code{showall}, like this: + +@smallexample +#+STARTUP: content +@end smallexample + + +@node Motion, Structure editing, Visibility cycling, Document Structure +@section Motion +The following commands jump to other headlines in the buffer. + +@table @kbd +@item C-c C-n +Next heading. +@item C-c C-p +Previous heading. +@item C-c C-f +Next heading same level. +@item C-c C-b +Previous heading same level. +@item C-c C-u +Backward to higher level heading. +@end table + +@node Structure editing, Sparse trees, Motion, Document Structure +@section Structure editing + +@table @kbd +@item M-@key{RET} +Insert new heading with same level as current. If the cursor is in a plain +list item, a new item is created (@pxref{Plain lists}). When this command is +used in the middle of a line, the line is split and the rest of the line +becomes the new headline@footnote{If you do not want the line to be split, +customize the variable @code{org-M-RET-may-split-line}.}. +@item M-S-@key{RET} +Insert new TODO entry with same level as current heading. +@item @key{TAB} @r{in new, empty entry} +In a new entry with no text yet, @key{TAB} will cycle through reasonable +levels. +@item M-@key{left}@r{/}@key{right} +Promote/demote current heading by one level. +@item M-S-@key{left}@r{/}@key{right} +Promote/demote the current subtree by one level. +@item M-S-@key{up}@r{/}@key{down} +Move subtree up/down (swap with previous/next subtree of same +level). +@item C-c C-w +Refile entry or region to a different location. @xref{Refiling notes}. +@item C-x n s/w +Narrow buffer to current subtree / widen it again +@end table + +When there is an active region (Transient Mark mode), promotion and +demotion work on all headlines in the region. + +@node Sparse trees, Plain lists, Structure editing, Document Structure +@section Sparse trees + +An important feature of Org mode is the ability to construct @emph{sparse +trees} for selected information in an outline tree, so that the entire +document is folded as much as possible, but the selected information is made +visible along with the headline structure above it@footnote{See also the +variables @code{org-show-hierarchy-above}, @code{org-show-following-heading}, +@code{org-show-siblings}, and @code{org-show-entry-below} for detailed +control on how much context is shown around each match.}. Just try it out +and you will see immediately how it works. + +Org mode contains several commands creating such trees, all these +commands can be accessed through a dispatcher: + +@table @kbd +@item C-c / +This prompts for an extra key to select a sparse-tree creating command. +@item C-c / r +Occur. Prompts for a regexp and shows a sparse tree with all matches. Each +match is also highlighted; the highlights disappear by pressing @kbd{C-c C-c}. +@end table + +The other sparse tree commands select headings based on TODO keywords, +tags, or properties and will be discussed later in this manual. + +@node Plain lists, Footnotes, Sparse trees, Document Structure +@section Plain lists + +Within an entry of the outline tree, hand-formatted lists can provide +additional structure. They also provide a way to create lists of +checkboxes (@pxref{Checkboxes}). Org supports editing such lists, +and the HTML exporter (@pxref{Exporting}) parses and formats them. + +Org knows ordered lists, unordered lists, and description lists. +@itemize @bullet +@item +@emph{Unordered} list items start with @samp{-}, @samp{+}, or +@samp{*} as bullets. +@item +@emph{Ordered} list items start with @samp{1.} or @samp{1)}. +@item +@emph{Description} list use @samp{ :: } to separate the @emph{term} from the +description. +@end itemize + +Items belonging to the same list must have the same indentation on the first +line. A list ends before the next line that is indented like the +bullet/number, or less. An example: + +@smallexample +@group +** Lord of the Rings + My favorite scenes are (in this order) + 1. The attack of the Rohirrim + 2. Eowyn's fight with the witch king + + this was already my favorite scene in the book + + I really like Miranda Otto. + Important actors in this film are: + - @b{Elijah Wood} :: He plays Frodo + - @b{Sean Austin} :: He plays Sam, Frodo's friend. +@end group +@end smallexample + +The following commands act on items when the cursor is in the first line of +an item (the line with the bullet or number). + +@table @kbd +@item @key{TAB} +Items can be folded just like headline levels. +@item M-@key{RET} +Insert new item at current level. With a prefix argument, force a new +heading (@pxref{Structure editing}). +@item M-S-@key{RET} +Insert a new item with a checkbox (@pxref{Checkboxes}). +@item M-S-@key{up}@r{/}@key{down} +Move the item including subitems up/down (swap with previous/next item +of same indentation). If the list is ordered, renumbering is +automatic. +@item M-@key{left}@r{/}M-@key{right} +Decrease/increase the indentation of an item, leaving children alone. +@item M-S-@key{left}@r{/}@key{right} +Decrease/increase the indentation of the item, including subitems. +@item C-c C-c +If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the +state of the checkbox. If not, make sure all items have the same bullet type +and renumber ordered lists. +@item C-c - +Cycle the entire list level through the different itemize/enumerate bullets +(@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}). +@end table + +@node Footnotes, , Plain lists, Document Structure +@section Footnotes + +A footnote is defined in a paragraph that is started by a footnote marker in +square brackets in column 0, no indentation allowed. The footnote reference +is simply the marker in square brackets, inside text. For example: + +@smallexample +The Org homepage[fn:1] now looks a lot better than it used to. +... +[fn:1] The link is: http://orgmode.org +@end smallexample + +@noindent The following commands handle footnotes: + +@table @kbd +@item C-c C-x f +The footnote action command. When the cursor is on a footnote reference, +jump to the definition. When it is at a definition, jump to the (first) +reference. Otherwise, create a new footnote. When this command is called +with a prefix argument, a menu of additional options including renumbering is +offered. + +@item C-c C-c +Jump between definition and reference. +@end table + +@seealso{ +@uref{http://orgmode.org/manual/Document-Structure.html#Document-Structure, +Chapter 2 of the manual}@* +@uref{http://sachachua.com/wp/2008/01/outlining-your-notes-with-org/, +Sacha Chua's tutorial}} + + +@node Tables, Hyperlinks, Document Structure, Top +@chapter Tables + +Org comes with a fast and intuitive table editor. Spreadsheet-like +calculations are supported in connection with the Emacs @file{calc} +package +@ifinfo +(@pxref{Top,Calc,,Calc,Gnu Emacs Calculator Manual}). +@end ifinfo +@ifnotinfo +(see the Emacs Calculator manual for more information about the Emacs +calculator). +@end ifnotinfo + +Org makes it easy to format tables in plain ASCII. Any line with +@samp{|} as the first non-whitespace character is considered part of a +table. @samp{|} is also the column separator. A table might look like +this: + +@smallexample +| Name | Phone | Age | +|-------+-------+-----| +| Peter | 1234 | 17 | +| Anna | 4321 | 25 | +@end smallexample + +A table is re-aligned automatically each time you press @key{TAB} or +@key{RET} or @kbd{C-c C-c} inside the table. @key{TAB} also moves to +the next field (@key{RET} to the next row) and creates new table rows +at the end of the table or before horizontal lines. The indentation +of the table is set by the first line. Any line starting with +@samp{|-} is considered as a horizontal separator line and will be +expanded on the next re-align to span the whole table width. So, to +create the above table, you would only type + +@smallexample +|Name|Phone|Age| +|- +@end smallexample + +@noindent and then press @key{TAB} to align the table and start filling in +fields. Even faster would be to type @code{|Name|Phone|Age} followed by +@kbd{C-c @key{RET}}. + +When typing text into a field, Org treats @key{DEL}, +@key{Backspace}, and all character keys in a special way, so that +inserting and deleting avoids shifting other fields. Also, when +typing @emph{immediately after the cursor was moved into a new field +with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the +field is automatically made blank. + +@table @kbd +@tsubheading{Creation and conversion} +@item C-c | +Convert the active region to table. If every line contains at least one +TAB character, the function assumes that the material is tab separated. +If every line contains a comma, comma-separated values (CSV) are assumed. +If not, lines are split at whitespace into fields. +@* +If there is no active region, this command creates an empty Org +table. But it's easier just to start typing, like +@kbd{|Name|Phone|Age C-c @key{RET}}. + +@tsubheading{Re-aligning and field motion} +@item C-c C-c +Re-align the table without moving the cursor. +@c +@item @key{TAB} +Re-align the table, move to the next field. Creates a new row if +necessary. +@c +@item S-@key{TAB} +Re-align, move to previous field. +@c +@item @key{RET} +Re-align the table and move down to next row. Creates a new row if +necessary. + +@tsubheading{Column and row editing} +@item M-@key{left} +@itemx M-@key{right} +Move the current column left/right. +@c +@item M-S-@key{left} +Kill the current column. +@c +@item M-S-@key{right} +Insert a new column to the left of the cursor position. +@c +@item M-@key{up} +@itemx M-@key{down} +Move the current row up/down. +@c +@item M-S-@key{up} +Kill the current row or horizontal line. +@c +@item M-S-@key{down} +Insert a new row above the current row. With a prefix argument, the line is +created below the current one. +@c +@item C-c - +Insert a horizontal line below current row. With a prefix argument, the line +is created above the current line. +@c +@item C-c @key{RET} +Insert a horizontal line below current row, and move the cursor into the row +below that line. +@c +@item C-c ^ +Sort the table lines in the region. The position of point indicates the +column to be used for sorting, and the range of lines is the range +between the nearest horizontal separator lines, or the entire table. + +@end table + +@seealso{ +@uref{http://orgmode.org/manual/Tables.html#Tables, Chapter 3 of the +manual}@* +@uref{http://orgmode.org/worg/org-tutorials/tables.php, Bastien's +table tutorial}@* +@uref{http://orgmode.org/worg/org-tutorials/org-spreadsheet-intro.php, +Bastien's spreadsheet tutorial}@* +@uref{http://orgmode.org/worg/org-tutorials/org-plot.php, Eric's plotting tutorial}} + +@node Hyperlinks, TODO Items, Tables, Top +@chapter Hyperlinks + +Like HTML, Org provides links inside a file, external links to +other files, Usenet articles, emails, and much more. + +@menu +* Link format:: How links in Org are formatted +* Internal links:: Links to other places in the current file +* External links:: URL-like links to the world +* Handling links:: Creating, inserting and following +* Targeted links:: Point at a location in a file +@end menu + +@node Link format, Internal links, Hyperlinks, Hyperlinks +@section Link format + +Org will recognize plain URL-like links and activate them as +clickable links. The general link format, however, looks like this: + +@smallexample +[[link][description]] @r{or alternatively} [[link]] +@end smallexample + +@noindent +Once a link in the buffer is complete (all brackets present), Org will change +the display so that @samp{description} is displayed instead of +@samp{[[link][description]]} and @samp{link} is displayed instead of +@samp{[[link]]}. To edit the invisible @samp{link} part, use @kbd{C-c +C-l} with the cursor on the link. + +@node Internal links, External links, Link format, Hyperlinks +@section Internal links + +If the link does not look like a URL, it is considered to be internal in the +current file. The most important case is a link like +@samp{[[#my-custom-id]]} which will link to the entry with the +@code{CUSTOM_ID} property @samp{my-custom-id}. + +Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]} +lead to a text search in the current file for the corresponding target which +looks like @samp{<>}. + +@node External links, Handling links, Internal links, Hyperlinks +@section External links + +Org supports links to files, websites, Usenet and email messages, +BBDB database entries and links to both IRC conversations and their +logs. External links are URL-like locators. They start with a short +identifying string followed by a colon. There can be no space after +the colon. Here are some examples: + +@smallexample +http://www.astro.uva.nl/~dominik @r{on the web} +file:/home/dominik/images/jupiter.jpg @r{file, absolute path} +/home/dominik/images/jupiter.jpg @r{same as above} +file:papers/last.pdf @r{file, relative path} +file:projects.org @r{another Org file} +docview:papers/last.pdf::NNN @r{open file in doc-view mode at page NNN} +id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID} +news:comp.emacs @r{Usenet link} +mailto:adent@@galaxy.net @r{Mail link} +vm:folder @r{VM folder link} +vm:folder#id @r{VM message link} +wl:folder#id @r{WANDERLUST message link} +mhe:folder#id @r{MH-E message link} +rmail:folder#id @r{RMAIL message link} +gnus:group#id @r{Gnus article link} +bbdb:R.*Stallman @r{BBDB link (with regexp)} +irc:/irc.com/#emacs/bob @r{IRC link} +info:org:External%20links @r{Info node link (with encoded space)} +@end smallexample + +A link should be enclosed in double brackets and may contain a +descriptive text to be displayed instead of the URL (@pxref{Link +format}), for example: + +@smallexample +[[http://www.gnu.org/software/emacs/][GNU Emacs]] +@end smallexample + +@noindent +If the description is a file name or URL that points to an image, HTML export +(@pxref{HTML export}) will inline the image as a clickable button. If there +is no description at all and the link points to an image, that image will be +inlined into the exported HTML file. + +@node Handling links, Targeted links, External links, Hyperlinks +@section Handling links + +Org provides methods to create a link in the correct syntax, to +insert it into an Org file, and to follow the link. + +@table @kbd +@item C-c l +Store a link to the current location. This is a @emph{global} command (you +must create the key binding yourself) which can be used in any buffer to +create a link. The link will be stored for later insertion into an Org +buffer (see below). +@c +@item C-c C-l +Insert a link. This prompts for a link to be inserted into the buffer. You +can just type a link, or use history keys @key{up} and @key{down} to access +stored links. You will be prompted for the description part of the link. +When called with a @kbd{C-u} prefix argument, file name completion is used to +link to a file. +@c +@item C-c C-l @r{(with cursor on existing link)} +When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the +link and description parts of the link. +@c +@item C-c C-o @r{or} mouse-1 @r{or} mouse-2 +Open link at point. +@item C-c & +Jump back to a recorded position. A position is recorded by the +commands following internal links, and by @kbd{C-c %}. Using this +command several times in direct succession moves through a ring of +previously recorded positions. +@c +@end table + +@node Targeted links, , Handling links, Hyperlinks +@section Targeted links + +File links can contain additional information to make Emacs jump to a +particular location in the file when following a link. This can be a +line number or a search option after a double colon. + +Here is the syntax of the different ways to attach a search to a file +link, together with an explanation: + +@smallexample +[[file:~/code/main.c::255]] @r{Find line 255} +[[file:~/xx.org::My Target]] @r{Find @samp{<>}} +[[file:~/xx.org::#my-custom-id]] @r{Find entry with custom id} +@end smallexample + +@seealso{ +@uref{http://orgmode.org/manual/Hyperlinks.html#Hyperlinks, Chapter 4 of the +manual}} + +@node TODO Items, Tags, Hyperlinks, Top +@chapter TODO Items + +Org mode does not maintain TODO lists as separate documents@footnote{Of +course, you can make a document that contains only long lists of TODO items, +but this is not required.}. Instead, TODO items are an integral part of the +notes file, because TODO items usually come up while taking notes! With Org +mode, simply mark any entry in a tree as being a TODO item. In this way, +information is not duplicated, and the entire context from which the TODO +item emerged is always present. + +Of course, this technique for managing TODO items scatters them +throughout your notes file. Org mode compensates for this by providing +methods to give you an overview of all the things that you have to do. + +@menu +* Using TODO states:: +* Multi-state workflows:: +* Progress logging:: Dates and notes for progress +* Priorities:: Some things are more important than others +* Breaking down tasks:: Splitting a task into manageable pieces +* Checkboxes:: Tick-off lists +@end menu + +@node Using TODO states, Multi-state workflows, TODO Items, TODO Items +@section Using TODO states + +Any headline becomes a TODO item when it starts with the word +@samp{TODO}, for example: + +@smallexample +*** TODO Write letter to Sam Fortune +@end smallexample + +@noindent +The most important commands to work with TODO entries are: + +@table @kbd +@item C-c C-t +Rotate the TODO state of the current item among + +@smallexample +,-> (unmarked) -> TODO -> DONE --. +'--------------------------------' +@end smallexample + +The same rotation can also be done ``remotely'' from the timeline and +agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}). + +@item S-@key{right}@r{/}@key{left} +Select the following/preceding TODO state, similar to cycling. +@item C-c / t +View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the +buffer, but shows all TODO items and the headings hierarchy above +them. +@item C-c a t +Show the global TODO list. Collects the TODO items from all agenda files +(@pxref{Agenda Views}) into a single buffer. @xref{Global TODO list}, for +more information. +@item S-M-@key{RET} +Insert a new TODO entry below the current one. +@end table + +@noindent +Changing a TODO state can also trigger tag changes. See the docstring of the +option @code{org-todo-state-tags-triggers} for details. + +@node Multi-state workflows, Progress logging, Using TODO states, TODO Items +@section Multi-state workflows + +You can use TODO keywords to indicate different @emph{sequential} states +in the process of working on an item, for example: + +@smalllisp +(setq org-todo-keywords + '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED"))) +@end smalllisp + +The vertical bar separates the TODO keywords (states that @emph{need +action}) from the DONE states (which need @emph{no further action}). If +you don't provide the separator bar, the last state is used as the DONE +state. +With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO +to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED. + +Sometimes you may want to use different sets of TODO keywords in +parallel. For example, you may want to have the basic +@code{TODO}/@code{DONE}, but also a workflow for bug fixing, and a +separate state indicating that an item has been canceled (so it is not +DONE, but also does not require action). Your setup would then look +like this: + +@smalllisp +(setq org-todo-keywords + '((sequence "TODO(t)" "|" "DONE(d)") + (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)") + (sequence "|" "CANCELED(c)"))) +@end smalllisp + +The keywords should all be different, this helps Org mode to keep track of +which subsequence should be used for a given entry. The example also shows +how to define keys for fast access of a particular state, by adding a letter +in parenthesis after each keyword - you will be prompted for the key after +@kbd{C-c C-t}. + +To define TODO keywords that are valid only in a single file, use the +following text anywhere in the file. + +@smallexample +#+TODO: TODO(t) | DONE(d) +#+TODO: REPORT(r) BUG(b) KNOWNCAUSE(k) | FIXED(f) +#+TODO: | CANCELED(c) +@end smallexample + +After changing one of these lines, use @kbd{C-c C-c} with the cursor still in +the line to make the changes known to Org mode. + +@node Progress logging, Priorities, Multi-state workflows, TODO Items +@section Progress logging + +Org mode can automatically record a timestamp and possibly a note when +you mark a TODO item as DONE, or even each time you change the state of +a TODO item. This system is highly configurable, settings can be on a +per-keyword basis and can be localized to a file or even a subtree. For +information on how to clock working time for a task, see @ref{Clocking +work time}. + +@menu +* Closing items:: When was this entry marked DONE? +* Tracking TODO state changes:: When did the status change? +@end menu + +@node Closing items, Tracking TODO state changes, Progress logging, Progress logging +@unnumberedsubsec Closing items + +The most basic logging is to keep track of @emph{when} a certain TODO +item was finished. This is achieved with@footnote{The corresponding +in-buffer setting is: @code{#+STARTUP: logdone}}. + +@smalllisp +(setq org-log-done 'time) +@end smalllisp + +@noindent +Then each time you turn an entry from a TODO (not-done) state into any of the +DONE states, a line @samp{CLOSED: [timestamp]} will be inserted just after +the headline. If you want to record a note along with the timestamp, +use@footnote{The corresponding in-buffer setting is: @code{#+STARTUP: +lognotedone}} + +@smalllisp +(setq org-log-done 'note) +@end smalllisp + +@noindent +You will then be prompted for a note, and that note will be stored below +the entry with a @samp{Closing Note} heading. + +@node Tracking TODO state changes, , Closing items, Progress logging +@unnumberedsubsec Tracking TODO state changes + +You might want to keep track of TODO state changes. You can either record +just a timestamp, or a time-stamped note for a change. These records will be +inserted after the headline as an itemized list. When taking a lot of notes, +you might want to get the notes out of the way into a drawer. Customize the +variable @code{org-log-into-drawer} to get this behavior. + +For state logging, Org mode expects configuration on a per-keyword basis. +This is achieved by adding special markers @samp{!} (for a timestamp) and +@samp{@@} (for a note) in parentheses after each keyword. For example: +@smallexample +#+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@) +@end smallexample +@noindent +will define TODO keywords and fast access keys, and also request that a time +is recorded when the entry is set to DONE, and that a note is recorded when +switching to WAIT or CANCELED. The same syntax works also when setting +@code{org-todo-keywords}. + +@node Priorities, Breaking down tasks, Progress logging, TODO Items +@section Priorities + +If you use Org mode extensively, you may end up with enough TODO items that +it starts to make sense to prioritize them. Prioritizing can be done by +placing a @emph{priority cookie} into the headline of a TODO item, like this + +@smallexample +*** TODO [#A] Write letter to Sam Fortune +@end smallexample + +@noindent +Org mode supports three priorities: @samp{A}, @samp{B}, and @samp{C}. +@samp{A} is the highest, @samp{B} the default if none is given. Priorities +make a difference only in the agenda. + +@table @kbd +@item @kbd{C-c ,} +Set the priority of the current headline. Press @samp{A}, @samp{B} or +@samp{C} to select a priority, or @key{SPC} to remove the cookie. +@c +@item S-@key{up} +@itemx S-@key{down} +Increase/decrease priority of current headline +@end table + +@node Breaking down tasks, Checkboxes, Priorities, TODO Items +@section Breaking tasks down into subtasks + +It is often advisable to break down large tasks into smaller, manageable +subtasks. You can do this by creating an outline tree below a TODO item, +with detailed subtasks on the tree. To keep the overview over the fraction +of subtasks that are already completed, insert either @samp{[/]} or +@samp{[%]} anywhere in the headline. These cookies will be updated each time +the TODO status of a child changes, or when pressing @kbd{C-c C-c} on the +cookie. For example: + +@smallexample +* Organize Party [33%] +** TODO Call people [1/2] +*** TODO Peter +*** DONE Sarah +** TODO Buy food +** DONE Talk to neighbor +@end smallexample + +@node Checkboxes, , Breaking down tasks, TODO Items +@section Checkboxes + +Every item in a plain list (@pxref{Plain lists}) can be made into a checkbox +by starting it with the string @samp{[ ]}. Checkboxes are not included into +the global TODO list, so they are often great to split a task into a number +of simple steps. +Here is an example of a checkbox list. + +@smallexample +* TODO Organize party [1/3] + - [-] call people [1/2] + - [ ] Peter + - [X] Sarah + - [X] order food + - [ ] think about what music to play +@end smallexample + +Checkboxes work hierarchically, so if a checkbox item has children that +are checkboxes, toggling one of the children checkboxes will make the +parent checkbox reflect if none, some, or all of the children are +checked. + +@noindent The following commands work with checkboxes: + +@table @kbd +@item C-c C-c +Toggle checkbox status or (with prefix arg) checkbox presence at point. +@item M-S-@key{RET} +Insert a new item with a checkbox. +This works only if the cursor is already in a plain list item +(@pxref{Plain lists}). +@end table + +@seealso{ +@uref{http://orgmode.org/manual/TODO-Items.html#TODO-Items, Chapter 5 of the manual}@* +@uref{http://orgmode.org/worg/org-tutorials/orgtutorial_dto.php, David +O'Toole's introductory tutorial}@* +@uref{http://members.optusnet.com.au/~charles57/GTD/gtd_workflow.html, +Charles Cave's GTD setup}} + +@node Tags, Properties, TODO Items, Top +@chapter Tags + +An excellent way to implement labels and contexts for cross-correlating +information is to assign @i{tags} to headlines. Org mode has extensive +support for tags. + +Every headline can contain a list of tags; they occur at the end of the +headline. Tags are normal words containing letters, numbers, @samp{_}, and +@samp{@@}. Tags must be preceded and followed by a single colon, e.g., +@samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}. +Tags will by default be in bold face with the same color as the headline. + +@menu +* Tag inheritance:: Tags use the tree structure of the outline +* Setting tags:: How to assign tags to a headline +* Tag searches:: Searching for combinations of tags +@end menu + +@node Tag inheritance, Setting tags, Tags, Tags +@section Tag inheritance + +@i{Tags} make use of the hierarchical structure of outline trees. If a +heading has a certain tag, all subheadings will inherit the tag as +well. For example, in the list + +@smallexample +* Meeting with the French group :work: +** Summary by Frank :boss:notes: +*** TODO Prepare slides for him :action: +@end smallexample + +@noindent +the final heading will have the tags @samp{:work:}, @samp{:boss:}, +@samp{:notes:}, and @samp{:action:} even though the final heading is not +explicitly marked with those tags. You can also set tags that all entries in +a file should inherit just as if these tags were defined in a hypothetical +level zero that surrounds the entire file. Use a line like this@footnote{As +with all these in-buffer settings, pressing @kbd{C-c C-c} activates any +changes in the line.}: + +@smallexample +#+FILETAGS: :Peter:Boss:Secret: +@end smallexample + +@node Setting tags, Tag searches, Tag inheritance, Tags +@section Setting tags + +Tags can simply be typed into the buffer at the end of a headline. +After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is +also a special command for inserting tags: + +@table @kbd +@item C-c C-q +Enter new tags for the current headline. Org mode will either offer +completion or a special single-key interface for setting tags, see +below. After pressing @key{RET}, the tags will be inserted and aligned +to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all +tags in the current buffer will be aligned to that column, just to make +things look nice. +@item C-c C-c +When the cursor is in a headline, this does the same as @kbd{C-c C-q}. +@end table + +Org will support tag insertion based on a @emph{list of tags}. By +default this list is constructed dynamically, containing all tags +currently used in the buffer. You may also globally specify a hard list +of tags with the variable @code{org-tag-alist}. Finally you can set +the default tags for a given file with lines like + +@smallexample +#+TAGS: @@work @@home @@tennisclub +#+TAGS: laptop car pc sailboat +@end smallexample + +By default Org mode uses the standard minibuffer completion facilities for +entering tags. However, it also implements another, quicker, tag selection +method called @emph{fast tag selection}. This allows you to select and +deselect tags with just a single key press. For this to work well you should +assign unique letters to most of your commonly used tags. You can do this +globally by configuring the variable @code{org-tag-alist} in your +@file{.emacs} file. For example, you may find the need to tag many items in +different files with @samp{:@@home:}. In this case you can set something +like: + +@smalllisp +(setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l))) +@end smalllisp + +@noindent If the tag is only relevant to the file you are working on, then you +can instead set the TAGS option line as: + +@smallexample +#+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p) +@end smallexample + +@node Tag searches, , Setting tags, Tags +@section Tag searches + +Once a system of tags has been set up, it can be used to collect related +information into special lists. + +@table @kbd +@item C-c \ +@itemx C-c / m +Create a sparse tree with all headlines matching a tags search. With a +@kbd{C-u} prefix argument, ignore headlines that are not a TODO line. +@item C-c a m +Create a global list of tag matches from all agenda files. +@xref{Matching tags and properties}. +@item C-c a M +Create a global list of tag matches from all agenda files, but check +only TODO items and force checking subitems (see variable +@code{org-tags-match-list-sublevels}). +@end table + +These commands all prompt for a match string which allows basic Boolean logic +like @samp{+boss+urgent-project1}, to find entries with tags @samp{boss} and +@samp{urgent}, but not @samp{project1}, or @samp{Kathy|Sally} to find entries +which are tagged, like @samp{Kathy} or @samp{Sally}. The full syntax of the +search string is rich and allows also matching against TODO keywords, entry +levels and properties. For a complete description with many examples, see +@ref{Matching tags and properties}. + +@seealso{ +@uref{http://orgmode.org/manual/Tags.html#Tags, Chapter 6 of the manual}@* +@uref{http://sachachua.com/wp/2008/01/tagging-in-org-plus-bonus-code-for-timeclocks-and-tags/, +Sacha Chua's article about tagging in Org-mode}} + +@node Properties, Dates and Times, Tags, Top +@chapter Properties + +Properties are key-value pairs associates with and entry. They live in a +special drawer with the name @code{PROPERTIES}. Each +property is specified on a single line, with the key (surrounded by colons) +first, and the value after it: + +@smallexample +* CD collection +** Classic +*** Goldberg Variations + :PROPERTIES: + :Title: Goldberg Variations + :Composer: J.S. Bach + :Publisher: Deutsche Grammophon + :NDisks: 1 + :END: +@end smallexample + +You may define the allowed values for a particular property @samp{:Xyz:} +by setting a property @samp{:Xyz_ALL:}. This special property is +@emph{inherited}, so if you set it in a level 1 entry, it will apply to +the entire tree. When allowed values are defined, setting the +corresponding property becomes easier and is less prone to typing +errors. For the example with the CD collection, we can predefine +publishers and the number of disks in a box like this: + +@smallexample +* CD collection + :PROPERTIES: + :NDisks_ALL: 1 2 3 4 + :Publisher_ALL: "Deutsche Grammophon" Philips EMI + :END: +@end smallexample +or globally using @code{org-global-properties}, or file-wide like this: +@smallexample +#+PROPERTY: NDisks_ALL 1 2 3 4 +@end smallexample + +@table @kbd +@item C-c C-x p +Set a property. This prompts for a property name and a value. +@item C-c C-c d +Remove a property from the current entry. +@end table + +To create sparse trees and special lists with selection based on properties, +the same commands are used as for tag searches (@pxref{Tag searches}). The +syntax for the search string is described in @ref{Matching tags and +properties}. + +@table @kbd +@end table + +@seealso{ +@uref{http://orgmode.org/manual/Properties-and-Columns.html#Properties-and-Columns, +Chapter 7 of the manual}@* +@uref{http://orgmode.org/worg/org-tutorials/org-column-view-tutorial.php,Bastien +Guerry's column view tutorial}} + +@node Dates and Times, Capture - Refile - Archive, Properties, Top +@chapter Dates and Times + +To assist project planning, TODO items can be labeled with a date and/or +a time. The specially formatted string carrying the date and time +information is called a @emph{timestamp} in Org mode. + +@menu +* Timestamps:: Assigning a time to a tree entry +* Creating timestamps:: Commands which insert timestamps +* Deadlines and scheduling:: Planning your work +* Clocking work time:: Tracking how long you spend on a task +@end menu + + +@node Timestamps, Creating timestamps, Dates and Times, Dates and Times +@section Timestamps + +A timestamp is a specification of a date (possibly with a time or a range of +times) in a special format, either @samp{<2003-09-16 Tue>} or +@samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue 12:00-12:30>}. A +timestamp can appear anywhere in the headline or body of an Org tree entry. +Its presence causes entries to be shown on specific dates in the agenda +(@pxref{Weekly/daily agenda}). We distinguish: + +@noindent @b{Plain timestamp; Event; Appointment}@* +A simple timestamp just assigns a date/time to an item. This is just +like writing down an appointment or event in a paper agenda. + +@smallexample +* Meet Peter at the movies <2006-11-01 Wed 19:15> +* Discussion on climate change <2006-11-02 Thu 20:00-22:00> +@end smallexample + +@noindent @b{Timestamp with repeater interval}@* +A timestamp may contain a @emph{repeater interval}, indicating that it +applies not only on the given date, but again and again after a certain +interval of N days (d), weeks (w), months (m), or years (y). The +following will show up in the agenda every Wednesday: +@smallexample +* Pick up Sam at school <2007-05-16 Wed 12:30 +1w> +@end smallexample + +@noindent @b{Diary-style sexp entries}@* +For more complex date specifications, Org mode supports using the +special sexp diary entries implemented in the Emacs calendar/diary +package. For example +@smallexample +* The nerd meeting on every 2nd Thursday of the month + <%%(diary-float t 4 2)> +@end smallexample + +@noindent @b{Time/Date range}@* +Two timestamps connected by @samp{--} denote a range. +@smallexample +** Meeting in Amsterdam + <2004-08-23 Mon>--<2004-08-26 Thu> +@end smallexample + +@noindent @b{Inactive timestamp}@* +Just like a plain timestamp, but with square brackets instead of +angular ones. These timestamps are inactive in the sense that they do +@emph{not} trigger an entry to show up in the agenda. + +@smallexample +* Gillian comes late for the fifth time [2006-11-01 Wed] +@end smallexample + + +@node Creating timestamps, Deadlines and scheduling, Timestamps, Dates and Times +@section Creating timestamps + +For Org mode to recognize timestamps, they need to be in the specific +format. All commands listed below produce timestamps in the correct +format. + +@table @kbd +@item C-c . +Prompt for a date and insert a corresponding timestamp. When the cursor is +at an existing timestamp in the buffer, the command is used to modify this +timestamp instead of inserting a new one. When this command is used twice in +succession, a time range is inserted. With a prefix, also add the current +time. +@c +@item C-c ! +Like @kbd{C-c .}, but insert an inactive timestamp that will not cause +an agenda entry. +@c +@item S-@key{left}@r{/}@key{right} +Change date at cursor by one day. +@c +@item S-@key{up}@r{/}@key{down} +Change the item under the cursor in a timestamp. The cursor can be on a +year, month, day, hour or minute. When the timestamp contains a time range +like @samp{15:30-16:30}, modifying the first time will also shift the second, +shifting the time block with constant length. To change the length, modify +the second time. +@end table + +When Org mode prompts for a date/time, it will accept any string containing +some date and/or time information, and intelligently interpret the string, +deriving defaults for unspecified information from the current date and time. +You can also select a date in the pop-up calendar. See the manual for more +information on how exactly the date/time prompt works. + +@node Deadlines and scheduling, Clocking work time, Creating timestamps, Dates and Times +@section Deadlines and scheduling + +A timestamp may be preceded by special keywords to facilitate planning: + +@noindent @b{DEADLINE}@* +Meaning: the task (most likely a TODO item, though not necessarily) is supposed +to be finished on that date. +@table @kbd +@item C-c C-d +Insert @samp{DEADLINE} keyword along with a stamp, in the line following the +headline. +@end table + +On the deadline date, the task will be listed in the agenda. In +addition, the agenda for @emph{today} will carry a warning about the +approaching or missed deadline, starting +@code{org-deadline-warning-days} before the due date, and continuing +until the entry is marked DONE. An example: + +@smallexample +*** TODO write article about the Earth for the Guide + The editor in charge is [[bbdb:Ford Prefect]] + DEADLINE: <2004-02-29 Sun> +@end smallexample + + +@noindent @b{SCHEDULED}@* +Meaning: you are @i{planning to start working} on that task on the given +date@footnote{This is quite different from what is normally understood by +@i{scheduling a meeting}, which is done in Org-mode by just inserting a time +stamp without keyword.}. + +@table @kbd +@item C-c C-s +Insert @samp{SCHEDULED} keyword along with a stamp, in the line following the +headline. +@end table + +The headline will be listed under the given date@footnote{It will still +be listed on that date after it has been marked DONE. If you don't like +this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In +addition, a reminder that the scheduled date has passed will be present +in the compilation for @emph{today}, until the entry is marked DONE. +I.e. the task will automatically be forwarded until completed. + +@smallexample +*** TODO Call Trillian for a date on New Years Eve. + SCHEDULED: <2004-12-25 Sat> +@end smallexample + +Some tasks need to be repeated again and again. Org mode helps to +organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED, +or plain timestamp. In the following example +@smallexample +** TODO Pay the rent + DEADLINE: <2005-10-01 Sat +1m> +@end smallexample +@noindent +the @code{+1m} is a repeater; the intended interpretation is that the task +has a deadline on <2005-10-01> and repeats itself every (one) month starting +from that time. + +@node Clocking work time, , Deadlines and scheduling, Dates and Times +@section Clocking work time + +Org mode allows you to clock the time you spend on specific tasks in a +project. + +@table @kbd +@item C-c C-x C-i +Start the clock on the current item (clock-in). This inserts the CLOCK +keyword together with a timestamp. When called with a @kbd{C-u} prefix +argument, select the task from a list of recently clocked tasks. +@c +@item C-c C-x C-o +Stop the clock (clock-out). This inserts another timestamp at the same +location where the clock was last started. It also directly computes +the resulting time in inserts it after the time range as @samp{=> +HH:MM}. +@item C-c C-x C-e +Update the effort estimate for the current clock task. +@item C-c C-x C-x +Cancel the current clock. This is useful if a clock was started by +mistake, or if you ended up working on something else. +@item C-c C-x C-j +Jump to the entry that contains the currently running clock. With a +@kbd{C-u} prefix arg, select the target task from a list of recently clocked +tasks. +@item C-c C-x C-r +Insert a dynamic block containing a clock +report as an Org-mode table into the current file. When the cursor is +at an existing clock table, just update it. +@smallexample +#+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file +#+END: clocktable +@end smallexample +@noindent +For details about how to customize this view, see @uref{http://orgmode.org/manual/Clocking-work-time.html#Clocking-work-time,the manual}. +@item C-c C-c +Update dynamic block at point. The cursor needs to be in the +@code{#+BEGIN} line of the dynamic block. +@end table + +The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in +the agenda (@pxref{Weekly/daily agenda}) to show which tasks have been +worked on or closed during a day. + +@seealso{ +@uref{http://orgmode.org/manual/Dates-and-Times.html#Dates-and-Times, +Chapter 8 of the manual}@* +@uref{http://members.optusnet.com.au/~charles57/GTD/org_dates/, Charles +Cave's Date and Time tutorial}@* +@uref{http://doc.norang.ca/org-mode.html#Clocking, Bernt Hansen's clocking workflow}} + +@node Capture - Refile - Archive, Agenda Views, Dates and Times, Top +@chapter Capture - Refile - Archive + +An important part of any organization system is the ability to quickly +capture new ideas and tasks, and to associate reference material with them. +Org uses the @file{remember.el} package to create tasks, and stores files +related to a task (@i{attachments}) in a special directory. Once in the +system, tasks and projects need to be moved around. Moving completed project +trees to an archive file keeps the system compact and fast. + +@menu +* Remember:: Capture new tasks/ideas with little interruption +* Refiling notes:: Moving a tree from one place to another +* Archiving:: What to do with finished projects +@end menu + +@node Remember, Refiling notes, Capture - Refile - Archive, Capture - Refile - Archive +@section Remember + +The Remember package by John Wiegley lets you store quick notes with little +interruption of your work flow. It is an excellent way to add new notes and +tasks to Org files. The @code{remember.el} package is part of Emacs 23, not +Emacs 22. See @uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for +more information. + +Org significantly expands the possibilities of Remember: you may define +templates for different note types, and associate target files and headlines +with specific templates. It also allows you to select the location where a +note should be stored interactively, on the fly. + +@menu +* Setting up Remember for Org:: Some code for .emacs to get things going +* Remember templates:: Define the outline of different note types +* Storing notes:: Directly get the note to where it belongs +@end menu + +@node Setting up Remember for Org, Remember templates, Remember, Remember +@unnumberedsubsec Setting up Remember for Org + +The following customization will tell Remember to use Org files as +target, and to create annotations compatible with Org links. + +@smallexample +(org-remember-insinuate) +(setq org-directory "~/path/to/my/orgfiles/") +(setq org-default-notes-file (concat org-directory "/notes.org")) +(define-key global-map "\C-cr" 'org-remember) +@end smallexample + +@noindent +The last line binds the command @code{org-remember} to a global +key@footnote{Please select your own key, @kbd{C-c r} is only a +suggestion.}. @code{org-remember} basically just calls Remember, +but it makes a few things easier: if there is an active region, it will +automatically copy the region into the Remember buffer. It also allows +to jump to the buffer and location where Remember notes are being +stored: just call @code{org-remember} with a prefix argument. If you +use two prefix arguments, Org jumps to the location where the last +remember note was stored. + +@node Remember templates, Storing notes, Setting up Remember for Org, Remember +@unnumberedsubsec Remember templates + +In combination with Org, you can use templates to generate +different types of Remember notes. For example, if you would like +to use one template to create general TODO entries, another one for +journal entries, and a third one for collecting random ideas, you could +use: + +@smallexample +(setq org-remember-templates + '(("Todo" ?t "* TODO %?\n %i\n %a" "~/org/TODO.org" "Tasks") + ("Journal" ?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org") + ("Idea" ?i "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas"))) +@end smallexample + +@noindent In these entries, the first string is just a name, and the +character specifies how to select the template. It is useful if the +character is also the first letter of the name. The next string specifies +the template. Two more (optional) strings give the file in which, and the +headline under which, the new note should be stored. + +When you call @kbd{M-x org-remember} (or @kbd{M-x remember}) to remember +something, Org will prompt for a key to select the template (if you have +more than one template) and then prepare the buffer like +@smallexample +* TODO + [[file:@var{link to where you called remember}]] +@end smallexample + +@noindent +During expansion of the template, special @kbd{%}-escapes@footnote{If you +need one of these sequences literally, escape the @kbd{%} with a backslash.} +allow dynamic insertion of content. Here is a small selection of the +possibilities, consult the manual for more. +@smallexample +%a @r{annotation, normally the link created with @code{org-store-link}} +%i @r{initial content, the region when remember is called with C-u.} +%t @r{timestamp, date only} +%T @r{timestamp with date and time} +%u, %U @r{like the above, but inactive timestamps} +@end smallexample + +@node Storing notes, , Remember templates, Remember +@unnumberedsubsec Storing notes + +When you are finished preparing a note with Remember, you have to press +@kbd{C-c C-c} to file the note away. + +The handler will store the note in the file and under the headline +specified in the template, or it will use the default file and headline. The +window configuration will be restored, sending you back to the working +context before the call to Remember. + +@node Refiling notes, Archiving, Remember, Capture - Refile - Archive +@section Refiling notes + +When reviewing the captured data, you may want to refile some of the entries +into a different list, for example into a project. Cutting, finding the +right location, and then pasting the note is cumbersome. To simplify this +process, you can use the following special command: + +@table @kbd +@item C-c C-w +Refile the entry or region at point. This command offers possible locations +for refiling the entry and lets you select one with completion. The item (or +all items in the region) is filed below the target heading as a subitem.@* +By default, all level 1 headlines in the current buffer are considered to be +targets, but you can have more complex definitions across a number of files. +See the variable @code{org-refile-targets} for details. +@item C-u C-c C-w +Use the refile interface to jump to a heading. +@item C-u C-u C-c C-w +Jump to the location where @code{org-refile} last moved a tree to. +@end table + +@node Archiving, , Refiling notes, Capture - Refile - Archive +@section Archiving + +When a project represented by a (sub)tree is finished, you may want +to move the tree out of the way and to stop it from contributing to the +agenda. Archiving is important to keep your working files compact and global +searches like the construction of agenda views fast. +The most common archiving action is to move a project tree to another file, +the archive file. + +@table @kbd +@item C-c C-x C-a +Archive the current entry using the command specified in the variable +@code{org-archive-default-command}. +@item C-c C-x C-s@ @r{or short} @ C-c $ +Archive the subtree starting at the cursor position to the location +given by @code{org-archive-location}. +@end table + +The default archive location is a file in the same directory as the +current file, with the name derived by appending @file{_archive} to the +current file name. For information and examples on how to change this, +see the documentation string of the variable +@code{org-archive-location}. There is also an in-buffer option for +setting this variable, for example + +@smallexample +#+ARCHIVE: %s_done:: +@end smallexample + +@seealso{ +@uref{http://orgmode.org/manual/Capture-_002d-Refile-_002d-Archive.html#Capture-_002d-Refile-_002d-Archive, +Chapter 9 of the manual}@* +@uref{http://members.optusnet.com.au/~charles57/GTD/remember.html, Charles +Cave's remember tutorial}@* +@uref{http://orgmode.org/worg/org-tutorials/org-protocol-custom-handler.php, +Sebastian Rose's tutorial for capturing from a web browser}}@uref{}@* + +@node Agenda Views, Markup, Capture - Refile - Archive, Top +@chapter Agenda Views + +Due to the way Org works, TODO items, time-stamped items, and tagged +headlines can be scattered throughout a file or even a number of files. To +get an overview of open action items, or of events that are important for a +particular date, this information must be collected, sorted and displayed in +an organized way. There are several different views, see below. + +The extracted information is displayed in a special @emph{agenda buffer}. +This buffer is read-only, but provides commands to visit the corresponding +locations in the original Org files, and even to edit these files remotely. +Remote editing from the agenda buffer means, for example, that you can +change the dates of deadlines and appointments from the agenda buffer. +The commands available in the Agenda buffer are listed in @ref{Agenda +commands}. + +@menu +* Agenda files:: Files being searched for agenda information +* Agenda dispatcher:: Keyboard access to agenda views +* Built-in agenda views:: What is available out of the box? +* Agenda commands:: Remote editing of Org trees +* Custom agenda views:: Defining special searches and views +@end menu + +@node Agenda files, Agenda dispatcher, Agenda Views, Agenda Views +@section Agenda files + +The information to be shown is normally collected from all @emph{agenda +files}, the files listed in the variable +@code{org-agenda-files}. + +@table @kbd +@item C-c [ +Add current file to the list of agenda files. The file is added to +the front of the list. If it was already in the list, it is moved to +the front. With a prefix argument, file is added/moved to the end. +@item C-c ] +Remove current file from the list of agenda files. +@item C-, +Cycle through agenda file list, visiting one file after the other. +@end table + +@node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda Views +@section The agenda dispatcher +The views are created through a dispatcher, which should be bound to a +global key---for example @kbd{C-c a} (@pxref{Installation}). After +pressing @kbd{C-c a}, an additional letter is required to execute a +command: +@table @kbd +@item a +The calendar-like agenda (@pxref{Weekly/daily agenda}). +@item t @r{/} T +A list of all TODO items (@pxref{Global TODO list}). +@item m @r{/} M +A list of headlines matching a TAGS expression (@pxref{Matching +tags and properties}). +@item L +The timeline view for the current buffer (@pxref{Timeline}). +@item s +A list of entries selected by a boolean expression of keywords +and/or regular expressions that must or must not occur in the entry. +@end table + +@node Built-in agenda views, Agenda commands, Agenda dispatcher, Agenda Views +@section The built-in agenda views + +@menu +* Weekly/daily agenda:: The calendar page with current tasks +* Global TODO list:: All unfinished action items +* Matching tags and properties:: Structured information with fine-tuned search +* Timeline:: Time-sorted view for single file +* Search view:: Find entries by searching for text +@end menu + +@node Weekly/daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views +@subsection The weekly/daily agenda + +The purpose of the weekly/daily @emph{agenda} is to act like a page of a +paper agenda, showing all the tasks for the current week or day. + +@table @kbd +@item C-c a a +Compile an agenda for the current week from a list of Org files. The agenda +shows the entries for each day. +@end table + +Emacs contains the calendar and diary by Edward M. Reingold. Org-mode +understands the syntax of the diary and allows you to use diary sexp entries +directly in Org files: + +@smallexample +* Birthdays and similar stuff +#+CATEGORY: Holiday +%%(org-calendar-holiday) ; special function for holiday names +#+CATEGORY: Ann +%%(diary-anniversary 5 14 1956)@footnote{Note that the order of the arguments (month, day, year) depends on the setting of @code{calendar-date-style}.} Arthur Dent is %d years old +%%(diary-anniversary 10 2 1869) Mahatma Gandhi would be %d years old +@end smallexample + +Org can interact with Emacs appointments notification facility. To add all +the appointments of your agenda files, use the command +@code{org-agenda-to-appt}. See the docstring for details. + +@node Global TODO list, Matching tags and properties, Weekly/daily agenda, Built-in agenda views +@subsection The global TODO list + +The global TODO list contains all unfinished TODO items formatted and +collected into a single place. Remote editing of TODO items lets you +can change the state of a TODO entry with a single key press. The commands +available in the TODO list are described in @ref{Agenda commands}. + +@table @kbd +@item C-c a t +Show the global TODO list. This collects the TODO items from all +agenda files (@pxref{Agenda Views}) into a single buffer. +@item C-c a T +Like the above, but allows selection of a specific TODO keyword. +@end table + +@node Matching tags and properties, Timeline, Global TODO list, Built-in agenda views +@subsection Matching tags and properties + +If headlines in the agenda files are marked with @emph{tags} (@pxref{Tags}), +or have properties (@pxref{Properties}), you can select headlines +based on this metadata and collect them into an agenda buffer. The match +syntax described here also applies when creating sparse trees with @kbd{C-c / +m}. The commands available in the tags list are described in @ref{Agenda +commands}. + +@table @kbd +@item C-c a m +Produce a list of all headlines that match a given set of tags. The +command prompts for a selection criterion, which is a boolean logic +expression with tags, like @samp{+work+urgent-withboss} or +@samp{work|home} (@pxref{Tags}). If you often need a specific search, +define a custom command for it (@pxref{Agenda dispatcher}). +@item C-c a M +Like @kbd{C-c a m}, but only select headlines that are also TODO items. +@end table + +@subsubheading Match syntax + +A search string can use Boolean operators @samp{&} for AND and @samp{|} for +OR. @samp{&} binds more strongly than @samp{|}. Parentheses are currently +not implemented. Each element in the search is either a tag, a regular +expression matching tags, or an expression like @code{PROPERTY OPERATOR +VALUE} with a comparison operator, accessing a property value. Each element +may be preceded by @samp{-}, to select against it, and @samp{+} is syntactic +sugar for positive selection. The AND operator @samp{&} is optional when +@samp{+} or @samp{-} is present. Here are some examples, using only tags. + +@table @samp +@item +work-boss +Select headlines tagged @samp{:work:}, but discard those also tagged +@samp{:boss:}. +@item work|laptop +Selects lines tagged @samp{:work:} or @samp{:laptop:}. +@item work|laptop+night +Like before, but require the @samp{:laptop:} lines to be tagged also +@samp{:night:}. +@end table + +You may also test for properties at the same +time as matching tags, see the manual for more information. + +@node Timeline, Search view, Matching tags and properties, Built-in agenda views +@subsection Timeline for a single file + +The timeline summarizes all time-stamped items from a single Org mode +file in a @emph{time-sorted view}. The main purpose of this command is +to give an overview over events in a project. + +@table @kbd +@item C-c a L +Show a time-sorted view of the Org file, with all time-stamped items. +When called with a @kbd{C-u} prefix, all unfinished TODO entries +(scheduled or not) are also listed under the current date. +@end table + +@node Search view, , Timeline, Built-in agenda views +@subsection Search view + +This agenda view is a general text search facility for Org mode entries. +It is particularly useful to find notes. + +@table @kbd +@item C-c a s +This is a special search that lets you select entries by matching a substring +or specific words using a boolean logic. +@end table +For example, the search string @samp{computer equipment} will find entries +that contain @samp{computer equipment} as a substring. +Search view can also search for specific keywords in the entry, using Boolean +logic. The search string @samp{+computer +wifi -ethernet -@{8\.11[bg]@}} +will search for note entries that contain the keywords @code{computer} +and @code{wifi}, but not the keyword @code{ethernet}, and which are also +not matched by the regular expression @code{8\.11[bg]}, meaning to +exclude both 8.11b and 8.11g. + +Note that in addition to the agenda files, this command will also search +the files listed in @code{org-agenda-text-search-extra-files}. + +@node Agenda commands, Custom agenda views, Built-in agenda views, Agenda Views +@section Commands in the agenda buffer + +Entries in the agenda buffer are linked back to the Org file or diary +file where they originate. Commands are provided to show and jump to the +original entry location, and to edit the Org files ``remotely'' from +the agenda buffer. This is just a selection of the many commands, explore +the @code{Agenda} menu and the manual for a complete list. + +@table @kbd +@tsubheading{Motion} +@item n +Next line (same as @key{up} and @kbd{C-p}). +@item p +Previous line (same as @key{down} and @kbd{C-n}). +@tsubheading{View/Go to Org file} +@item mouse-3 +@itemx @key{SPC} +Display the original location of the item in another window. +With prefix arg, make sure that the entire entry is made visible in the +outline, not only the heading. +@c +@itemx @key{TAB} +Go to the original location of the item in another window. Under Emacs +22, @kbd{mouse-1} will also works for this. +@c +@itemx @key{RET} +Go to the original location of the item and delete other windows. +@c + +@tsubheading{Change display} +@item o +Delete other windows. +@c +@item d @r{/} w +Switch to day/week view. +@c +@item f @r{and} b +Go forward/backward in time to display the following @code{org-agenda-ndays} +days. For example, if the display covers a week, switch to the +following/previous week. +@c +@item . +Go to today. +@c +@item j +Prompt for a date and go there. +@c +@item v l @ @r{or short} @ l +Toggle Logbook mode. In Logbook mode, entries that were marked DONE while +logging was on (variable @code{org-log-done}) are shown in the agenda, as are +entries that have been clocked on that day. When called with a @kbd{C-u} +prefix, show all possible logbook entries, including state changes. +@c +@item r @r{or} g +Recreate the agenda buffer, to reflect the changes. +@item s +Save all Org buffers in the current Emacs session, and also the locations of +IDs. + +@tsubheading{Secondary filtering and query editing} + +@item / +Filter the current agenda view with respect to a tag. You are prompted for a +letter to select a tag. Press @samp{-} first to select against the tag. + +@item \ +Narrow the current agenda filter by an additional condition. + +@tsubheading{Remote editing (see the manual for many more commands)} + +@item 0-9 +Digit argument. +@c +@item t +Change the TODO state of the item, in the agenda and in the +org file. +@c +@item C-k +Delete the current agenda item along with the entire subtree belonging +to it in the original Org file. +@c +@item C-c C-w +Refile the entry at point. +@c +@item C-c C-x C-a @ @r{or short} @ a +Archive the subtree corresponding to the entry at point using the default +archiving command set in @code{org-archive-default-command}. +@c +@item C-c C-x C-s @ @r{or short} @ $ +Archive the subtree corresponding to the current headline. +@c +@item C-c C-s +Schedule this item, with prefix arg remove the scheduling timestamp +@c +@item C-c C-d +Set a deadline for this item, with prefix arg remove the deadline. +@c +@item S-@key{right} @r{and} S-@key{left} +Change the timestamp associated with the current line by one day. +@c +@item I +Start the clock on the current item. +@c +@item O / X +Stop/cancel the previously started clock. + +@item J +Jump to the running clock in another window. +@end table + +@node Custom agenda views, , Agenda commands, Agenda Views +@section Custom agenda views + +The main application of custom searches is the definition of keyboard +shortcuts for frequently used searches, either creating an agenda +buffer, or a sparse tree (the latter covering of course only the current +buffer). +Custom commands are configured in the variable +@code{org-agenda-custom-commands}. You can customize this variable, for +example by pressing @kbd{C-c a C}. You can also directly set it with +Emacs Lisp in @file{.emacs}. The following example contains all valid +search types: + +@smalllisp +@group +(setq org-agenda-custom-commands + '(("w" todo "WAITING") + ("u" tags "+boss-urgent") + ("v" tags-todo "+boss-urgent"))) +@end group +@end smalllisp + +@noindent +The initial string in each entry defines the keys you have to press after the +dispatcher command @kbd{C-c a} in order to access the command. Usually this +will be just a single character. The second parameter is the search type, +followed by the string or regular expression to be used for the matching. +The example above will therefore define: + +@table @kbd +@item C-c a w +as a global search for TODO entries with @samp{WAITING} as the TODO +keyword +@item C-c a u +as a global tags search for headlines marked @samp{:boss:} but not +@samp{:urgent:} +@item C-c a v +as the same search as @kbd{C-c a u}, but limiting the search to +headlines that are also TODO items +@end table + +@seealso{ +@uref{http://orgmode.org/manual/Agenda-Views.html#Agenda-Views, Chapter 10 of +the manual}@* +@uref{http://orgmode.org/worg/org-tutorials/org-custom-agenda-commands.php, +Mat Lundin's tutorial about custom agenda commands}@* +@uref{http://www.newartisans.com/2007/08/using-org-mode-as-a-day-planner.html, +John Wiegley's setup}} + +@node Markup, Exporting, Agenda Views, Top +@chapter Markup for rich export + +When exporting Org-mode documents, the exporter tries to reflect the +structure of the document as accurately as possible in the backend. Since +export targets like HTML, La@TeX{}, or DocBook allow much richer formatting, +Org mode has rules on how to prepare text for rich export. This section +summarizes the markup rules used in an Org-mode buffer. + +@menu +* Structural markup elements:: The basic structure as seen by the exporter +* Images and tables:: Tables and Images will be included +* Literal examples:: Source code examples with special formatting +* Include files:: Include additional files into a document +* Embedded LaTeX:: LaTeX can be freely used inside Org documents +@end menu + +@node Structural markup elements, Images and tables, Markup, Markup +@section Structural markup elements + +@menu +* Document title:: Where the title is taken from +* Headings and sections:: The document structure as seen by the exporter +* Table of contents:: The if and where of the table of contents +* Paragraphs:: Paragraphs +* Emphasis and monospace:: Bold, italic, etc. +* Comment lines:: What will *not* be exported +@end menu + +@node Document title, Headings and sections, Structural markup elements, Structural markup elements +@subheading Document title + +@noindent +The title of the exported document is taken from the special line + +@smallexample +#+TITLE: This is the title of the document +@end smallexample + +@node Headings and sections, Table of contents, Document title, Structural markup elements +@subheading Headings and sections + +The outline structure of the document as described in @ref{Document +Structure}, forms the basis for defining sections of the exported document. +However, since the outline structure is also used for (for example) lists of +tasks, only the first three outline levels will be used as headings. Deeper +levels will become itemized lists. You can change the location of this +switch globally by setting the variable @code{org-export-headline-levels}, or on a +per-file basis with a line + +@smallexample +#+OPTIONS: H:4 +@end smallexample + +@node Table of contents, Paragraphs, Headings and sections, Structural markup elements +@subheading Table of contents + +The table of contents is normally inserted directly before the first headline +of the file. + +@smallexample +#+OPTIONS: toc:2 (only to two levels in TOC) +#+OPTIONS: toc:nil (no TOC at all) +@end smallexample + +@node Paragraphs, Emphasis and monospace, Table of contents, Structural markup elements +@subheading Paragraphs, line breaks, and quoting + +Paragraphs are separated by at least one empty line. If you need to enforce +a line break within a paragraph, use @samp{\\} at the end of a line. + +To keep the line breaks in a region, but otherwise use normal formatting, you +can use this construct, which can also be used to format poetry. + +@smallexample +#+BEGIN_VERSE + Great clouds overhead + Tiny black birds rise and fall + Snow covers Emacs + + -- AlexSchroeder +#+END_VERSE +@end smallexample + +When quoting a passage from another document, it is customary to format this +as a paragraph that is indented on both the left and the right margin. You +can include quotations in Org-mode documents like this: + +@smallexample +#+BEGIN_QUOTE +Everything should be made as simple as possible, +but not any simpler -- Albert Einstein +#+END_QUOTE +@end smallexample + +If you would like to center some text, do it like this: +@smallexample +#+BEGIN_CENTER +Everything should be made as simple as possible, \\ +but not any simpler +#+END_CENTER +@end smallexample + +@node Emphasis and monospace, Comment lines, Paragraphs, Structural markup elements +@subheading Emphasis and monospace + +You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=} +and @code{~verbatim~}, and, if you must, @samp{+strike-through+}. Text +in the code and verbatim string is not processed for Org-mode specific +syntax, it is exported verbatim. To insert a horizontal rules, use a line +consisting of only dashes, and at least 5 of them. + +@node Comment lines, , Emphasis and monospace, Structural markup elements +@subheading Comment lines + +Lines starting with @samp{#} in column zero are treated as comments and will +never be exported. If you want an indented line to be treated as a comment, +start it with @samp{#+ }. Also entire subtrees starting with the word +@samp{COMMENT} will never be exported. Finally, regions surrounded by +@samp{#+BEGIN_COMMENT} ... @samp{#+END_COMMENT} will not be exported. + +@table @kbd +@item C-c ; +Toggle the COMMENT keyword at the beginning of an entry. +@end table + +@node Images and tables, Literal examples, Structural markup elements, Markup +@section Images and Tables + +For Org mode tables, the lines before the first horizontal separator line +will become table header lines. You can use the following lines somewhere +before the table to assign a caption and a label for cross references, and in +the text you can refer to the object with @code{\ref@{tab:basic-data@}}: + +@smallexample +#+CAPTION: This is the caption for the next table (or link) +#+LABEL: tbl:basic-data + | ... | ...| + |-----|----| +@end smallexample + +Some backends (HTML, La@TeX{}, and DocBook) allow you to directly include +images into the exported document. Org does this, if a link to an image +files does not have a description part, for example @code{[[./img/a.jpg]]}. +If you wish to define a caption for the image and maybe a label for internal +cross references, you sure that the link is on a line by itself precede it +with: + +@smallexample +#+CAPTION: This is the caption for the next figure link (or table) +#+LABEL: fig:SED-HR4049 +[[./img/a.jpg]] +@end smallexample + +You may also define additional attributes for the figure. As this is +backend-specific, see the sections about the individual backends for more +information. + + +@node Literal examples, Include files, Images and tables, Markup +@section Literal examples + +You can include literal examples that should not be subjected to +markup. Such examples will be typeset in monospace, so this is well suited +for source code and similar examples. + +@smallexample +#+BEGIN_EXAMPLE +Some example from a text file. +#+END_EXAMPLE +@end smallexample + +For simplicity when using small examples, you can also start the example +lines with a colon followed by a space. There may also be additional +whitespace before the colon: + +@smallexample +Here is an example + : Some example from a text file. +@end smallexample + +For source code from a programming language, or any other text +that can be marked up by font-lock in Emacs, you can ask for it to +look like the fontified Emacs buffer + +@smallexample +#+BEGIN_SRC emacs-lisp +(defun org-xor (a b) + "Exclusive or." + (if a (not b) b)) +#+END_SRC +@end smallexample + +To edit the example in a special buffer supporting this language, use +@kbd{C-c '} to both enter and leave the editing buffer. + +@node Include files, Embedded LaTeX, Literal examples, Markup +@section Include files + +During export, you can include the content of another file. For example, to +include your @file{.emacs} file, you could use: + +@smallexample +#+INCLUDE: "~/.emacs" src emacs-lisp +@end smallexample +@noindent +The optional second and third parameter are the markup (e.g. @samp{quote}, +@samp{example}, or @samp{src}), and, if the markup is @samp{src}, the +language for formatting the contents. The markup is optional, if it is not +given, the text will be assumed to be in Org mode format and will be +processed normally. @kbd{C-c '} will visit the included file. + +@node Embedded LaTeX, , Include files, Markup +@section Embedded La@TeX{} + +For scientific notes which need to be able to contain mathematical symbols +and the occasional formula, Org-mode supports embedding La@TeX{} code into +its files. You can directly use TeX-like macros for special symbols, enter +formulas and entire LaTeX environments. + +@smallexample +Angles are written as Greek letters \alpha, \beta and \gamma. The mass if +the sun is M_sun = 1.989 x 10^30 kg. The radius of the sun is R_@{sun@} = +6.96 x 10^8 m. If $a^2=b$ and $b=2$, then the solution must be either +$a=+\sqrt@{2@}$ or $a=-\sqrt@{2@}$. + +\begin@{equation@} +x=\sqrt@{b@} +\end@{equation@} +@end smallexample +@noindent With +@uref{http://orgmode.org/manual/LaTeX-fragments.html#LaTeX-fragments,special +setup}, LaTeX snippets will be included as images when exporting to HTML. + +@seealso{ +@uref{http://orgmode.org/manual/Markup.html#Markup, Chapter 11 of the manual}} + +@node Exporting, Publishing, Markup, Top +@chapter Exporting + +Org-mode documents can be exported into a variety of other formats: ASCII +export for inclusion into emails, HTML to publish on the web, La@TeX{}/PDF +for beautiful printed documents and DocBook to enter the world of many other +formats using DocBook tools. There is also export to iCalendar format so +that planning information can be incorporated into desktop calendars. + +@menu +* Export options:: Per-file export settings +* The export dispatcher:: How to access exporter commands +* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding +* HTML export:: Exporting to HTML +* LaTeX and PDF export:: Exporting to La@TeX{}, and processing to PDF +* DocBook export:: Exporting to DocBook +* iCalendar export:: +@end menu + +@node Export options, The export dispatcher, Exporting, Exporting +@section Export options + +The exporter recognizes special lines in the buffer which provide +additional information. These lines may be put anywhere in the file. +The whole set of lines can be inserted into the buffer with @kbd{C-c +C-e t}. + +@table @kbd +@item C-c C-e t +Insert template with export options, see example below. +@end table + +@smallexample +#+TITLE: the title to be shown (default is the buffer name) +#+AUTHOR: the author (default taken from @code{user-full-name}) +#+DATE: a date, fixed, of a format string for @code{format-time-string} +#+EMAIL: his/her email address (default from @code{user-mail-address}) +#+DESCRIPTION: the page description, e.g. for the XHTML meta tag +#+KEYWORDS: the page keywords, e.g. for the XHTML meta tag +#+LANGUAGE: language for HTML, e.g. @samp{en} (@code{org-export-default-language}) +#+TEXT: Some descriptive text to be inserted at the beginning. +#+TEXT: Several lines may be given. +#+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ... +#+LINK_UP: the ``up'' link of an exported page +#+LINK_HOME: the ``home'' link of an exported page +#+LATEX_HEADER: extra line(s) for the LaTeX header, like \usepackage@{xyz@} +@end smallexample + +@node The export dispatcher, ASCII/Latin-1/UTF-8 export, Export options, Exporting +@section The export dispatcher + +All export commands can be reached using the export dispatcher, which is a +prefix key that prompts for an additional key specifying the command. +Normally the entire file is exported, but if there is an active region that +contains one outline tree, the first heading is used as document title and +the subtrees are exported. + +@table @kbd +@item C-c C-e +Dispatcher for export and publishing commands. +@end table + +@node ASCII/Latin-1/UTF-8 export, HTML export, The export dispatcher, Exporting +@section ASCII/Latin-1/UTF-8 export + +ASCII export produces a simple and very readable version of an Org-mode +file, containing only plain ASCII. Latin-1 and UTF-8 export augment the file +with special characters and symbols available in these encodings. + +@table @kbd +@item C-c C-e a +Export as ASCII file. +@item C-c C-e n @ @ @r{and} @ @ C-c C-e N +Like the above commands, but use Latin-1 encoding. +@item C-c C-e u @ @ @r{and} @ @ C-c C-e U +Like the above commands, but use UTF-8 encoding. +@end table + +@node HTML export, LaTeX and PDF export, ASCII/Latin-1/UTF-8 export, Exporting +@section HTML export + +@table @kbd +@item C-c C-e h +Export as HTML file @file{myfile.html}. +@item C-c C-e b +Export as HTML file and immediately open it with a browser. +@end table + +To insert HTML that should be copied verbatim to +the exported file use either + +@smallexample +#+HTML: Literal HTML code for export +@end smallexample +@noindent or +@smallexample +#+BEGIN_HTML +All lines between these markers are exported literally +#+END_HTML +@end smallexample + +@node LaTeX and PDF export, DocBook export, HTML export, Exporting +@section La@TeX{} and PDF export + +@table @kbd +@item C-c C-e l +Export as La@TeX{} file @file{myfile.tex}. +@item C-c C-e p +Export as La@TeX{} and then process to PDF. +@item C-c C-e d +Export as La@TeX{} and then process to PDF, then open the resulting PDF file. +@end table + +By default, the La@TeX{} output uses the class @code{article}. You can +change this by adding an option like @code{#+LaTeX_CLASS: myclass} in your +file. The class must be listed in @code{org-export-latex-classes}. + +Embedded La@TeX{} as described in @ref{Embedded LaTeX}, will be correctly +inserted into the La@TeX{} file. Similarly to the HTML exporter, you can use +@code{#+LaTeX:} and @code{#+BEGIN_LaTeX ... #+END_LaTeX} construct to add +verbatim LaTeX code. + +@node DocBook export, iCalendar export, LaTeX and PDF export, Exporting +@section DocBook export + +@table @kbd +@item C-c C-e D +Export as DocBook file. +@end table + +Similarly to the HTML exporter, you can use @code{#+DocBook:} and +@code{#+BEGIN_DocBook ... #+END_DocBook} construct to add verbatim LaTeX +code. + +@node iCalendar export, , DocBook export, Exporting +@section iCalendar export + +@table @kbd +@kindex C-c C-e i +@item C-c C-e i +Create iCalendar entries for the current file in a @file{.ics} file. +@kindex C-c C-e c +@item C-c C-e c +Create a single large iCalendar file from all files in +@code{org-agenda-files} and write it to the file given by +@code{org-combined-agenda-icalendar-file}. +@end table + +@seealso{ +@uref{http://orgmode.org/manual/Exporting.html#Exporting, Chapter 12 of the manual}@* +@uref{http://orgmode.org/worg/org-tutorials/images-and-xhtml-export.php, +Sebastian Rose's image handling tutorial}@* +@uref{http://orgmode.org/worg/org-tutorials/org-latex-export.php, Thomas +Dye's LaTeX export tutorial} +@uref{http://orgmode.org/worg/org-tutorials/org-beamer/tutorial.php, Eric +Fraga's BEAMER presentation tutorial}} + +@node Publishing, Miscellaneous, Exporting, Top +@chapter Publishing + +Org includes a publishing management system that allows you to configure +automatic HTML conversion of @emph{projects} composed of interlinked org +files. You can also configure Org to automatically upload your exported HTML +pages and related attachments, such as images and source code files, to a web +server. For detailed instructions about setup, see the manual. + +Here is an example: + +@smalllisp +(setq org-publish-project-alist + '(("org" + :base-directory "~/org/" + :publishing-directory "~/public_html" + :section-numbers nil + :table-of-contents nil + :style ""))) +@end smalllisp + +@table @kbd +@item C-c C-e C +Prompt for a specific project and publish all files that belong to it. +@item C-c C-e P +Publish the project containing the current file. +@item C-c C-e F +Publish only the current file. +@item C-c C-e E +Publish every project. +@end table + +Org uses timestamps to track when a file has changed. The above functions +normally only publish changed files. You can override this and force +publishing of all files by giving a prefix argument to any of the commands +above. + +@seealso{ +@uref{http://orgmode.org/manual/Publishing.html#Publishing, Chapter 12 of the +manual}@* +@uref{http://orgmode.org/worg/org-tutorials/org-publish-html-tutorial.php, +Sebastian Rose's publishing tutorial}@* +@uref{http://orgmode.org/worg/org-tutorials/org-jekyll.php, Ian Barton's +Jekyll/blogging setup}} + +@node Miscellaneous, , Publishing, Top +@chapter Miscellaneous + +@menu +* Completion:: M-TAB knows what you need +* Clean view:: Getting rid of leading stars in the outline +* MobileOrg:: Org-mode on the iPhone +@end menu + +@node Completion, Clean view, Miscellaneous, Miscellaneous +@section Completion + +Org supports in-buffer completion with @kbd{M-@key{TAB}}. This type of +completion does not make use of the minibuffer. You simply type a few +letters into the buffer and use the key to complete text right there. For +example, this command will complete @TeX{} symbols after @samp{\}, TODO +keywords at the beginning of a headline, and ags after @samp{:} in a +headline. + +@node Clean view, MobileOrg, Completion, Miscellaneous +@section A cleaner outline view + +Some people find it noisy and distracting that the Org headlines start with a +potentially large number of stars, and that text below the headlines is not +indented. While this is no problem when writing a @emph{book-like} document +where the outline headings are really section headings, in a more +@emph{list-oriented} outline, indented structure is a lot cleaner: + +@smallexample +@group +* Top level headline | * Top level headline +** Second level | * Second level +*** 3rd level | * 3rd level +some text | some text +*** 3rd level | * 3rd level +more text | more text +* Another top level headline | * Another top level headline +@end group +@end smallexample + +@noindent +If you are using at least Emacs 23.1.50.3 and version 6.29 of Org, this kind +of view can be achieved dynamically at display time using +@code{org-indent-mode}, which will prepend intangible space to each line. +You can turn on @code{org-indent-mode} for all files by customizing the +variable @code{org-startup-indented}, or you can turn it on for individual +files using + +@smallexample +#+STARTUP: indent +@end smallexample + +If you want a similar effect in earlier version of Emacs and/or Org, or if +you want the indentation to be hard space characters so that the plain text +file looks as similar as possible to the Emacs display, Org supports you by +helping to indent (with @key{TAB}) text below each headline, by hiding +leading stars, and by only using levels 1, 3, etc to get two characters +indentation for each level. To get this support in a file, use + +@smallexample +#+STARTUP: hidestars odd +@end smallexample + +@node MobileOrg, , Clean view, Miscellaneous +@section MobileOrg + +@i{MobileOrg} is an application for the @i{iPhone/iPod Touch} series of +devices, developed by Richard Moreland. For details, see the Org-mode +manual. + +@seealso{ +@uref{http://orgmode.org/manual/Miscellaneous.html#Miscellaneous, Chapter 14 +of the manual}@* +@uref{http://orgmode.org/manual/MobileOrg.html#MobileOrg, Appendix B of the +manual}@* +@uref{http://orgmode.org/orgcard.pdf,Key reference card}} + +@bye + +@ignore + arch-tag: 8f0a8557-0acc-4436-b2b2-0197699e1452 +@end ignore + +@c Local variables: +@c ispell-local-dictionary: "en_US-w_accents" +@c ispell-local-pdict: "./.aspell.org.pws" +@c fill-column: 77 +@c End: + + +@c LocalWords: webdavhost pre From d3315ff844023768f7423868451b92c419374520 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Sat, 1 May 2010 20:42:46 +0200 Subject: [PATCH 26/34] Minor fixes --- doc/orgguide.texi | 26 +++++++++++--------------- 1 file changed, 11 insertions(+), 15 deletions(-) diff --git a/doc/orgguide.texi b/doc/orgguide.texi index e3e45bc21..4b4a69ca2 100644 --- a/doc/orgguide.texi +++ b/doc/orgguide.texi @@ -244,10 +244,11 @@ Miscellaneous @node Preface, Installation, Introduction, Introduction @section Preface -Org is a mode for keeping notes, maintaining TODO lists, and doing -project planning with a fast and effective plain-text system. +Org is a mode for keeping notes, maintaining TODO lists, and doing project +planning with a fast and effective plain-text system. It is also an +authoring and publishing system. -@i{This document is an extract from the +@i{This document is a much compressed derivative of the @uref{http://orgmode.org/index.html#sec-4_1, comprehensive Org-mode manual}. It contains all basic features and commands, along with important hints for customization. It is intended for beginners who would shy back from a 200 @@ -262,8 +263,8 @@ to @ref{Activation}.} If you have downloaded Org from the Web, either as a distribution @file{.zip} or @file{.tar} file, or as a Git archive, it is best to run it directly from -the distribution directory. You need to add @file{lisp} subdirectory to the -Emacs load path. To do this, add the following line to @file{.emacs}: +the distribution directory. You need to add the @file{lisp} subdirectories +to the Emacs load path. To do this, add the following line to @file{.emacs}: @smallexample (setq load-path (cons "~/path/to/orgdir/lisp" load-path)) @@ -284,20 +285,17 @@ when Org-mode starts. (require 'org-install) @end smalllisp -Do not forget to activate Org as described in the following section. - @node Activation, Feedback, Installation, Introduction @section Activation Add the following lines to your @file{.emacs} file. The last three lines -define @emph{global} keys for the commands @command{org-store-link}, -@command{org-agenda}, and @command{org-iswitchb}---please choose suitable -keys yourself. +define @emph{global} keys for some commands --- please choose suitable keys +yourself. @smalllisp ;; The following lines are always needed. Choose your own keys. (add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode)) -(global-font-lock-mode 1) ; for all buffers +(add-hook 'org-mode-hook 'turn-on-font-lock) ; not needed when global-font-lock-mode is on (global-set-key "\C-cl" 'org-store-link) (global-set-key "\C-ca" 'org-agenda) (global-set-key "\C-cb" 'org-iswitchb) @@ -311,9 +309,7 @@ into Org mode. If you find problems with Org, or if you have questions, remarks, or ideas about it, please mail to the Org mailing list @email{emacs-orgmode@@gnu.org}. -If you are not a member of the mailing list, your mail will be passed to the -list after a moderator has approved it. For information on how to submit bug -reports, see the main manual. +For information on how to submit bug reports, see the main manual. @node Document Structure, Tables, Introduction, Top @chapter Document Structure @@ -2518,7 +2514,7 @@ Org supports in-buffer completion with @kbd{M-@key{TAB}}. This type of completion does not make use of the minibuffer. You simply type a few letters into the buffer and use the key to complete text right there. For example, this command will complete @TeX{} symbols after @samp{\}, TODO -keywords at the beginning of a headline, and ags after @samp{:} in a +keywords at the beginning of a headline, and tags after @samp{:} in a headline. @node Clean view, MobileOrg, Completion, Miscellaneous From 57afeb8585dd0462c590bcf0c90b460ef2a85ccf Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Sat, 1 May 2010 21:40:44 +0200 Subject: [PATCH 27/34] Revert org.texi back to the state before I mistakenly merged the babel branch --- doc/org.texi | 1232 +------------------------------------------------- 1 file changed, 3 insertions(+), 1229 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 781cc761c..4fe4daa91 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -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: -#+begin_src
- -#+end_src -@end example - -@table @code -@item -An optional name for the block (see @ref{Evaluating Code Blocks}) -@item -The language of the code in the block. -@item -Optional links FIXME link/relocate switches discussion in @ref{Literal examples} -@item
-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 -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{-mode} exists, where -@code{} 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 - =<>=. - - This behavior is illustrated in the following example. Because - the =<>= noweb reference appears behind the SQL - comment syntax, each line of the expanded noweb reference will - be commented. - - This source code block: - - @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: - : <> - - 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 =<>= 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]]. - -@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 From 7389ecea0348d32063723647dfd1fb80f0e848f8 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Sat, 1 May 2010 21:57:50 +0200 Subject: [PATCH 28/34] Fix permissions --- lisp/ChangeLog | 0 lisp/org-clock.el | 0 2 files changed, 0 insertions(+), 0 deletions(-) mode change 100755 => 100644 lisp/ChangeLog mode change 100755 => 100644 lisp/org-clock.el diff --git a/lisp/ChangeLog b/lisp/ChangeLog old mode 100755 new mode 100644 diff --git a/lisp/org-clock.el b/lisp/org-clock.el old mode 100755 new mode 100644 From 65a98e3282b01f498d7a4c18cf01eb9cc2afea9a Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 2 May 2010 00:41:53 -0400 Subject: [PATCH 29/34] babel: fix editing error in org-babel-octave.el --- contrib/babel/lisp/langs/org-babel-octave.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contrib/babel/lisp/langs/org-babel-octave.el b/contrib/babel/lisp/langs/org-babel-octave.el index f20492ada..d7bd911fe 100644 --- a/contrib/babel/lisp/langs/org-babel-octave.el +++ b/contrib/babel/lisp/langs/org-babel-octave.el @@ -41,7 +41,7 @@ (defvar org-babel-octave-shell-command "octave -q" "Shell command to use to run octave as an external process.") -(defun org-babel-expand-body:octave (org-babel-process-params params) +(defun org-babel-expand-body:octave (body params &optional processed-params) (let ((vars (second (or processed-params (org-babel-process-params params))))) (concat ;; prepend code to define all arguments passed to the code block From b1f1cdda408a5f2c63c5a3e681166980a8f235d1 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 2 May 2010 00:57:30 -0400 Subject: [PATCH 30/34] Correct free variable error in org-src.el --- lisp/ChangeLog | 5 +++++ lisp/org-src.el | 2 +- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/lisp/ChangeLog b/lisp/ChangeLog index aa8d0232f..7f1a5071f 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,8 @@ +2010-05-02 Dan Davison + + * org-src.el (org-edit-src-code): allow-write-back-p had + erroneously been omitted from let binding + 2010-04-30 Carsten Dominik * org-agenda.el (org-sorting-choice): New sorting type alpha. diff --git a/lisp/org-src.el b/lisp/org-src.el index 529413846..e3560df19 100644 --- a/lisp/org-src.el +++ b/lisp/org-src.el @@ -205,12 +205,12 @@ the edited version. Optional argument CONTEXT is used by (beg (make-marker)) (end (make-marker)) (preserve-indentation org-src-preserve-indentation) + (allow-write-back-p (null code)) block-nindent total-nindent ovl lang lang-f single lfmt begline buffer msg) (if (not info) nil (setq beg (move-marker beg (nth 0 info)) end (move-marker end (nth 1 info)) - allow-write-back-p (null code) msg (if allow-write-back-p (substitute-command-keys "Edit, then exit with C-c ' (C-c and single quote)") From d2b9343029f71ef329ac71863627d9b2b5afb89e Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 2 May 2010 18:25:41 -0400 Subject: [PATCH 31/34] babel: Avoid trouble with '%' in matlab/octave output Patch by Christopher Long --- contrib/babel/lisp/langs/org-babel-octave.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contrib/babel/lisp/langs/org-babel-octave.el b/contrib/babel/lisp/langs/org-babel-octave.el index d7bd911fe..a59f86c15 100644 --- a/contrib/babel/lisp/langs/org-babel-octave.el +++ b/contrib/babel/lisp/langs/org-babel-octave.el @@ -113,7 +113,7 @@ then create. Return the initialized session." "%s if ischar(ans) fid = fopen('%s', 'w') - fprintf(fid, ans) + fprintf(fid, '%%s', ans) fprintf(fid, '\\n') fclose(fid) else From c133dd394ed70bb347d11c30d60e7904e2704797 Mon Sep 17 00:00:00 2001 From: Benjamin Andresen Date: Sun, 2 May 2010 21:30:13 -0400 Subject: [PATCH 32/34] babel: Fix org-babel-screen after expand changes --- contrib/babel/lisp/langs/org-babel-screen.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contrib/babel/lisp/langs/org-babel-screen.el b/contrib/babel/lisp/langs/org-babel-screen.el index 98b9d011a..d4b5c4c56 100644 --- a/contrib/babel/lisp/langs/org-babel-screen.el +++ b/contrib/babel/lisp/langs/org-babel-screen.el @@ -62,7 +62,7 @@ In case you want to use a different screen than one selected by your $PATH") (socket (org-babel-screen-session-socketname session))) (unless socket (org-babel-prep-session:screen session params)) (org-babel-screen-session-execute-string - session (org-babel-expand-body:screen body))))) + session (org-babel-expand-body:screen body params))))) (defun org-babel-prep-session:screen (session params) "Prepare SESSION according to the header arguments specified in PARAMS." From 245d98786d1bc6b49b6b7bb622b591076b19767c Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Mon, 3 May 2010 21:43:23 -0400 Subject: [PATCH 33/34] babel: matlab: detect end of evaluation under Emacs Link Currently, this uses the presence of a temporary file to signal that Matlab Emacs Link evaluation is not yet complete. Emacs Link support added in collaboration with Christopher Long. --- contrib/babel/lisp/langs/org-babel-matlab.el | 8 ++++++++ contrib/babel/lisp/langs/org-babel-octave.el | 15 ++++++++++++--- 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/contrib/babel/lisp/langs/org-babel-matlab.el b/contrib/babel/lisp/langs/org-babel-matlab.el index 4809b56f3..b54f571f3 100644 --- a/contrib/babel/lisp/langs/org-babel-matlab.el +++ b/contrib/babel/lisp/langs/org-babel-matlab.el @@ -55,6 +55,14 @@ evaluation. This will use EmacsLink if (matlab-with-emacs-link) evaluates to a non-nil value.") +(defvar org-babel-matlab-emacs-link-wrapper-method + "%s +if ischar(ans), fid = fopen('%s', 'w'); fprintf(fid, '%%s\\n', ans); fclose(fid); +else, save -ascii %s ans +end +delete('%s') +") + (defun org-babel-execute:matlab (body params) "Execute a block of matlab code with org-babel." (org-babel-execute:octave body params 'matlab)) diff --git a/contrib/babel/lisp/langs/org-babel-octave.el b/contrib/babel/lisp/langs/org-babel-octave.el index a59f86c15..3267a56dc 100644 --- a/contrib/babel/lisp/langs/org-babel-octave.el +++ b/contrib/babel/lisp/langs/org-babel-octave.el @@ -155,6 +155,7 @@ value of the last statement in BODY, as elisp." (defun org-babel-octave-evaluate-session (session body result-type &optional matlabp) (let* ((tmp-file (make-temp-file "org-babel-results-")) + (wait-file (make-temp-file "org-babel-matlab-emacs-link-wait-signal-")) (full-body (case result-type (output @@ -162,14 +163,22 @@ value of the last statement in BODY, as elisp." #'org-babel-chomp (list body org-babel-octave-eoe-indicator) "\n")) (value - (mapconcat - #'org-babel-chomp - (list (format org-babel-octave-wrapper-method body tmp-file tmp-file) org-babel-octave-eoe-indicator) "\n")))) + (if (and matlabp org-babel-matlab-with-emacs-link) + (concat + (format org-babel-matlab-emacs-link-wrapper-method + body tmp-file tmp-file wait-file) "\n") + (mapconcat + #'org-babel-chomp + (list (format org-babel-octave-wrapper-method body tmp-file tmp-file) + org-babel-octave-eoe-indicator) "\n"))))) (raw (if (and matlabp org-babel-matlab-with-emacs-link) (save-window-excursion (with-temp-buffer (insert full-body) + (write-region "" 'ignored wait-file nil nil nil 'excl) (matlab-shell-run-region (point-min) (point-max)) + (message "Waiting for Matlab Emacs Link") + (while (file-exists-p wait-file) (sit-for 0.01)) "")) ;; matlab-shell-run-region doesn't seem to ;; make *matlab* buffer contents easily ;; available, so :results output currently From 2d1025298e31889655dc2507b52d53aa8be87a7a Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Mon, 3 May 2010 21:43:42 -0400 Subject: [PATCH 34/34] babel: More concise matlab/octave code template Patch by Christopher Long --- contrib/babel/lisp/langs/org-babel-octave.el | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/contrib/babel/lisp/langs/org-babel-octave.el b/contrib/babel/lisp/langs/org-babel-octave.el index 3267a56dc..41a5be65c 100644 --- a/contrib/babel/lisp/langs/org-babel-octave.el +++ b/contrib/babel/lisp/langs/org-babel-octave.el @@ -111,13 +111,8 @@ then create. Return the initialized session." (defvar org-babel-octave-wrapper-method "%s -if ischar(ans) - fid = fopen('%s', 'w') - fprintf(fid, '%%s', ans) - fprintf(fid, '\\n') - fclose(fid) -else - save -ascii %s ans +if ischar(ans), fid = fopen('%s', 'w'); fprintf(fid, '%%s\\n', ans); fclose(fid); +else, save -ascii %s ans end") (defvar org-babel-octave-eoe-indicator "\'org_babel_eoe\'")