Interested in Org but not enough to monitor the mailing list? In this blog I digest developments, and each month regurgitate what I consider the highlights, along with anything else Org-related I consider nifty.

Posts are published in .html, .org, .org.html, .txt, and .pdf forms — because why not πŸ˜›

June 2021 2021-06-34

The previous two months have been pretty good for Org development — with many bug fixes and feature improvements. This month has been substantially slower than the last[1], but that’s not to say not much is happening: in fact, there are some rather nifty contributions lined up for the not-too-distant future and a certain long-awaited feature branch[2] is getting very close to merging πŸ˜€. You’ll just have to stick around to hear about those in a future edition of TMIO πŸ˜‰.

dilbert-zenos-paradox.jpg
Figure 1: It’s right around the corner, I swear!

Customise the reference command used in LaTeX

Previously, whenever you linked to another part of your document (with or without giving it a name) — for example with [[Profound section]] or similar — when exporting to LaTeX Org would always use the \ref command.

org-latex-default-reference-to-sec.png
Figure 2: A LaTeX export of a simple document with a reference to both the first and second section. “2” what? Section 2, Table 2, Figure 2, …

You can now set the format string org-latex-reference-command (\\ref{%s} by default) to anything you’d like. For example, making use of the cleveref package I can set this to \\cref{%s} and then add ("capitalize" "cleveref" nil)[3] to org-latex-packages-alist.

org-latex-cref-reference-to-sec.png
Figure 3: A LaTeX export of the same document, but now using cleveref. Note the change from “1” and “2” to “Section 1” and “Section 2”.

A diversion into writing Org for LaTeX

Speaking of LaTeX exports, a member of the Org mailing list recently told us about a paper pushed to arXiv which was written entirely in Org. Why don’t we use that as a prompt to talk a bit about generating LaTeX documents from Org?

For an experienced LaTeX-er, Org may initially appear best suited to simple documents, but in fact it’s possible to reproduce any LaTeX structure in Org with no more difficulty (often less) than in LaTeX.

Simple elements

The “basic” Org elements are simply translated to their LaTeX counterparts. Markup like bold, italic, etc. are simply translated through org-latex-text-markup-alist.

For those of us who dabble with equations, Org is very accomodating. You can type (LaTeX-style) inline and display equations in exactly the same way (\( \) and \[ \]), and what’s more, if you have a LaTeX environment statement \begin{...} on its own line, Org will recognise it and pass it into the generated LaTeX.

Figures and tables

One area where the improvement when moving to Org is particularly apparent is with figures and tables. To simply include an image, an image link alone is sufficient.

Org mode
#

When exported to LaTeX this will be expanded to

LaTeX
#
\includegraphics[width=.9\linewidth]{figures/salvador-dali-persistence-of-memory.jpg}

As soon as you add a #+caption, though, Org knows you mean business and generates a proper figure.

Org mode
#
#+caption: A famous surrealist painting
file:figures/salvador-dali-persistence-of-memory.jpg
LaTeX
#
\begin{figure}[htbp]
\centering
\includegraphics[width=.9\linewidth]{figures/salvador-dali-persistence-of-memory.jpg}
\caption{A famous surrealist painting}
\end{figure}

As you may have guessed from the fact this works without a LaTeX-specific keyword, this works nicely in HTML too πŸ™‚.

salvador-dali-persistence-of-memory.jpg
Figure 4: A famous surrealist painting

The LaTeX backend also accepts additional image attributes (manual page). For example, to set the image width I can simply add

Org mode
#
#+attr_latex: :width 0.4\linewidth

above the image link.

You can do the same with tables:

Org mode
#
#+caption: A selection of famous paintings by Salvador Dalí
| Year | Painting                   |
|------+----------------------------|
| 1931 | The persistence of memory  |
| 1937 | Swans reflecting elephants |
| 1837 | Metamorphosis of narcissus |
| 1952 | Galatea of the spheres     |
| 1966 | Tuna fishing               |

I like to set (setq org-latex-tables-booktabs t) to use the nice booktabs rules in the generated tables. Just remember to ensure the booktabs package is loaded.

LaTeX
#
\begin{table}[htbp]
\caption{A selection of famous paintings by Salvador Dalí}
\centering
\begin{tabular}{rl}
\toprule
Year & Painting\\
\midrule
1931 & The persistence of memory\\
1937 & Swans reflecting elephants\\
1837 & Metamorphosis of narcissus\\
1952 & Galatea of the spheres\\
1966 & Tuna fishing\\
\bottomrule
\end{tabular}
\end{table}

Org is nice and does the right thingTM by including the caption at the top.

org-table-to-latex-example.png
Figure 5: Look ma, I put the caption in the right place.

There are also some more attributes you can supply to tables. Should I want the table to spread out I could use #+attr_latex: :environment tabularx (as long as I’ve loaded the tabularx package) and then set the columns with :align lX.

Code blocks

By default, source code blocks are translated verbatim. We can do better than that however. We can tell Org to use listings, but I’d recommend going one step further and using minted. For this to work we need to perform three actions:

  • Tell Org we want to use minted environments for source code
  • Load the minted package by default
  • Add -shell-escape to our LaTeX compiler flags, so minted may call pygments.

This can easily be accomplished via the following snippet:

Emacs Lisp
#
(setq org-latex-listings 'minted
      ;; as long as you have latexmk installed
      org-latex-pdf-process
      '("latexmk -f -pdf -%latex -shell-escape -interaction=nonstopmode -output-directory=%o %f"))
(add-to-list 'org-latex-packages-alist '("" "minted"))

To customise minted, as well as inserting content into the preamble, one can also customise org-latex-minted-options to control what options are applied to each minted environment.

Custom environments

Org has a number of blocks which are treated specially, like #+begin_src for source code, and #+begin_centre for centered text. When exporting this same syntax allows you to wrap Org content in any LaTeX environments (as long as it doesn’t match one of Org’s recognised environments).

For example, if you wrote a warning environment in LaTeX to box and emphasise text, to wrap some Org content in it one simply needs to write:

Org mode
#
#+begin_warning
Pay close attention! This is very important.
#+end_warning

and the content will be wrapped in \begin{warning} ... \end{warning}.

The LaTeX escape hatches

Should there be a particular LaTeX command you wish to insert somewhere, you simply need to put it on its own line with #+latex: in front and it will be transferred to the generated LaTeX (this works with other formats too).

Org mode
#
#+latex: \newpage

For larger snippets of LaTeX, there’s always the export block.

Org mode
#
#+begin_export latex
\cleardoublepage
\vfil
\hfil This page is intentionally left blank \hfil
\vfil
\newpage
#+end_export

Preamble content

Should you wish to include the line in the preamble (before \begin{document}), then all you need to do is use #+latex_header:.

Org mode
#
#+latex_header: \newcommand{\RR}{\mathbb{R}}
#+latex_header: \usepackage{svg} % so that [[file:*.svg]] works nicely

This is great for adding one-off \usepackage commands, but what if you find yourself wanting a package (like svg) to be always included? Well the we have the aforementioned org-latex-packages-alist which will include the packages set when exporting; you can even set some packages to only be included when using a certain LaTeX compiler.

Should you want to use a certain preset preamble, you can make use of the #+latex_class keyword. This is used to set the base preamble template used when generating the LaTeX. See org-latex-classes for what’s available by default. You should see entries for:

  • article
  • report
  • book
  • beamer

One of these is always used when generating LaTeX; when no #+latex_class is set in the document, the template named by org-latex-default-class will be used.

What’s great about this is that is makes it really easy to add your own templates. Each template simply takes three components:

  1. A name
  2. A preamble template
  3. A series of format strings to translate headings to LaTeX, with and without numbering

For example, I’m quite a fan of the KOMA-script family. Should I want to add a kart class (for: koma article), I simply need to do something like the following:

Emacs Lisp
#
(add-to-list 'org-latex-classes
             '("kart" ; class name
               "\\documentclass{scrartcl}" ; preamble template
               ("\\section{%s}" . "\\section*{%s}") ; H1 translation
               ("\\subsection{%s}" . "\\subsection*{%s}") ; H2 translation
               ("\\subsubsection{%s}" . "\\subsubsection*{%s}") ; H3...
               ("\\paragraph{%s}" . "\\paragraph*{%s}")
               ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))

See the documentation for org-latex-classes for more information on how the preamble template in handled.

Other improvements

  • ox-koma-letter.el has been brought into Org’s main directory from the ) contrib/ repo Bastien Guerry
  • Speed up publishing by using delayed hooks and temp buffers instead of finding files Gustav WikstrΓΆm
  • Improve generated HTML quality: prevent W3C warning and add some accessibility labels TEC
  • Make the behaviour of the “goto variant” of org-refile (org-speed-commands) less confusing Marco Wahl
  • Backport an update to the OpenDocument schema Kyle Meyer

Bugfixes

  • Off by one error in texinfo menu generation Nicolas Goaziou
  • Error in entry/conversion of non-24h times in the agenda Nicolas Goaziou
  • Only use replace-buffer-contents with Emacs 27+ when saving src blocks, as the behaviour isn’t consistent until then Nicolas Goaziou
  • Prevent “before first headline” error in org-clock when clocking out Nicolas Goaziou
  • Avoid setting the global agenda name when following a timestamp link Ingo Lohmar
  • Don’t bind <tab> in org-mode-map Nicolas Goaziou
  • Erroneous tangling of source block with :tangle no to a file no when the tangle command is called with a single universal argument Jacopo De Simoi

May 2021 2021-05-31

Async Babel sessions have landed

Jack Kamm has made a fantastic contribution to Org: ob-comint.el now supports asynchronous output from source blocks with full support for sessions πŸŽ‰.

Read more…

April 2021 2021-04-30

A discussion on contributor support

Concerns were raised[1] about some contributors’ patches languishing, and it not being made clear how long it might take to get a response from someone.

Read more…

Welcome 2021-04-26

Introduction

Org is an absolutely marvellous project. However, a quick glance at https://orgmode.org can lead one to think “so… it’s an Emacs version of Markdown? What’s the big deal?”. While it’s easy to understand how someone might think that at first, that impression misses two crucial points:

  • While for simple constructs (bold, italic, headlines, etc.) the syntax is very much analogous[1], Org scales to much more powerful forms that are a headache to replicate in Markdown

Read more…

CC0 To the extent possible under law, TEC has waived all copyright and related or neighboring rights to This Month in Org.