Docs: homogenize and emphasize hooks filtering text

doc/pages/hooks.asciidoc

@@ -43,8 +43,8 @@ of the given *group*.
 *NormalEnd*::
     leaving normal mode
 
-*NormalKey*::
+*NormalKey* `key`::
-    a key is received in normal mode, the key is used for filtering
+    a key is received in normal mode
 
 *InsertIdle*::
     a certain duration has passed since last key was pressed in insert mode
@@ -55,80 +55,70 @@ of the given *group*.
 *InsertEnd*::
     leaving insert mode
 
-*InsertKey*::
+*InsertKey* `key`::
-    a key is received in insert mode, the key is used for filtering
+    a key is received in insert mode
 
-*InsertChar*::
+*InsertChar* `char`::
-    a character is received in insert mode, the character is used for
+    a character is received in insert mode
-    filtering
 
-*InsertDelete*::
+*InsertDelete* `deleted char`::
-    a character is deleted in insert mode, the character deleted by
+    a character is deleted in insert mode
-    the main selection is used for filtering
 
-*InsertMove*::
+*InsertMove* `move key`::
-    the cursor moved (without inserting) in insert mode, the key that
+    the cursor moved (without inserting) in insert mode
-    triggered the move is used for filtering
 
 *PromptIdle*::
     a certain duration has passed since last key was pressed in prompt mode
 
-*WinCreate*::
+*WinCreate* `buffer name`::
-    a window was created, the filtering text is the buffer name
+    a window was created
 
-*WinClose*::
+*WinClose* `buffer name`::
-    a window was destroyed, the filtering text is the buffer name
+    a window was destroyed
 
-*WinResize*::
+*WinResize* `<line>.<column>`::
-    a window resized, the filtering text is *<line>.<column>*
+    a window was resized
 
-*WinDisplay*::
+*WinDisplay* `buffer name`::
-    a window was bound a client, the filtering text is the buffer name
+    a window was bound a client
 
-*WinSetOption*::
+*WinSetOption* `<option_name>=<new_value>`::
-    an option was set in a window context, the filtering text is
+    an option was set in a window context
-    *<option_name>=<new_value>*
 
-*BufSetOption*::
+*BufSetOption* `<option_name>=<new_value>`::
-    an option was set in a buffer context, the filtering text is
+    an option was set in a buffer context
-    *<option_name>=<new_value>*
 
-*BufNewFile*::
+*BufNewFile* `filename`::
-    a buffer for a new file has been created, filename is used for
+    a buffer for a new file has been created
-    filtering
 
-*BufOpenFile*::
+*BufOpenFile* `filename`::
-    a buffer for an existing file has been created, filename is used
+    a buffer for an existing file has been created
-    for filtering
 
-*BufCreate*::
+*BufCreate* `filename`::
-    a buffer has been created, filename is used for filtering
+    a buffer has been created
 
-*BufWritePre*::
+*BufWritePre* `filename`::
-    executed just before a buffer is written, filename is used for
+    executed just before a buffer is written
-    filtering
 
-*BufWritePost*::
+*BufWritePost* `filename`::
-    executed just after a buffer is written, filename is used for filtering
+    executed just after a buffer is written
 
-*BufClose*::
+*BufClose* `buffer name`::
     executed when a buffer is deleted, while it is still valid
 
-*BufOpenFifo*::
+*BufOpenFifo* `buffer name`::
     executed when a buffer opens a fifo
 
-*BufReadFifo*::
+*BufReadFifo* `buffer name`::
     executed after some data has been read from a fifo and inserted in
     the buffer
 
 *BufCloseFifo*::
     executed when a fifo buffer closes its fifo file descriptor either
-    because the buffer is being deleted,
+    because the buffer is being deleted or the writing end has been closed
-    or because the writing end has been closed
 
-*RuntimeError*::
+*RuntimeError* `error message`::
-    an error was encountered while executing a user command the error
+    an error was encountered while executing a user command
-    message is used for filtering
 
 *KakBegin*::
     kakoune has started, this hook is called just after reading the user
@@ -137,13 +127,11 @@ of the given *group*.
 *KakEnd*::
     kakoune is quitting
 
-*FocusIn*::
+*FocusIn* `client name`::
-    on supported clients, triggered when the client gets focused. The
+    on supported clients, triggered when the client gets focused
-    filtering text is the client name
 
-*FocusOut*::
+*FocusOut* `client name`::
-    on supported clients, triggered when the client gets unfocused. The
+    on supported clients, triggered when the client gets unfocused
-    filtering text is the client name
 
 *InsertCompletionShow*::
     Triggered when the insert completion menu gets displayed
@@ -151,14 +139,13 @@ of the given *group*.
 *InsertCompletionHide*::
     Triggered when the insert completion menu gets hidden
 
-*InsertCompletionSelect*::
+*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.
 
-*RawKey*::
+*RawKey* `key`::
-    Triggered whenever a key is pressed by the user, the key is
+    Triggered whenever a key is pressed by the user
-    used for filtering.
 
 When not specified, the filtering text is an empty string. Note that
 some hooks will not consider underlying scopes depending on what context