doc/filters.md: describe technical details of filter invocations (#6815)

1 files changed, 79 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`