From dd28d6f560dd4d4462fc48f6b814165ecf2896c1 Mon Sep 17 00:00:00 2001
From: Tim Allen <screwtape@froup.com>
Date: Mon, 19 Apr 2021 12:46:47 +1000
Subject: [PATCH] doc: Ensure the hook -always switch is documented.

- Make sure switches are in commands.asciidoc.
- Make hooks.asciidoc link to commands.asciidoc.
- Minor wording fix-ups.
---
 doc/pages/commands.asciidoc | 17 +++++++++++++++--
 doc/pages/hooks.asciidoc    | 18 +++++++++---------
 2 files changed, 24 insertions(+), 11 deletions(-)

diff --git a/doc/pages/commands.asciidoc b/doc/pages/commands.asciidoc
index 53e84c98a..0d9c8fcec 100644
--- a/doc/pages/commands.asciidoc
+++ b/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>::
diff --git a/doc/pages/hooks.asciidoc b/doc/pages/hooks.asciidoc
index d6a63ba6b..baab06a12 100644
--- a/doc/pages/hooks.asciidoc
+++ b/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: