mirrors/org-mode
0
0
Fork 1
mirror of https://git.savannah.gnu.org/git/emacs/org-mode.git synced 2024-08-25 14:02:51 +00:00
Code Releases Activity

o-b-worg.org: Move source-block syntax section into main body of document, etc

Browse source
This commit is contained in:
Dan Davison 2009-09-04 22:57:25 -04:00
parent a94ae463e7
commit 0c8c3a5f59
1 changed files with 34 additions and 49 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

83
org-babel-worg.org
View file

@ -164,26 +164,32 @@ matrix(rnorm(6), nrow=2)
#+resname:
[[file:images/blue.png]]
*** Additional source block syntax
Org-babel adds some new syntactical elements to source blocks in
org-mode, illustrated here:
*** Source code block syntax
: #+srcname: source-block-name(arg1=value1, arg2=value2)
: #+begin_src language :var1 var1-value :var2 var2-value ...
:
: <code goes here>
:
The basic syntax of source-code blocks in Org-babel is as follows:
: #+srcname: name(arguments)
: #+begin_src language header-arguments
: body
: #+end_src
Note the following two new features
**** =srcname= with optional arguments
The optional =srcname= line allows a name to be given to the
source block, together with any arguments to the source block
(see [[#arguments-to-source-code-blocks][below]])
**** Header arguments
An arbitrary series of :variable value pairs can be specified
after the language, controlling various aspects of org-babel
operation. The available header arguments are documented [[#header-arguments][below.]]
- name :: This name is associated with the source-code block. This is
similar to the =#+TBLNAME= lines which can be used to name tables
in org-mode files. By referencing the srcname of a source-code
block it is possible to evaluate the block from other places,
files, or from inside tables.
- arguments :: Code blocks can have arguments (see [[#arguments-to-source-code-blocks][below]]) which are
provided using a familiar function-call syntax similar
to (e.g.) python or R.
- 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 actual source code which will be evaluated. This can be
edited with `org-edit-special'.
*** What happens to the results?
:PROPERTIES:
:CUSTOM_ID: results
@ -468,8 +474,8 @@ generated the figures.
[[http://reproducibleresearch.net/index.php/Main_Page][Reproducible Research]] (RR) is the practice of distributing along with
an article of research all data, code, and tools required to reproduce
the results discussed in the paper. As such the paper becomes not
only a document describing the research but a complete laboratory
reproducing the research.
only a document describing the research but a complete laboratory in
which the research can be reproduced and extended.
Org-mode already has exceptional support for [[http://orgmode.org/manual/Exporting.html#Exporting][exporting to html and
LaTeX]]. Org-babel makes Org-mode a tool for RR by *activating* the
@ -478,12 +484,14 @@ entire document executable. This makes it not only possible, but
natural to distribute research in a format that encourages readers to
recreate your results, and perform their own analysis.
Existing RR tools like [[http://en.wikipedia.org/wiki/Sweave][Sweave]] provide for the embedding of [[http://www.r-project.org/][R]] code into
LaTeX documents. While this is very useful, such documents often
still require a large degree of "glue code" in the form of external
shell scripts, python scripts, and Makefiles. To our knowledge
Org-babel is the only RR tool which allows multiple languages and data
to coexist and cooperate inside of a single document.
One notable existing RR tool is [[http://en.wikipedia.org/wiki/Sweave][Sweave]] which provides for the
embedding of [[http://www.r-project.org/][R]] code into LaTeX documents. While Sweave is a mature
and very useful tool, we believe that Org-babel has several
advantages:
- It supports multiple languages (we're not aware of other RR tools that do this)
- The [[http://orgmode.org/manual/Exporting.html#Exporting][export process]] is flexible and powerful, including HTML as a target in addition to LaTeX
- The document can make native use of all the features of Org-mode,
such as those for [[http://orgmode.org/manual/Agenda-Views.html#Agenda-Views][project planning]] and [[http://orgmode.org/manual/TODO-Items.html#TODO-Items][task management]]
* Literate programming
:PROPERTIES:
@ -694,29 +702,6 @@ For a simple example of usage follow these 4 steps.
;; (require 'org-babel-sql) ;; none
#+end_src
*** Source Code block syntax
The basic syntax of source-code blocks is as follows:
: #+srcname: name
: #+begin_src language header-arguments
: body
: #+end_src
- name :: This name is associated with the source-code block. This is
similar to the =#+TBLNAME= lines which can be used to name tables
in org-mode files. By referencing the srcname of a source-code
block it is possible to evaluate the block for other places,
files, or from inside tables.
- 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
input to, evaluation of, and output of source-code blocks. See
the [[* Header Arguments][Header Arguments]] section for a complete review of available
header arguments.
- body :: The actual source code which will be evaluated. This can be
edited with `org-edit-special'.
*** Header Arguments
:PROPERTIES:
:CUSTOM_ID: header-arguments