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

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)