org-babel-load-languages usability issue
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
Tim Cross 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 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
Ihor Radchenko writes: > Tim Cross 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 > 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
Tim Cross 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
Ihor Radchenko writes: > Tim Cross 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
Tim Cross 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
Ihor Radchenko writes: > Tim Cross 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.