2 'echo' bash instructions produce a table

2 'echo' bash instructions produce a table

[Alain.Cochard]

Hello.

I do

   emacs -Q -l ~/.emacs.git

with .emacs.git being

   (add-to-list 'load-path "~/Org/Coch-git/org-mode/lisp")
   (custom-set-variables
    '(org-babel-load-languages
      '(
	(shell . t))
      )
    '(debug-on-error t)
    )

   Org mode version 9.6-pre (release_9.5.5-1075-g3e010d @
   /home/cochard/Org/Coch-git/org-mode/lisp/)

Then I visit an Org file which contains only

   #+begin_src bash
   echo "foo"
   echo "bar"
   #+end_src

Typing 'C-c C-c' produces

   #+RESULTS:
   | foo |
   | bar |

By contrast, with only 'echo "foo"', it produces what I expect:

   #+RESULTS:
   : foo



-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 110]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

Re: 2 'echo' bash instructions produce a table

[Ihor Radchenko]

Alain.Cochard@unistra.fr writes:

>    #+begin_src bash
>    echo "foo"
>    echo "bar"
>    #+end_src
>
> Typing 'C-c C-c' produces
>
>    #+RESULTS:
>    | foo |
>    | bar |
>
> By contrast, with only 'echo "foo"', it produces what I expect:
>
>    #+RESULTS:
>    : foo

If you want to force string output, use :results output.

By default, ob-shell tries to guess the output type.
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.

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

Re: 2 'echo' bash instructions produce a table

[Alain.Cochard]

Ihor Radchenko writes on Mon  7 Nov 2022 02:31:

 > If you want to force string output, use :results output.
 > 
 > By default, ob-shell tries to guess the output type.  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.

Thanks a lot.

I find it strange, though, that the default is not as what one gets
from running the code from a terminal.  I imagine there are good
reasons for that, but I think this should be made clear (or at least
clearer) in the manual.  I browsed through section 16 of the manual,
with particular attention to 16.5 (Evaluating Code Blocks) and 16.6
(Results of Evaluation), but still cannot see where this is said or
hinted; if it is there, I missed it or do not know enough to
understand it.

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.

Regards.

PS1

In section 16.3 of the manual (Using Header Arguments):

   System-wide values of header arguments can be specified by
   customizing the ‘org-babel-default-header-args’ variable, which
   defaults to the following values:

	:session    => "none"
	:results    => "replace"
	:exports    => "code"
	:cache      => "no"
	:noweb      => "no"


but the docstring of 'org-babel-default-header-args' says:

   org-babel-default-header-args is a variable defined in ‘ob-core.el’.
   Its value is
   ((:session . "none")
    (:results . "replace")
    (:exports . "code")
    (:cache . "no")
    (:noweb . "no")
    (:hlines . "no")
    (:tangle . "no"))

so I was wondering if there should be

   :hlines      => "no"
   :tangle      => "no"

added above.

PS2

In section 16.6 (Results of Evaluation)
   
   [The ‘results’ header argument] accepts four classes of options
   [Collection, Type, Format, Handling]

   Each code block can take only one option per class:

Now, the paragraphs related to Collection, Type, & Format all contain
the statement

   "Choose one of the options; they are mutually exclusive".

I thought this statement was saying the same thing as the "only one
option per class" above, but then why not also repeat the statement in
the Handling paragraph?

PS3

In section 16.4 (Environment of a Code Block)

    A simple named list.

	 #+NAME: example-list
	 - simple
	   - not
	   - nested
	 - list

	 #+BEGIN_SRC emacs-lisp :var x=example-list
	   (print x)
	 #+END_SRC

	 #+RESULTS:
	 | simple | list |

But if I evaluate the code, I get

	 #+RESULTS:
	 | simple | (unordered (not) (nested)) |
	 | list   |                            |

PS4

In 16.5 (Evaluating Code Blocks), in this code

   #+NAME: random
   #+BEGIN_SRC R :cache yes
     runif(1)
   #+END_SRC

the (1) seems to be understood as a footnote in Info, at least for me.
E.g., <RET> on it goes to the footnote

   (1) The option ‘org-babel-no-eval-on-ctrl-c-ctrl-c’ [...]

and <RET> on this (1) goes back to the above code instead of to the
actual call

   "Org provides many ways to execute code blocks.  ‘C-c C-c’ or ‘C-c
   C-v e’ with the point on a code block(1)"

     
