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 😛

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 🎉.

If you haven’t used sessions before, you’re in for a treat! By simply assigning a named session to a source code block, e.g. :session foo, the same process will be reused for any other code blocks that specify the foo session. To do this for a certain language across the entire document, you can set the header argument property, i.e.

Org mode
#
#+property: header-args:lang :session foo

Along with the asyncronous process communication in ob.comint.el, we have an implementation for Python, and we should see support for R and Ruby in the not-too-distant future 😍.

To use this, just add the :async parameter to a python block. Instead of Emacs freezing until it completes execution, you’ll see a placeholder inserted which is replaced by the result when it is ready.

Figure 0: A demonstration of the new asyncronous Python execution capabilities.

emacs-jupyter allowed for asynchronous code execution (with sessions), but it’s great to have a solution that doesn’t require Jupyter kernels, and is part of Org.

Font lock for inline export snippets

Now, this isn’t necessarily a significant change, but I don’t think many people know about this feature so I’ll take the opportunity to go over it 🙂.

If you want to include a snippet of HTML/LaTeX etc. when exporting to that format, you can use a #+begin_export html block which simply includes the enclosed content verbatim. This doesn’t really work for small inline snippets though — but never fear, Org has inline export snippets which simply follow the form @@format:content@@. For example:

Org mode
#
I love using Org to export to @@html:<abbr title="Hyper Text Markup Language">HTML</abbr>@@ @@latex:\LaTeX{}@@ documents.

which will export to HTML as,

HTML
#
I love using Org to export to <abbr title="Hyper Text Markup Language">HTML</abbr> documents.

and then in LaTeX will be,

LaTeX
#
I love using Org to export to \LaTeX{} documents.

isn’t that neat!

Now you’ll find the @@ parts using the comment face and the format: bit using the Org tag’s face. It’s a small change, but it makes it easier to see what’s going on.

No mode-specific syntax hightlighting yet, but that may come in the future 😉.

#+plot your #+results

Org-plot has been getting some more love as of late (see last month’s post), and that hasn’t stopped yet. This month there’s been a fairly minor change that I’m quite a fan of. If you have a source block that produces a table of #+results, you can now put a #+plot statement immediately above to get a visualisation of those results!

Org mode
#
#+begin_src python
# pretend this is some profound source of information
return [[i, i^3 - 4*i^2 - 2*i] for i in range(5)]
#+end_src

#+plot: ind:1
#+RESULTS:
| 0 |  1 |
| 1 | -2 |
| 2 |  7 |
| 3 |  8 |
| 4 | 13 |

As usual, this relies on gnuplot being present. You can read more about it in the manual.

Fancier LaTeX verses

With the use of verse.sty you can now export fancier verses from Org, as verse blocks now support four new attributes:

  • :lines for the numbering interval.
  • :center which can be set to t and works as long as,
    • :versewidth, the longest line in the verse as a text string is set.
  • You can also easily add arbitrary LaTeX code to be included with :latexcode.
Org mode
#
#+latex_header: \usepackage{verse}

#+latex: \poemtitle{A Dream Within a Dream}
#+attr_latex: :lines 3 :center t
#+attr_latex: :versewidth Through my fingers to the deep,
#+begin_verse
Take this kiss upon the brow!
And, in parting from you now,
Thus much let me avow —
You are not wrong, who deem
That my days have been a dream;
Yet if hope has flown away
In a night, or in a day,
In a vision, or in none,
Is it therefore the less gone?
All that we see or seem
Is but a dream within a dream.

I stand amid the roar
Of a surf-tormented shore,
And I hold within my hand
Grains of the golden sand —
How few! yet how they creep
Through my fingers to the deep,
While I weep — while I weep!
O God! Can I not grasp
Them with a tighter clasp?
O God! can I not save
One from the pitiless wave?
Is all that we see or seem
But a dream within a dream?
#+end_verse
org-verses-example-poem-dream-within-dream.png
Figure 1: A short Poe-em

Easy zero-width spaces with Org

Occasionally you may run into annoyances when you wish to have two different Org elements right next to each other (no space) — for example, emphasising part of a word or putting a currency symbol immediately before an inline source block.

The best solution to this in Org is zero-width spaces. As such, I’ve found it rather nice adding insertion of a zero-width space to the org-mode-map in my config. Perhaps some of you might find this solution useful too 🙂.

Emacs Lisp
#
(define-key org-mode-map (kbd "M-SPC M-SPC")
  (lambda () (interactive) (insert "\u200b")))

Should you want to keep zero-width spaces out of exports, that’s easy enough to accomplish with an export filter.

