Merge remote-tracking branch 'krobelus/04-replace-ranges-docs'

doc/autoedit.asciidoc

@@ -1,12 +1,12 @@
 Edition auto insertion in Kakoune
 =================================
 
-It is a quite common feature for code editor to help the programmer by 
+It is a quite common feature for a code editor to help the programmer
-automatically inserting some text in certain contexts. This document
+by automatically inserting some text in certain contexts. This document
 goal is to explain how this is done in Kakoune.
 
-There is no special support in Kakoune for this problem, hooks are
+There is no special support in Kakoune for this task, hooks are
-expected to be used in order to manage that, and the normal kakoune
+expected to be used in order to manage that, and the normal Kakoune
 editing command are expected to be expressive enough so that relatively
 complex indentation can be written concisely.
 
@@ -27,7 +27,7 @@ s^\h+<ret>y # 2. select the leading spaces and copy them
 j<a-h>P     # 3. go back to next line start and paste the spaces
 ----------------------------------------------------------------
 
-note that if nothing gets selected on phase *2.*, an error will be raised.
+Note that if nothing gets selected on phase *2.*, an error will be raised.
 
 We want to do that each time the user jumps a line, just after the new line
 is inserted. So the hook would be:
@@ -71,13 +71,13 @@ k<a-x>             # 1. select the previous line
 j<a-gt>            # 3. go back to next line and indent it even if it is empty
 -------------------------------------------------------------------------------
 