-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 110]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

Re: 2 'echo' bash instructions produce a table

[Ihor Radchenko]

Alain.Cochard@unistra.fr writes:

> Ihor Radchenko writes on Mon  7 Nov 2022 02:31:
>
>  > If you want to force string output, use :results output.
>  > 
>  > By default, ob-shell tries to guess the output type.  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.
>
> Thanks a lot.
>
> I find it strange, though, that the default is not as what one gets
> from running the code from a terminal.  I imagine there are good
> reasons for that, but I think this should be made clear (or at least
> clearer) in the manual.  I browsed through section 16 of the manual,
> with particular attention to 16.5 (Evaluating Code Blocks) and 16.6
> (Results of Evaluation), but still cannot see where this is said or
> hinted; if it is there, I missed it or do not know enough to
> understand it.

The manual describes generic code execution. If you do not explicitly
specify the :results header arg, it is the specific babel backend that
specifies the defaults.

Will it help if we mention this fact in "16.6 Results of Evaluation"
section?

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

> In section 16.3 of the manual (Using Header Arguments):
>
>    System-wide values of header arguments can be specified by
>    customizing the ‘org-babel-default-header-args’ variable, which
>    defaults to the following values:
>
> 	:session    => "none"
> 	:results    => "replace"
> 	:exports    => "code"
> 	:cache      => "no"
> 	:noweb      => "no"
>
>
> but the docstring of 'org-babel-default-header-args' says:
>
>    org-babel-default-header-args is a variable defined in ‘ob-core.el’.
>    Its value is
>    ((:session . "none")
>     (:results . "replace")
>     (:exports . "code")
>     (:cache . "no")
>     (:noweb . "no")
>     (:hlines . "no")
>     (:tangle . "no"))
>
> so I was wondering if there should be
>
>    :hlines      => "no"
>    :tangle      => "no"
>
> added above.

It will be fixed in the next release. The online and built-in Emacs
manual are only reflecting the current stable Org version.

> PS2
>
> In section 16.6 (Results of Evaluation)
>    
>    [The ‘results’ header argument] accepts four classes of options
>    [Collection, Type, Format, Handling]
>
>    Each code block can take only one option per class:
>
> Now, the paragraphs related to Collection, Type, & Format all contain
> the statement
>
>    "Choose one of the options; they are mutually exclusive".
>
> I thought this statement was saying the same thing as the "only one
> option per class" above, but then why not also repeat the statement in
> the Handling paragraph?

Makes sense.
Done on main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=4260f5a8d74c965fccf200aa71da0c6d338573c0

> PS3
>
> In section 16.4 (Environment of a Code Block)
>
>     A simple named list.
>
> 	 #+NAME: example-list
> 	 - simple
> 	   - not
> 	   - nested
> 	 - list
>
> 	 #+BEGIN_SRC emacs-lisp :var x=example-list
> 	   (print x)
> 	 #+END_SRC
>
> 	 #+RESULTS:
> 	 | simple | list |
>
> But if I evaluate the code, I get
>
> 	 #+RESULTS:
> 	 | simple | (unordered (not) (nested)) |
> 	 | list   |                            |

Confirmed. Need to look into this.

> PS4
>
> In 16.5 (Evaluating Code Blocks), in this code
>
>    #+NAME: random
>    #+BEGIN_SRC R :cache yes
>      runif(1)
>    #+END_SRC
>
> the (1) seems to be understood as a footnote in Info, at least for me.
> E.g., <RET> on it goes to the footnote
>
>    (1) The option ‘org-babel-no-eval-on-ctrl-c-ctrl-c’ [...]
>
> and <RET> on this (1) goes back to the above code instead of to the
> actual call
>
>    "Org provides many ways to execute code blocks.  ‘C-c C-c’ or ‘C-c
>    C-v e’ with the point on a code block(1)"

Confirmed, but it does not look like Org's fault.
Org correctly produces the following texinfo source:

@example
#+NAME: random
#+BEGIN_SRC R :cache yes
  runif(1)
#+END_SRC

#+RESULTS[a2a72cd647ad44515fab62e144796432793d68e1]: random
0.4659510825295

#+NAME: caller
#+BEGIN_SRC emacs-lisp :var x=random :cache yes
  x
#+END_SRC

#+RESULTS[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
0.254227238707244
@end example

