Doc pages: Use passive form, never address the reader as 'you'

Except for the FAQ, it could be fixed, but it does not have to be
as formal as the rest of the docs.

doc/pages/buffers.asciidoc

@@ -2,29 +2,33 @@
 
 == Commands
 
-To open buffers or navigate through the buffers list
-see <<commands#files-and-buffers,`:doc commands files-and-buffers`>>.
+To open buffers or navigate through the buffers list see
+<<commands#files-and-buffers,`:doc commands files-and-buffers`>>.
 
 == Scratch Buffers
 
 Scratch buffers are useful for volatile data and quick prototyping.
 They are not linked to files.
 
-One particular scratch buffer, named *\*scratch*\*, is automatically created
-when there are no other buffers left in the current session. (which is also
-the case at Kakoune's startup when no files to open have been provided)
+One particular scratch buffer, named *\*scratch*\*, is automatically
+created when there are no other buffers left in the current
+session. (which is also the case at Kakoune's startup when no files to
+open have been provided)
 
-You can create you own by using the `-scratch` parameter of the `:edit` command.
+A scratch buffer can be created by passing the `-scratch` switch to the
+`:edit` command.
 
 == Debug Buffers
 
-Debug buffers are used to gather diagnostics. They are not accessible while cycling
-over the buffers list.
+Debug buffers are used to gather diagnostics. They are not accessible
+while cycling over the buffers list.
 
-A specific *\*debug*\* buffer is used by Kakoune to write errors or warnings.
-This is also where the ouput of the `:debug` and the `:echo -debug` commands will land.
+A specific *\*debug*\* buffer is used by Kakoune to write errors or
+warnings.  This is also where the ouput of the `:debug` and the `:echo
+-debug` commands will land.
 
-You can create you own by using the `-debug` parameter of the `:edit` command.
+A scratch buffer can be created by passing the `-debug` switch to the
+`:edit` command.
 
 == FIFO Buffers
 
@@ -34,16 +38,17 @@ The `:edit` command can take a `-fifo` parameter:
 :edit -fifo <filename> [-scroll] <buffername>
 ---------------------------------------------
 
-In this case, a buffer named `<buffername>` is created which reads its content
-from the fifo `<filename>`. When the fifo is written to, the buffer is
-automatically updated.
+In this case, a buffer named `<buffername>` is created which reads
+its content from the fifo `<filename>`. When the fifo is written to,
+the buffer is automatically updated.
 
 If the `-scroll` switch is specified, the window displaying the buffer
 will scroll so that the newest data is always visible.
 
-This is very useful for running some commands asynchronously while displaying
-their result in a buffer. See `rc/make.kak` and `rc/grep.kak` for examples.
+This is very useful for running some commands asynchronously while
+displaying their result in a buffer. See `rc/make.kak` and `rc/grep.kak`
+for examples.
 
-When the buffer is deleted, the fifo will be closed, so any program writing
-to it will receive `SIGPIPE`. This is useful as it permits to stop the writing
-program when the buffer is deleted.
+When the buffer is deleted, the fifo will be closed, so any program
+writing to it will receive `SIGPIPE`. This is useful as it permits to
+stop the writing program when the buffer is deleted.

doc/pages/expansions.asciidoc

@@ -10,8 +10,8 @@
 %\{strings\}::
     these strings are very useful when entering commands
 +
-    * the '{' and '}' delimiters are configurable, you can use any non
-    alphanumeric character
+    * the '{' and '}' delimiters are configurable, any non alphanumeric
+    character can be used
 +
 ----------------------------------------------------------
 e.g. %[string], %<string>, %(string), %~string~, %!string!

doc/pages/highlighters.asciidoc

@@ -115,8 +115,8 @@ add-highlighter window regex //\h*(TODO:)[^\n]* 0:cyan 1:yellow,red
 == Highlighting Groups
 
 
-The *group* highlighter is a container for other highlighters. You can add a
-a subgroup to an existing group, or scope using:
+The *group* highlighter is a container for other highlighters. A subgroup
+can be added to an existing group or scope using:
 
 -----------------------------------
 add-highlighter <path> group <name>

doc/pages/hooks.asciidoc

@@ -160,8 +160,8 @@ 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, you have access to
-the following expansions:
+While defining hook commands with a `%sh{}` block, some additional env
+vars are available:
 
 * `kak_hook_param`: filtering text passed to the currently executing hook
 * `kak_hook_param_capture_N`: text captured by the hook filter regex capture N

doc/pages/keys.asciidoc

@@ -566,8 +566,8 @@ level to select.
 *}*::
     extends selections to object end
 
-After these keys, you need to enter a second key in order to specify which
-object you want
+After these keys, a second key needs to be entered in order to specify
+the wanted object:
 
 *b*, *(*, *)*::
     select the enclosing parenthesis

doc/pages/options.asciidoc

@@ -250,7 +250,7 @@ are exclusively available to built-in options.
             at the top of the terminal rather than at the bottom
 
         *ncurses_assistant*:::
-            specify the nice assistant you get in info boxes,
+            specify the nice assistant displayed in info boxes,
             can be *clippy* (the default), *cat*, *dilbert* or *none*
 
         *ncurses_enable_mouse*:::