aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/org.md129
1 files changed, 114 insertions, 15 deletions
diff --git a/doc/org.md b/doc/org.md
index 2a87f826c..201418303 100644
--- a/doc/org.md
+++ b/doc/org.md
@@ -3,8 +3,38 @@ 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.
+Pandoc's handling of org files is similar to that of Emacs
+org-mode. This document aims to highlight the cases where this is
+not possible or just not the case yet.
+
+Export options
+==============
+
+The following export keywords are supported:
+
+- AUTHOR: comma-separated list of author(s); fully supported.
+
+- CREATOR: output generator; passed as metadata entry, but
+ ignored by most output formats.
+
+- DATE: creation or publication date; well supported by pandoc.
+
+- EMAIL: author email address; passed as metadata entry, but not
+ included in most output formats.
+
+- LANGUAGE: currently unsupported; use `#+LANG:` instead.
+
+- SELECT_TAGS: tags which select a tree for export. Currently
+ *unsupported*.
+
+- EXCLUDE\_TAGS: tags which prevent a subtree from being
+ exported. Fully supported.
+
+- TITLE: document title; fully supported.
+
+- EXPORT\_FILE\_NAME: target filename; *unsupported*, the output
+ defaults to stdout unless a target has to be given as a command
+ line option.
Citations
@@ -14,28 +44,70 @@ Emacs org-mode lacks an official citation syntax, leading to
multiple syntaxes coexisting. Pandoc recognizes four different
syntaxes for citations.
+Citation support for org-mode is enabled by default. Support can
+be toggled off by disabling the `citation` extension; e.g.
+`pandoc --from=org-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.
+The semi-offical Org-mode citation syntax was designed by Richard
+Lawrence with additions by contributors on the [emacs-orgmode
+mailing list]. It is based on John MacFarlane's pandoc Markdown
+syntax. It's dubbed Berkeley syntax due the place of activity of
+its creators, both philosophers at UC Berkeley.
+
+### Simple in-text citation
+
+This is the simplest form of citation. It consists of the citation
+ID prefixed by '@'.
+
+Example:
+
+ @WatsonCrick1953 showed that DNA forms a double-helix.
+
+### In-text citation list
+
+Citations presented in the text unparenthesized are called
+*in-text citations*. The syntax for these citations is
+
+ [cite: PREFIX; INDIVIDUAL-REFERENCE; ... INDIVIDUAL-REFERENCE; SUFFIX]
+
+where the initial PREFIX and final SUFFIX are optional. At least
+one INDIVIDUAL-REFERENCE must be present. The colon and
+semicolons here are literal and indicate the end of the TAG and
+the end of a PREFIX or INDIVIDUAL-REFERENCE respectively.
+
+An INDIVIDUAL-REFERENCE has the format:
+
+ PREFIX KEY SUFFIX
+
+The KEY is obligatory, and the prefix and suffix are optional.
+
+A PREFIX or SUFFIX is arbitrary text (except `;`, `]`, and
+citation keys).
Example:
- See @john_doe_2006.
[cite: See; @Mandelkern1981; and @Watson1953]
+
+### Parenthetical citation
+
+Citations surrounded by parantheses. The syntax is identical to
+in-text citations, except for the addtional parentheses enclosing
+the initial `cite` tag.
+
[(cite): See; @Mandelkern1981; and @Watson1953]
+[emacs-orgmode mailing list]: https://lists.gnu.org/archive/html/emacs-orgmode/2015-02/msg00932.html
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.
+The [org-ref] package by [John Kitchen] 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
@@ -46,13 +118,28 @@ 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.
+was added to pandoc's org reader. It is close to Markdown's
+citation syntax.
+
+Citations go inside square brackets and are separated by
+semicolons. Each citation must have a key, composed of '@' plus
+the citation identifier from the database, and may optionally
+have a prefix, a locator, and a suffix. The citation key must
+begin with a letter, digit, or `_`, and may contain
+alphanumerics, `_`, and internal punctuation characters
+(`:.#$%&-+?<>~/`). Here are some examples:
+
+### Simple citation
+
+The simplest method to insert a citation is to write the citation
+ID prefixed by '@'.
+
Example:
[prefix @citekey suffix]
- [see @doe2000 p. 23-42]
+ [see @doe2000 pp. 23-42]
+ [@doe2000 p. 5; to a lesser extend @doe2005]
LaTeX-Syntax
@@ -62,6 +149,7 @@ Use normal latex citation commands like `\cite{x}` or
`\citet{y}`.
[org-ref]: https://github.com/jkitchin/org-ref
+[John Kitchen]: https://kitchingroup.cheme.cmu.edu/
Emphasis rules
@@ -75,7 +163,7 @@ 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.
@@ -93,3 +181,14 @@ be parsed using default emphasis rules:
[/test/]
#+pandoc-emphasis-pre:
#+pandoc-emphasis-post:
+
+
+Currently unsupported features
+==============================
+
+Library of babel
+----------------
+
+The library of babel translates between various programming
+languages. This is out-of-scope for pandoc. Use Emacs to run
+code, then feed the resulting org file to pandoc.