[Orgmode] [Update Config] Babel changes -- security updates and final integration push

[Eric Schulte]

Hi,

I've just merged a large set of Babel related security measures and
layout/initialization updates into the master branch of the git
repository.

These changes will require existing babel users to update their
configuration, see the following instructions for details -- even if you
think you've read similar instructions before these are worth reading.
http://eschulte.github.com/babel-dev/DONE-document-configuration-changes-for-Babel-integration.html

>From here on out Babel development in the master branch will settle down
along with the rest of the current Org-mode feature freeze.

Thanks -- Eric

please reply to this email with any question or problems you encounter,
a text export of the contents of the web page linked above is provided
below.

DONE document configuration changes for Babel integration 
==========================================================
Babel took the integration into Org-mode as an opportunity to do
some much needed house cleaning.  Most importantly we have
simplified the enabling of language support, and cleared out
unnecessary configuration variables -- which is great unless you
already have a working configuration under the old model.

The most important changes regard the /location/ and /enabling/
of Babel (both core functionality and language specific support).

Babel: Babel is now part of the core of Org-mode, so it is
     now loaded along with the rest of Org-mode.  That means that
     there is /no configuration/ required to enable the main
     Babel functionality.  For current users, this means that
     statements like

     (require 'org-babel)

     or

     (require 'org-babel-init)

     that may by lying around in your configuration must now be
     removed.

load path: Babel (including all language specific files --
     aside from those which are located in the =contrib/=
     directory for reasons of licencing) now lives in the base of
     the Org-mode lisp directory, so /no additional directories/
     need to be added to your load path to use babel.  For Babel
     users this means that statements adding babel-specific
     directories to your load-path should now be removed from
     your config.

language support: It is no longer necessary to require
     language specific support on a language-by-language basis.
     Specific language support should now be managed through the
     `org-babel-load-languages' variable.  This variable can be
     customized using the Emacs customization interface, or
     through the addition of something like the following to your
     configuration (note: any language not mentioned will /not/
     be enabled, aside from =emacs-lisp= which is enabled by
     default)

     (org-babel-do-load-languages
      'org-babel-load-languages
      '((R . t)
        (ditaa . t)
        (dot . t)
        (emacs-lisp . t)
        (gnuplot . t)
        (haskell . nil)
        (ocaml . nil)
        (python . t)
        (ruby . t)
        (screen . nil)
        (sh . t)
        (sql . nil)
        (sqlite . t)))
     
     Despite this change it is still possible to add
     language support through the use of =require=
     statements, however to conform to Emacs file-name
     regulations all Babel language files have changed
     prefix from =org-babel-*= to =ob-*=, so the require
     lines must also change e.g.

     (require 'org-babel-R)

     should be changed to

     (require 'ob-R)

We have eliminated the =org-babel-tangle-w-comments= variable as
well as the two main internal lists of languages, namely
- =org-babel-interpreters= and
- =org-babel-tangle-langs= 

so any config lines which mention those variables, can/should be
stripped out in their entirety.  This includes any calls to the
=org-babl-add-interpreter= function, whose sole purpose was to
add languages to the =org-babel-interpreters= variable.

With those calls stripped out, we may still in some cases want to
associate a file name extension with certain languages, for
example we want all of our emacs-lisp files to end in a =.el=, we
can do this will the =org-babel-tangle-lang-exts= variable.  In
general you shouldn't need to touch this as it already has
defaults for most common languages, and if a language is not
present in org-babel-tangle-langs, then babel will just use the
language name, so for example a file of =c= code will have a =.c=
extension by default, shell-scripts (identified with =sh=) will
have a =.sh= extension etc...

The configuration of /shebang/ lines now lives in header
arguments.  So the shebang for a single file can be set at the
code block level, e.g.


  #+begin_src clojure :shebang #!/usr/bin/env clj
    (println "with a shebang line, I can be run as a script!")
  #+end_src

Note that whenever a file is tangled which includes a /shebang/
line, Babel will make the file executable, so there is good
reason to only add /shebangs/ at the source-code block level.
However if you're sure that you want all of your code in some
language (say shell scripts) to tangle out with shebang lines,
then you can customize the default header arguments for that
language, e.g.


  ;; ensure this variable is defined defined
  (unless (boundp 'org-babel-default-header-args:sh)
    (setq org-babel-default-header-args:sh '()))
  
  ;; add a default shebang header argument
  (add-to-list 'org-babel-default-header-args:sh
               '(:shebang . "#!/bin/bash"))

The final important change included in this release is the
addition of new security measures into Babel.  These measures are
in place to protect users from the accidental or uninformed
execution of code.  Along these lines /every/ execution of a code
block will now require an explicit confirmation from the user.
These confirmations can be stifled through customization of the
`org-confirm-babel-evaluate' variable, e.g.

  ;; I don't want to be prompted on every code block evaluation
  (setq org-confirm-babel-evaluate nil)

In addition, it is now possible to remove code block evaluation
form the =C-c C-c= keybinding.  This can be done by setting the
=org-babel-no-eval-on-ctrl-c-ctrl-c= variable to a non-nil value,
e.g.

  ;; I don't want to execute code blocks with C-c C-c
  (setq org-babel-no-eval-on-ctrl-c-ctrl-c t)

An additional keybinding has been added for code block
evaluation, namely =C-c C-v e=.

Whew! that seems like a lot of effort for a /simplification/ of
configuration.