git.iko.soy/typeable/pandoc
on dark-mode help sign in
typeable/pandoc/doc/org.md
365 lines 12 kB history raw
1---
2title: Org-mode features and differences
3author: Albert Krewinkel
4---
6Pandoc's handling of org files is similar to that of Emacs
7org-mode. This document aims to highlight the cases where this is
8not possible or just not the case yet.
10Export options
11==============
13The following export keywords are supported:
15- AUTHOR: comma-separated list of author(s); fully supported.
17- CREATOR: output generator; passed as plain-text metadata entry
18 `creator`, but not used by any default templates.
20- DATE: creation or publication date; well supported by pandoc.
22- EMAIL: author email address; passed as plain-text metadata
23 field `email`, but not used by any default templates.
25- LANGUAGE: document language; included as plain-text metadata
26 field `lang`. The value should be a [BCP47 language tag].
28- SELECT_TAGS: tags which select a tree for export. Currently
29 *unsupported*.
31- EXCLUDE\_TAGS: tags which prevent a subtree from being
32 exported. Fully supported.
34- TITLE: document title; fully supported.
36- EXPORT\_FILE\_NAME: target filename; *unsupported*, the output
37 defaults to stdout unless a target has to be given as a command
38 line option.
40[BCP47 language tag]: https://tools.ietf.org/html/bcp47
42Format-specific options
43-----------------------
45Emacs Org-mode supports additional export options which work for
46specific export formats. Some of these options' behavior differs
47in Org-mode depending on the output format, while pandoc is
48format-agnostic when parsing; differences are noted where they
49occur.
51- DESCRIPTION: the document's description; pandoc parses this
52 option as text with markup into the `description` metadata
53 field. The field is not used in default templates.
55 Pandoc follows the LaTeX exporter in that it allows markup in
56 the description. In contrast, the Org-mode HTML exporter treats
57 the description as plain text.
59- LATEX\_HEADER and LATEX_HEADER_EXTRA: arbitrary lines to add to
60 the document's preamble. Contrary to Org-mode, these lines are
61 not inserted before the hyperref settings, but close to the end
62 of the preamble.
64 The contents of this option are stored as a list of raw LaTeX
65 lines in the `header-includes` metadata field.
67- LATEX\_CLASS: the LaTeX document class; like Org-mode, pandoc
68 uses `article` as the default class.
70 The contents of this option are stored as plain text in the
71 `documentclass` metadata field.
73- LATEX\_CLASS\_OPTIONS: Options for the LaTeX document class;
74 fully supported.
76 The contents of this option are stored as plain text in the
77 `classoption` metadata field.
79- SUBTITLE: the document's subtitle; fully supported.
81 The content of this option is stored as inlines in the
82 `subtitle` metadata field.
84- HTML\_HEAD and HTML\_HEAD\_EXTRA: arbitrary lines to add to the
85 HTML document's head; fully supported.
87 The contents of these options are stored as a list of raw HTML
88 lines in the `header-includes` metadata field.
90Pandoc-specific options
91-----------------------
93Pandoc recognizes some export options not used by Emacs Org.
95- NOCITE: this field adds the listed citations to the
96 bibliography, without the need to mention them to the text. The
97 special value `@*` causes all available references to be added
98 the bibliography.
100- HEADER-INCLUDES: like HTML_HEAD and, LATEX_HEADER, but treats
101 the option's value as normal text with markup.
103- INSTITUTE: Affiliation of the author; the value is read as text
104 with markup and is stored in the `institute` metadata field. The
105 field is included by default on the title slide of beamer
106 presentations.
108Other options
109-------------
111Any export option or directive not listed above has no effect when
112parsing with pandoc. However, the information is retained as a
113*raw block*. It can be accessed through a
114[filter](https://pandoc.org/filters.html) and will be included in
115org output.
117### Directives as metadata
119As an example, we will restore an old behavior of pandoc versions
120prior to 2.10. Unknown keywords were treated as variable
121definitions, and were added the document's metadata. Typing
122`#+key: value` in the org-file used to have the same effect as
123running pandoc with the `--metadata key=value` option.
125Since pandoc 2.10, each unhandled line starting with `#+` is kept
126internally as a raw block with format `org`. This block can be
127inspected and processed by a filter. Below is a [Lua
128filter](https://pandoc.org/lua-filters.html) which converts these
129unhandled lines into metadata key-value pairs.
131``` lua
132-- intermediate store for variables and their values
133local variables = {}
135--- Function called for each raw block element.
136function RawBlock (raw)
137 -- Don't do anything unless the block contains *org* markup.
138 if raw.format ~= 'org' then return nil end
140 -- extract variable name and value
141 local name, value = raw.text:match '#%+(%w+):%s*(.+)$'
142 if name and value then
143 variables[name] = value
144 end
145end
147-- Add the extracted variables to the document's metadata.
148function Meta (meta)
149 for name, value in pairs(variables) do
150 meta[name] = value
151 end
152 return meta
153end
154```
156Citations
157=========
159Emacs org-mode lacks an official citation syntax, leading to
160multiple syntaxes coexisting. Pandoc recognizes four different
161syntaxes for citations.
163Citation support for org-mode is enabled by default. Support can
164be toggled off by disabling the `citation` extension; e.g.
165`pandoc --from=org-citations`.
167Berkeley-style citations
168------------------------
170The semi-official Org-mode citation syntax was designed by Richard
171Lawrence with additions by contributors on the [emacs-orgmode
172mailing list]. It is based on John MacFarlane's pandoc Markdown
173syntax. It's dubbed Berkeley syntax due the place of activity of
174its creators, both philosophers at UC Berkeley.
176### Simple in-text citation
178This is the simplest form of citation. It consists of the citation
179ID prefixed by '@'.
181Example:
183 @WatsonCrick1953 showed that DNA forms a double-helix.
185### In-text citation list
187Citations presented in the text unparenthesized are called
188*in-text citations*. The syntax for these citations is
190 [cite: PREFIX; INDIVIDUAL-REFERENCE; ... INDIVIDUAL-REFERENCE; SUFFIX]
192where the initial PREFIX and final SUFFIX are optional. At least
193one INDIVIDUAL-REFERENCE must be present. The colon and
194semicolons here are literal and indicate the end of the TAG and
195the end of a PREFIX or INDIVIDUAL-REFERENCE respectively.
197An INDIVIDUAL-REFERENCE has the format:
199 PREFIX KEY SUFFIX
201The KEY is obligatory, and the prefix and suffix are optional.
203A PREFIX or SUFFIX is arbitrary text (except `;`, `]`, and
204citation keys).
206Example:
208 [cite: See; @Mandelkern1981; and @Watson1953]
210### Parenthetical citation
212Citations surrounded by parentheses. The syntax is identical to
213in-text citations, except for the additional parentheses enclosing
214the initial `cite` tag.
216 [(cite): See; @Mandelkern1981; and @Watson1953]
218[emacs-orgmode mailing list]: https://lists.gnu.org/archive/html/emacs-orgmode/2015-02/msg00932.html
220org-ref citations
221-----------------
223The [org-ref] package by [John Kitchen] is in wide use to handle
224citations and has excellent tooling support in Emacs. Its
225citation syntax is geared towards users in the natural sciences
226but still very flexible regardless.
228 cite:doe_john_2000
229 citep:doe_jane_1989
230 [[citep:Dominik201408][See page 20 of::, for example]]
233Pandoc-Markdown-like syntax
234---------------------------
236Historically, Markdown-style citations syntax was the first that
237was added to pandoc's org reader. It is close to Markdown's
238citation syntax.
240Citations go inside square brackets and are separated by
241semicolons. Each citation must have a key, composed of '@' plus
242the citation identifier from the database, and may optionally
243have a prefix, a locator, and a suffix. The citation key must
244begin with a letter, digit, or `_`, and may contain
245alphanumerics, `_`, and internal punctuation characters
246(`:.#$%&-+?<>~/`). Here are some examples:
248### Simple citation
250The simplest method to insert a citation is to write the citation
251ID prefixed by '@'.
254Example:
256 [prefix @citekey suffix]
257 [see @doe2000 pp. 23-42]
258 [@doe2000 p. 5; to a lesser extend @doe2005]
261LaTeX-Syntax
262------------
264Use normal latex citation commands like `\cite{x}` or
265`\citet{y}`.
267[org-ref]: https://github.com/jkitchin/org-ref
268[John Kitchen]: https://kitchingroup.cheme.cmu.edu/
270Tables
271======
273Pandoc supports normal org tables (sometimes called "pipe tables")
274and grid tables (tables created by [table.el]).
276Column widths
277-------------
279Org mode tables don't allow line-breaks within cells, and lines
280which contain text can get very long. This often leads to tables
281which run off the page when exporting, especially when exporting
282to PDF via LaTeX. Overlong lines in the source text are this is
283usually hidden by setting a [column width], but the default Emacs
284exporters ignore that setting. Pandoc deviates from Emacs's
285behavior and uses this information to resize the table columns
286when exporting.
288Limitations
289-----------
291There is no support yet for cells spanning multiple columns or
292rows. The table.el grid tables allows rowspans and colspans and so
293does pandoc's internal structure since 2.10, but the parser has
294not been updated yet.
296[table.el]: http://table.sourceforge.net/
297[column width]: https://orgmode.org/manual/Column-Width-and-Alignment.html
299Emphasis rules
300==============
302Org-mode uses complex rules to decide whether a string
303represents emphasized text. In Emacs, this can be customized via
304the variable `org-emphasis-regexp-components`. A variable like
305this doesn't fit well with pandoc's model. Instead, it is
306possible to use special lines to change these values:
308 #+pandoc-emphasis-pre: "-\t ('\"{"
309 #+pandoc-emphasis-post: "-\t\n .,:!?;'\")}["
311The above describes the default values of these variables. The
312arguments must be valid (Haskell) strings. If interpretation of
313the argument as string fails, the default is restored.
315Changing emphasis rules only affect the part of the document
316following the special lines. They must be some of the first
317lines to alter parsing behavior for the whole document. It is
318also possible to change the values temporarily for selected
319sections only. The string `test` in the following snippet will
320be read as emphasized text, while the rest of the document will
321be parsed using default emphasis rules:
323 #+pandoc-emphasis-pre: "["
324 #+pandoc-emphasis-post: "]"
325 [/test/]
326 #+pandoc-emphasis-pre:
327 #+pandoc-emphasis-post:
329`smart` extension
330=================
332Org-mode allows to insert certain characters via special character
333sequences. For example, instead of typing the Unicode /HORIZONTAL
334ELLISPIS/ character `…` by hand, one can instead type tree dots
335`...`. En dashes and em dashes can be written as `--` and `---`
336respectively. Furthermore, quotation marks (`"`) and
337apostrophe-quotes (`'`) can be treated in a "smart" way,
338potentially replacing them with proper, language specific unicode
339quotation characters.
341Like in Markdown, these behaviors can be turned on all-at-once by
342enabling the `smart` extension. However, disabling `smart` (the
343default) will *not* necessarily disable smart quotes and special
344strings. Instead, it will just result in the default Org mode
345behavior.
347The special string feature can be turned off via the `#+OPTIONS:
348-:nil` [export setting]. There are currently no command line flags
349which control these features. As a workaround, one can use process
350substitution, a feature supported by most shells. It allows to
351provide the options line on the command line:
353 pandoc -f org <(printf "#+OPTIONS: -:nil\n") …
355[export setting]: https://orgmode.org/manual/Export-Settings.html
357Currently unsupported features
358==============================
360Library of babel
361----------------
363The library of babel translates between various programming
364languages. This is out-of-scope for pandoc. Use Emacs to run
365code, then feed the resulting org file to pandoc.