-Note that if no previous lines end with a +{+ or +(+, the +<a-k>+ command will
+Note that if no previous line ends with a +{+ or +(+, the +<a-k>+ command will
 raise an error, and stop the execution. This is what we want: it is similar to
 what would happen if we would continue with no selections; the following 
 commands would have no effects.
 
 However, the error would end up being caught by the hook execution code, and
-it will write informations about it in the debug buffer, which we do not want,
+it will write information about it in the debug buffer, which we do not want,
 as this is actually expected. In order to prevent that, the exec should be
 wrapped in a try command. So we would have:
 

doc/pages/changelog.asciidoc

@@ -13,7 +13,7 @@ released versions.
 
 * replace-ranges highlighter now support empty and multi-lines ranges
 
-* `%var{...}` now expands to list of strings, `$kak_quoted_...` now work
+* `%val{...}` now expands to list of strings, `$kak_quoted_...` now work
   as expected with these.
 
 == Kakoune v2020.01.16

doc/pages/commands.asciidoc

@@ -2,7 +2,7 @@
 
 Some commands take an exclamation mark (*!*), which can be used to force
 the execution of the command (i.e. to quit a modified buffer, the
-command *q!* has to be used). Aliases are mentionned below each commands.
+command *q!* has to be used). Aliases are mentioned below each command.
 
 *doc* <topic>::
     *alias* help +
@@ -74,12 +74,12 @@ of the file onto the filesystem
 
 *write-all* [-sync]::
     *alias* wa +
-    write all changed buffers that are associated to a file
+    write all changed buffers that are associated with a file
 
 *quit[!]* [<exit status>]::
     *alias* q +
     exit Kakoune, use quit! to force quitting even if there is some
-    unsaved buffers remaining. If specified, the client exit status
+    unsaved buffer remaining. If specified, the client exit status
     will be set to <exit status>
 
 *write-quit[!]* [-sync] [<exit status>]::
@@ -227,7 +227,7 @@ of the file onto the filesystem
         filesystem.
 
     *-quoting* <quoting>:::
-        define how each arguments are quoted in echo output:
+        define how arguments are quoted in echo output:
 
         - *raw* (default)::::
             just join each argument with a space
@@ -446,10 +446,10 @@ New commands can be defined using the *define-command* command:
 
 *-shell-script-completion*:::
     following string is a shell command which takes parameters as
-    positional params and output one completion candidate per line.
+    positional params and outputs one completion candidate per line.
     The provided shell command will run after each keypress
 
-    during the executing of the shell command, the following env vars are
+    during the execution of the shell command, the following env vars are
     available:
 
     - *kak_token_to_complete*::::
@@ -461,12 +461,12 @@ New commands can be defined using the *define-command* command:
 
 *-shell-script-candidates*:::
     following string is a shell command which takes parameters as
-    positional params and output one completion candidate per line.
+    positional params and outputs one completion candidate per line.
     The provided shell command will run once at the beginning of each
     completion session, candidates are cached and then used by kakoune
     internal fuzzy engine
 
-    during the executing of the shell command, the following env vars are
+    during the execution of the shell command, the following env vars are
     available:
 
     - *kak_token_to_complete*::::

doc/pages/faces.asciidoc

@@ -2,7 +2,7 @@
 
 == Declaration
 
-A 'face' refers how the specified text is displayed, it has a foreground
+A 'face' determines how text is displayed, it has a foreground
 color, a background color, and some attributes. The value of a face has the
 following format:
 
@@ -41,9 +41,9 @@ following format:
         *i*:::
             italic
         *F*:::
-            final, override the previous face instead of merging with it
+            final, override the previous face instead of merging with it,
-            an will only be replaced if another face with the final
+            and this face will only be replaced if another face with
-            attribute is applied
+            the final attribute is applied
         *f*:::
             final foreground, as final but only applies to face's
             foreground color
@@ -56,7 +56,7 @@ following format:
 
 'base'::
     The base face on which this face applies, which can be any face name,
-    as long as a cycle is not introduced. A face can reference itself, in
+    as long as no cycle is introduced. A face can reference itself, in
     which case it will apply on top of the parent scope version.
 
 == Builtin faces
@@ -80,10 +80,10 @@ areas of the user interface:
     cursor of the secondary selection
 
 *PrimaryCursorEol*::
-    cursor of the primary selection when it lies on and end of line character
+    cursor of the primary selection when it lies on an end of line character
 
 *SecondaryCursorEol*::
-    cursor of the secondary selection when it lies on and end of line character
+    cursor of the secondary selection when it lies on an end of line character
 
 *MenuForeground*::
     face for the selected element in menus
@@ -147,7 +147,7 @@ The following faces are used by builtin highlighters if enabled.
 == Markup strings
 
 In certain contexts, Kakoune can take a markup string, which is a string
-containing formatting informations. In these strings, the {facename}
+containing formatting information. In these strings, the {facename}
 syntax will enable the face facename until another face gets activated,
 or the end of the string is reached.
 
@@ -167,7 +167,7 @@ and can be used to avoid having to escape text that might be mistaken
 for markup instructions.
 
 For example this will prevent any '{' in the current buffer name from
-being incorrectly interpreted as markup instructions.
+being incorrectly interpreted as markup instruction.
 
 ----
 echo -markup "{Information}name:{\} %val{bufname}"

doc/pages/faq.asciidoc

@@ -3,7 +3,7 @@
 == How to pronounce the name of the project and what does it mean ?
 
 The name of the project is pronounced "Kak-oon", and is a word taken from a
-New Caledonian dialect based on french. It means a hard blow, usually a punch,
+New Caledonian dialect based on French. It means a hard blow, usually a punch,
 but generally refers to a blow into which all of one's strength went.
 
 == Is there going to be a Windows port of Kakoune ?
@@ -88,7 +88,7 @@ dedicated tool, as is the case with `clang` and C code: you can use the
 `clang-enable-autocomplete` and `clang-complete` builtin commands whenever
 editing a C/C++ file, and completion will work on function parameters.
 
-Note that the same features are available for python buffers, with the
+Note that the same features are available for Python buffers, with the
 `jedi` script.
 
 == Why aren't widely known command line shortcuts such as <c-w> or <c-u> available in Kakoune ?
@@ -145,7 +145,7 @@ possible.
 
 == My file seems to be highlighted with the wrong colors, I thought syntax highlighting was detected automatically ?
 
-The `file` utility has several short comings, such as detecting the
+The `file` utility has several shortcomings, such as detecting the
 wrong mimetype for a file containing data with different syntax, e.g.
 a Python script containing hardcoded HTML templates detected as an HTML
 file.
@@ -174,7 +174,7 @@ balanced against the ability to select data over several lines.
 
 As a fairly compliant follower of the UNIX philosophy, Kakoune does not
 try to implement features that are best handled by separate, dedicated
-tools. Windows splitting in terminals is a prime example of that
+tools. Window splitting in terminals is a prime example of that
 concept, where the editor provides commands to interact with several
 terminal multiplexers (e.g. `tmux`), as opposed to emulating their
 functionalities.

doc/pages/highlighters.asciidoc

@@ -62,7 +62,7 @@ highlighter is replaced with the new one.
         highlight the cursor line with a separate face
 
     *-separator* <separator text>:::
-        specify a string to separate the line numbers column with
+        specify a string to separate the line numbers column from
         the rest of the buffer (default is '|')
 
     *-min-digits* <num>:::
@@ -123,7 +123,7 @@ add-highlighter window/ dynregex '%reg{/}' 0:+i
 == Specs highlighters
 
 The following highlighters are useful to add indicators like lint warnings,
-git blame output or spelling typos.
+git blame output or spelling mistakes.
 See <<options#types,`:doc options types`>> for the format of `line-specs`
 and `range-specs`.
 
@@ -154,7 +154,8 @@ add-highlighter window/ ranges my_range
 *replace-ranges* <option_name>::
     use the data in the `range-specs` option of the given name to highlight
     the buffer. The string part of each tuple of the range-specs is
-    interpreted as a *display line* to display in place of the range.
+    interpreted as markup string (see <<faces#markup-strings,
+    `:doc faces markup-strings`>>) and displayed in place of the range.
     Here, the 3 first chars of the buffer will be replaced by the word 'red':
 
 --------------------------------------------------------
@@ -216,7 +217,7 @@ add-highlighter <path>/<name>/<region_name> region \
     match of *end*, preventing it from closing the region.
 
 *type* and *params*::
-    An highlighter type, and associated params, as they would be passed
+    A highlighter type, and associated params, as they would be passed
     to `add-highlighter` if they were not applied as a region.
 
 If the *-match-capture* switch is passed, then region closing and recurse
@@ -248,7 +249,7 @@ another region.
 
 That matches the rule governing most programming language parsing.
 
-A default region, that will apply its given highlighter for segments of the
+A default region, that will apply its given highlighter to the segments of the
 buffer that are not in any defined region, can be added with the *default-region*
 highlighter type.
 

doc/pages/hooks.asciidoc

@@ -171,7 +171,7 @@ name. Hooks with no description will always use an empty string.
 *RawKey* `key`::
     Triggered whenever a key is pressed by the user, regardless of what mode
     Kakoune is in, or what mappings are present (see
-    <<mapping#,`:doc mapping`>>). It cannot triggered by `execute-keys`,
+    <<mapping#,`:doc mapping`>>). It cannot be triggered by `execute-keys`,
     even with the `-with-hooks` option (see
     <<execeval#execute-keys-specific-switches,`:doc execeval execute-keys-specific-switches`>>).
 
@@ -194,7 +194,7 @@ vars are available:
 == Disabling Hooks
 
 Any normal mode command can be prefixed with `\ ` which will disable hook
-execution for the duration for the command (including the duration of modes
+execution for the duration of the command (including the duration of modes
 the command could move to, so `\i` will disable hooks for the whole insert
 session).
 

doc/pages/keys.asciidoc

@@ -144,7 +144,7 @@ the Shift modifier and moving will extend each selection instead.
     repeat last object or *f*/*t* selection command
 
 *m*::
-    select to the next sequence enclosed by matching character, see the
+    select to the next sequence enclosed by matching characters, see the
     `matching_pairs` option in <<options#,`:doc options`>>
 
 *M*::
@@ -152,12 +152,12 @@ the Shift modifier and moving will extend each selection instead.
     character, see the `matching_pairs` option in <<options#,`:doc options`>>
 
 *<a-m>*::
-    select to the previous sequence enclosed by matching character, see the
+    select to the previous sequence enclosed by matching characters, see the
     `matching_pairs` option in <<options#,`:doc options`>>
 
 *<a-M>*::
     extend the current selection to the previous sequence enclosed by matching
-    character, see the `matching_pairs` option in <<options#,`:doc options`>>
+    characters, see the `matching_pairs` option in <<options#,`:doc options`>>
 
 *x*::
     select line on which the end of each selection lies (or next line when end lies
@@ -292,10 +292,10 @@ Yanking (copying) and pasting use the *"* register by default (See <<registers#,
     indent selected lines, including empty lines
 
 *<*::
-    deindent selected lines
+    unindent selected lines
 
 *<a-<>*::
-    deindent selected lines, do not remove incomplete indent (3 leading
+    unindent selected lines, do not remove incomplete indent (3 leading
     spaces when indent is 4)
 
 *u*::
@@ -347,7 +347,7 @@ Yanking (copying) and pasting use the *"* register by default (See <<registers#,
     3<a-)>
 ----------
 
-    rotate (1, 2, 3) and (3, 4, 6) independently
+    rotates (1, 2, 3) and (3, 4, 6) independently
 
 *<a-(>*::
     rotate selections content backward

doc/pages/options.asciidoc

@@ -31,7 +31,7 @@ command:
 unset-option <scope> <name>
 ---------------------------
 
-Unsetting an option will make it fallback to the value of its parent mode,
+Unsetting an option will make it fallback to the value of its parent scope,
 hence options cannot be unset from the *global* scope.
 
 [[declare-option]]
@@ -111,9 +111,9 @@ are exclusively available to built-in options.
 
     All numeric fields are 1-based.
 
-    When the `update-option` is used on an option of this type, its
+    When the command `update-option` is used on an option of this type,
-    ranges gets updated according to all the buffer modifications that
+    its ranges get updated according to all the buffer modifications
-    happened since its timestamp.
+    that happened since its timestamp.
 
     `set -add` appends the new pair to the list
 
@@ -122,8 +122,8 @@ are exclusively available to built-in options.
 *line-specs*::
     a list of a line number and a corresponding flag (`<line>|<flag
     text>`), except for the first element which is just the timestamp
-    of the buffer. When the `update-option` is used on an option of this
+    of the buffer. When `update-option` is used on an option of this
-    type, its lines gets updated according to all the buffer modifications
+    type, its lines get updated according to all the buffer modifications
     that happened since its timestamp.
     See <<highlighters#specs-highlighters,`:doc highlighters specs-highlighters`>>)
     `set -add` appends the new spec to the list
@@ -134,7 +134,7 @@ are exclusively available to built-in options.
     `<line>.<column>[+<length>]@<timestamp>` format to define where the
     completion apply in the buffer.
 
-    Select commands are arbitrary kakoune commands that will be executed
+    Select commands are arbitrary Kakoune commands that will be executed
     each time the element is selected in the menu. The common use case is
     to display element specific documentation.
 

doc/pages/regex.asciidoc

@@ -147,8 +147,7 @@ More complex assertions can be expressed with lookarounds:
              not match the text preceding the current position
 
 For performance reasons lookaround contents must be sequence of literals,
-character classes or any-character (`.`); The use of quantifiers
+character classes or any-character (`.`); Quantifiers are not supported.
-are not supported.
 
 For example, `(?<!bar)(?=foo).` will match any character which is not
 preceded by `bar` and where `foo` matches from the current position
@@ -179,7 +178,7 @@ The syntax tries to follow the ECMAScript regex syntax as defined by
 https://www.ecma-international.org/ecma-262/8.0/ some divergences
 exists for ease of use or performance reasons:
 
-* lookarounds are not arbitrary, but lookbehind are supported.
+* lookarounds are not arbitrary, but lookbehind is supported.
 * `\K`, `\Q..\E`, `\A`, `\h` and `\z` are added.
 * Stricter handling of escaping, as we introduce additional
   escapes, identity escapes like `\X` with X a non-special character

doc/pages/registers.asciidoc

@@ -102,7 +102,7 @@ with:
     `%val{buffile}` of the buffer selections relate to
 
 *timestamp*::
-    `%val{timestamp}` at which the selection apply to
+    `%val{timestamp}` at which the selection applies to
 
 *main sel index*::
     0-based index of the main selection