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
+To open buffers or navigate through the buffers list see
-see <<commands#files-and-buffers,`:doc commands files-and-buffers`>>.
+<<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
+One particular scratch buffer, named *\*scratch*\*, is automatically
-when there are no other buffers left in the current session. (which is also
+created when there are no other buffers left in the current
-the case at Kakoune's startup when no files to open have been provided)
+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
+Debug buffers are used to gather diagnostics. They are not accessible
-over the buffers list.
+while cycling over the buffers list.
 
-A specific *\*debug*\* buffer is used by Kakoune to write errors or warnings.
+A specific *\*debug*\* buffer is used by Kakoune to write errors or
-This is also where the ouput of the `:debug` and the `:echo -debug` commands will land.
+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
+In this case, a buffer named `<buffername>` is created which reads
-from the fifo `<filename>`. When the fifo is written to, the buffer is
+its content from the fifo `<filename>`. When the fifo is written to,
-automatically updated.
+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
+This is very useful for running some commands asynchronously while
-their result in a buffer. See `rc/make.kak` and `rc/grep.kak` for examples.
+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
+When the buffer is deleted, the fifo will be closed, so any program
-to it will receive `SIGPIPE`. This is useful as it permits to stop the writing
+writing to it will receive `SIGPIPE`. This is useful as it permits to
-program when the buffer is deleted.
+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
+    * the '{' and '}' delimiters are configurable, any non alphanumeric
-    alphanumeric character
+    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
+The *group* highlighter is a container for other highlighters. A subgroup
-a subgroup to an existing group, or scope using:
+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
+While defining hook commands with a `%sh{}` block, some additional env
-the following expansions:
+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
+After these keys, a second key needs to be entered in order to specify
-object you want
+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*:::