Merge remote-tracking branch 'Screwtapello/cleanup-hook-docs'

doc/pages/hooks.asciidoc

@@ -5,23 +5,22 @@
 Commands can be registered to be executed when certain events arise. To
 register a hook use the following command:
 
-----------------------------------------------------------------------
+------------------------------------------------------------------------------
-hook [-group <group>] <scope> <hook_name> <filtering_regex> <commands>
+hook [-group <group> | -once] <scope> <hook_name> <filtering_regex> <commands>
-----------------------------------------------------------------------
+------------------------------------------------------------------------------
 
 *scope* can be one of *global*, *buffer* or *window* (See
 <<scopes#,`:doc scopes`>>).
 
+*hook_name* must be one of the hook names in the list below, like `InsertKey`
+or `BufSetOption`.
+
+*filtering_regex* must match the entire parameter string in order for the
+commands to be executed.
+
 *command* is a string containing the commands to execute when the hook
 is called.
 
-For example to automatically use line numbering with .cc files, use the
-following command:
-
---------------------------------------------------------------
-hook global WinCreate .*\.cc %{ add-highlighter number-lines }
---------------------------------------------------------------
-
 If *group* is given, make this hook part of the named group. Groups are used
 for removing hooks with the following command:
 
@@ -29,13 +28,23 @@ for removing hooks with the following command:
 remove-hooks <scope> <group>
 ----------------------------
 
-A call to the command above will remove every hooks in *scope* that are part
+A call to the command above will remove every hook in *scope* whose group
-of whose group match the given *group* regex.
+matches the given *group* regex.
 
-Hooks declared with the `-once` switch are automatically removed after running.
+If `-once` is given, the hook is automatically removed after running.
+
+For example to automatically use line numbering with .cc files, use the
+following command:
+
+--------------------------------------------------------------
+hook global WinCreate .*\.cc %{ add-highlighter number-lines }
+--------------------------------------------------------------
 
 == Default hooks
 
+The parameter string associated with each hook is described after the hook
+name. Hooks with no description will always use an empty string.
+
 *NormalIdle*::
     a certain duration has passed since last key was pressed in normal mode
 
@@ -163,9 +172,8 @@ Hooks declared with the `-once` switch are automatically removed after running.
 *RawKey* `key`::
     Triggered whenever a key is pressed by the user
 
-When not specified, the filtering text is an empty string. Note that
+Note that some hooks will not consider underlying scopes depending on what
-some hooks will not consider underlying scopes depending on what context
+context they are bound to be run into, e.g. the `BufWritePost` hook is a buffer
-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, some additional env