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.