git.iko.soy/typeable/pandoc
on rc/2.9.1.1 help sign in
typeable/pandoc/doc/org.md
194 lines 5.8 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 metadata entry, but
18 ignored by most output formats.
20- DATE: creation or publication date; well supported by pandoc.
22- EMAIL: author email address; passed as metadata entry, but not
23 included in most output formats.
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.
40Citations
41=========
43Emacs org-mode lacks an official citation syntax, leading to
44multiple syntaxes coexisting. Pandoc recognizes four different
45syntaxes for citations.
47Citation support for org-mode is enabled by default. Support can
48be toggled off by disabling the `citation` extension; e.g.
49`pandoc --from=org-citations`.
51Berkeley-style citations
52------------------------
54The semi-official Org-mode citation syntax was designed by Richard
55Lawrence with additions by contributors on the [emacs-orgmode
56mailing list]. It is based on John MacFarlane's pandoc Markdown
57syntax. It's dubbed Berkeley syntax due the place of activity of
58its creators, both philosophers at UC Berkeley.
60### Simple in-text citation
62This is the simplest form of citation. It consists of the citation
63ID prefixed by '@'.
65Example:
67 @WatsonCrick1953 showed that DNA forms a double-helix.
69### In-text citation list
71Citations presented in the text unparenthesized are called
72*in-text citations*. The syntax for these citations is
74 [cite: PREFIX; INDIVIDUAL-REFERENCE; ... INDIVIDUAL-REFERENCE; SUFFIX]
76where the initial PREFIX and final SUFFIX are optional. At least
77one INDIVIDUAL-REFERENCE must be present. The colon and
78semicolons here are literal and indicate the end of the TAG and
79the end of a PREFIX or INDIVIDUAL-REFERENCE respectively.
81An INDIVIDUAL-REFERENCE has the format:
83 PREFIX KEY SUFFIX
85The KEY is obligatory, and the prefix and suffix are optional.
87A PREFIX or SUFFIX is arbitrary text (except `;`, `]`, and
88citation keys).
90Example:
92 [cite: See; @Mandelkern1981; and @Watson1953]
94### Parenthetical citation
96Citations surrounded by parantheses. The syntax is identical to
97in-text citations, except for the additional parentheses enclosing
98the initial `cite` tag.
100 [(cite): See; @Mandelkern1981; and @Watson1953]
102[emacs-orgmode mailing list]: https://lists.gnu.org/archive/html/emacs-orgmode/2015-02/msg00932.html
104org-ref citations
105-----------------
107The [org-ref] package by [John Kitchen] is in wide use to handle
108citations and has excellent tooling support in Emacs. Its
109citation syntax is geared towards users in the natural sciences
110but still very flexible regardless.
112 cite:doe_john_2000
113 citep:doe_jane_1989
114 [[citep:Dominik201408][See page 20 of::, for example]]
117Pandoc-Markdown-like syntax
118---------------------------
120Historically, Markdown-style citations syntax was the first that
121was added to pandoc's org reader. It is close to Markdown's
122citation syntax.
124Citations go inside square brackets and are separated by
125semicolons. Each citation must have a key, composed of '@' plus
126the citation identifier from the database, and may optionally
127have a prefix, a locator, and a suffix. The citation key must
128begin with a letter, digit, or `_`, and may contain
129alphanumerics, `_`, and internal punctuation characters
130(`:.#$%&-+?<>~/`). Here are some examples:
132### Simple citation
134The simplest method to insert a citation is to write the citation
135ID prefixed by '@'.
138Example:
140 [prefix @citekey suffix]
141 [see @doe2000 pp. 23-42]
142 [@doe2000 p. 5; to a lesser extend @doe2005]
145LaTeX-Syntax
146------------
148Use normal latex citation commands like `\cite{x}` or
149`\citet{y}`.
151[org-ref]: https://github.com/jkitchin/org-ref
152[John Kitchen]: https://kitchingroup.cheme.cmu.edu/
155Emphasis rules
156==============
158Org-mode uses complex rules to decide whether a string
159represents emphasized text. In Emacs, this can be customized via
160the variable `org-emphasis-regexp-components`. A variable like
161this doesn't fit well with pandoc's model. Instead, it is
162possible to use special lines to change these values:
164 #+pandoc-emphasis-pre: "-\t ('\"{"
165 #+pandoc-emphasis-post: "-\t\n .,:!?;'\")}["
167The above describes the default values of these variables. The
168arguments must be valid (Haskell) strings. If interpretation of
169the argument as string fails, the default is restored.
171Changing emphasis rules only affect the part of the document
172following the special lines. They must be some of the first
173lines to alter parsing behavior for the whole document. It is
174also possible to change the values temporarily for selected
175sections only. The string `test` in the following snippet will
176be read as emphasized text, while the rest of the document will
177be parsed using default emphasis rules:
179 #+pandoc-emphasis-pre: "["
180 #+pandoc-emphasis-post: "]"
181 [/test/]
182 #+pandoc-emphasis-pre:
183 #+pandoc-emphasis-post:
186Currently unsupported features
187==============================
189Library of babel
190----------------
192The library of babel translates between various programming
193languages. This is out-of-scope for pandoc. Use Emacs to run
194code, then feed the resulting org file to pandoc.