Merge remote-tracking branch 'Delapouite/current-selection'

1 files changed, 71 insertions, 69 deletions

diff --git a/doc/pages/keys.asciidoc b/doc/pages/keys.asciidoc
index b2b376b2..9658f10a 100644
--- a/doc/pages/keys.asciidoc
+++ b/doc/pages/keys.asciidoc
@@ -81,7 +81,7 @@ In normal mode, commands can be prefixed with a numeric count, which can control
 the command behaviour.
 
 For example, *3W* selects 3 consecutive words and *3w* select the third word on
-the right of selection end.
+the right of the end of each selection.
 
 == Disabling Hooks
 
@@ -96,29 +96,29 @@ it when pasting text.
 
 'word' is a sequence of alphanumeric characters or underscore, and 'WORD'
 is a sequence of non whitespace characters. Generally, a movement on it own
-will move the selection to cover the text moved over, while holding down
-the Shift modifier and moving will extend the selection instead.
+will move each selection to cover the text moved over, while holding down
+the Shift modifier and moving will extend each selection instead.
 
 *h*, *<left>*::
-    select the character on the left of selection end
+    select the character on the left of the end of each selection
 
 *j*, *<down>*::
-    select the character below the selection end
+    select the character below the end of each selection
 
 *k*, *<up>*::
-    select the character above the selection end
+    select the character above the end of each selection
 
 *l*, *<right>*::
-    select the character on the right of selection end
+    select the character on the right of the end of each selection
 
 *w*::
-    select the word and following whitespaces on the right of selection end
+    select the word and following whitespaces on the right of the end of each selection
 
 *b*::
-    select preceding whitespaces and the word on the left of selection end
+    select preceding whitespaces and the word on the left of the end of each selection
 
 *e*::
-    select preceding whitespaces and the word on the right of selection end
+    select preceding whitespaces and the word on the right of the end of each selection
 
 *<a-[wbe]>*::
     same as [wbe] but select WORD instead of word
@@ -137,7 +137,7 @@ the Shift modifier and moving will extend the selection instead.
     in <<options#,`:doc options`>>
 
 *x*::
