clarify use of header arg page.
[worg.git] / org-contrib / babel / header-args.org
1 #+OPTIONS:    H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
5 #+TITLE:      Header arguments and result types in Org Babel
6 #+AUTHOR:     Thorsten Jolitz, Eric Schulte
7 #+EMAIL:      tj[at]data-driven[dot]de
8 #+LANGUAGE:   en
9 #+LINK_UP:    index.php
10 #+LINK_HOME:  http://orgmode.org/worg/
11 #+EXPORT_EXCLUDE_TAGS: noexport
12
13 For a complete header argument reference see the Org-mode manual's
14 page which lists all [[http://orgmode.org/manual/Specific-header-arguments.html][Specific-header-arguments]].  This page holds
15 ancillary notes and tricks which have not made it into the manual.
16
17 * Common combinations of header-args and result types
18    Many combinations of header arguments and result types are
19    supported by Org Babel. Individual languages may even define
20    special header args. Like always in combinatorics, the number
21    of possible combinations increases rapidly when there are several
22    factors with several levels each that can be freely combined.
23
24    The following table shows combinations of header arguments and
25    result types that might be considered reasonable for many
26    programming languages.
27
28     #+tblname: header-args-combinations
29     | evaluation | collection | type              |
30     | (:session) | (:results) | (:results)        |
31     |------------+------------+-------------------|
32     | external   | value      | table (vector)    |
33     |            |            | scalar (verbatim) |
34     |            |            | file              |
35     |            |            | raw (org)         |
36     |            |            | html              |
37     |            |            | latex             |
38     |            |            | code              |
39     |            |            | pp                |
40     |            | output     | table (vector)    |
41     |            |            | scalar (verbatim) |
42     |            |            | file              |
43     |            |            | raw (org)         |
44     |            |            | html              |
45     |            |            | latex             |
46     |            |            | code              |
47     |            |            | pp                |
48     | session    | value      | table (vector)    |
49     |            |            | scalar (verbatim) |
50     |            |            | file              |
51     |            |            | raw (org)         |
52     |            |            | html              |
53     |            |            | latex             |
54     |            |            | code              |
55     |            |            | pp                |
56     |            | output     | table (vector)    |
57     |            |            | scalar (verbatim) |
58     |            |            | file              |
59     |            |            | raw (org)         |
60     |            |            | html              |
61     |            |            | latex             |
62     |            |            | code              |
63     |            |            | pp                |
64
65      
66     More special header arguments and their possible values are
67     summarized in the next table:
68    
69     #+tblname: other-header-args
70     
71     | header-arg |          | values  |          |         |
72     |------------+----------+---------+----------+---------|
73     | :results   | silent   | replace | append   | prepend |
74     | (handling) |          |         |          |         |
75     | :exports   | code     | results | both     | none    |
76     | :comments  | yes      | (no?)   |          |         |
77     | :noweb     | no       | yes     |          |         |
78     | :tangle    | yes      | no      | filename |         |
79     | :no-expand |          |         |          |         |
80     | :file      |          |         |          |         |
81     | :dir       |          |         |          |         |
82     | :cache     | no       | yes     |          |         |
83     | :var       | x=y      |         |          |         |
84     | :hlines    | no       | yes     |          |         |
85     | :colnames  | nil      | no      | yes      |         |
86     | :rownames  | no       | yes     |          |         |
87     | :shebang   | "string" |         |          |         |
88     | :eval      | never    | query   |          |         |
89
90
91 * Setting language and file specific default header argument values
92 This may be useful to e.g., have all Python code blocks in a file use
93 the same session.  The following file-local-variable syntax should be
94 used, placing the customization at the end of the Org-mode file.
95
96 : #+Title: Example of default file and language session
97
98 : The value in this buffer is...
99 : #+begin_src emacs-lisp
100 :   org-babel-default-header-args:Python
101 : #+end_src
102
103 : #+RESULTS:
104 : | (:session . foo) |
105
106 : # Local Variables:
107 : # eval: (setq-local org-babel-default-header-args:Python '((:session . "foo")))
108 : # End: