The previous post discussed how to use org-mode as a notebook. You can have blocks of code and blocks of results, analogous to cells in a Jupyter notebook. The code and the results export as obvious blocks when you export the org file to another format, such as LaTeX or HTML. And that’s fine for a notebook.
Now suppose you want to do something more subtle. You want to splice in the result of a computed value without being obvious about it. Maybe you want to compute a value rather than directly enter it so that the document will remain consistent. Maybe you have a template and you want to set the parameters of the template at the top of the file.
Web development languages like PHP do this well. You can write a PHP file that is essentially an HTML file with pieces of code spliced in. You do this my inserting
<?php … ?>
into the HTML code, and when the page is rendered the code between the <?php
and ?>
tags is replaced with the result of executing the code. We’d like to do something analogous in org-mode with org-babel. (org-babel is the subsystem of org-mode that interacts with code.)
Here’s an org-mode example that sets length
and width
as variables at the top of a file and multiplies them later in the body of the file to get area.
We define our variables as follows. The block is marked :exports none
because we do not want to display the code or the values. We just want the code to run when we export the file.
#+begin_src python :session :exports none length, width = 7, 13 #+end_src
The following almost does what we want [1].
Area equals src_python[:session]{length*width}.
This renders as
Area equals 91
.
if we export our org file to HTML The number 91 is typeset differently than the words before it. This would be more obvious if the computed value were a string rather than a number.
Org-mode is wrapping <code>
tags around the computed result. If we were to export the org file to LaTeX it would wrap the result with \texttt{}
. This is because, by default, the output of a computation is displayed as computer output, which is conventionally set in a monospace font like Courier. That’s fine in a technical document when we want to make it obvious that a calculation is a calculation, but typically not in a business context. You wouldn’t want, for example, to generate a letter that starts
Dear Michael
,
with Michael’s name set in Courier, announcing that this is a form letter.
The fix is to add :results raw
to the header session, the part in square brackets between src_python
and the Python code.
Area equals src_python[:session :results raw]{length*width}.
Now the calculation result is reported “raw”, i.e. without any special markup surrounding it.
***
[1] In this example I’m using Python, and so I used the function src_python
. org-babel supports dozens of languages, and each has its src_<language>
counterpart.