Merge remote-tracking branch 'Screwtapello/add-hook-options-docs'

doc/pages/commands.asciidoc

@@ -209,13 +209,26 @@ of the file onto the filesystem
 
 == Hooks
 
-*hook* [-group <group>] <scope> <hook_name> <filtering_regex> <command>::
+*hook* [<switches>] <scope> <hook_name> <filtering_regex> <command>::
     execute *command* whenever a *hook_name* is triggered in *scope*
     (See <<hooks#,`:doc hooks`>> and <<scopes#,`:doc scopes`>>)
 
+    *-group <groupname>*:::
+        Add this hook to the *groupname* group, so it can be removed by the
+        `remove-hooks` command (below)
+        or disabled with the `disabled_hooks` option
+        (see <<options#builtin-options,`:doc options builtin-options`>>).
+
+    *-once*:::
+        This hook will be automatically removed after it has been executed.
+
+    *-always*:::
+        This hook will run even while hooks are disabled.
+        See <<hooks#disabling-hooks,`:doc hooks disabling-hooks`>>.
+
 *remove-hooks* <scope> <group>::
     *alias* rmhooks +
-    remove every hooks in *scope* that are part of the given *group*
+    remove every hook in *scope* whose group matches the regex *group*
     (See <<hooks#,`:doc hooks`>> and <<scopes#,`:doc scopes`>>)
 
 *trigger-user-hook* <param>::

doc/pages/hooks.asciidoc

@@ -5,9 +5,9 @@
 Commands can be registered to be executed when certain events arise. To
 register a hook use the following command:
 
-------------------------------------------------------------------------------
-hook [-group <group> | -once] <scope> <hook_name> <filtering_regex> <commands>
-------------------------------------------------------------------------------
+------------------------------------------------------------------
+hook [<switches>] <scope> <hook_name> <filtering_regex> <commands>
+------------------------------------------------------------------
 
 *scope* can be one of *global*, *buffer* or *window* (See
 <<scopes#,`:doc scopes`>>).
@@ -21,17 +21,17 @@ commands to be executed.
 *command* is a string containing the commands to execute when the hook
 is called.
 
-If *group* is given, make this hook part of the named group. Groups are used
-for removing hooks with the following command:
+For *switches*, see <<commands#hooks,`:doc commands hooks`>>.
+
+If a hook is registered with the `-group` switch, it can later be removed with
+the `remove-hooks` command:
 
 ----------------------------
 remove-hooks <scope> <group>
 ----------------------------
 
-A call to the command above will remove every hook in *scope* whose group
-matches the given *group* regex.
-
-If `-once` is given, the hook is automatically removed after running.
+This command removes all hooks originally registered in *scope* whose
+`-group` switch matches the regex *group*.
 
 For example to automatically use line numbering with .cc files, use the
 following command: