emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Ihor Radchenko <yantar92@posteo.net>
To: alain.cochard@unistra.fr
Cc: Org Mode List <emacs-orgmode@gnu.org>
Subject: Re: 2 'echo' bash instructions produce a table
Date: Tue, 22 Nov 2022 08:16:31 +0000	[thread overview]
Message-ID: <87wn7nieu8.fsf@localhost> (raw)
In-Reply-To: <25461.4423.734070.149776@gargle.gargle.HOWL>

[-- Attachment #1: Type: text/plain, Size: 1885 bytes --]

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.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-manual-Clarify-auto-detection-of-code-block-resu.patch --]
[-- Type: text/x-patch, Size: 2629 bytes --]

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: 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


[-- Attachment #3: Type: text/plain, Size: 225 bytes --]



-- 
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>

  parent reply	other threads:[~2022-11-22  8:17 UTC|newest]

Thread overview: 22+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-11-06  6:58 2 'echo' bash instructions produce a table Alain.Cochard
2022-11-07  2:31 ` Ihor Radchenko
2022-11-13 20:41   ` Alain.Cochard
2022-11-14  3:59     ` Ihor Radchenko
2022-11-15  6:00       ` [RFC] :var x=list-name should be resolved into simple lists (item1 item2 ...); not nested ((item1) (item2) ...) (was: 2 'echo' bash instructions produce a table) Ihor Radchenko
2022-11-26  1:54         ` Ihor Radchenko
2022-11-16  1:24       ` 2 'echo' bash instructions produce a table Ihor Radchenko
2022-11-21  9:04         ` Ihor Radchenko
2022-11-21  9:05         ` Ihor Radchenko
2022-11-16 16:35       ` Alain.Cochard
2022-11-19 12:28         ` Rudolf Adamkovič
2022-11-20  5:05           ` Ihor Radchenko
2022-11-22  8:16         ` Ihor Radchenko [this message]
2022-11-22 19:13           ` Alain.Cochard
2022-11-24  1:55             ` Ihor Radchenko
2022-11-22  8:31         ` [RFC] Backend vs. back-end (was: 2 'echo' bash instructions produce a table) Ihor Radchenko
2023-02-20 10:07           ` Ihor Radchenko
2023-02-20 14:54             ` Alain.Cochard
2023-04-06  9:57               ` Ihor Radchenko
2023-04-20 12:17                 ` Ihor Radchenko
2023-04-06 23:43           ` Samuel Wales
2022-11-22  8:37         ` [BUG] Make source block auto-completion work for all the loaded babel backends " Ihor Radchenko

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87wn7nieu8.fsf@localhost \
    --to=yantar92@posteo.net \
    --cc=alain.cochard@unistra.fr \
    --cc=emacs-orgmode@gnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).