From 3819304589c5cb70f44a3ed326afc3625d0b4cd8 Mon Sep 17 00:00:00 2001
From: Tim Allen <screwtape@froup.com>
Date: Sat, 22 Sep 2018 18:43:56 +1000
Subject: [PATCH] hooks.asciidoc: Make sure all parts of the hook command are
 described.

Also, some minor grammar fixes.
---
 doc/pages/hooks.asciidoc | 40 ++++++++++++++++++++++++----------------
 1 file changed, 24 insertions(+), 16 deletions(-)

diff --git a/doc/pages/hooks.asciidoc b/doc/pages/hooks.asciidoc
index 982b8daf..3ddd5553 100644
--- a/doc/pages/hooks.asciidoc
+++ b/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
-of whose group match the given *group* regex.
+A call to the command above will remove every hook in *scope* whose group
+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
-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
+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, some additional env