Create tables with paragraph-like content in Org mode, with the least amount of hassle


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

Screenshot from 2020-04-26 10-00-28

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 list table

Fortunately, there is a hassle-free solution.  It involves creating a list table.  

According to List Tables in ODT export (OpenDocument Text Exporter for Emacs’ Org Mode),

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.[1]

The manual page linked above gives examples of how one may use list tables to publish real-life tables.  Specificallyyou 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

  1. it does NOT come with standard Emacs Org mode
  2. 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.

According to Getting Started with ODT export (OpenDocument Text Exporter for Emacs’ Org Mode),

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                 9.2.6.263  ... 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 [1], and the bottom-right window that displays the HTML table is indeed a native Firefox window.

Working with List Tables in a Nutshell

Screenshot from 2020-04-26 10-09-40

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.

Conclusion

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

  1. produce ODT documents that contains Citations and Bibliography [1]
  2. apply custom styles through keywords [1]

I find feature (2) above interesting.  As an aspiring writer, I can imagine using ODT_EXTRA_STYLES [1]  to create documents in the Manuscript format. [1]

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-9.3.2.306/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.

Categories gnu

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this:
search previous next tag category expand menu location phone mail time cart zoom edit close