Hello,
Aaron Ecay <aarone...@gmail.com> writes:
> See the attached patch. I’ve tried to put all my experience and best
> practices in there; comments are welcome of course.
Thank you. It looks good. Some comments follow.
> +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 (see @ref{var}). That is, the function always returns the
> same
(see @ref{var}) => (@pxref{var})
> +results when given the same arguments, and does not touch external resources
> +(like the filesystem or the language’s RNG) in any way.
> +
> +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”.
Shouldn't this be : ``Even more stuff for cache?''. Ditto for the other
title.
> (Obviously, you will have to abstract away from the knitr
> +implementation details which the documentation also discusses.)
I think this last paragraph could go in a footnote at the end of the
paragraph before it.
> +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 (see @ref{Noweb reference syntax}) are currently not
(see @ref{Noweb reference syntax}) => (@pxref{Noweb reference syntax})
> +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}.
Regards,
--
Nicolas Goaziou
