From 467ea4e02cbf09e47c619e59496a3b71142b9710 Mon Sep 17 00:00:00 2001
From: Albert Krewinkel <albert@zeitkraut.de>
Date: Sat, 11 Jan 2020 00:19:26 +0100
Subject: [PATCH] docs/lua-filters.md: clarify filter function execution order
(#6059)
---
doc/lua-filters.md | 32 ++++++++++++++++++++++++++++++--
1 file changed, 30 insertions(+), 2 deletions(-)
diff --git a/doc/lua-filters.md b/doc/lua-filters.md
index d9c1debc0..7d084ecb4 100644
--- a/doc/lua-filters.md
+++ b/doc/lua-filters.md
@@ -2,7 +2,7 @@
author:
- Albert Krewinkel
- John MacFarlane
-date: 'December 6, 2017'
+date: 'January 10, 2020'
title: Pandoc Lua Filters
---
@@ -28,7 +28,7 @@ in JSON form. One cannot simply provide a filter that can be
used by anyone who has a certain version of the pandoc
executable.
-Starting with pandoc 2.0, we have made it possible to write
+Starting with version 2.0, pandoc makes it possible to write
filters in lua without any external dependencies at all. A lua
interpreter (version 5.3) and a lua library for creating pandoc
filters is built into the pandoc executable. Pandoc data types
@@ -136,6 +136,34 @@ Elements without matching functions are left untouched.
See [module documentation](#module-pandoc) for a list of pandoc
elements.
+## Execution order
+
+Element filter functions within a filter set are called in a
+fixed order, skipping any which are not present:
+
+ 1. functions for [*Inline* elements](#type-ref-Inline),
+ 2. functions for [*Block* elements](#type-ref-Block) ,
+ 3. the [*Meta*](#type-ref-Meta) filter function, and last
+ 4. the [*Pandoc*](#type-ref-Meta) filter function.
+
+It is still possible to force a different order by explicitly
+returning multiple filter sets. For example, if the filter for
+*Meta* is to be run before that for *Str*, one can write
+
+``` lua
+-- ... filter definitions ...
+
+return {
+ { Meta = Meta }, -- (1)
+ { Str = Str } -- (2)
+}
+```
+
+Filter sets are applied in the order in which they are returned.
+All functions in set (1) are thus run before those in (2),
+causing the filter function for *Meta* to be run before the
+filtering of *Str* elements is started.
+
## Global variables
Pandoc passes additional data to Lua filters by setting global