Miskatonic University PressI made a schoolboy error last week: I narrowed down a problem I was having with a program to one line and one setting … but then I didn’t read the documentation. It was Org mode in Emacs, and the variable was org-export-babel-evaluate. I set it to nil, and what happened wasn’t what I thought should happen, so I thought it was a bug, when actually it’s all set out in the docs. Lesson re-learned: RTFM.
Here’s what happened. At work I did a long report analyzing some aspects of the library’s presence in the university’s course management system. We made a box in Moodle that generates customized recommendations to students based on the course code: students see links to relevant research guides (for example poli sci students see a link to the poli sci research guide), to the course’s specific guide and/or reserves if they exist, and to the profile of the librarian who handles that subject. Turns out the links in the box don’t get many clickthroughs, but that’s something I’ll write up some other time.
The thing is, doing the full analysis means looking at millions of lines of data from log files, then processing things in R and Ruby, generating charts, tables of numbers, the whole schmear. The way I have it set up, the Org file, which is full of source code blocks, can be fully reproducible research: when I export to PDF, every data file is read in and analyzed fresh, every table and chart are regenerated. That’s wonderful, and it’s one of the reasons I love Org—but it’s intensive, and it takes about five minutes to run on my personal machine, and usually crashes my slower work machine. (I asked for a new one.) And when I’m rewriting and editing and want to see how the changes look, I don’t need to regenerate all the data, I just want to turn what’s there into a PDF as is.
Because I didn’t want any of the code blocks evaluated, I set this in a file variable (it’s the first line in the Org file):
# -*- org-export-babel-evaluate: nil -*-
But when I exported the file to PDF, all of a sudden not only were the results of the code blocks in the PDF (as desired) but also the code that generated them. Instead of showing the results of a bit of Ruby, the Ruby was there too. Instead of just showing a chart, the R that made it was there too. Not what I wanted!
I spent about an hour narrowing this down and reported it as a possible bug to the Org mailing list. Very quickly Charles Berry replied and gently corrected me, pointing me to the documentation (which I now notice contains a typo, which I’ll submit a real bug report for):
Switch controlling code evaluation during export.
When set to nil no code will be evaluated as part of the export
process and no header argumentss will be obeyed. When set to
‘inline-only’, only inline code blocks will be executed. Users
who wish to avoid evaluating code on export should use the header
argument ‘:eval never-export’.
It’s the “no header arguments will be obeyed” that was causing my trouble. I needed that “:eval never-export” thing, which isn’t managed like the org-export-babel-evaluate variable, but is a header argument, which I’d never used before (and had to search GitHub to find examples of). I put this near the start of the file and hit C-c C-c on the line to make Emacs know about it:
#+PROPERTY: header-args :eval never-export
Now when I export the file to PDF (C-c C-e l o) it just blasts the document as is into LaTeX and turns it into a PDF, no calculating done. For minor tweaks and copy editing, that’s just what I need. When I need to rerun some data analysis, I can remove the line to rerun everything fully and completely.
This is all a bit arcane, so I document this in the hopes it will save someone, perhaps just future me, a moment of trouble in some month or year to come.