aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAlbert Krewinkel <albert@zeitkraut.de>2020-11-07 00:37:24 +0100
committerGitHub <noreply@github.com>2020-11-06 15:37:24 -0800
commit0ed3436588951d457eefb11351f72d3560bdc544 (patch)
treebd1167ef62a87d95b13be6ffa2a31a29019612a0
parent22e5efe6a2cb48183cb3eb31c19add63fbd6d9f3 (diff)
downloadpandoc-0ed3436588951d457eefb11351f72d3560bdc544.tar.gz
doc/filters.md: describe technical details of filter invocations (#6815)
-rw-r--r--doc/filters.md79
-rw-r--r--src/Text/Pandoc/Options.hs2
2 files changed, 81 insertions, 0 deletions
diff --git a/doc/filters.md b/doc/filters.md
index e398fc468..8b6002467 100644
--- a/doc/filters.md
+++ b/doc/filters.md
@@ -425,3 +425,82 @@ the Japanese characters (e.g. "Noto Sans CJK TC"), and add
5. Find all code blocks with class `python` and run them
using the python interpreter, printing the results to the console.
+# Technical details of JSON filters
+
+A JSON filter is any program which can consume and produce a
+valid pandoc JSON document representation. This section describes
+the technical details surrounding the invocation of filters.
+
+## Arguments
+
+The program will always be called with the target format as the
+only argument. A pandoc invocation like
+
+ pandoc --filter demo --to=html
+
+will cause pandoc to call the program `demo` with argument `html`.
+
+## Environment variables
+
+Pandoc sets additional environment variables before calling a
+filter.
+
+`PANDOC_VERSION`
+: The version of the pandoc binary used to process the document.
+ Example: `2.11.1`.
+
+`PANDOC_READER_OPTIONS`
+: JSON object representation of the options passed to the input
+ parser.
+
+ Object fields:
+
+ `readerAbbreviations`
+ : set of known abbreviations (array of strings).
+
+ `readerColumns`
+ : number of columns in terminal; an integer.
+
+ `readerDefaultImageExtension`
+ : default extension for images; a string.
+
+ `readerExtensions`
+ : integer representation of the syntax extensions bit
+ field.
+
+ `readerIndentedCodeClasses`
+ : default classes for indented code blocks; array of
+ strings.
+
+ `readerStandalone`
+ : whether the input was a standalone document with header;
+ either `true` or `false`.
+
+ `readerStripComments`
+ : HTML comments are stripped instead of parsed as raw HTML;
+ either `true` or `false`.
+
+ `readerTabStop`
+ : width (i.e. equivalent number of spaces) of tab stops;
+ integer.
+
+ `readerTrackChanges`
+ : track changes setting for docx; one of
+ `"accept-changes"`, `"reject-changes"`, and
+ `"all-changes"`.
+
+## Supported interpreters
+
+Files passed to the `--filter`/`-F` parameter are expected to be
+executable. However, if the executable bit is not set, then
+pandoc tries to guess a suitable interpreter from the file
+extension.
+
+ file extension interpreter
+ ---------------- --------------
+ .py `python`
+ .hs `runhaskell`
+ .pl `ruby`
+ .php `php`
+ .js `node`
+ .r `Rscript`
diff --git a/src/Text/Pandoc/Options.hs b/src/Text/Pandoc/Options.hs
index 21093e007..f1d9d44b7 100644
--- a/src/Text/Pandoc/Options.hs
+++ b/src/Text/Pandoc/Options.hs
@@ -314,6 +314,7 @@ defaultMathJaxURL = "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml-full.j
defaultKaTeXURL :: Text
defaultKaTeXURL = "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.11.1/"
+-- Update documentation in doc/filters.md if this is changed.
$(deriveJSON defaultOptions ''ReaderOptions)
$(deriveJSON defaultOptions{
@@ -337,6 +338,7 @@ $(deriveJSON defaultOptions{ constructorTagModifier =
$(deriveJSON defaultOptions ''HTMLSlideVariant)
+-- Update documentation in doc/filters.md if this is changed.
$(deriveJSON defaultOptions{ constructorTagModifier =
camelCaseStrToHyphenated
} ''TrackChanges)