branch: externals-release/org
commit 83fe95d2ee035dac883e9e31cd6b1caa0f703b56
Author: Ihor Radchenko <yanta...@posteo.net>
Commit: Ihor Radchenko <yanta...@posteo.net>
org-babel-insert-result: Improve docstring
* lisp/ob-core.el (org-babel-insert-result): Explain that
RESULT-PARAMS is a list. Clarify the treatment of INFO. Fix
incorrect :file parameters that is actually not used. Instead,
document :file-desc parameter that is being used.
Reported-by: Stefan Kangas <stefankan...@gmail.com>
Link: https://orgmode.org/list/871q4fzx0k.fsf@localhost
---
lisp/ob-core.el | 20 +++++++++++---------
1 file changed, 11 insertions(+), 9 deletions(-)
diff --git a/lisp/ob-core.el b/lisp/ob-core.el
index 727ace8446..0878c27a14 100644
--- a/lisp/ob-core.el
+++ b/lisp/ob-core.el
@@ -2453,8 +2453,8 @@ the inline source block. The macro is stripped upon
export.
Multiline and non-scalar RESULTS from inline source blocks are
not allowed. When EXEC-TIME is provided it may be included in a
generated message. With optional argument RESULT-PARAMS controls
-insertion of results in the Org mode file. RESULT-PARAMS can
-take the following values:
+insertion of results in the Org mode file. RESULT-PARAMS is a list
+that can contain the following values:
replace - (default option) insert results after the source block
or inline source block replacing any previously
@@ -2513,15 +2513,17 @@ list ---- the results are rendered as a list. This
option not
table --- the results are rendered as a table. This option not
allowed for inline source blocks.
-INFO may provide the values of these header arguments (in the
-`header-arguments-alist' see the docstring for
-`org-babel-get-src-block-info'):
+INFO is the src block info, as returned by
+`org-babel-get-src-block-info' (which see). Some values from its
+PARAMETERS part (header argument alist) can affect the inserted
+result:
-:file --- the name of the file to which output should be written.
+:file-desc - when RESULT-PARAMS contains \"file\", use it as
+ description of the inserted link.
-:wrap --- the effect is similar to `latex' in RESULT-PARAMS but
- using the argument supplied to specify the export block
- or snippet type."
+:wrap the effect is similar to `latex' in RESULT-PARAMS but
+ using the argument supplied to specify the export block
+ or snippet type."
(cond ((stringp result)
(setq result (substring-no-properties result))
(when (member "file" result-params)