As you can see, no @footnote command is there.

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

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

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

Ihor Radchenko <yantar92@posteo.net> writes:

>> In section 16.4 (Environment of a Code Block)
>>
>>     A simple named list.
>>
>> 	 #+NAME: example-list
>> 	 - simple
>> 	   - not
>> 	   - nested
>> 	 - list
>>
>> 	 #+BEGIN_SRC emacs-lisp :var x=example-list
>> 	   (print x)
>> 	 #+END_SRC
>>
>> 	 #+RESULTS:
>> 	 | simple | list |
>>
>> But if I evaluate the code, I get
>>
>> 	 #+RESULTS:
>> 	 | simple | (unordered (not) (nested)) |
>> 	 | list   |                            |
>
> Confirmed. Need to look into this.

The attached is a fix for this discrepancy with the manual.

However, it looks like at least ob-java already tried to work around the
erroneous return value of org-babel-read-list.

Hence, we at least need to announce this fix in ORG-NEWS.

Or maybe there are other objections?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ob-core-Resolve-named-list-references-to-simple-list.patch --]
[-- Type: text/x-patch, Size: 5924 bytes --]

From cc1dbc5ca61d04e8a52598feb031e24102575f0d Mon Sep 17 00:00:00 2001
Message-Id: <cc1dbc5ca61d04e8a52598feb031e24102575f0d.1668491919.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Tue, 15 Nov 2022 13:52:04 +0800
Subject: [PATCH] ob-core: Resolve named list references to simple lists

* lisp/ob-core.el (org-babel-read-list): Return a simple list instead
of list of lists.  Document this in the docstring.
* testing/lisp/test-ob-java.el (ob-java/read-return-list):
(ob-java/read-list-return-array):
(ob-java/read-return-list-with-package): Fix tests assuming previous
behavior.
* testing/lisp/test-ob.el (test-ob/simple-variable-resolution): Add
new tests.
* etc/ORG-NEWS (List references in source block variable assignments
are now proper lists): Document the change.

This commit fixes the broken promise in the manual section 16.4
Environment of a Code Block where the named references to lists should
be converted to simple lists consisting of the top-level items.

The inconsistency existed for a while and possibly lurked into some
third-party packages.  So, announcement in NEWS is required.

