diff options
authorAlbert Krewinkel <>2018-02-25 14:26:53 +0100
committerAlbert Krewinkel <>2018-02-25 14:30:15 +0100
commitb4717a6acbd998e31542c18d885e377a4113fd7b (patch)
parent66368ab330386a83b800d80cd8562c405ac3531d (diff)
doc/ Add Org-mode documentation (very first draft)
1 files changed, 95 insertions, 0 deletions
diff --git a/doc/ b/doc/
new file mode 100644
index 000000000..2a87f826c
--- /dev/null
+++ b/doc/
@@ -0,0 +1,95 @@
+title: Org-mode features and differences
+author: Albert Krewinkel
+Pandoc handles org files very similarly to Emacs org-mode.
+However, there are differences worth highlighting.
+Emacs org-mode lacks an official citation syntax, leading to
+multiple syntaxes coexisting. Pandoc recognizes four different
+syntaxes for citations.
+Berkeley-style citations
+The semi-offical Org-mode citation syntax is based on John
+MacFarlane's Pandoc syntax and org-oriented enhancements
+contributed by Richard Lawrence and others. It's dubbed Berkeley
+syntax due the place of activity of its main contributors.
+ See @john_doe_2006.
+ [cite: See; @Mandelkern1981; and @Watson1953]
+ [(cite): See; @Mandelkern1981; and @Watson1953]
+org-ref citations
+The [org-ref] package is in wide use to handle citations and has
+excellent tooling support in Emacs. Its citation syntax is
+geared towards users in the natural sciences but still very
+flexible regardless.
+ cite:doe_john_2000
+ citep:doe_jane_1989
+ [[citep:Dominik201408][See page 20 of::, for example]]
+Pandoc-Markdown-like syntax
+Historically, Markdown-style citations syntax was the first that
+was added to pandoc's org reader. It is almost identical to
+Markdown's citation syntax.
+ [prefix @citekey suffix]
+ [see @doe2000 p. 23-42]
+Use normal latex citation commands like `\cite{x}` or
+Emphasis rules
+Org-mode uses complex rules to decide whether a string
+represents emphasized text. In Emacs, this can be customized via
+the variable `org-emphasis-regexp-components`. A variable like
+this doesn't fit well with pandoc's model. Instead, it is
+possible to use special lines to change these values:
+ #+pandoc-emphasis-pre: "-\t ('\"{"
+ #+pandoc-emphasis-post: "-\t\n .,:!?;'\")}["
+The above describes the default values of these variables. The
+arguments must be valid (Haskell) strings. If interpretation of
+the argument as string fails, the default is restored.
+Changing emphasis rules only affect the part of the document
+following the special lines. They must be some of the first
+lines to alter parsing behavior for the whole document. It is
+also possible to change the values temporarily for selected
+sections only. The string `test` in the following snippet will
+be read as emphasized text, while the rest of the document will
+be parsed using default emphasis rules:
+ #+pandoc-emphasis-pre: "["
+ #+pandoc-emphasis-post: "]"
+ [/test/]
+ #+pandoc-emphasis-pre:
+ #+pandoc-emphasis-post: