@@ -351,16 +351,69 @@ remove emphasis, or replace specially marked code blocks with
351351images). To make this easier and more efficient, `pandoc-types`
352352includes a module [Text.Pandoc.Walk].
353353
354−walk and query, with examples
355−including RawBlock
354+Here's the essential documentation:
356355
357−# Filters
356+```haskell
357+class Walkable a b where
358+ -- | @walk f x@ walks the structure @x@ (bottom up) and replaces every
359+ -- occurrence of an @a@ with the result of applying @f@ to it.
360+ walk :: (a -> a) -> b -> b
361+ walk f = runIdentity . walkM (return . f)
362+ -- | A monadic version of 'walk'.
363+ walkM :: (Monad m, Functor m) => (a -> m a) -> b -> m b
364+ -- | @query f x@ walks the structure @x@ (bottom up) and applies @f@
365+ -- to every @a@, appending the results.
366+ query :: Monoid c => (a -> c) -> b -> c
367+```
368+
369+`Walkable` instances are defined for most combinations of
370+Pandoc types. For example, the `Walkable Inline Block`
371+instance allows you to take a function `Inline -> Inline`
372+and apply it over every inline in a `Block`. And
373+`Walkable [Inline] Pandoc` allows you to take a function
374+`[Inline] -> [Inline]` and apply it over every maximal
375+list of `Inline`s in a `Pandoc`.
376+
377+Here's a simple example of a function that promotes
378+the levels of headers:
379+
380+```haskell
381+promoteHeaderLevels :: Pandoc -> Pandoc
382+promoteHeaderLevels = walk promote
383+ where promote :: Block -> Block
384+ promote (Header lev attr ils) = Header (lev + 1) attr ils
385+ promote x = x
386+```
358387
359−These make it easy for users to add their own transformations.
360−two types: json and lua.
361−Filters: see filters.md, lua-filters.md
388+`walkM` is a monadic version of `walk`; it can be used, for
389+example, when you need your transformations to perform IO
390+operations, use PandocMonad operations, or update internal
391+state. Here's an example using the State monad to add unique
392+identifiers to each code block:
362393
363−applyFilters, applyLuaFilters from Text.Pandoc.App.
394+```haskell
395+addCodeIdentifiers :: Pandoc -> Pandoc
396+addCodeIdentifiers doc = evalState (walkM addCodeId doc) 1
397+ where addCodeId :: Block -> State Int Block
398+ addCodeId (CodeBlock (_,classes,kvs) code) = do
399+ curId <- get
400+ put (curId + 1)
401+ return $ CodeBlock (show curId,classes,kvs) code
402+ addCodeId x = return x
403+```
404+
405+`query` is used to collect information from the AST.
406+Its argument is a query function that produces a result
407+in some monoidal type (e.g. a list). The results are
408+concatenated together. Here's an example that returns a
409+list of the URLs linked to in a document:
410+
411+```haskell
412+listURLs :: Pandoc -> [String]
413+listURLs = query urls
414+ where urls (Link _ _ (src, _)) = [src]
415+ urls _ = []
416+```
364417
365418# Creating a PDF
366419