From 1f02a1f7e2cb5ccbb3ccf18bf9156354b79d8f95 Mon Sep 17 00:00:00 2001 From: Maxime Coste Date: Sun, 12 Nov 2017 22:44:04 +0800 Subject: [PATCH] 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 | 43 ++++++++++++++++++--------------- doc/pages/expansions.asciidoc | 4 +-- doc/pages/highlighters.asciidoc | 4 +-- doc/pages/hooks.asciidoc | 4 +-- doc/pages/keys.asciidoc | 4 +-- doc/pages/options.asciidoc | 2 +- 6 files changed, 33 insertions(+), 28 deletions(-) diff --git a/doc/pages/buffers.asciidoc b/doc/pages/buffers.asciidoc index 68de1360..491cae13 100644 --- a/doc/pages/buffers.asciidoc +++ b/doc/pages/buffers.asciidoc @@ -2,29 +2,33 @@ == Commands -To open buffers or navigate through the buffers list -see <>. +To open buffers or navigate through the buffers list see +<>. == 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 [-scroll] --------------------------------------------- -In this case, a buffer named `` is created which reads its content -from the fifo ``. When the fifo is written to, the buffer is -automatically updated. +In this case, a buffer named `` is created which reads +its content from the fifo ``. 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. diff --git a/doc/pages/expansions.asciidoc b/doc/pages/expansions.asciidoc index 88068d7d..14149324 100644 --- a/doc/pages/expansions.asciidoc +++ b/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! diff --git a/doc/pages/highlighters.asciidoc b/doc/pages/highlighters.asciidoc index 7940b646..b8093238 100644 --- a/doc/pages/highlighters.asciidoc +++ b/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 group diff --git a/doc/pages/hooks.asciidoc b/doc/pages/hooks.asciidoc index b3fdc22e..6dd455f2 100644 --- a/doc/pages/hooks.asciidoc +++ b/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 diff --git a/doc/pages/keys.asciidoc b/doc/pages/keys.asciidoc index c0c86312..85588b39 100644 --- a/doc/pages/keys.asciidoc +++ b/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 diff --git a/doc/pages/options.asciidoc b/doc/pages/options.asciidoc index 0398af30..38434629 100644 --- a/doc/pages/options.asciidoc +++ b/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*:::