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