From 231e140d37ce27906e0869a2fc9e444bcf8d9a29 Mon Sep 17 00:00:00 2001
From: Delapouite <delapouite@gmail.com>
Date: Thu, 16 Aug 2018 19:06:57 +0200
Subject: [PATCH] docs: add -always and -once switch on hooks page

---
 doc/pages/execeval.asciidoc |  2 +-
 doc/pages/hooks.asciidoc    | 15 ++++++++++-----
 doc/pages/options.asciidoc  |  3 ++-
 3 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/doc/pages/execeval.asciidoc b/doc/pages/execeval.asciidoc
index 9d784e225..427cff89b 100644
--- a/doc/pages/execeval.asciidoc
+++ b/doc/pages/execeval.asciidoc
@@ -52,7 +52,7 @@ when the commands have been executed: */*, *"*, *|*, *^*, *@*.
 
 *-no-hooks*::
     disable hook execution while executing the keys/commands
-    (See <<hooks#,`:doc hooks`>>)
+    (See <<hooks#disabling-hooks,`:doc hooks`>>)
 
 == execute-keys specific switches
 
diff --git a/doc/pages/hooks.asciidoc b/doc/pages/hooks.asciidoc
index dc0bc1d0f..1ff0f0db7 100644
--- a/doc/pages/hooks.asciidoc
+++ b/doc/pages/hooks.asciidoc
@@ -18,20 +18,22 @@ 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:
 
------------------------
+----------------------------
 remove-hooks <scope> <group>
------------------------
+----------------------------
 
 A call to the command above will remove every hooks in *scope* that are part
 of the given *group*.
 
+Hooks declared with the `-once` switch are automatically removed after running.
+
 == Default hooks
 
 *NormalIdle*::
@@ -152,7 +154,7 @@ of the given *group*.
 *InsertCompletionSelect* `selected completion`::
     Triggered when an entry is selected in the insert completion
     menu. The filtering text is the selected completion text or
-    the empty string if the original text was selected back.
+    the empty string if the original text was selected back
 
 *RawKey* `key`::
     Triggered whenever a key is pressed by the user
@@ -186,3 +188,6 @@ For example indentation hooks can be disabled with '.*-indent'.
 Finally, hook execution can be disabled while using the `execute-keys` or
 `evaluate-commands` commands by using the `-no-hooks` switch.
 (See <<execeval#,`:doc execeval`>>)
+
+As an exception to these rules, hooks declared with the `-always` switch
+are triggered no matter what. A good use case is doing some cleanup on `BufCloseFifo`.
diff --git a/doc/pages/options.asciidoc b/doc/pages/options.asciidoc
index d56c3ccbe..7e8bb52eb 100644
--- a/doc/pages/options.asciidoc
+++ b/doc/pages/options.asciidoc
@@ -177,7 +177,8 @@ are exclusively available to built-in options.
 
 *disabled_hooks* `regex`::
     hooks whose group matches this regex won't be executed. For example
-    indentation hooks can be disabled with `.*-indent`
+    indentation hooks can be disabled with `.*-indent`.
+    (See <<hooks#disabling-hooks,`:doc hooks`>>)
 
 *filetype* `str`::
     arbitrary string defining the type of the file filetype dependant