summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAchim Gratz <Stromeko@Stromeko.DE>2013-06-23 15:29:00 (GMT)
committer Achim Gratz <Stromeko@Stromeko.DE>2013-06-23 17:35:13 (GMT)
commit8cbbbe16a516ee4e9614f30972b6f6c7c14126a6 (patch)
treeaf4dcdf785238c5631585718684d6fd93c9f2e24
parent90b168705eea60767403344f9da2ca26d429dd30 (diff)
downloadorg-mode-8cbbbe16a516ee4e9614f30972b6f6c7c14126a6.zip
org-mode-8cbbbe16a516ee4e9614f30972b6f6c7c14126a6.tar.gz
org.texi: document header-args[:lang] properties
* doc/org.texi: Document header-args[:lang] properties and remove deprecated old-style properties from documentation.
-rw-r--r--doc/org.texi95
1 files changed, 61 insertions, 34 deletions
diff --git a/doc/org.texi b/doc/org.texi
index 2349778..6053bea 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -688,8 +688,8 @@ Using header arguments
* System-wide header arguments:: Set global default values
* Language-specific header arguments:: Set default values by language
-* Buffer-wide header arguments:: Set default values for a specific buffer
* Header arguments in Org mode properties:: Set default values for a buffer or heading
+* Language-specific header arguments in Org mode properties:: Set langugage-specific default values for a buffer or heading
* Code block specific header arguments:: The most common way to set values
* Header arguments in function calls:: The most specific level
@@ -13965,13 +13965,16 @@ describes each header argument in detail.
@node Using header arguments, Specific header arguments, Header arguments, Header arguments
@subsection Using header arguments
-The values of header arguments can be set in six different ways, each more
-specific (and having higher priority) than the last.
+The values of header arguments can be set in several way. When the header
+arguments in each layer have been determined, they are combined in order from
+the first, least specific (having the lowest priority) up to the last, most
+specific (having the highest priority). A header argument with a higher
+priority replaces the same header argument specified at lower priority.
@menu
* System-wide header arguments:: Set global default values
* Language-specific header arguments:: Set default values by language
-* Buffer-wide header arguments:: Set default values for a specific buffer
* Header arguments in Org mode properties:: Set default values for a buffer or heading
+* Language-specific header arguments in Org mode properties:: Set language-specific default values for a buffer or heading
* Code block specific header arguments:: The most common way to set values
* Header arguments in function calls:: The most specific level
@end menu
@@ -14002,61 +14005,85 @@ blocks.
(assq-delete-all :noweb org-babel-default-header-args)))
@end lisp
-@node Language-specific header arguments, Buffer-wide header arguments, System-wide header arguments, Using header arguments
+@node Language-specific header arguments, Header arguments in Org mode properties, System-wide header arguments, Using header arguments
@subsubheading Language-specific header arguments
-Each language can define its own set of default header arguments. See the
-language-specific documentation available online at
+Each language can define its own set of default header arguments in variable
+@code{org-babel-default-header-args:<lang>}, where @code{<lang>} is the name
+of the language. See the language-specific documentation available online at
@uref{http://orgmode.org/worg/org-contrib/babel}.
-@node Buffer-wide header arguments, Header arguments in Org mode properties, Language-specific header arguments, Using header arguments
-@subsubheading Buffer-wide header arguments
+@node Header arguments in Org mode properties, Language-specific header arguments in Org mode properties, Language-specific header arguments, Using header arguments
+@subsubheading Header arguments in Org mode properties
+
Buffer-wide header arguments may be specified as properties through the use
of @code{#+PROPERTY:} lines placed anywhere in an Org mode file (see
@ref{Property syntax}).
-For example the following would set @code{session} to @code{*R*}, and
-@code{results} to @code{silent} for every code block in the buffer, ensuring
-that all execution took place in the same session, and no results would be
-inserted into the buffer.
+For example the following would set @code{session} to @code{*R*} (only for R
+code blocks), and @code{results} to @code{silent} for every code block in the
+buffer, ensuring that all execution took place in the same session, and no
+results would be inserted into the buffer.
@example
-#+PROPERTY: session *R*
-#+PROPERTY: results silent
-@end example
-
-@node Header arguments in Org mode properties, Code block specific header arguments, Buffer-wide header arguments, Using header arguments
-@subsubheading Header arguments in Org mode properties
-
-Header arguments are also read from Org mode properties (see @ref{Property
-syntax}), which can be set on a buffer-wide or per-heading basis. An example
-of setting a header argument for all code blocks in a buffer is
-
-@example
-#+PROPERTY: tangle yes
+#+PROPERTY: header-args:R :session *R*
+#+PROPERTY: header-args :results silent
@end example
+Header arguments read from Org mode properties can also be set on a
+per-subtree basis using property drawers (see @ref{Property syntax}).
@vindex org-use-property-inheritance
-When properties are used to set default header arguments, they are looked up
-with inheritance, regardless of the value of
-@code{org-use-property-inheritance}. In the following example the value of
+When properties are used to set default header arguments, they are always
+looked up with inheritance, regardless of the value of
+@code{org-use-property-inheritance}. Properties are evaluated as seen by the
+outermost call or source block.@footnote{The deprecated syntax for default
+header argument properties, using the name of the header argument as a
+property name directly, evaluates the property as seen by the corresponding
+source block definition. This behaviour has been kept for backwards
+compatibility.}
+
+In the following example the value of
the @code{:cache} header argument will default to @code{yes} in all code
blocks in the subtree rooted at the following heading:
@example
* outline header
:PROPERTIES:
- :cache: yes
+ :header-args: :cache yes
:END:
@end example
@kindex C-c C-x p
@vindex org-babel-default-header-args
Properties defined in this way override the properties set in
-@code{org-babel-default-header-args}. It is convenient to use the
-@code{org-set-property} function bound to @kbd{C-c C-x p} to set properties
-in Org mode documents.
+@code{org-babel-default-header-args} and are applied for all activated
+languages. It is convenient to use the @code{org-set-property} function
+bound to @kbd{C-c C-x p} to set properties in Org mode documents.
+
+@node Language-specific header arguments in Org mode properties, Code block specific header arguments, Header arguments in Org mode properties, Using header arguments
+@subsubheading Language-specific header arguments in Org mode properties
+
+Language-specific header arguments are also read from properties
+@code{header-args:<lang>} where @code{<lang>} is the name of the language
+targeted. As an example
+
+@example
+* Heading
+ :PROPERTIES:
+ :header-args:clojure: :session *clojure-1*
+ :header-args:R: :session *R*
+ :END:
+** Subheading
+ :PROPERTIES:
+ :header-args:clojure: :session *clojure-2*
+ :END:
+@end example
+
+would independently set a default session header argument for R and clojure
+for calls and source blocks under subtree ``Heading'' and change to a
+different clojure setting for evaluations under subtree ``Subheading'', while
+the R session is inherited from ``Heading'' and therefore unchanged.
-@node Code block specific header arguments, Header arguments in function calls, Header arguments in Org mode properties, Using header arguments
+@node Code block specific header arguments, Header arguments in function calls, Language-specific header arguments in Org mode properties, Using header arguments
@subsubheading Code block specific header arguments
The most common way to assign values to header arguments is at the