Merge remote-tracking branch 'Delapouite/hook-expansions'

doc/manpages/hooks.asciidoc

@@ -162,3 +162,27 @@ When not specified, the filtering text is an empty string. Note that
 some hooks will not consider underlying scopes depending on what context
 they are bound to be run into, e.g. the `BufWritePost` hook is a buffer
 hook, and will not consider the `window` scope.
+
+While defining hook commands with a `%sh{}` block, you have access to
+the following expansions:
+
+* `kak_hook_param`: filtering text passed to the currently executing hook
+* `kak_hook_param_capture_N`: text captured by the hook filter regex capture N
+
+Disabling Hooks
+---------------
+
+Any normal mode command can be prefixed with `\` which will disable hook
+execution for the duration for the command (including the duration of modes
+the command could move to, so `\i` will disable hooks for the whole insert
+session).
+
+As autoindentation is implemented in terms of hooks, this can be used to
+disable it when pasting text.
+
+A less temporary alternative is to set the `disabled_hooks` option which
+accepts a regex describing which hooks won't be executed.
+For example indentation hooks can be disabled with '.*-indent'.
+
+Finally, hook execution can be disabled while using the `exec` or `eval`
+commands by using the `-no-hooks` switch.