org-babel-load-languages usability issue

org-babel-load-languages usability issue

[Tim Cross]

I'm not sure when the definition of the variable
org-babel-load-languages changed, but I think we may need to consider
either reverting it or making some other adjustment.

Originally, this variable was an alist of languages and a boolean
indicating whether the language should be loaded e.g.

'((emacs-lisp . t)
  (clojure . t)
  (sql . nil))

which would load emacs-lisp and clojure, but not sql. However, the
default value for the variable now appears to just be

'((emacs-lisp . t))

This has two consequences. The first is that the doc string for the
variable is now incorrect. It states in part 

"This list can be used to load support for any of the languages
below. "

There are no languages listed below. This also leads to the
next issue. How does a user know what languages are supported and can be
enabled? Previously, you had a list of all the supported built-in languages -
most of which would be disabled (nil) by default. However, this did make
it easy to know what languages are supported - you could use customize
to change the flag from nil to t (or copy the default into your init
file and modify appropriately. Now it doesn't seem to be as clear.

Note also that the doc string refers to the variable as a list, when it
is actually an alist (association list). This could be confusing,
especially for new users. The doc string probably should describe the
format more precisely i.e the CAR of each con cell making up the
alist is a language syumbol e.g. emacs-lisp and the CDR is a boolean
that will be 't if the language is to be loaded or nil otherwise. . 

Should the default value for this variable be a list of all the
supported babel languages which are bundled with emacs, all of which set to 'nil' to disable them
except emacs-lisp (to maintain existing semantics, though I do wonder if
we should also enable eshell given we enable emacs-lisp by default
because all necessary dependencies are provided by emacs, as is the case
with eshell)?

The alternative is to update the doc string. I guess we could reference
the URL to the worg page which lists supported languages. However, I'm
not sure this is a great solution from a usability perspective,
particularly for new org mode users.

Re: org-babel-load-languages usability issue

[Ihor Radchenko]

Tim Cross <theophilusx@gmail.com> writes:

> I'm not sure when the definition of the variable
> org-babel-load-languages changed, but I think we may need to consider
> either reverting it or making some other adjustment.
>
> Originally, this variable was an alist of languages and a boolean
> indicating whether the language should be loaded e.g.
>
> '((emacs-lisp . t)
>   (clojure . t)
>   (sql . nil))
>
> which would load emacs-lisp and clojure, but not sql. However, the
> default value for the variable now appears to just be
>
> '((emacs-lisp . t))

Are you sure? '((emacs-lisp . t)) is the default value in the commit
that introduced this variable 12 years ago:

6e469f4afba4bf7d6e8983d1e4f3e981252f8f60
Author:     Eric Schulte <schulte.eric@gmail.com>
AuthorDate: Fri Jul 2 11:32:38 2010 -0700
babel: `org-babel-load-languages' activates code blocks by language

> This has two consequences. The first is that the doc string for the
> variable is now incorrect. It states in part 
>
> "This list can be used to load support for any of the languages
> below. "

Well. There are actually languages below if you look into the source
code. Indeed, it is confusing in the help/customize buffer. We can fix
this, say, by adding the language list into the docstring itself. Though
it will not cover third-party ob-*.el modules.

> There are no languages listed below. This also leads to the
> next issue. How does a user know what languages are supported and can be
> enabled? Previously, you had a list of all the supported built-in languages -
> most of which would be disabled (nil) by default. However, this did make
> it easy to know what languages are supported - you could use customize
> to change the flag from nil to t (or copy the default into your init
> file and modify appropriately. Now it doesn't seem to be as clear.

The (incomplete) list is actually available in cutomize interface. Of
course, we can still improve the docstring.

> Note also that the doc string refers to the variable as a list, when it
> is actually an alist (association list). This could be confusing,
> especially for new users. The doc string probably should describe the
> format more precisely i.e the CAR of each con cell making up the
> alist is a language syumbol e.g. emacs-lisp and the CDR is a boolean
> that will be 't if the language is to be loaded or nil otherwise. . 

Agreed.

> Should the default value for this variable be a list of all the
> supported babel languages which are bundled with emacs, all of which set to 'nil' to disable them
> except emacs-lisp (to maintain existing semantics, though I do wonder if
> we should also enable eshell given we enable emacs-lisp by default
> because all necessary dependencies are provided by emacs, as is the case
> with eshell)?

The primary goal of this variable is reducing startup time. Loading all
the 44 built-in babel backends would be slow.

-- 
Ihor Radchenko,
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: org-babel-load-languages usability issue

[Tim Cross]

Ihor Radchenko <yantar92@gmail.com> writes:

> Tim Cross <theophilusx@gmail.com> writes:
>
>> I'm not sure when the definition of the variable
>> org-babel-load-languages changed, but I think we may need to consider
>> either reverting it or making some other adjustment.
>>
>> Originally, this variable was an alist of languages and a boolean
>> indicating whether the language should be loaded e.g.
>>
>> '((emacs-lisp . t)
>>   (clojure . t)
>>   (sql . nil))
>>
>> which would load emacs-lisp and clojure, but not sql. However, the
>> default value for the variable now appears to just be
>>
>> '((emacs-lisp . t))
>
> Are you sure? '((emacs-lisp . t)) is the default value in the commit
> that introduced this variable 12 years ago:
>
No, not sure at all. It was a long time ago that I last needed to look
at it (I only noticed this now as I'm re-doing my org config as a lot
has changed since much of it was first coded/configured. 

> 6e469f4afba4bf7d6e8983d1e4f3e981252f8f60
> Author:     Eric Schulte <schulte.eric@gmail.com>
> AuthorDate: Fri Jul 2 11:32:38 2010 -0700
> babel: `org-babel-load-languages' activates code blocks by language
>
>> This has two consequences. The first is that the doc string for the
>> variable is now incorrect. It states in part 
>>
>> "This list can be used to load support for any of the languages
>> below. "
>
> Well. There are actually languages below if you look into the source
> code. Indeed, it is confusing in the help/customize buffer. We can fix
> this, say, by adding the language list into the docstring itself. Though
> it will not cover third-party ob-*.el modules.