-    select line on which selection end lies (or next line when end lies
+    select line on which the end of each selection lies (or next line when end lies
     on an end-of-line)
 
 *<a-x>*::
@@ -192,17 +192,11 @@ the Shift modifier and moving will extend the selection instead.
 *<c-d>*::
     scroll half a page down
 
-*)*::
-    rotate main selection (the main selection becomes the next one)
-
-*(*::
-    rotate main selection backward (the main selection becomes the previous one)
-
 *;*::
     reduce selections to their cursor
 
 *<a-;>*::
-    flip the selections direction
+    flip the direction of each selection
 
 *<a-:>*::
     ensure selections are in forward direction (cursor after anchor)
@@ -213,40 +207,42 @@ the Shift modifier and moving will extend the selection instead.
 == Changes
 
 *i*::
-    enter insert mode before current selection
+    enter insert mode before selections
 
 *a*::
-    enter insert mode after current selection
+    enter insert mode after selections
 
 *d*::
-    yank and delete current selection
+    yank and delete selections
 
 *c*::
-    yank and delete current selection and enter insert mode
+    yank and delete selections and enter insert mode
 
 *.*::
     repeat last insert mode change (*i*, *a*, or *c*, including the
     inserted text)
 
 *<a-d>*::
-    delete current selection (not yanking)
+    delete selections (not yanking)
 
 *<a-c>*::
-    delete current selection and enter insert mode (not yanking)
+    delete selections and enter insert mode (not yanking)
 
 *I*::
-    enter insert mode at current selection begin line start
+    enter insert mode at the beginning of the lines containing
+    the start of each selection
 
 *A*::
-    enter insert mode at current selection end line end
+    enter insert mode at the end of the lines containing
+    the end of each selection
 
 *o*::
-    enter insert mode in a new line (or in a given count of new lines) below
-    current selection end
+    enter insert mode in a new line (or in a given count of new lines)
+    below the end of each selection
 
 *O*::
-    enter insert mode in a new line (or in a given count of new lines) above
-    current selection begin
+    enter insert mode in a new line (or in a given count of new lines)
+    above the beginning of each selection
 
 *<a-o>*::
     add an empty line below cursor
@@ -258,22 +254,22 @@ the Shift modifier and moving will extend the selection instead.
     yank selections
 
 *p*::
-    paste after current selection end
+    paste after the end of each selection
 
 *P*::
-    paste before current selection begin
+    paste before the beginning of each selection
 
 *<a-p>*::
-    paste all after current selection end, and select each pasted string
+    paste all after the end of each selection, and select each pasted string
 
 *<a-P>*::
-    paste all before current selection begin, and select each pasted string
+    paste all before the start of each selection, and select each pasted string
 
 *R*::
-    replace current selection with yanked text
+    replace selections with yanked text
 
 *<a-R>*::
-    replace current selection with every yanked text
+    replace selections with every yanked text
 
 *r*::
     replace each character with the next entered one
@@ -311,11 +307,11 @@ the Shift modifier and moving will extend the selection instead.
     (See <<expansions#shell-expansions,`:doc expansions shell-expansions`>>)
 
 *!*::
-    insert command output before selection. Shell expansions are available,
+    insert command output before each selection. Shell expansions are available,
     (See <<expansions#shell-expansions,`:doc expansions shell-expansions`>>)
 
 *<a-!>*::
-    append command output after selection. Shell expansions are available,
+    append command output after each selection. Shell expansions are available,
     (See <<expansions#shell-expansions,`:doc expansions shell-expansions`>>)
 
 *u*::
@@ -331,8 +327,8 @@ the Shift modifier and moving will extend the selection instead.
     move forward in history
 
 *&*::
-    align selection, align the cursor of selections by inserting spaces
-    before the first character of the selection
+    align selections, align the cursor of each selection by inserting spaces
+    before the first character of each selection
 
 *<a-&>*::
     copy indent, copy the indentation of the main selection (or the
@@ -348,11 +344,11 @@ the Shift modifier and moving will extend the selection instead.
     swap case
 
 *@*::
-    convert tabs to spaces in current selections, uses the buffer tabstop
+    convert tabs to spaces in each selection, uses the buffer tabstop
     option or the count parameter for tabstop
 
 *<a-@>*::
-    convert spaces to tabs in current selections, uses the buffer tabstop
+    convert spaces to tabs in each selection, uses the buffer tabstop
     option or the count parameter for tabstop
 
 *_*::
@@ -374,7 +370,7 @@ the Shift modifier and moving will extend the selection instead.
 == Goto commands
 
 *g*, *G*::
-    When a count is specified, *G* only extends the current selection to the given line,
+    When a count is specified, *G* only extends the selection to the given line,
     *g* sends the anchor to the given line and a menu is then displayed which waits
     for one of the following additional keys:
 
@@ -451,24 +447,24 @@ Current selections position can be saved in a register and restored later on.
 Marks use the *^* register by default (See <<registers#,`:doc registers`>>)
 
 *Z*::
-    save the current selections to the register
+    save selections to the register
 
 *z*::
-    restore the selections from the register
+    restore selections from the register
 
 *<a-z>*, *<a-Z>*::
-    *<a-z>* combines the selections from the register with the current ones, whereas
-    *<a-Z>* combines the current selections with the register; a menu is then
-    displayed which waits for one of the following additional keys:
+    *<a-z>* combines selections from the register with the current ones, whereas
+    *<a-Z>* combines current selections with the ones in the register; a menu
+    is then displayed which waits for one of the following additional keys:
 
     *a*:::
-        append the selections
+        append selections
 
     *u*:::
-        keep a union of the selections
+        keep a union of selections
 
     *i*:::
-        keep an intersection of the selections
+        keep an intersection of selections
 
     *<*:::
         select the selection with the leftmost cursor for each pair
@@ -500,11 +496,11 @@ Macros use the *@* register by default (See <<registers#,`:doc registers`>>)
 Searches use the */* register by default (See <<registers#,`:doc registers`>>)
 
 ***::
-    set the search pattern to the current selection (automatically
+    set the search pattern to the main selection (automatically
     detects word boundaries)
 
 *<a-***>*::
-    set the search pattern to the current selection (verbatim, no smart
+    set the search pattern to the main selection (verbatim, no smart
     detection)
 
 == Jump list
@@ -520,36 +516,36 @@ to skim through the jump list using:
     jump backward
 
 *<c-s>*::
-    save current selections
+    save selections
 
 == Multiple selections
 
 *s*::
-    create a selection
+    create a selection for each match of the given regex
 
 *S*::
-    split the current selection
+    split selections with the given regex
 
 *<a-s>*::
-    split the current selections on line boundaries
+    split selections on line boundaries
 
 *<a-S>*::
-    select first and last characters of each selections
+    select first and last characters of each selection
 
 *C*::
-    copy the current selection to the next line
+    copy the main selection to the next line
 
 *<a-C>*::
-    copy the current selection to the previous line
+    copy the main selection to the previous line
 
 *<space>*::
-    clear a multiple selection
+    clear selections to only keep the main one
 
 *<a-space>*::
-    clear the current selection
+    clear the main selection
 
 *<a-k>*::
-    keep the selections that match the given regex
+    keep selections that match the given regex
 
 *<a-K>*::
     clear selections that match the given regex
@@ -559,30 +555,36 @@ to skim through the jump list using:
     for which the shell returned 0. Shell expansions are available,
     (See <<expansions#shell-expansions,`:doc expansions shell-expansions`>>)
 
+*)*::
+    rotate main selection (the main selection becomes the next one)
+
+*(*::
+    rotate main selection backward (the main selection becomes the previous one)
+
 == Object Selection
 
 For nestable objects, a count can be used in order to specify which surrounding
 level to select.
 
 *<a-a>*::
-    selects the whole object
+    select the whole object
 
 *<a-i>*::
-    selects the inner object, that is the object excluding its surrounder.
+    select the inner object, that is the object excluding its surrounder.
     For example, for a quoted string, this will not select the quote, and
     for a word this will not select trailing spaces.
 
 *[*::
-    selects to object start
+    select to object start
 
 *]*::
-    selects to object end
+    select to object end
 
 *{*::
-    extends selections to object start
+    extend selections to object start
 
 *}*::
-    extends selections to object end
+    extend selections to object end
 
 After these keys, a second key needs to be entered in order to specify
 the wanted object: