@@ -105,11 +105,22 @@ element filtering function. In other words, filter entries will
105105be called for each corresponding element in the document,
106106getting the respective element as input.
107107
108−The element function's output must be an element of the same
109−type as the input. This means a filter function acting on an
110−inline element must return an inline, and a block element must
111−remain a block element after filter application. Pandoc will
112−throw an error if this condition is violated.
108+The return of a filter function must one of the following:
109+
110+- nil: this means that the object should remain unchanged.
111+- a pandoc object: this must be of the same type as the input
112+ and will replace the original object.
113+- a list of pandoc objects: these will replace the original
114+ object; the list is merged with the neighbors of the orignal
115+ objects (spliced into the list the original object belongs
116+ to); returning an empty list deletes the object.
117+
118+The function's output must result in an element of the same type
119+as the input. This means a filter function acting on an inline
120+element must return either nil, an inline, or a list of inlines,
121+and a function filtering a block element must return one of nil,
122+a block, or a list of block elements. Pandoc will throw an error
123+if this condition is violated.
113124
114125If there is no function matching the element's node type, then
115126the filtering system will look for a more general fallback