Pandoc handles most text format conversions effortlessly, but there are some major glitches when the source is Emacs Org.
Numbering of Headings and Unwanted Table of Contents
The first is Pandoc’s tendency to automatically attribute numbers to chapter headings in a single-file Emacs Org input. Thus the prerequisites to the problem are:
- A single Emacs Org source file with headings in the text
- Convert to e.g. Epub with Pandoc
You may have your headings numbered your own way in the Emacs Org source file, but Pandoc will re-number them again. If such numbering of the headings by Pandoc is undesirable, the Org file needs a metadata section (which I normally do not use). Pandoc takes note of the metadata section in Emacs Org files.
Pandoc also generates a table of contents when creating an Epub. Table of Contents is nice maybe for some purposes, such as the first page of a magnum opus Word document (Pandoc can do this conversion also), but not when it appears as an introductory chapter in Epub in addition to the structural and ereader-navigable table of contents function. In Epubs that kind of additional unwanted Table of Contents is to be eliminated.
Here’s a useful metadata section to the very beginning of an Emacs Org file:
#+date: #+author: #+title: #+options: toc:nil #+options: num:nil #+language: en #+description:
The two lines with #+options: prevent numbering of headings and the unexpected table of contents from being generated while exporting Emacs Org files to other formats. Other metadata lines here are just examples of usable lines. It’s safe to have empty metadata lines.
Caps + . = List?
In prose (that is Emacs Org), some paragraphs may start as e.g. C. Iulius Caesar.
Pandoc interprets this kind of beginning of paragraph as a list item on export and numbers it grossly (and mangles the formatting of the rest of the chapter also). Unfortunately there is no lists:nil option in Org metadata. (And why should there be? Plain prose should not need special settings like this.)
The workaround that I have found for now is to concatenate “C. Iulius Caesar” to “C.Iulius Caesar”. That is, rigidly avoid any sequence of caps-dot-space in the beginning of paragraphs or lines.
Some study of Pandoc man page seems to suggest that it should work to turn off Pandoc’s fancy_lists extension while exporting, but I have found this to be of no avail.
