From c2541dbfe251067a3253594cc025240e6825f3b1 Mon Sep 17 00:00:00 2001 From: Delapouite Date: Fri, 23 Feb 2018 14:31:28 +0100 Subject: [PATCH] Docs: add modes page --- README.asciidoc | 2 + doc/pages/mapping.asciidoc | 4 +- doc/pages/modes.asciidoc | 103 +++++++++++++++++++++++++++++++++++++ 3 files changed, 108 insertions(+), 1 deletion(-) create mode 100644 doc/pages/modes.asciidoc diff --git a/README.asciidoc b/README.asciidoc index 43d21c4f..cc66f6f8 100644 --- a/README.asciidoc +++ b/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 ``, executing normal mode command and entering back insert mode (with which binding ?) +See <>. + Highlighters ~~~~~~~~~~~~ diff --git a/doc/pages/mapping.asciidoc b/doc/pages/mapping.asciidoc index c3c890fe..517c486c 100644 --- a/doc/pages/mapping.asciidoc +++ b/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 <> 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 <> to discover the list of default bindings. + For *key* and *keys* in the *map* command, the following key names can be used: diff --git a/doc/pages/modes.asciidoc b/doc/pages/modes.asciidoc new file mode 100644 index 00000000..12acf6f6 --- /dev/null +++ b/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 `` 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 <> + +To get a comprehensive list of commands available for each modes, +see <>. +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 <>. + +== 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 <>. + +=== 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 <>. + +Use `` to go back to Normal Mode: it pops Insert mode from the modes stack. +Use `` to temporary enable Normal mode for one command: in this case, this quick +Normal Mode is pushed on the modes stack. + +See insert commands <>. + +=== Goto mode + +Default keys: `g`, `G` +Goto mode groups commands dedicated to jump inside a buffer (top, bottom…). +See goto commands <>. + +=== View mode + +Default keys: `v`, `V` +View mode let users center and scroll the current window. +See 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 <>. + +=== Object mode + +Mode entered with ``, `` and various combinations of `[]{}` keys. +It aims at crafting semantic selections, often called *text-objects*. +See 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 +-------------------------------- + +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 +------------------------------- + +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 `` could be used to enter this mode.