Maybe only add/list those languages 'bundled' with Emacs or perhaps just
add a link to the worg page listing all the supported languages. I'm
reluctant to add the list to the doc string as it will make it even
longer and there will always be the issue of it not being current as
languages are added/removed (I find doc string drift out more than code,
where people tend to update/fix code more readily). 

>
>> There are no languages listed below. This also leads to the
>> next issue. How does a user know what languages are supported and can be
>> enabled? Previously, you had a list of all the supported built-in languages -
>> most of which would be disabled (nil) by default. However, this did make
>> it easy to know what languages are supported - you could use customize
>> to change the flag from nil to t (or copy the default into your init
>> file and modify appropriately. Now it doesn't seem to be as clear.
>
> The (incomplete) list is actually available in cutomize interface. Of
> course, we can still improve the docstring.
>
>> Note also that the doc string refers to the variable as a list, when it
>> is actually an alist (association list). This could be confusing,
>> especially for new users. The doc string probably should describe the
>> format more precisely i.e the CAR of each con cell making up the
>> alist is a language syumbol e.g. emacs-lisp and the CDR is a boolean
>> that will be 't if the language is to be loaded or nil otherwise. . 
>
> Agreed.
>
>> Should the default value for this variable be a list of all the
>> supported babel languages which are bundled with emacs, all of which set to 'nil' to disable them
>> except emacs-lisp (to maintain existing semantics, though I do wonder if
>> we should also enable eshell given we enable emacs-lisp by default
>> because all necessary dependencies are provided by emacs, as is the case
>> with eshell)?
>
> The primary goal of this variable is reducing startup time. Loading all
> the 44 built-in babel backends would be slow.

Would it load them if the default values for all the languages which
have bundleed modes in Emacs were set to nil rather than t?

I guess the issue isn't as bad if you do get the list of available
languages when you use the customize interface (I should have checked
that). I never use customise and I know lots of other Emacs users don't
either. Maybe just fixing up the doc string would be sufficient?

Re: org-babel-load-languages usability issue

[Ihor Radchenko]

Tim Cross <theophilusx@gmail.com> writes:

>> Well. There are actually languages below if you look into the source
>> code. Indeed, it is confusing in the help/customize buffer. We can fix
>> this, say, by adding the language list into the docstring itself. Though
>> it will not cover third-party ob-*.el modules.
>
> Maybe only add/list those languages 'bundled' with Emacs or perhaps just
> add a link to the worg page listing all the supported languages. I'm
> reluctant to add the list to the doc string as it will make it even
> longer and there will always be the issue of it not being current as
> languages are added/removed (I find doc string drift out more than code,
> where people tend to update/fix code more readily). 

We have [[info:org#Languages]] linking to
https://orgmode.org/worg/org-contrib/babel/languages/index.html
I guess we can simply add the manual link to the docstring. Would it be
sufficient?

>> The primary goal of this variable is reducing startup time. Loading all
>> the 44 built-in babel backends would be slow.
>
> Would it load them if the default values for all the languages which
> have bundleed modes in Emacs were set to nil rather than t?

I am not sure if it is a good idea.
I am now looking at the usage of org-babel-load-languages in the code,
and I am seeing `org-lint-wrong-header-argument',
`org-babel-demarcate-block' ignoring difference between (lang . nil) and
(lang .t).

-- 
Ihor Radchenko,
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: org-babel-load-languages usability issue

[Tim Cross]

Ihor Radchenko <yantar92@gmail.com> writes:

> Tim Cross <theophilusx@gmail.com> writes:
>
>>> Well. There are actually languages below if you look into the source
>>> code. Indeed, it is confusing in the help/customize buffer. We can fix
>>> this, say, by adding the language list into the docstring itself. Though
>>> it will not cover third-party ob-*.el modules.
>>
>> Maybe only add/list those languages 'bundled' with Emacs or perhaps just
>> add a link to the worg page listing all the supported languages. I'm
>> reluctant to add the list to the doc string as it will make it even
>> longer and there will always be the issue of it not being current as
>> languages are added/removed (I find doc string drift out more than code,
>> where people tend to update/fix code more readily). 
>
> We have [[info:org#Languages]] linking to
> https://orgmode.org/worg/org-contrib/babel/languages/index.html
> I guess we can simply add the manual link to the docstring. Would it be
> sufficient?
>

Yes, I think so. That was what I was thinking would be reasonable and
would avoid maintenance issues for the doc string when languages are
added/removed.


>>> The primary goal of this variable is reducing startup time. Loading all
>>> the 44 built-in babel backends would be slow.
>>
>> Would it load them if the default values for all the languages which
>> have bundleed modes in Emacs were set to nil rather than t?
>
> I am not sure if it is a good idea.
> I am now looking at the usage of org-babel-load-languages in the code,
> and I am seeing `org-lint-wrong-header-argument',
> `org-babel-demarcate-block' ignoring difference between (lang . nil) and
> (lang .t).

OK, so if I understand you correctly, not all of org code honours the
enabled/disabled setting so adding all bundled languages, but setting
them to nil, would result in unexpected or additional processing for
those languages despite them being disabled?

If that is the case, you right and adding them would be
problematic. However, I would also argue this is probably a
bug. Essentially, it means that the value associated with the language
symbol key is sometimes interpreted and sometimes ignored. I think this
is an inconsistency which can potentially cause confusion and could
contribute to subtle bugs.

One thing I do wonder though wrt the two examples you cited. Could this
be deliberate/intentional for these functions?

I wondering about the scenario where you want to include blocks for a
certain language, but you do not need to evaluate them, so no need for
babel support. Might this be a case where you would set the language to
nil, but be fine with lint and other checks verifying the block
structure? Provided this isn't also resulting in loading of language
specific babel code, it may not be an issue?

Re: org-babel-load-languages usability issue

[Ihor Radchenko]

Tim Cross <theophilusx@gmail.com> writes:

>> We have [[info:org#Languages]] linking to
>> https://orgmode.org/worg/org-contrib/babel/languages/index.html
>> I guess we can simply add the manual link to the docstring. Would it be
>> sufficient?
>>
>
> Yes, I think so. That was what I was thinking would be reasonable and
> would avoid maintenance issues for the doc string when languages are
> added/removed.

Done.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=7c20552ed636d6c058d6be649e19d3d5edc0f62a

>>> Would it load them if the default values for all the languages which
>>> have bundleed modes in Emacs were set to nil rather than t?
>>
>> I am not sure if it is a good idea.
>> I am now looking at the usage of org-babel-load-languages in the code,
>> and I am seeing `org-lint-wrong-header-argument',
>> `org-babel-demarcate-block' ignoring difference between (lang . nil) and
>> (lang .t).
>
> OK, so if I understand you correctly, not all of org code honours the
> enabled/disabled setting so adding all bundled languages, but setting
> them to nil, would result in unexpected or additional processing for
> those languages despite them being disabled?

Yes, though I am not 100% sure if the impact is significant enough for
us to care.

> If that is the case, you right and adding them would be
> problematic. However, I would also argue this is probably a
> bug. Essentially, it means that the value associated with the language
> symbol key is sometimes interpreted and sometimes ignored. I think this
> is an inconsistency which can potentially cause confusion and could
> contribute to subtle bugs.

Agree. 

> One thing I do wonder though wrt the two examples you cited. Could this
> be deliberate/intentional for these functions?
>
> I wondering about the scenario where you want to include blocks for a
> certain language, but you do not need to evaluate them, so no need for
> babel support. Might this be a case where you would set the language to
> nil, but be fine with lint and other checks verifying the block
> structure? Provided this isn't also resulting in loading of language
> specific babel code, it may not be an issue?

I do not think that your example is a valid use-case.
(lang . nil), when set during startup, means that (require 'ob-lang) has
never been executed (or, at least, we cannot guarantee it).
When (lang . nil) is changed from (lang . t) at some point,
(require 'ob-lang) is executed, but org-babel-do-load-languages
explicitly unloads the babel function that executes the LANG blocks.

In general, we cannot assume that any of the ob-lang functions are
loaded when there is (lang . nil). No LANG-specific info is available.

Also, (lang . nil) is supposed to deny loading LANG. It should be no
different compared to not listing LANG at all.

-- 
Ihor Radchenko,
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: org-babel-load-languages usability issue

[Tim Cross]

Ihor Radchenko <yantar92@gmail.com> writes:

> Tim Cross <theophilusx@gmail.com> writes:
>
>>> We have [[info:org#Languages]] linking to
>>> https://orgmode.org/worg/org-contrib/babel/languages/index.html
>>> I guess we can simply add the manual link to the docstring. Would it be
>>> sufficient?
>>>
>>
>> Yes, I think so. That was what I was thinking would be reasonable and
>> would avoid maintenance issues for the doc string when languages are
>> added/removed.
>
> Done.
> https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=7c20552ed636d6c058d6be649e19d3d5edc0f62a
>

Excellent. Thanks.

>>>> Would it load them if the default values for all the languages which
>>>> have bundleed modes in Emacs were set to nil rather than t?
>>>
>>> I am not sure if it is a good idea.
>>> I am now looking at the usage of org-babel-load-languages in the code,
>>> and I am seeing `org-lint-wrong-header-argument',
>>> `org-babel-demarcate-block' ignoring difference between (lang . nil) and
>>> (lang .t).
>>
>> OK, so if I understand you correctly, not all of org code honours the
>> enabled/disabled setting so adding all bundled languages, but setting
>> them to nil, would result in unexpected or additional processing for
>> those languages despite them being disabled?
>
> Yes, though I am not 100% sure if the impact is significant enough for
> us to care.
>

Agreed.

>> If that is the case, you right and adding them would be
>> problematic. However, I would also argue this is probably a
>> bug. Essentially, it means that the value associated with the language
>> symbol key is sometimes interpreted and sometimes ignored. I think this
>> is an inconsistency which can potentially cause confusion and could
>> contribute to subtle bugs.
>
> Agree. 
>
>> One thing I do wonder though wrt the two examples you cited. Could this
>> be deliberate/intentional for these functions?
>>
>> I wondering about the scenario where you want to include blocks for a
>> certain language, but you do not need to evaluate them, so no need for
>> babel support. Might this be a case where you would set the language to
>> nil, but be fine with lint and other checks verifying the block
>> structure? Provided this isn't also resulting in loading of language
>> specific babel code, it may not be an issue?
>
> I do not think that your example is a valid use-case.
> (lang . nil), when set during startup, means that (require 'ob-lang) has
> never been executed (or, at least, we cannot guarantee it).
> When (lang . nil) is changed from (lang . t) at some point,
> (require 'ob-lang) is executed, but org-babel-do-load-languages
> explicitly unloads the babel function that executes the LANG blocks.
>
> In general, we cannot assume that any of the ob-lang functions are
> loaded when there is (lang . nil). No LANG-specific info is available.
>
> Also, (lang . nil) is supposed to deny loading LANG. It should be no
> different compared to not listing LANG at all.

OK, fair enough. The point regarding (lang . nil) being supposed to deny
loding LANG is my main point. I would hope it is exactly the same as not
listening LANG. Originally, my thought was it would be easier for the
user from a usability perspective if they could just look at the value
of this variable and immediately see not only the languages currently
enabled, but also those languages which could be trivially enabled
because they are bundled with Emacs - for example, 'shell', 'eshell' and
possibly others which tend to have the runtime installed in most cases
and where Emacs has a built in mode.

At any rate, the changes made are a good start and I'm happy if things
are left there for now.