mirror/org-mode
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs/org-mode.git synced 2024-11-23 07:18:53 +00:00
Code

babel: update the manual wrt :cache header arg

Browse Source 
* doc/org.texi (cache): Update manual section.
This commit is contained in:
Aaron Ecay 2015-11-04 11:57:49 +00:00
parent 02c7850147
commit e47c7c3ed6
1 changed files with 30 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
doc/org.texi
View File

@ -16166,11 +16166,36 @@ used.
The @code{:cache} header argument controls the use of in-buffer caching of
the results of evaluating code blocks. It can be used to avoid re-evaluating
unchanged code blocks. Note that the @code{:cache} header argument will not
attempt to cache results when the @code{:session} header argument is used,
because the results of the code block execution may be stored in the session
outside of the Org mode buffer. The @code{:cache} header argument can have
one of two values: @code{yes} or @code{no}.
unchanged code blocks. When the cache is active, a source block is not
re-evaluated if a result for it is present in the buffer and neither the
header arguments (including the value of @code{:var} references) nor the text
of the block itself has changed since the result was computed. The feature
helps avoid re-running long calculations. However, there are edge cases and
you should not rely on the cache to behave reliably in all circumstances.
The caching feature works best when a babel block is a pure function of its
arguments (@pxref{var}). That is, the function always returns the same
results when given the same arguments, and does not touch external resources
(like the filesystem or the language’s RNG) in any way.@footnote{The
documentation of the knitr reproducible research package for the R language
has some good discussion of issues that may arise when using the cache in
such a context. See @uref{http://yihui.name/knitr/demo/cache/}, especially
the sections ``Even more stuff for cache?'' and ``Reproducibility with RNG''.
(Obviously, you will have to abstract away from the knitr implementation
details which the documentation also discusses.)}
Note that the @code{:cache} header argument will attempt to cache results
when the @code{:session} header argument is used, even though the results of
the code block execution stored in the session may lead to unexpected
results.
Noweb references (@pxref{Noweb reference syntax}) are currently not expanded
when calculating whether the text of the code block has changed. Perhaps in
principle they ought to be, but this could introduce unexpected complexity.
See @uref{http://thread.gmane.org/gmane.emacs.orgmode/79046}.
The @code{:cache} header argument can have one of two values: @code{yes} or
@code{no}.
@itemize @bullet
@item @code{no}