Merge branch 'master' into groff_reader

2 files changed, 132 insertions, 4 deletions

diff --git a/doc/lua-filters.md b/doc/lua-filters.md
index 6f03360bb..170aaa8f5 100644
--- a/doc/lua-filters.md
+++ b/doc/lua-filters.md
@@ -135,9 +135,42 @@ Elements without matching functions are left untouched.
 See [module documentation](#module-pandoc) for a list of pandoc
 elements.
 
-The global `FORMAT` is set to the format of the pandoc writer
-being used (`html5`, `latex`, etc.), so the behavior of a filter
-can be made conditional on the eventual output format.
+
+## Global variables
+
+Pandoc passes additional data to Lua filters by setting global
+variables.
+
+`FORMAT`
+:   The global `FORMAT` is set to the format of the pandoc
+    writer being used (`html5`, `latex`, etc.), so the behavior
+    of a filter can be made conditional on the eventual output
+    format.
+
+`PANDOC_READER_OPTIONS`
+:   Table of the options which were provided to the parser.
+
+`PANDOC_VERSION`
+:   Contains the pandoc version as a numerically indexed table,
+    most significant number first. E.g., for pandoc 2.1.1, the
+    value of the variable is a table `{2, 1, 1}`. Use
+    `table.concat(PANDOC_VERSION, '.')` to produce a version
+    string. This variable is also set in custom writers.
+
+`PANDOC_API_VERSION`
+:   Contains the version of the pandoc-types API against which
+    pandoc was compiled. It is given as a numerically indexed
+    table, most significant number first. E.g., if pandoc was
+    compiled against pandoc-types 1.17.3, then the value of the
+    variable will be a table `{1, 17, 3}`. Use
+    `table.concat(PANDOC_API_VERSION, '.')` to produce a version
+    string from this table. This variable is also set in custom
+    writers.
+
+`PANDOC_SCRIPT_FILE`
+:   The name used to involve the filter. This value can be used
+    to find files relative to the script file. This variable is
+    also set in custom writers.
 
 # Pandoc Module
 
@@ -318,7 +351,7 @@ local vars = {}
 function get_vars (meta)
   for k, v in pairs(meta) do
     if v.t == 'MetaInlines' then
-      vars["$" .. k .. "$"] = v
+      vars["$" .. k .. "$"] = {table.unpack(v)}
     end
   end
 end
diff --git a/doc/org.md b/doc/org.md
new file mode 100644
index 000000000..2a87f826c
--- /dev/null
+++ b/doc/org.md
@@ -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.
+
+
+Citations
+=========
+
+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.
+
+Example:
+
+    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.
+
+Example:
+
+    [prefix @citekey suffix]
+    [see @doe2000 p. 23-42]
+
+
+LaTeX-Syntax
+------------
+
+Use normal latex citation commands like `\cite{x}` or
+`\citet{y}`.
+
+[org-ref]: https://github.com/jkitchin/org-ref
+
+
+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: