Docs: add modes page

README.asciidoc

@@ -740,6 +740,8 @@ This feature is tailored for scripting/macros, as it provides a more predictable
 behaviour than leaving insert mode with `<esc>`, executing normal mode command
 and entering back insert mode (with which binding ?)
 
+See <<doc/pages/modes#,`:doc modes`>>.
+
 Highlighters
 ~~~~~~~~~~~~
 

doc/pages/mapping.asciidoc

@@ -33,7 +33,7 @@ The *map* command makes *key* behave as if the *keys* sequence was typed.
 
 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).
+in a 'normal' context). Refer to <<modes#,`:doc modes`>> for more details.
 
 An optional *-docstring* switch followed by a string can be used
 to describe what the mapping does. This docstring will be used
@@ -48,6 +48,8 @@ For more information about the values of the *scope* parameter, refer to
 
 == Mappable keys
 
+See <<keys#,`:doc keys`>> to discover the list of default bindings.
+
 For *key* and *keys* in the *map* command, the following key names can
 be used:
 

doc/pages/modes.asciidoc

@@ -0,0 +1,103 @@
+= Modes
+
+== Description
+
+Kakoune is a modal editor which means that keys have different effects depending
+on the current mode. Therefore, modes can be conceptualized as a way to group
+related behaviors together during a text editing workflow.
+
+By default Kakoune starts in Normal mode. A few keys let users enter other
+modes where they can focus on a specific task before going back to Normal mode
+explicitly with `<esc>` or automatically in the case of *one shot* modes.
+
+Modes are stored in a stack with the top of the stack being the active mode.
+So in some scenarios, the Normal mode may feel *nested* in another one.
+The `ModeChange` hook is triggered each time a mode is popped or pushed
+on this stack. See <<hooks#,`:doc hooks`>>
+
+To get a comprehensive list of commands available for each modes,
+see <<keys#,`:doc keys`>>.
+Most of them are described in *info* boxes in real-time if the `autoinfo` option is set.
+
+To customize key mappings in various modes, refer to <<mapping#,`:doc mapping`>>.
+
+== Builtin modes
+
+=== Normal mode
+
+Normal mode is the starting mode mainly dedicated to move, extend or create
+selections where users spend most of their time (besides inserting content).
+It also serves as a *basecamp* to access other modes.
+
+See normal commands <<keys#movement,`:doc keys movement`>>.
+
+=== Insert mode
+
+In Insert mode, typing keys add content to the current buffer like in many other
+text editors. There are several ways to reach Insert Mode and start editing at
+common locations for maximum efficiency (after cursor, at the beginning of the line…).
+See changes <<keys#changes,`:doc keys changes`>>.
+
+Use `<esc>` to go back to Normal Mode: it pops Insert mode from the modes stack.
+Use `<a-;>` to temporary enable Normal mode for one command: in this case, this quick
+Normal Mode is pushed on the modes stack.
+
+See insert commands <<keys#insert-mode,`:doc keys insert-mode`>>.
+
+=== Goto mode
+
+Default keys: `g`, `G`
+Goto mode groups commands dedicated to jump inside a buffer (top, bottom…).
+See goto commands <<keys#goto-commands,`:doc keys goto-commands`>>.
+
+=== View mode
+
+Default keys: `v`, `V`
+View mode let users center and scroll the current window.
+See view commands <<keys#view-commands,`:doc keys view-commands`>>.
+
+=== Menu mode
+
+Mode entered when a menu is displayed with the *menu* command or by autocompletion.
+Mappings are used to choose and select intended items.
+
+=== Prompt mode
+
+Mode entered with `:`, `/` or the `:prompt` command.
+The commands defined in this mode help editing.
+See prompt commands <<keys#prompt-commands,`:doc keys prompt-commands`>>.
+
+=== Object mode
+
+Mode entered with `<a-i>`, `<a-a>` and various combinations of `[]{}` keys.
+It aims at crafting semantic selections, often called *text-objects*.
+See object commands <<keys#object-commands,`:doc keys object-commands`>>.
+
+=== User mode
+
+Default key: `,`
+The user mode is empty by default and is the opportunity to store custom mappings
+with no risk to shadow builtin ones. The context of execution is always the Normal mode.
+
+== User modes
+
+The following two commands are useful in advanced use cases, when the builtin User mode
+gets too crowded by mappings competing for the same key that deserves to be split
+in more meaningful collections. It's mostly useful for plugin authors who want
+to bind their new commands in extensible menus.
+
+--------------------------------
+declare-user-mode <scope> <name>
+--------------------------------
+
+Declare a new custom mode that can later be referred by the *map* command.
+For example a `grep` custom mode to attach keys like `n` or `p` to skim
+through the output results.
+
+-------------------------------
+enter-user-mode <scope> <name>
+-------------------------------
+
+Enable the designated mode for the next key. Docstrings are shown in the automatic
+info box to increase discoverability. To keep illustrating the aforementioned
+fictional `grep` mode, a normal mapping on `<a-g>` could be used to enter this mode.