@@ -3,8 +3,38 @@ title: Org-mode features and differences
33author: Albert Krewinkel
44---
55
6−Pandoc handles org files very similarly to Emacs org-mode.
7−However, there are differences worth highlighting.
6+Pandoc's handling of org files is similar to that of Emacs
7+org-mode. This document aims to highlight the cases where this is
8+not possible or just not the case yet.
9+
10+Export options
11+==============
12+
13+The following export keywords are supported:
14+
15+- AUTHOR: comma-separated list of author(s); fully supported.
16+
17+- CREATOR: output generator; passed as metadata entry, but
18+ ignored by most output formats.
19+
20+- DATE: creation or publication date; well supported by pandoc.
21+
22+- EMAIL: author email address; passed as metadata entry, but not
23+ included in most output formats.
24+
25+- LANGUAGE: currently unsupported; use `#+LANG:` instead.
26+
27+- SELECT_TAGS: tags which select a tree for export. Currently
28+ *unsupported*.
29+
30+- EXCLUDE\_TAGS: tags which prevent a subtree from being
31+ exported. Fully supported.
32+
33+- TITLE: document title; fully supported.
34+
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.
838
939
1040Citations
@@ -14,28 +44,70 @@ Emacs org-mode lacks an official citation syntax, leading to
1444multiple syntaxes coexisting. Pandoc recognizes four different
1545syntaxes for citations.
1646
47+Citation support for org-mode is enabled by default. Support can
48+be toggled off by disabling the `citation` extension; e.g.
49+`pandoc --from=org-citations`.
50+
1751Berkeley-style citations
1852------------------------
1953
20−The semi-offical Org-mode citation syntax is based on John
21−MacFarlane's Pandoc syntax and org-oriented enhancements
22−contributed by Richard Lawrence and others. It's dubbed Berkeley
23−syntax due the place of activity of its main contributors.
54+The semi-offical Org-mode citation syntax was designed by Richard
55+Lawrence with additions by contributors on the [emacs-orgmode
56+mailing list]. It is based on John MacFarlane's pandoc Markdown
57+syntax. It's dubbed Berkeley syntax due the place of activity of
58+its creators, both philosophers at UC Berkeley.
59+
60+### Simple in-text citation
61+
62+This is the simplest form of citation. It consists of the citation
63+ID prefixed by '@'.
64+
65+Example:
66+
67+ @WatsonCrick1953 showed that DNA forms a double-helix.
68+
69+### In-text citation list
70+
71+Citations presented in the text unparenthesized are called
72+*in-text citations*. The syntax for these citations is
73+
74+ [cite: PREFIX; INDIVIDUAL-REFERENCE; ... INDIVIDUAL-REFERENCE; SUFFIX]
75+
76+where the initial PREFIX and final SUFFIX are optional. At least
77+one INDIVIDUAL-REFERENCE must be present. The colon and
78+semicolons here are literal and indicate the end of the TAG and
79+the end of a PREFIX or INDIVIDUAL-REFERENCE respectively.
80+
81+An INDIVIDUAL-REFERENCE has the format:
82+
83+ PREFIX KEY SUFFIX
84+
85+The KEY is obligatory, and the prefix and suffix are optional.
86+
87+A PREFIX or SUFFIX is arbitrary text (except `;`, `]`, and
88+citation keys).
2489
2590Example:
2691
27− See @john_doe_2006.
2892 [cite: See; @Mandelkern1981; and @Watson1953]
93+
94+### Parenthetical citation
95+
96+Citations surrounded by parantheses. The syntax is identical to
97+in-text citations, except for the addtional parentheses enclosing
98+the initial `cite` tag.
99+
29100 [(cite): See; @Mandelkern1981; and @Watson1953]
30101
102+[emacs-orgmode mailing list]: https://lists.gnu.org/archive/html/emacs-orgmode/2015-02/msg00932.html
31103
32104org-ref citations
33105-----------------
34106
35−The [org-ref] package is in wide use to handle citations and has
36−excellent tooling support in Emacs. Its citation syntax is
37−geared towards users in the natural sciences but still very
38−flexible regardless.
107+The [org-ref] package by [John Kitchen] is in wide use to handle
108+citations and has excellent tooling support in Emacs. Its
109+citation syntax is geared towards users in the natural sciences
110+but still very flexible regardless.
39111
40112 cite:doe_john_2000
41113 citep:doe_jane_1989
@@ -46,13 +118,28 @@ Pandoc-Markdown-like syntax
46118---------------------------
47119
48120Historically, Markdown-style citations syntax was the first that
49−was added to pandoc's org reader. It is almost identical to
50−Markdown's citation syntax.
121+was added to pandoc's org reader. It is close to Markdown's
122+citation syntax.
123+
124+Citations go inside square brackets and are separated by
125+semicolons. Each citation must have a key, composed of '@' plus
126+the citation identifier from the database, and may optionally
127+have a prefix, a locator, and a suffix. The citation key must
128+begin with a letter, digit, or `_`, and may contain
129+alphanumerics, `_`, and internal punctuation characters
130+(`:.#$%&-+?<>~/`). Here are some examples:
131+
132+### Simple citation
133+
134+The simplest method to insert a citation is to write the citation
135+ID prefixed by '@'.
136+
51137
52138Example:
53139
54140 [prefix @citekey suffix]
55− [see @doe2000 p. 23-42]
141+ [see @doe2000 pp. 23-42]
142+ [@doe2000 p. 5; to a lesser extend @doe2005]
56143
57144
58145LaTeX-Syntax
@@ -62,6 +149,7 @@ Use normal latex citation commands like `\cite{x}` or
62149`\citet{y}`.
63150
64151[org-ref]: https://github.com/jkitchin/org-ref
152+[John Kitchen]: https://kitchingroup.cheme.cmu.edu/
65153
66154
67155Emphasis rules
@@ -75,7 +163,7 @@ possible to use special lines to change these values:
75163
76164 #+pandoc-emphasis-pre: "-\t ('\"{"
77165 #+pandoc-emphasis-post: "-\t\n .,:!?;'\")}["
78−
166+
79167The above describes the default values of these variables. The
80168arguments must be valid (Haskell) strings. If interpretation of
81169the argument as string fails, the default is restored.
@@ -93,3 +181,14 @@ be parsed using default emphasis rules:
93181 [/test/]
94182 #+pandoc-emphasis-pre:
95183 #+pandoc-emphasis-post:
184+
185+
186+Currently unsupported features
187+==============================
188+
189+Library of babel
190+----------------
191+
192+The library of babel translates between various programming
193+languages. This is out-of-scope for pandoc. Use Emacs to run
194+code, then feed the resulting org file to pandoc.