From b8ada284b1f6a4b37cd72f4f2f0e6707a1a7160b Mon Sep 17 00:00:00 2001 From: Albert Krewinkel Date: Mon, 13 Dec 2021 21:02:19 +0100 Subject: doc/lua-filters.md: update description of walk methods, fix typos --- doc/lua-filters.md | 41 +++++++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/doc/lua-filters.md b/doc/lua-filters.md index 778934e17..b0ae3f7a7 100644 --- a/doc/lua-filters.md +++ b/doc/lua-filters.md @@ -174,7 +174,7 @@ This functionality has been added in pandoc 2.9.2. [Inlines filter example]: #remove-spaces-before-citations -## Traversal Order +## Traversal order The traversal order of filters can be selected by setting the key `traverse` to either `'topdown'` or `'typewise'`; the default is @@ -230,7 +230,7 @@ depth-first from the root towards the leaves, and all in a single run. For example, a block list `[Plain [Str "a"], Para [Str -"b"]]`{.haskell} will be try the following filter functions, in +"b"]]`{.haskell} will try the following filter functions, in order: `Blocks`, `Plain`, `Inlines`, `Str`, `Para`, `Inlines`, `Str`. @@ -846,8 +846,9 @@ determined via [`pandoc.utils.equals`]. `walk(self, lua_filter)` Applies a Lua filter to the Pandoc element. Just as for -full-document filters, the order in which elements are handled -are Inline → Inlines → Block → Blocks → Meta → Pandoc. +full-document filters, the order in which elements are traversed +can be controlled by setting the `traverse` field of the filter; +see the section on [traversal order][Traversal order]. Parameters: @@ -910,19 +911,21 @@ or `pandoc.Blocks`. Object equality is determined via [`pandoc.utils.equals`]. -### Common Methods +### Common methods #### walk {#type-block:walk} `walk(self, lua_filter)` Applies a Lua filter to the block element. Just as for -full-document filters, the order in which elements are handled -are Inline → Inlines → Block → Blocks. +full-document filters, the order in which elements are traversed +can be controlled by setting the `traverse` field of the filter; +see the section on [traversal order][Traversal order]. Note that the filter is applied to the subtree, but not to the -element itself. The rationale is that the element might be -deleted by the filter, leading to possibly unexpected results. +`self` block element. The rationale is that otherwise the element +could be deleted by the filter, or replaced with multiple block +elements, which might lead to possibly unexpected results. Parameters: @@ -1264,9 +1267,9 @@ values: `walk(self, lua_filter)` Applies a Lua filter to the Blocks list. Just as for -full-document filters, the order in which elements are handled -are are Inline → Inlines → Block → Blocks. The filter is applied -to all list items *and* to the list itself. +full-document filters, the order in which elements are traversed +can be controlled by setting the `traverse` field of the filter; +see the section on [traversal order][Traversal order]. Parameters: @@ -1292,19 +1295,21 @@ Usage: Object equality is determined by checking the Haskell representation for equality. -### Common Methods +### Common methods #### walk {#type-inline:walk} `walk(self, lua_filter)` Applies a Lua filter to the Inline element. Just as for -full-document filters, the order in which elements are handled -are are Inline → Inlines → Block → Blocks. +full-document filters, the order in which elements are traversed +can be controlled by setting the `traverse` field of the filter; +see the section on [traversal order][Traversal order]. -Note that the filter is applied to the subtree, but *not* to the -element itself. The rationale is that the element might be -deleted by the filter, leading to possibly unexpected results. +Note that the filter is applied to the subtree, but not to the +`self` inline element. The rationale is that otherwise the +element could be deleted by the filter, or replaced with multiple +inline elements, which might lead to possibly unexpected results. Parameters: -- cgit v1.2.3