git.iko.soy/typeable/pandoc
on 2.10 help sign in
typeable/pandoc/doc/org.md
287 lines 9.4 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.
106Citations
107=========
109Emacs org-mode lacks an official citation syntax, leading to
110multiple syntaxes coexisting. Pandoc recognizes four different
111syntaxes for citations.
113Citation support for org-mode is enabled by default. Support can
114be toggled off by disabling the `citation` extension; e.g.
115`pandoc --from=org-citations`.
117Berkeley-style citations
118------------------------
120The semi-official Org-mode citation syntax was designed by Richard
121Lawrence with additions by contributors on the [emacs-orgmode
122mailing list]. It is based on John MacFarlane's pandoc Markdown
123syntax. It's dubbed Berkeley syntax due the place of activity of
124its creators, both philosophers at UC Berkeley.
126### Simple in-text citation
128This is the simplest form of citation. It consists of the citation
129ID prefixed by '@'.
131Example:
133 @WatsonCrick1953 showed that DNA forms a double-helix.
135### In-text citation list
137Citations presented in the text unparenthesized are called
138*in-text citations*. The syntax for these citations is
140 [cite: PREFIX; INDIVIDUAL-REFERENCE; ... INDIVIDUAL-REFERENCE; SUFFIX]
142where the initial PREFIX and final SUFFIX are optional. At least
143one INDIVIDUAL-REFERENCE must be present. The colon and
144semicolons here are literal and indicate the end of the TAG and
145the end of a PREFIX or INDIVIDUAL-REFERENCE respectively.
147An INDIVIDUAL-REFERENCE has the format:
149 PREFIX KEY SUFFIX
151The KEY is obligatory, and the prefix and suffix are optional.
153A PREFIX or SUFFIX is arbitrary text (except `;`, `]`, and
154citation keys).
156Example:
158 [cite: See; @Mandelkern1981; and @Watson1953]
160### Parenthetical citation
162Citations surrounded by parantheses. The syntax is identical to
163in-text citations, except for the additional parentheses enclosing
164the initial `cite` tag.
166 [(cite): See; @Mandelkern1981; and @Watson1953]
168[emacs-orgmode mailing list]: https://lists.gnu.org/archive/html/emacs-orgmode/2015-02/msg00932.html
170org-ref citations
171-----------------
173The [org-ref] package by [John Kitchen] is in wide use to handle
174citations and has excellent tooling support in Emacs. Its
175citation syntax is geared towards users in the natural sciences
176but still very flexible regardless.
178 cite:doe_john_2000
179 citep:doe_jane_1989
180 [[citep:Dominik201408][See page 20 of::, for example]]
183Pandoc-Markdown-like syntax
184---------------------------
186Historically, Markdown-style citations syntax was the first that
187was added to pandoc's org reader. It is close to Markdown's
188citation syntax.
190Citations go inside square brackets and are separated by
191semicolons. Each citation must have a key, composed of '@' plus
192the citation identifier from the database, and may optionally
193have a prefix, a locator, and a suffix. The citation key must
194begin with a letter, digit, or `_`, and may contain
195alphanumerics, `_`, and internal punctuation characters
196(`:.#$%&-+?<>~/`). Here are some examples:
198### Simple citation
200The simplest method to insert a citation is to write the citation
201ID prefixed by '@'.
204Example:
206 [prefix @citekey suffix]
207 [see @doe2000 pp. 23-42]
208 [@doe2000 p. 5; to a lesser extend @doe2005]
211LaTeX-Syntax
212------------
214Use normal latex citation commands like `\cite{x}` or
215`\citet{y}`.
217[org-ref]: https://github.com/jkitchin/org-ref
218[John Kitchen]: https://kitchingroup.cheme.cmu.edu/
221Emphasis rules
222==============
224Org-mode uses complex rules to decide whether a string
225represents emphasized text. In Emacs, this can be customized via
226the variable `org-emphasis-regexp-components`. A variable like
227this doesn't fit well with pandoc's model. Instead, it is
228possible to use special lines to change these values:
230 #+pandoc-emphasis-pre: "-\t ('\"{"
231 #+pandoc-emphasis-post: "-\t\n .,:!?;'\")}["
233The above describes the default values of these variables. The
234arguments must be valid (Haskell) strings. If interpretation of
235the argument as string fails, the default is restored.
237Changing emphasis rules only affect the part of the document
238following the special lines. They must be some of the first
239lines to alter parsing behavior for the whole document. It is
240also possible to change the values temporarily for selected
241sections only. The string `test` in the following snippet will
242be read as emphasized text, while the rest of the document will
243be parsed using default emphasis rules:
245 #+pandoc-emphasis-pre: "["
246 #+pandoc-emphasis-post: "]"
247 [/test/]
248 #+pandoc-emphasis-pre:
249 #+pandoc-emphasis-post:
251`smart` extension
252=================
254Org-mode allows to insert certain characters via special character
255sequences. For example, instead of typing the Unicode /HORIZONTAL
256ELLISPIS/ character `…` by hand, one can instead type tree dots
257`...`. En dashes and em dashes can be written as `--` and `---`
258respectively. Furthermore, quotation marks (`"`) and
259apostrophe-quotes (`'`) can be treated in a "smart" way,
260potentially replacing them with proper, language specific unicode
261quotation characters.
263Like in Markdown, these behaviors can be turned on all-at-once by
264enabling the `smart` extension. However, disabling `smart` (the
265default) will *not* necessarily disable smart quotes and special
266strings. Instead, it will just result in the default Org mode
267behavior.
269The special string feature can be turned off via the `#+OPTIONS:
270-:nil` [export setting]. There are currently no command line flags
271which control these features. As a workaround, one can use process
272substitution, a feature supported by most shells. It allows to
273provide the options line on the command line:
275 pandoc -f org <(printf "#+OPTIONS: -:nil\n") …
277[export setting]: https://orgmode.org/manual/Export-Settings.html
279Currently unsupported features
280==============================
282Library of babel
283----------------
285The library of babel translates between various programming
286languages. This is out-of-scope for pandoc. Use Emacs to run
287code, then feed the resulting org file to pandoc.