Re: 2 'echo' bash instructions produce a table

[Ihor Radchenko]

Alain.Cochard@unistra.fr writes:

>  > Will it help if we mention this fact in "16.6 Results of Evaluation"
>  > section?
>
> Yes, it would help me.  At least I would been warned.  But it would be
> complete only if knew where to read about each specific babel backend.
>
>  > > For the sake of newcomers, it seems to me that something along the
>  > > line of what you write above would fit somewhere in 16.6, with a first
>  > > short mention/warning (and reference to it) next to that excerpt in
>  > > 16.5:
>  > >
>  > >    Org captures the results of the code block evaluation and inserts
>  > >    them in the Org file, right after the code block.
>
>  > Talking about ob-shell does not belong to this section of the
>  > manual.  Other backends have different behaviour. Have you seen
>  > examples in
>  > https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-shell.html
>  > ?  Are they not clear enough?
>
> No, I had not seen this before.  If I had, I might have understood why
> I was getting the "strange" output that originated this thread -- but
> I do not find it explained as clearly as you explained it:
>
>    "In the case of two commands returning output, the guess is
>     yielding the table. In the case of a single command, the guess is
>     yielding a single string output."
>
> I can now see that the ob-doc-shell.html page is (indirectly) referred
> to in 16.9, via
> https://orgmode.org/worg/org-contrib/babel/languages/index.html.
> Maybe this is enough for some, but for me it is too convoluted.  I had
> seen this page, but it was a long time ago, when I checked whether the
> languages I use were supported or not.  So why not also refer to it in
> 16.6, together with the mentioned fact to which you are referring
> above?

See the attached patch with tentative changes to the manual.
Let me know if you think that things are still not clear.

>From 015dcb2837089fed8040553d35757818013d991f Mon Sep 17 00:00:00 2001
Message-Id: 
<015dcb2837089fed8040553d35757818013d991f.1669104972.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Tue, 22 Nov 2022 16:13:31 +0800
Subject: [PATCH] org-manual: Clarify auto-detection of code block result type

* doc/org-manual.org (How to evaluate source code): Link to Results of
evaluation section for details about the inserted code block result.
(Type): Clarify that auto-detecting result type relies on specific
language backend, linking to the relevant manual section.
(Languages): Clarify that Worg is a website.

Reported-by: Alain.Cochard@unistra.fr
Link: 25461.4423.734070.149776@gargle.gargle.HOWL">https://orgmode.org/list/25461.4423.734070.149776@gargle.gargle.HOWL
---
 doc/org-manual.org | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 70d1c01a3..f395a0986 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -18002,7 +18002,8 @@ *** How to evaluate source code
 Org captures the results of the code block evaluation and inserts them
 in the Org file, right after the code block.  The insertion point is
 after a newline and the =RESULTS= keyword.  Org creates the =RESULTS=
-keyword if one is not already there.
+keyword if one is not already there.  More details in [[*Results of
+Evaluation]].
 
 By default, Org enables only Emacs Lisp code blocks for execution.
 See [[*Languages]] to enable other languages.
@@ -18257,8 +18258,11 @@ *** Type
 :END:
 
 Type tells what result types to expect from the execution of the code
-block.  Choose one of the options; they are mutually exclusive.  The
-default behavior is to automatically determine the result type.
+block.  Choose one of the options; they are mutually exclusive.
+
+The default behavior is to automatically determine the result type.
+The result type detection depends on the code block language, as
+described in the documentation for individual [[*Languages][languages]].
 
 #+attr_texinfo: :sep ,
 - =table=, =vector= ::
@@ -18865,8 +18869,8 @@ ** Languages
 #+cindex: source code, languages
 #+cindex: code block, languages
 
-Code blocks in dozens of languages are supported.  See Worg for
-[[https://orgmode.org/worg/org-contrib/babel/languages/index.html][language 
specific documentation]].
+Code blocks in dozens of languages are supported.  See Worg website
+for 
[[https://orgmode.org/worg/org-contrib/babel/languages/index.html][language 
specific documentation]].
 
 #+vindex: org-babel-load-languages
 By default, only Emacs Lisp is enabled for evaluation.  To enable or
-- 
2.35.1


-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>