Reported-by: Alain.Cochard@unistra.fr
Link: https://orgmode.org/list/87pmdqfao4.fsf@localhost
---
 etc/ORG-NEWS                 | 34 ++++++++++++++++++++++++++++++++++
 lisp/ob-core.el              | 11 +++++++++--
 testing/lisp/test-ob-java.el | 10 +++++-----
 testing/lisp/test-ob.el      | 26 +++++++++++++++++++++++---
 4 files changed, 71 insertions(+), 10 deletions(-)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 04b5be64a..4e23ac0e3 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -701,6 +701,40 @@ If you prefer to keep the keybinding, you can add it back to
 (define-key org-mode-map (kbd "C-c SPC") #'org-table-blank-field)
 #+end_src
 
+*** List references in source block variable assignments are now proper lists
+
+List representation of named lists is now converted to a simple list
+as promised by the manual section [[info:org#Environment of a Code Block][org#Environment of a Code Block]].
+Previously, it was converted to a list of lists.
+
+Before:
+
+#+begin_src org
+,#+NAME: example-list
+- simple
+  - not
+  - nested
+- list
+
+,#+BEGIN_SRC emacs-lisp :var x=example-list :results value
+(format "%S" x)
+,#+END_SRC
+
+,#+RESULTS:
+: (("simple" (unordered ("not") ("nested"))) ("list"))
+#+end_src
+
+After:
+
+#+begin_src org
+,#+BEGIN_SRC emacs-lisp :var x=example-list :results value
+(format "%S" x)
+,#+END_SRC
+
+,#+RESULTS:
+: ("simple" "list")
+#+end_src
+
 ** New features
 
 *** New citation engine
diff --git a/lisp/ob-core.el b/lisp/ob-core.el
index 1259909a0..3a07c10d5 100644
--- a/lisp/ob-core.el
+++ b/lisp/ob-core.el
@@ -2239,8 +2239,15 @@ (defun org-babel-read-table ()
           (org-table-to-lisp)))
 
 (defun org-babel-read-list ()
-  "Read the list at point into emacs-lisp."
-  (mapcar (lambda (el) (org-babel-read el 'inhibit-lisp-eval))
+  "Read the list at point into emacs-lisp.
+
+Return the list of strings representing top level items:
+
+   (item1 item2 ...)
+
+Only consider top level items.  See Info node `(org)Environment of \
+a Code Block'."
+  (mapcar (lambda (el) (org-babel-read (car el) 'inhibit-lisp-eval))
 	  (cdr (org-list-to-lisp))))
 
 (defvar org-link-types-re)
diff --git a/testing/lisp/test-ob-java.el b/testing/lisp/test-ob-java.el
index 07540ed74..65b7259d3 100644
--- a/testing/lisp/test-ob-java.el
+++ b/testing/lisp/test-ob-java.el
@@ -379,8 +379,8 @@ (ert-deftest ob-java/read-return-list ()
       "#+begin_src java :dir 'nil :var a=java_list :results value silent
 import java.util.List;
 import java.util.Arrays;
-List<String> b = Arrays.asList(a.get(0).get(0),
-                               a.get(1).get(0));
+List<String> b = Arrays.asList(a.get(0),
+                               a.get(1));
 return b;
 #+end_src
 
@@ -394,7 +394,7 @@ (ert-deftest ob-java/read-list-return-array ()
   "Read a list and return an array."
   (org-test-with-temp-text
       "#+begin_src java :dir 'nil :var a=java_list :results value silent
-String[] b = {a.get(0).get(0), a.get(1).get(0)};
+String[] b = {a.get(0), a.get(1)};
 return b;
 #+end_src
 
@@ -411,8 +411,8 @@ (ert-deftest ob-java/read-return-list-with-package ()
 package pkg;
 import java.util.List;
 import java.util.Arrays;
-List<String> b = Arrays.asList(a.get(0).get(0),
-                               a.get(1).get(0));
+List<String> b = Arrays.asList(a.get(0),
+                               a.get(1));
 return b;
 #+end_src
 
diff --git a/testing/lisp/test-ob.el b/testing/lisp/test-ob.el
index 4beaecf7b..e4090d6d8 100644
--- a/testing/lisp/test-ob.el
+++ b/testing/lisp/test-ob.el
@@ -204,7 +204,27 @@ (ert-deftest test-ob/simple-variable-resolution ()
     (forward-line 5)
     (should (string= ": 4" (buffer-substring
 			    (point-at-bol)
-			    (point-at-eol))))))
+			    (point-at-eol)))))
+  ;; Test reading lists.
+  (org-test-with-temp-text-in-file "
+
+#+NAME: example-list
+- simple
+  - not
+  - nested
+- list
+
+<point>#+BEGIN_SRC emacs-lisp :var x=example-list
+(print x)
+#+END_SRC"
+
+    (should (equal '("simple" "list") (org-babel-execute-src-block)))
+    (forward-line 5)
+    (should (string=
+             "| simple | list |"
+             (buffer-substring
+	      (point-at-bol)
+	      (point-at-eol))))))
 
 (ert-deftest test-ob/block-content-resolution ()
   "Test block content resolution."
@@ -218,8 +238,8 @@ (ert-deftest test-ob/block-content-resolution ()
 #+begin_src emacs-lisp :var four=four[]
   (length (eval (car (read-from-string four))))
 #+end_src"
-                                   (org-babel-next-src-block 2)
-                                   (should (= 4 (org-babel-execute-src-block)))))
+    (org-babel-next-src-block 2)
+    (should (= 4 (org-babel-execute-src-block)))))
 
 (ert-deftest test-ob/cons-cell-as-variable ()
   "Test that cons cell can be assigned as variable."
-- 
2.35.1


[-- Attachment #3: Type: text/plain, Size: 224 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>

Re: [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]

Ihor Radchenko <yantar92@posteo.net> writes:

> The attached is a fix for this discrepancy with the manual.
>
> However, it looks like at least ob-java already tried to work around the
> erroneous return value of org-babel-read-list.
>
> Hence, we at least need to announce this fix in ORG-NEWS.
>
> Or maybe there are other objections?

No objections have been raised.
Applied onto main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=b4e437f968771df9555f9306467846965857f632

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

Re: 2 'echo' bash instructions produce a table

[Ihor Radchenko]

Ihor Radchenko <yantar92@posteo.net> writes:

>> In 16.5 (Evaluating Code Blocks), in this code
>>
>>    #+NAME: random
>>    #+BEGIN_SRC R :cache yes
>>      runif(1)
>>    #+END_SRC
>>
>> the (1) seems to be understood as a footnote in Info, at least for me.
>> E.g., <RET> on it goes to the footnote
>>
>>    (1) The option ‘org-babel-no-eval-on-ctrl-c-ctrl-c’ [...]
>>
>> and <RET> on this (1) goes back to the above code instead of to the
>> actual call
>>
>>    "Org provides many ways to execute code blocks.  ‘C-c C-c’ or ‘C-c
>>    C-v e’ with the point on a code block(1)"
>
> Confirmed, but it does not look like Org's fault.

Reported to Emacs devs.
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=59293

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

Re: 2 'echo' bash instructions produce a table

[Ihor Radchenko]

Ihor Radchenko <yantar92@posteo.net> writes:

>> Confirmed, but it does not look like Org's fault.
>
> Reported to Emacs devs.
> https://debbugs.gnu.org/cgi/bugreport.cgi?bug=59293

Upon discussion, I have settled with a workaround.
This is a known Emacs info.el limitation.

Fixed.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=79c64d8c3

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

Re: 2 'echo' bash instructions produce a table

[Ihor Radchenko]

Ihor Radchenko <yantar92@posteo.net> writes:

>> Confirmed, but it does not look like Org's fault.
>
> Reported to Emacs devs.
> https://debbugs.gnu.org/cgi/bugreport.cgi?bug=59293

Upon discussion, I have settled with a workaround.
This is a known Emacs info.el limitation.

Fixed.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=79c64d8c3

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

Re: 2 'echo' bash instructions produce a table

[Alain.Cochard]

Ihor Radchenko writes on Mon 14 Nov 2022 03:59:
 > Alain.Cochard@unistra.fr writes:
 > 
 > > Ihor Radchenko writes on Mon  7 Nov 2022 02:31:

 > > > If you want to force string output, use :results output.
 > > > 
 > > > By default, ob-shell tries to guess the output type.  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.
 > >
 > > Thanks a lot.
 > >
 > > I find it strange, though, that the default is not as what one gets
 > > from running the code from a terminal.  I imagine there are good
 > > reasons for that, but I think this should be made clear (or at least
 > > clearer) in the manual.  I browsed through section 16 of the manual,
 > > with particular attention to 16.5 (Evaluating Code Blocks) and 16.6
 > > (Results of Evaluation), but still cannot see where this is said or
 > > hinted; if it is there, I missed it or do not know enough to
 > > understand it.

 > The manual describes generic code execution. If you do not explicitly
 > specify the :results header arg, it is the specific babel backend that
 > specifies the defaults.

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

a.


PS 1: In the manual, I see "backend" and "back-end".  So it is an
issue similar to the "subtree/sub-tree" issue you fixed a few days
ago, to the "heading/headline" issue that was reported recently, and
to many similar cases I met in the past.  So I was wondering if there
could exist some (semi-)automatic way which would ensure that future
maintainers will not inadvertently re-introduce "sub-tree"
occurrences, or the like.  Perhaps some "accepted terminology" list
that would be checked upon?

PS 2: Reading the ob-doc-shell.html page, I understood (kind of) what
was so far a mystery to me : that a "#+begin_src bash" group works as
expected while "#+begin_src ba + C-M-i" fails to complete "ba" to
"bash": namely that all the shells fall inside the "shell" umbrella
keyword.  Still, would not it make sense that the completion mechanism
also work for all those particular shells?

-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 110]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

Re: 2 'echo' bash instructions produce a table

[Rudolf Adamkovič]

Alain.Cochard@unistra.fr writes:

> So I was wondering if there could exist some (semi-)automatic way
> which would ensure that future maintainers will not inadvertently
> re-introduce "sub-tree" occurrences, or the like.  Perhaps some
> "accepted terminology" list that would be checked upon?

We could perhaps start with a simple `grep' in `Makefile' that executes
on `make test'.

Rudy
-- 
"Thinking is a momentary dismissal of irrelevancies."
-- Richard Buckminster Fuller, 1969

Rudolf Adamkovič <salutis@me.com> [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

Re: 2 'echo' bash instructions produce a table

[Ihor Radchenko]

Rudolf Adamkovič <salutis@me.com> writes:

> Alain.Cochard@unistra.fr writes:
>
>> So I was wondering if there could exist some (semi-)automatic way
>> which would ensure that future maintainers will not inadvertently
>> re-introduce "sub-tree" occurrences, or the like.  Perhaps some
>> "accepted terminology" list that would be checked upon?
>
> We could perhaps start with a simple `grep' in `Makefile' that executes
> on `make test'.

Generally, we document such things in doc/Documentation_Standards.org
Auto-checking with Makefile could work. Patches welcome ;)

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

Re: 2 'echo' bash instructions produce a table

[Ihor Radchenko]

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

Re: 2 'echo' bash instructions produce a table

[Alain.Cochard]

Ihor Radchenko writes on Tue 22 Nov 2022 08:16:

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

Things are clear.  Thanks.

 > +The result type detection depends on the code block language, as
 > +described in the documentation for individual [[*Languages][languages]].

Is this intended?  On the pdf it looks strange to me:

   The result type detection depends on the code block language, as
   described in the documentation for individual Section 16.9
   [languages], page 239.


-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 110]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

Re: 2 'echo' bash instructions produce a table

[Ihor Radchenko]

Alain.Cochard@unistra.fr writes:

>  > +The result type detection depends on the code block language, as
>  > +described in the documentation for individual [[*Languages][languages]].
>
> Is this intended?  On the pdf it looks strange to me:
>
>    The result type detection depends on the code block language, as
>    described in the documentation for individual Section 16.9
>    [languages], page 239.

Good catch!
I applied amended version of the patch with this issue resolved.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=50a35580112bfb63a61f0e33f741e7119b1065de

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

[RFC] Backend vs. back-end (was: 2 'echo' bash instructions produce a table)

[Ihor Radchenko]

Alain.Cochard@unistra.fr writes:

> PS 1: In the manual, I see "backend" and "back-end".  So it is an
> issue similar to the "subtree/sub-tree" issue you fixed a few days
> ago, to the "heading/headline" issue that was reported recently, and
> to many similar cases I met in the past.  So I was wondering if there
> could exist some (semi-)automatic way which would ensure that future
> maintainers will not inadvertently re-introduce "sub-tree"
> occurrences, or the like.  Perhaps some "accepted terminology" list
> that would be checked upon?

I looked into the manual. It has 197 instances of "back-end" and 24
instances of "backend". In the code, "backend" is used almost exclusively
in symbol names (except 5 instances), and "back-end" is used in the
docstrings and comments.

It is actually a bit confusing.

I am looking at https://techterms.com/definition/backend, and it looks
like "backend" is the correct word we need to use here. Am I missing
something?

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

Re: [RFC] Backend vs. back-end (was: 2 'echo' bash instructions produce a table)

[Ihor Radchenko]

Ihor Radchenko <yantar92@posteo.net> writes:

> I am looking at https://techterms.com/definition/backend, and it looks
> like "backend" is the correct word we need to use here. Am I missing
> something?

I looked further, and the situation is not as simple.
https://grammarhow.com/backend-back-end-or-back-end/, for example,
claims that only "back-end" is grammatically correct.

I am now thinking to do the following:
1. Use "backend" in the code symbols
2. Use "back-end" in docstrings and the manual.

Would it make sense?

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

Re: [RFC] Backend vs. back-end (was: 2 'echo' bash instructions produce a table)

[Alain.Cochard]

Ihor Radchenko writes on Mon 20 Feb 2023 10:07:

 > I looked further, and the situation is not as simple.
 > https://grammarhow.com/backend-back-end-or-back-end/, for example,
 > claims that only "back-end" is grammatically correct.
 > 
 > I am now thinking to do the following:
 > 1. Use "backend" in the code symbols
 > 2. Use "back-end" in docstrings and the manual.
 > 
 > Would it make sense?


It is not clear to me why it would be a problem to use 'backend' in
code symbols as well, but the only important thing for me as a user is
that the terminology be consistent throughout the documentation.  So
yes, it makes sense.

The link you provide is very convincing.  Will it still hold in 5 or
10 year from now?  (see end of
https://www-cs-faculty.stanford.edu/~knuth/email.html)

-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 110]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

Re: [RFC] Backend vs. back-end (was: 2 'echo' bash instructions produce a table)

[Ihor Radchenko]

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

Alain.Cochard@unistra.fr writes:

>  > I looked further, and the situation is not as simple.
>  > https://grammarhow.com/backend-back-end-or-back-end/, for example,
>  > claims that only "back-end" is grammatically correct.
>  > 
>  > I am now thinking to do the following:
>  > 1. Use "backend" in the code symbols
>  > 2. Use "back-end" in docstrings and the manual.
>  > 
>  > Would it make sense?
>
>
> It is not clear to me why it would be a problem to use 'backend' in
> code symbols as well, but the only important thing for me as a user is
> that the terminology be consistent throughout the documentation.  So
> yes, it makes sense.
>
> The link you provide is very convincing.  Will it still hold in 5 or
> 10 year from now?  (see end of
> https://www-cs-faculty.stanford.edu/~knuth/email.html)

Well. This is a tricky subject.
5-10 years from now the grammar itself may change.
At the end, even Oxford Dictionary my link is referring to, when
defending that "backend" without hyphen is wrong, is not setting
standards, but just reflecting the existing ones.

If we look into
https://ell.stackexchange.com/questions/117383/what-is-the-correct-term-back-end-back-end-or-backend
and https://en.wikipedia.org/wiki/Frontend_and_backend, "backend" is
also used.

I am attaching Google trends stats for search term usage of "backend",
"back-end", and "back end".

It looks like "backend" is more popular at the end.

I will go for it everywhere unless there are objections.

P.S. It really feels a bit silly trying to weigh on this subject.


[-- Attachment #2: backend-stats.png --]
[-- Type: image/png, Size: 66328 bytes --]

[-- Attachment #3: Type: text/plain, Size: 224 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>

Re: [RFC] Backend vs. back-end (was: 2 'echo' bash instructions produce a table)

[Ihor Radchenko]

Ihor Radchenko <yantar92@posteo.net> writes:

> It looks like "backend" is more popular at the end.
>
> I will go for it everywhere unless there are objections.

Done on main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=f81ba451a

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

Re: [RFC] Backend vs. back-end (was: 2 'echo' bash instructions produce a table)

[Samuel Wales]

backend sounds good to me as a native speaker, for a term of art for
export modules or so, with defined api.  if you are talking about back
end code abstractly, i'd go for 2 words, but that's just me.  i
wouldn't rely on my sense for this one.

On 11/22/22, Ihor Radchenko <yantar92@posteo.net> wrote:
> Alain.Cochard@unistra.fr writes:
>
>> PS 1: In the manual, I see "backend" and "back-end".  So it is an
>> issue similar to the "subtree/sub-tree" issue you fixed a few days
>> ago, to the "heading/headline" issue that was reported recently, and
>> to many similar cases I met in the past.  So I was wondering if there
>> could exist some (semi-)automatic way which would ensure that future
>> maintainers will not inadvertently re-introduce "sub-tree"
>> occurrences, or the like.  Perhaps some "accepted terminology" list
>> that would be checked upon?
>
> I looked into the manual. It has 197 instances of "back-end" and 24
> instances of "backend". In the code, "backend" is used almost exclusively
> in symbol names (except 5 instances), and "back-end" is used in the
> docstrings and comments.
>
> It is actually a bit confusing.
>
> I am looking at https://techterms.com/definition/backend, and it looks
> like "backend" is the correct word we need to use here. Am I missing
> something?
>
> --
> 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>
>
>


-- 
The Kafka Pandemic

A blog about science, health, human rights, and misopathy:
https://thekafkapandemic.blogspot.com

[BUG] Make source block auto-completion work for all the loaded babel backends (was: 2 'echo' bash instructions produce a table)

[Ihor Radchenko]

Alain.Cochard@unistra.fr writes:

> PS 2: Reading the ob-doc-shell.html page, I understood (kind of) what
> was so far a mystery to me : that a "#+begin_src bash" group works as
> expected while "#+begin_src ba + C-M-i" fails to complete "ba" to
> "bash": namely that all the shells fall inside the "shell" umbrella
> keyword.  Still, would not it make sense that the completion mechanism
> also work for all those particular shells?

It would indeed make sense.

The current implementation of completion is somewhat awkward.
It resides in lisp/org-pcomplete.el
(pcomplete/org-mode/block-option/src) and relies on pre-defined known
values in `org-babel-load-languages' (see :type keyword of the
defcustom).

Such design is not reliable.

Ideally, we should examine the available function symbols
org-babel-execute:* and derive the completions from there.

Patches welcome!

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