doc: Write a dedicated "mapping" page

Closes #1189

doc/manpages/commands.asciidoc

@@ -118,21 +118,11 @@ command *q!* has to be used).
 	define a new command (c.f. the 'Declaring new commands' section below)
 
 *map* <scope> <mode> <key> <keys>::
-	make *key* behave as if *keys* were typed. with *scope*
+	bind a list of keys to a combination (c.f. the 'mapping' documentation
-	being one of *global*, *buffer* or *window*, *mode* being
+	page)
-	*insert*, *normal*, *prompt*, *menu* or *user*.
-
-	*user* mode allows for user mapping behind the *,* key. Keys
-	will be executed in normal mode.
-
-	An optional *-docstring* switch followed by a string can be used
-	to describe what the mapping does. This docstring will be used
-	in autoinfo boxes.
 
 *unmap* <scope> <mode> <key> [<expected>]::
-	remove the mapping of *key* in given *scope* and *mode*, if
+	unbind a key combination (c.f. the 'mapping' documentation page)
-	expected is specified, only remove the mapping it if matches
-	the expected keys.
 
 *hook* [-group <group>] <scope> <hook_name> <filtering_regex> <command>::
 	execute a command whenever an event is triggered (c.f. the 'hooks'

doc/manpages/keys.asciidoc

@@ -14,6 +14,9 @@ and *>*, such as *<esc>* or *<del>*. Modified keys are written between
 Control, or *a* for Alt, followed by a *-* and the key (either its
 name or ascii character), for example *<c-x>*, *<a-space>*.
 
+In order to bind some keys to arbitrary ones, refer to the 'mapping'
+documentation page.
+
 Insert mode
 -----------
 *<esc>*::
@@ -625,27 +628,3 @@ Prompt Commands
 
 *<c-o>*::
 	disable auto completion for this prompt
-
-Key mapping
------------
-Mapping a combination of keys to another one (a.k.a. key mapping or binding)
-can be done with the following command:
-
--------------------------------
-map <scope> <mode> <key> <keys>
--------------------------------
-
-*scope*::
-	can be one of *global*, *window* or *buffer*
-
-*mode*::
-	can be one of *insert*, *normal*, *prompt*, *menu*, *user* or a one
-	character long arbitrary prefix (the *user* mode uses the *,* prefix)
-
-*key*::
-	the key to which the combination will be bound
-
-*keys*::
-	string that lists the keys that will be executed when *key* is hit
-
-Keys are always executed within the *normal* mode.

doc/manpages/mapping.asciidoc

@@ -0,0 +1,52 @@
+KAKOUNE(1)
+==========
+
+NAME
+----
+mapping - a
+
+Description
+-----------
+Creating and removing shortcuts boils down to the following commands,
+respectively:
+
+---------------------------------------
+map [flags] <scope> <mode> <key> <keys>
+unmap <scope> <mode> <key> [<expected>]
+---------------------------------------
+
+The *map* command makes *key* behave as if the *keys* sequence was typed.
+
+*mode* dictates in what context the mapping will be available:
+
+	*insert*::
+		insert mode
+	*normal*::
+		normal mode
+	*prompt*::
+		prompts, such as when entering a command through *:*, or a regex through */*
+	*menu*::
+		mode entered when a menu is displayed with the 'menu' command
+	*user*::
+		mode entered when the user prefix is hit (default: ',')
+	*goto*::
+		mode entered when the goto key is hit (default: 'g')
+	*view*::
+		mode entered when the view key is hit (default: 'v')
+	*object*::
+		mode entered when an object selection is triggered (e.g. '<a-i>')
+
+The context of execution of the above modes is always the current one at the
+time of execution of the mapping, except for *user* mode (always executed
+in a 'normal' context).
+
+An optional *-docstring* switch followed by a string can be used
+to describe what the mapping does. This docstring will be used
+in autoinfo boxes.
+
+The *unmap* command removes a mapping of *key* in the given *scope* and
+*mode*. If *expected* is specified, the mapping is removed only if it is
+set to the same sequence of keys passed using the *expected* argument.
+
+For more information about the values of the *scope* parameter, refer to
+the 'scopes' documentation page.