Emacs Lisp
#
(defun +org-export-remove-zero-width-space (text _backend _info)
  "Remove zero width spaces from TEXT."
  (unless (org-export-derived-backend-p 'org)
    (replace-regexp-in-string "\u200b" "" text)))

(add-to-list 'org-export-filter-final-output-functions #'+org-export-remove-zero-width-space t)

Org’s repos have moved

Other improvements

  • Add support for HHhMM date formats (e.g. 13h20) Gustavo Barros
  • Make tangling faster and more robust Sébastien Miquel
  • Allow importing tables from files that don’t end in .txt, .tsv, or .csv Utkarsh Singh
  • Add an SVG-specific post-export ob-plantuml step: org-babel-plantuml-svg-text-to-path for running Inkscape text-to-path replacement Nick Daly
  • Refactor JavaScript in ox-html Anthony Carrico
  • Set org-html-head-include-scripts to nil by default (was t) Bastien Guerry
  • Remove LaTeX-environment type #+results TEC
  • New capture templates parameter, :refile-targets Richard Garner
  • Merge org-speed-commands-default and org-speed-commands-user into a new variable, org-speed-commands Bastien Guerry
  • URL recognition regex now handles up to two levels of nested brackets, and is tested Ihor Radchenko
  • Cache parent heading positions for faster movement up buffers. Significantly improves Org queries involving inheritance (~15-50x improvement) Ihor Radchenko
  • New command org-refile-reverse bound to C-c C-M-w Adam Spiers
  • Allow inline tasks to be dragged up/down Bastien Guerry
  • LaTeX export, allow arbitrary :float values Thomas S. Dye
  • Org attach git, new option org-attach-git-dir to use the attachment dir as a git repository Juan Manuel Macías
  • Use a write-back buffer in Org src Sébastien Miquel
  • Add the :environment and :options LaTeX attributes to Quote blocks Juan Manuel Macias
  • Surround LaTeX :options attribute with curly braces when it contains square braces Markus Huber
  • Recognise the specific contributions of Kyle Meyer, Ihor Radchenko, and TEC in the manual Bastien Guerry
  • Improve test coverage Ihor Radchenko, Kévin Le Gouguec
  • A bikeshed of new maintainers
    • New maintainer for ox-htmlTEC
    • New ob-ledger maintainer — Eric S Fraga
    • New ob-awk maintainer — Tyler Smith
    • New ob-calc maintainer — Tom Gillespie
    • New ob-asymptote and ob-coq maintainer — Luc Pellissier
  • General code cleanup Bastien Guerry
  • Documentation improvements Bastien Guerry, Eric S Fraga, Samim Pezeshki, Nicolar Goaziou

Bugfixes

  • Make ob-gnuplot work on remote systems Ihor Radchenko
  • Stop M-x org-toggle-link-display from affecting emphasis markers Bastien Guerry
  • Inserting a heading before a headline Bastien Guerry
  • Perform org-entry-put in a read-only buffer Ihor Radchenko
  • Emacs 24 compatibility for ob-C and org-agenda-show-new-time Kyle Meyer
  • Maintain Org’s keybindings when visual-line-mode active Bastien Guerry
  • Keep track of start of region beginning in org-table-wrap-region Bastien Guerry
  • Ensure correct visibility when unfolding subtree Bastien Guerry
  • Corner case in org--backwards-paragaph-once Bastien Guerry
  • Some byte compiler silencing Kyle Meyer
  • Make tags filtering case-sensitive Bastien Guerry
  • C-c C-c on a #+plot line can no longer cause an error Bastien Guerry
  • Ensure consistent position-translation in org-src by using point for position instead of column TEC
  • Prevent ob-sql from getting stuck on an error Ivan Sokolov
  • Make org-columns respect global-visual-line-mode, and simplify tag scanning Nick Savage
  • Don’t fontify :: in headlines as description item Ihor Radchenko
  • Handle a few corner-cases in ob-R Jeremie Juste
  • Many fixes to org-indent-line Bastien Guerry
  • Make headline numbering consistent with TOC Mingkai Dong
  • Allow read-only tangling again, and ensure the correct filename is used Sébastien Miquel
  • Fix edge case when converting durations to minutes Nicolas Goaziou
  • Make org-refile work in non-file-visiting buffers Bastien Guerry
  • Be more rigorous in org-sort-remove-invisible Nicolas Goaziou
  • Don’t update checkbox stats when heading has todo COOKIE_DATA Bastien Guerry
  • Don’t recognise a lone :END: to be forming a drawer Nicolas Goaziou
  • Allow new footnotes in empty table cells Nicolas Goaziou

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.