The Problem: It is impossible or bothersome to create Org mode tables that have paragraph-like content
Are you an Emacs Org mode user who wanted to publish a document that had a real-life table in it? If “yes”, you know how impossible or bothersome it is to create and edit such a table.
When I say a real-life table, I do NOT mean a very elaborate table that you see in some large Wikipedia pages, but a very mundane one that contains so much as even a single large paragraph.
Specifically, can you publish an HTML table like the one below using Org mode?
A HTML table with complex content
Before you jump to a solution, note that the 2nd-column of the table contains lists.
The sad answer is, it is impossible
A Solution to above Challenge: Use a
Fortunately, there is a hassle-free solution. It involves creating a
‘List Table’, in simple terms, is a list that is typeset as a table. Use it to create tables with multi-paragraph content.
- Why a ‘List Table’?
Org mode’s tables are line-oriented i.e., each row (and hence a cell) cannot span multiple lines. This choice has serious limitations. Specifically,
- a table cell cannot have more than a single paragraph
- if the sole paragraph has copious text, the table will overflow your display screen, and editing or reviewing such tables is very cumbersome and annoying.
A list table overcomes the above problem.
Lists that are marked with attribute
‘:list-table’are called as list tables. They will be rendered as a table within the exported document.
Note that a List table as defined above sounds similar to the eponymous one in reStructuredText.
The manual page linked above gives examples of how one may use list tables to publish real-life tables. Specifically, you can publish a table that has multiple paragraphs, lists or even sub-tables. You can also use it to create a tile of inlined images. The HTML table that you see in the challenge is also borrowed from the manual page.
A Problem with above Solution: ‘List tables’ are NOT part of standard Org mode
The only hassle with a list table is
- it does NOT come with standard Emacs Org mode
- it works only with ODT export
Solutions to above Problems
Step 1: Install the enhanced OpenDocument Text Exporter
Remember the OpenDocument Text exporter is NOT the one that comes with stock Emacs. It is an enhanced one, and is available in a separate repository of it’s own.
You can install the OpenDocument Text export backend using the Emacs package manager. The archive URL for the package is https://kjambunathan.github.io/elpa/.
A typical configuration look like this
(custom-set-variables '(package-archives (quote (("gnu" . "https://elpa.gnu.org/packages/") ("ox-odt" . "https://kjambunathan.github.io/elpa/")))))
In the ‘Packages’ buffer, packages from this archive show up as below
JabrefExportChicagoODF 1.2.2 ... Jabref Plugin for export to Chicago Manual of Style in OpenDocumentFormat ox-odt 22.214.171.1243 ... OpenDocument Text Exporter for Org Mode
Step 2: Install the export filter for list table in to HTML exporter
To overcome (2), add the following snippet to your .emacs
(with-eval-after-load 'ox-html (unless (featurep 'ox-odt) (require 'ox-odt)) (add-to-list 'org-export-filter-parse-tree-functions (defun org-html--translate-list-tables (tree backend info) (if (eq backend 'html) (org-odt--translate-list-tables tree backend info) tree))))
Step 3: Create a list table, and export it
To publish a HTML table that you saw in the challenge, create a following snippet, and export it.
#+ATTR_ODT: :list-table t - | / | < | > | | - | <l2> | <l1> | <l1> | <l8> | - - Day - Min Temp - Max Temp - Summary - ---------------- - Monday - 11C - 22C - 1. A clear day with lots of sunshine. 2. Late in the day, a strong breeze will bring down the temperatures. - ---------------- - Tuesday - 9C - 19C - 1. Cloudy with rain, across many northern regions. 2. Clear spells across most of Scotland and Northern Ireland, but rain reaching the far northwest.
The screenshot below summarizes the above steps in a nutshell. Note that I am running
EXWM , and the bottom-right window that displays the HTML table is indeed a native Firefox window.
Working with List Tables in a Nutshell
The HTML table matches the Org table. Specifically, the table header, row and column rules, are carried over. (My experiments suggests that) The column alignments also get carried over. However, the relative column widths are NOT getting carried over. The issue with column widths suggests the HTML export engine may require further changes to work with ODT backend’s list table export filter.
A list table is a life-saver for me. Publishing true-to-life tables from within Org mode is no more a tedious task. Instead it is a pleasurable one.
That said … the enhanced OpenDocument Text exporter looks interesting. It has many add-on features that are NOT available with standard Emacs.
According to What is New (OpenDocument Text Exporter for Emacs’ Org Mode), you can use the enhanced ODT exporter to
- produce ODT documents that contains Citations and Bibliography 
- apply custom styles through keywords 
Last but not the least, the enhanced ODT exporter not only has an online HTML manual, but also a Info manual. You can access the Info manual from within the
ELPA installation directory. In my case, I could access it with
C-u C-h i ~/.emacs.d/elpa/ox-odt-126.96.36.1996/docs/org-odt. In the screenshot above, you can see the
*info* node for
list table. The
Info manual contains images. In my decades of use, I have never seen a
Info manual with screenshots and images. Needless to say, I am very excited about the enhanced ODT exporter. I heartily recommend it.