kakoune

Fork of kakoune, an acceptable text editor
git clone git://git.laack.co/kakoune.git
Log | Files | Refs

README.asciidoc (28670B)


      1 = image:{logo}[K,32,32,link="{website}",title="Kakoune logo by p0nce"] Kakoune image:{cirrus-img}[link="{cirrus-url}"] image:{srht-img}[link="{srht-url}"] image:{irc-img}[link="{irc-url}"]
      2 ifdef::env-github,env-browser[:outfilesuffix: .asciidoc]
      3 :logo: http://kakoune.org/img/kakoune_logo_32.png
      4 :website: https://kakoune.org
      5 :cirrus-img: https://api.cirrus-ci.com/github/mawww/kakoune.svg
      6 :cirrus-url: https://cirrus-ci.com/github/mawww/kakoune
      7 :srht-img: https://builds.sr.ht/~mawww/kakoune.svg
      8 :srht-url: https://builds.sr.ht/~mawww/kakoune?
      9 :irc-img: https://img.shields.io/badge/IRC-%23kakoune-blue.svg
     10 :irc-url: https://web.libera.chat/?channels=kakoune
     11 :icons: font
     12 :toc: right
     13 :pp: ++
     14 
     15 TL;DR
     16 -----
     17 
     18 {website}
     19 
     20 *Modal editor* -- *Faster as in fewer keystrokes* --
     21 *Multiple selections* -- *Orthogonal design*
     22 
     23 ---------------------------------------------
     24 git clone https://github.com/mawww/kakoune.git
     25 cd kakoune
     26 make
     27 ./src/kak
     28 ---------------------------------------------
     29 
     30 See https://github.com/mawww/golf for Kakoune solutions to vimgolf challenges,
     31 regularly beating the best Vim solution.
     32 
     33 See the link:doc/design.asciidoc[design document] for more information on
     34 Kakoune's philosophy and design.
     35 
     36 Introduction
     37 ------------
     38 
     39 Kakoune is a code editor that implements Vi's "keystrokes as a text editing
     40 language" model. As it is also a modal editor, it is somewhat similar to the
     41 Vim editor (after which Kakoune was originally inspired).
     42 
     43 Kakoune can operate in two modes: *normal* and *insertion*. In insertion mode,
     44 keys are directly inserted into the current buffer. In normal mode, keys
     45 are used to manipulate the current selection and to enter insertion mode.
     46 
     47 Kakoune has a strong focus on interactivity. Most commands provide immediate
     48 and incremental results, while being competitive with Vim in terms of keystroke count.
     49 
     50 Kakoune works on selections, which are oriented, inclusive ranges of characters.
     51 Selections have an anchor and a cursor. Most commands move both of
     52 them except when extending selections, where the anchor character stays fixed
     53 and the cursor moves around.
     54 
     55 See https://vimeo.com/82711574
     56 
     57 Join us on libera IRC `#Kakoune`
     58 
     59 Features
     60 ~~~~~~~~
     61 
     62  * Multiple selections as a central way of interacting
     63  * Powerful selection manipulation primitives
     64    - Select all regex matches in current selections
     65    - Keep selections containing/not containing a match for a given regex
     66    - Split current selections with a regex
     67    - Text objects (paragraph, sentence, nestable blocks)
     68  * Powerful text manipulation primitives
     69    - Align selections
     70    - Rotate selection contents
     71    - Case manipulation
     72    - Indentation
     73    - Piping each selection to external filter
     74  * Client-Server architecture
     75    - Multiple clients on the same editing session
     76    - Use tmux, zellij, kitty, wezterm or your X11/Wayland window manager to
     77      manage splits/panes by spawning clients connected to the same session
     78  * Simple interaction with external programs
     79  * Automatic contextual help
     80  * Automatic as you type completion
     81  * Macros
     82  * Hooks
     83  * Syntax Highlighting
     84    - Supports multiple languages in the same buffer
     85    - Highlight a buffer differently in different windows
     86 
     87 Screenshots
     88 ~~~~~~~~~~~
     89 
     90 [[screenshot-i3]]
     91 .Kakoune in i3
     92 image::doc/screenshot-i3.gif[Kakoune in i3]
     93 
     94 [[screenshot-tmux]]
     95 .Kakoune in tmux
     96 image::doc/screenshot-tmux.gif[Kakoune in tmux]
     97 
     98 Getting started
     99 ---------------
    100 
    101 Building
    102 ~~~~~~~~
    103 
    104 Kakoune's dependencies are:
    105 
    106  * A {cpp}20 compliant compiler (GCC >= 10.3 or clang >= 11) along with its
    107    associated {cpp} standard library (libstdc{pp} >= 10 or libc{pp})
    108 
    109 To build, just type *make* in the root directory.
    110 To generate man pages, type *make man* in the root directory.
    111 
    112 Kakoune can be built on Linux, MacOS, and Cygwin. Due to Kakoune relying heavily
    113 on being in a Unix-like environment, no native Windows version is planned.
    114 
    115 Installing
    116 ~~~~~~~~~~
    117 
    118 In order to install *kak* on your system, rather than running it directly from
    119 its source directory, type *make install*. You can specify the `PREFIX` and
    120 `DESTDIR` if needed.
    121 
    122 [TIP]
    123 .Homebrew (macOS) or Linuxbrew
    124 ====
    125 ---------------------------------
    126 brew install kakoune
    127 ---------------------------------
    128 ====
    129 
    130 [TIP]
    131 .MacPorts (macOS)
    132 ====
    133 ---------------------------------
    134 sudo port selfupdate
    135 sudo port install kakoune
    136 ---------------------------------
    137 ====
    138 
    139 [TIP]
    140 .Fedora supported versions and Rawhide
    141 ====
    142 ---------------------------------
    143 dnf install kakoune
    144 ---------------------------------
    145 ====
    146 
    147 [TIP]
    148 .Fedora daily builds
    149 ====
    150 Use the https://copr.fedoraproject.org/coprs/jkonecny/kakoune/[copr] repository.
    151 ---------------------------------
    152 dnf copr enable jkonecny/kakoune
    153 dnf install kakoune
    154 ---------------------------------
    155 ====
    156 
    157 [TIP]
    158 .RHEL/CentOS 8
    159 ====
    160 Kakoune can be found in the https://src.fedoraproject.org/rpms/kakoune/tree/epel8[EPEL8 repositories].
    161 ---------------------------------
    162 dnf install kakoune
    163 ---------------------------------
    164 ====
    165 
    166 [TIP]
    167 .Arch Linux
    168 ====
    169 Kakoune is found in the https://www.archlinux.org/packages/community/x86_64/kakoune/[repositories].
    170 --------------------------------------------------
    171 pacman -S kakoune
    172 --------------------------------------------------
    173 ====
    174 
    175 [TIP]
    176 .Gentoo
    177 ====
    178 Kakoune is found in portage as
    179 https://packages.gentoo.org/packages/app-editors/kakoune[app-editors/kakoune].
    180 --------------------------------
    181 emerge kakoune
    182 --------------------------------
    183 https://wiki.gentoo.org/wiki/Kakoune[Installation and Gentoo specific documentation] is available.
    184 ====
    185 
    186 [TIP]
    187 .Exherbo
    188 ====
    189 --------------------------------
    190 cave resolve -x repository/mawww
    191 cave resolve -x kakoune
    192 --------------------------------
    193 ====
    194 
    195 [TIP]
    196 .openSUSE
    197 ====
    198 Kakoune can be found in the https://software.opensuse.org/package/kakoune[repositories].
    199 
    200 ---------------------------
    201 sudo zypper install kakoune
    202 ---------------------------
    203 ====
    204 
    205 [TIP]
    206 .Ubuntu
    207 ====
    208 Kakoune can be found in the Ubuntu repositories.
    209 
    210 ----------------------------
    211 sudo apt install kakoune
    212 ----------------------------
    213 
    214 If you want to compile from source on 20.04 or earlier, you must force the build to use GCC 10, which is not the default. Also, make sure you have .local/bin in your path so that kak is available after the installation.
    215 
    216 ----------------------------------------------------------------
    217 git clone https://github.com/mawww/kakoune.git && cd kakoune/src
    218 CXX=g++-10 make
    219 make PREFIX=$HOME/.local install
    220 ----------------------------------------------------------------
    221 ====
    222 
    223 [TIP]
    224 .Debian
    225 ====
    226 Kakoune can be found in Debian 9 (Stretch) and later releases.
    227 
    228 ---------------------------
    229 sudo apt install kakoune
    230 ---------------------------
    231 ====
    232 
    233 [TIP]
    234 .FreeBSD
    235 ====
    236 Kakoune is available in the official ports tree as
    237 https://www.freshports.org/editors/kakoune[editors/kakoune].
    238 
    239 A binary package is also available and can be installed with
    240 --------------------------------------------------
    241 pkg install kakoune
    242 --------------------------------------------------
    243 ====
    244 
    245 [TIP]
    246 .OpenBSD
    247 ====
    248 Building on OpenBSD 6.7 amd64.
    249 
    250 --------------------------------------------------
    251 # pkg_add git gmake
    252 # git clone https://github.com/mawww/kakoune
    253 # cd kakoune
    254 # export CXX=clang++
    255 # gmake install
    256 --------------------------------------------------
    257 
    258 Kakoune is available in the 6.7-current port tree as 
    259 http://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/editors/kakoune/[editors/kakoune]
    260 
    261 A binary package is also available for -current snapshot and can be installed with
    262 --------------------------------------------------
    263 # pkg_add kakoune
    264 --------------------------------------------------
    265 
    266 Running with support for plugins.
    267 --------------------------------------------------
    268 # pkg_add dash
    269 $ export KAKOUNE_POSIX_SHELL=/usr/local/bin/dash 
    270 $ kak
    271 --------------------------------------------------
    272 ====
    273 
    274 [TIP]
    275 .Solus
    276 ====
    277 Kakoune is available in the Solus stable repository.
    278 
    279 It can be installed with
    280 ---------------------
    281 eopkg install kakoune
    282 ---------------------
    283 ====
    284 
    285 [TIP]
    286 .Void
    287 ====
    288 Kakoune is available in the repositories.
    289 
    290 It can be installed with
    291 -----------------------
    292 xbps-install -S kakoune
    293 -----------------------
    294 ====
    295 
    296 [TIP]
    297 .Termux
    298 ====
    299 Kakoune is available in the repositories.
    300 
    301 It can be installed with
    302 -------------------
    303 pkg install kakoune
    304 -------------------
    305 ====
    306 
    307 [TIP]
    308 .Nix
    309 ====
    310 --------------------------------
    311 nix-env -iA nixpkgs.kakoune
    312 --------------------------------
    313 ====
    314 
    315 [TIP]
    316 .pkgsrc (NetBSD, SmartOS, macOS, Linux, etc)
    317 ====
    318 --------------------------------
    319 pkg_add kakoune
    320 --------------------------------
    321 ====
    322 https://repology.org/project/kakoune/versions[image:https://repology.org/badge/vertical-allrepos/kakoune.svg[Packaging status]]
    323 
    324 Running
    325 ~~~~~~~
    326 
    327 Running *kak* launches a new kak session with a client on local terminal.
    328 Run *kak -help* to discover the valid command line flags.
    329 
    330 Configuration
    331 ^^^^^^^^^^^^^
    332 
    333 There are two directories containing Kakoune's scripts:
    334 
    335 * `runtime`: located in `../share/kak/` relative to the `kak` binary
    336   contains the system scripts, installed with Kakoune.
    337 * `userconf`: located in `$XDG_CONFIG_HOME/kak/`, which will fallback
    338   to `$HOME/.config/kak/` if `$XDG_CONFIG_HOME` is not set, containing
    339   the user configuration.
    340 
    341 Unless `-n` is specified, Kakoune will load its startup script located
    342 at `${runtime}/kakrc` relative to the `kak` binary. This startup script
    343 is responsible for loading the user configuration.
    344 
    345 First, Kakoune will search recursively for `.kak` files in the `autoload`
    346 directory. It will first look for an `autoload` directory at
    347 `${userconf}/autoload` and will fallback to `${runtime}/autoload` if
    348 it does not exist.
    349 
    350 Once all those files are loaded, Kakoune will try to source
    351 `${runtime}/kakrc.local`, which is expected to contain distribution provided
    352 configuration.
    353 
    354 Finally, the user configuration will load from `${userconf}/kakrc`.
    355 
    356 NOTE: If you create a user `autoload` directory in `${userconf}/autoload`,
    357 the system one at `${runtime}/autoload` will not load anymore. You can
    358 add a symbolic link to it (or to individual scripts) inside
    359 `${userconf}/autoload` to keep loading system scripts.
    360 
    361 Basic Interaction
    362 -----------------
    363 
    364 Selections
    365 ~~~~~~~~~~
    366 
    367 The main concept in Kakoune is the selection. A selection is an inclusive,
    368 directed range of characters. A selection has two ends, the anchor and the
    369 cursor.
    370 
    371 There is always at least one selection, and a selection is always at least
    372 one character (in which case the anchor and cursor of the selection are
    373 on the same character).
    374 
    375 Normal Mode
    376 ~~~~~~~~~~~
    377 
    378 In normal mode, keys are not inserted directly inside the buffer, but are editing
    379 commands. These commands provide ways to manipulate either the selections themselves
    380 or the selected text.
    381 
    382 Insert Mode
    383 ~~~~~~~~~~~
    384 
    385 When entering insert mode, keys are now directly inserted before each
    386 selection's cursor. Some additional keys are recognised in insert mode:
    387 
    388  * `<esc>`: leave insert mode
    389  * `<backspace>`: delete characters before cursors
    390  * `<del>`: delete characters under cursors
    391  * `<left>, <right>, <up>, <down>`: move cursors in given direction
    392  * `<home>`: move cursors to line beginning
    393  * `<end>`: move cursors to line ending
    394 
    395  * `<c-n>`: select next completion candidate
    396  * `<c-p>`: select previous completion candidate
    397  * `<c-x>`: explicit insert completion query, followed by:
    398    - `f`: explicit file completion
    399    - `w`: explicit word completion
    400    - `l`: explicit line completion
    401  * `<c-o>`: disable automatic completion for this insert session
    402 
    403  * `<c-r>`: insert contents of the register given by next key
    404  * `<c-v>`: insert next keystroke directly into the buffer,
    405     without interpreting it
    406 
    407  * `<c-u>`: commit changes up to now as a single undo group
    408 
    409  * `<a-;>`: escape to normal mode for a single command
    410 
    411 Movement
    412 ~~~~~~~~
    413 
    414 See <<Appending>> below for instructions on extending (appending to) the current selection in order to select more text.
    415 
    416  * `h`: select the character on the left of selection end
    417  * `j`: select the character below the selection end
    418  * `k`: select the character above the selection end
    419  * `l`: select the character on the right of selection end
    420 
    421  * `w`: select the word and following whitespaces on the right of selection end
    422  * `b`: select preceding whitespaces and the word on the left of selection end
    423  * `e`: select preceding whitespaces and the word on the right of selection end
    424  * `<a-[wbe]>`: same as [wbe], but select WORD instead of word
    425 
    426  * `f`: select to (including) the next occurrence of the given character
    427  * `t`: select until (excluding) the next occurrence of the given character
    428  * `<a-[ft]>`: same as [ft] but in the other direction
    429 
    430  * `m`: select to matching character
    431  * `M`: extend selection to matching character
    432 
    433  * `x`: expand selections to contain full lines (including end-of-lines)
    434  * `<a-x>`: trim selections to only contain full lines (including
    435             end-of-lines)
    436 
    437  * `%`: select whole buffer
    438 
    439  * `<a-h>`: select to line begin
    440  * `<a-l>`: select to line end
    441 
    442  * `/`: search (select next match)
    443  * `<a-/>`: search (select previous match)
    444  * `?`: search (extend to next match)
    445  * `<a-?>`: search (extend to previous match)
    446  * `n`: select next match
    447  * `N`: add a new selection with next match
    448  * `<a-n>`: select previous match
    449  * `<a-N>`: add a new selection with previous match
    450 
    451  * `pageup, <c-b>`: scroll one page up
    452  * `pagedown, <c-f>`: scroll one page down
    453  * `<c-u>`: scroll half a page up
    454  * `<c-d>`: scroll half a page down
    455 
    456  * `)`: rotate selections (the main selection becomes the next one)
    457  * `(`: rotate selections backwards
    458 
    459  * `;`: reduce selections to their cursor
    460  * `<a-;>`: flip the selections' direction
    461  * `<a-:>`: ensure selections are in forward direction (cursor after anchor)
    462 
    463  * `<a-.>`: repeat last object or `f`/`t` selection command.
    464 
    465  * `_`: trim selections
    466 
    467 A word is a sequence of alphanumeric characters or underscore, a WORD is a
    468 sequence of non whitespace characters.
    469 
    470 Appending
    471 ~~~~~~~~~
    472 
    473 For most <<Movement>> commands, using `Shift` extends the current selection
    474 instead of replacing it.
    475 
    476 Examples:
    477 
    478  * `wWW` selects 3 consecutive words: first `w` selects a word, then `WW` extends the selection two words further.
    479  * `f/F/` selects up to and including the second `/` character forward.
    480 
    481 Using Counts
    482 ~~~~~~~~~~~~
    483 
    484 Most selection commands also support counts, which are entered before the
    485 command itself.
    486 
    487 For example, `3W` selects 3 consecutive words and `3w` select the third word on
    488 the right of selection end.
    489 
    490 Disabling Hooks
    491 ~~~~~~~~~~~~~~~
    492 
    493 Any normal mode command can be prefixed with `\` which will disable hook execution
    494 for the duration for the command (including the duration of modes the command could
    495 move to, so `\i` will disable hooks for the whole insert session).
    496 
    497 As autoindentation is implemented in terms of hooks, this can be used to disable
    498 it when pasting text.
    499 
    500 Changes
    501 ~~~~~~~
    502 
    503  * `i`: enter insert mode before each selection
    504  * `a`: enter insert mode after each selection
    505  * `d`: yank and delete each selection
    506  * `c`: yank and delete each selection and enter insert mode
    507  * `.`: repeat last insert mode change (`i`, `a`, or `c`, including
    508         the inserted text)
    509 
    510  * `<a-d>`: delete each selection
    511  * `<a-c>`: delete each selection and enter insert mode
    512 
    513  * `I`: enter insert mode at each selection begin line start
    514  * `A`: enter insert mode at each selection end line end
    515  * `o`: enter insert mode in one (or given count) new lines below
    516         each selection end
    517  * `O`: enter insert mode in one (or given count)  new lines above
    518         each selection begin
    519 
    520  * `<a-o>`: add an empty line below each cursor
    521  * `<a-O>`: add an empty line above each cursor
    522 
    523  * `y`: yank selections
    524  * `p`: paste after each selection end
    525  * `P`: paste before each selection begin
    526  * `<a-p>`: paste all after each selection end
    527  * `<a-P>`: paste all before each selection begin
    528  * `R`: replace each selection with yanked text
    529  * `<a-R>`: replace each selection with every yanked text
    530 
    531  * `r`: replace each character with the next entered one
    532 
    533  * `<a-j>`: join selected lines
    534  * `<a-J>`: join selected lines and select spaces inserted
    535             in place of line breaks
    536  * `<a-_>`: merge contiguous selections together (works across lines as well)
    537 
    538  * `<gt> (>)`: indent selected lines
    539  * `<a-gt>`: indent selected lines, including empty lines
    540  * `<lt> (<)`: deindent selected lines
    541  * `<a-lt>`: deindent selected lines, do not remove incomplete
    542         indent (3 leading spaces when indent is 4)
    543 
    544  * `|`: pipe each selection through the given external filter program
    545         and replace the selection with its output.
    546  * `<a-|>`: pipe each selection through the given external filter program
    547         and ignore its output
    548 
    549  * `!`: insert command output before each selection
    550  * `<a-!>`: append command output after each selection
    551 
    552  * `u`: undo last change
    553  * `<c-k>`: move backward in history
    554  * `<a-u>`: undo selection changes
    555  * `U`: redo last change
    556  * `<c-j>`: move forward in history
    557  * `<a-U>`: redo selection changes
    558 
    559  * `&`: align selections, align the cursor of selections by inserting
    560         spaces before the first character of the selection
    561  * `<a-&>`: copy indent, copy the indentation of the main selection
    562         (or the count one if a count is given) to all other ones
    563 
    564  * ```: to lower case
    565  * `~`: to upper case
    566  * ``<a-`>``: swap case
    567 
    568  * `@`: convert selected tabs to spaces, uses the buffer tabstop option or
    569         the count parameter for tabstop.
    570  * `<a-@>`: convert selected spaces to tabs, uses the buffer tabstop option
    571             or the count parameter for tabstop.
    572 
    573  * `<a-)>`: rotate selections content, if specified, the count groups
    574             selections, so `3<a-)>` rotate (1, 2, 3) and (4, 5, 6)
    575             independently.
    576  * `<a-(>`: rotate selections content backwards
    577 
    578 Goto Commands
    579 ~~~~~~~~~~~~~
    580 
    581 Commands beginning with `g` are used to goto certain position and or buffer.
    582 If a count is given prior to hitting `g`, `g` will jump to the given line.
    583 Using `G` will extend the selection rather than jump.
    584 
    585 See <<doc/pages/keys#goto-commands,`:doc keys goto-commands`>>.
    586 
    587 View commands
    588 ~~~~~~~~~~~~~
    589 
    590 Commands beginning with `v` permit to center or scroll the current
    591 view. Using `V` will lock view mode until `<esc>` is hit
    592 
    593 See <<doc/pages/keys#view-commands,`:doc keys view-commands`>>.
    594 
    595 Marks
    596 ~~~~~
    597 
    598 Current selections position can be saved in a register and restored later on.
    599 
    600 See <<doc/pages/keys#marks,`:doc keys marks`>>.
    601 
    602 Jump list
    603 ~~~~~~~~~
    604 
    605 Some commands, like the goto commands, buffer switch or search commands,
    606 push the previous selections to the client's jump list.
    607 
    608 See <<doc/pages/keys#jump-list,`:doc keys jump-list`>>.
    609 
    610 Multi Selection
    611 ~~~~~~~~~~~~~~~
    612 
    613 Kak was designed from the start to handle multiple selections.
    614 One way to get a multiselection is via the `s` key.
    615 
    616 For example, to change all occurrences of word 'roger' to word 'marcel'
    617 in a paragraph, here is what can be done:
    618 
    619  * select the paragraph with `x` then enough `J`
    620  * press `s` and enter roger, then enter
    621  * now paragraph selection was replaced with multiselection of each roger in
    622 the paragraph
    623  * press `c` and marcel<esc> to replace rogers with marcels
    624 
    625 A multiselection can also be obtained with `S`, which splits the current
    626 selection according to the regex entered. To split a comma separated list,
    627 use `S` then ', *'
    628 
    629 The regex syntax supported by Kakoune is the based on the ECMAScript script
    630 syntax and is described at <<doc/pages/regex#,`:doc regex`>>.
    631 
    632 `s` and `S` share the search pattern with `/`, and hence entering an empty
    633 pattern uses the last one.
    634 
    635 As a convenience, `<a-s>` allows you to split the current selections on
    636 line boundaries.
    637 
    638 To clear multiple selections, use `,`. To keep only the nth selection
    639 use `n` followed by `,`, in order to remove a selection, use `<a-,>`.
    640 
    641 `<a-k>` allows you to enter a regex and keep only the selections that
    642 contains a match for this regex. Using `<a-K>` you can keep the selections
    643 not containing a match.
    644 
    645 `C` duplicates selections on the lines that follow them, column-wise.
    646 `<a-C>` does the same but on the preceding lines.
    647 
    648 `$` allows you to enter a shell command and pipe each selection to it.
    649 Selections whose shell command returns 0 will be kept, other will be dropped.
    650 
    651 Object Selection
    652 ~~~~~~~~~~~~~~~~
    653 
    654 Objects are specific portions of text, like sentences, paragraphs, numbers…
    655 Kakoune offers many keys allowing you to select various text objects.
    656 
    657 See <<doc/pages/keys#object-selection,`:doc keys object-selection`>>.
    658 
    659 Commands
    660 --------
    661 
    662 When pressing `:` in normal mode, Kakoune will open a prompt to enter a command.
    663 
    664 Commands are used for non editing tasks, such as opening a buffer, writing the
    665 current one, quitting, etc.
    666 
    667 See <<doc/pages/keys#prompt-commands,`:doc keys prompt-commands`>>.
    668 
    669 Basic Commands
    670 ~~~~~~~~~~~~~~
    671 
    672 Some commands take an exclamation mark (`!`), which can be used to force
    673 the execution of the command (i.e. to quit a modified buffer, the
    674 command `q!` has to be used).
    675 
    676 Commands starting with horizontal whitespace (e.g. a space) will not be
    677 saved in the command history.
    678 
    679  * `cd [<directory>]`: change the current directory to `<directory>`, or the home directory if unspecified
    680  * `doc <topic>`: display documentation about a topic. The completion list
    681      displays the available topics.
    682  * `e[dit][!] <filename> [<line> [<column>]]`: open buffer on file, go to given
    683      line and column. If file is already opened, just switch to this file.
    684      Use edit! to force reloading.
    685  * `w[rite][!] [<filename>]`: write buffer to <filename> or use its name if
    686      filename is not given. If the file is write-protected, its
    687      permissions are temporarily changed to allow saving the buffer and
    688      restored afterwards when the write! command is used.
    689  * `w[rite]a[ll]`: write all buffers that are associated to a file.
    690  * `q[uit][!] [<exit status>]`: exit Kakoune, use quit! to force quitting even
    691      if there is some unsaved buffers remaining. If specified, the client exit
    692      status will be set to <exit status>.
    693  * `w[a]q[!] [<exit status>]`: write the current buffer (or all buffers when
    694      `waq` is used) and quit. If specified, the client exit status will be set
    695      to <exit status>.
    696  * `kill[!]`: terminate the current session, all the clients as well as the server,
    697      use kill! to ignore unsaved buffers
    698  * `b[uffer] <name>`: switch to buffer <name>
    699  * `b[uffer]n[ext]`: switch to the next buffer
    700  * `b[uffer]p[rev]`: switch to the previous buffer
    701  * `d[el]b[uf][!] [<name>]`: delete the buffer <name>
    702  * `source <filename>`: execute commands in <filename>
    703  * `colorscheme <name>`: load named colorscheme.
    704  * `rename-client <name>`: set current client name
    705  * `rename-buffer <name>`: set current buffer name
    706  * `rename-session <name>`: set current session name
    707  * `echo [options] <text>`: show <text> in status line, with the following options:
    708    ** `-markup`: expand the markup strings in <text>
    709    ** `-debug`: print the given text to the `\*debug*` buffer
    710  * `nop`: does nothing, but as with every other commands, arguments may be
    711      evaluated. So nop can be used for example to execute a shell command
    712      while being sure that its output will not be interpreted by kak.
    713      `:%sh{ echo echo tchou }` will echo tchou in Kakoune, whereas
    714      `:nop %sh{ echo echo tchou }` will not, but both will execute the
    715      shell command.
    716  * `fail <text>`: raise an error, uses <text> as its description
    717 
    718 Multiple commands
    719 ~~~~~~~~~~~~~~~~~
    720 
    721 Multiple commands can be separated either by new lines or by semicolons,
    722 as such a semicolon must be escaped with `\;` to be considered as a literal
    723 semicolon argument.
    724 
    725 String syntax and expansions
    726 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    727 
    728 Values, options and shell context can be interpolated in strings.
    729 
    730 See <<doc/pages/expansions#,`:doc expansions`>>.
    731 
    732 Configuration & Autoloading
    733 ---------------------------
    734 
    735 Kakrc
    736 ~~~~~
    737 
    738 If not launched with the `-n` switch, Kakoune will source the
    739 `../share/kak/kakrc` file relative to the `kak` binary, which
    740 will source additional files:
    741 
    742 If the `$XDG_CONFIG_HOME/kak/autoload` directory exists, load every
    743 `*.kak` files in it, and load recursively any subdirectory.
    744 
    745 If it does not exist, falls back to the site wide autoload directory
    746 in `../share/kak/autoload/`.
    747 
    748 After that, if it exists, source the `$XDG_CONFIG_HOME/kak/kakrc` file
    749 which should be used for user configuration.
    750 
    751 In order to continue autoloading site-wide files with a local autoload
    752 directory, just add a symbolic link to `../share/kak/autoload/` into
    753 your local autoload directory.
    754 
    755 Color Schemes
    756 ~~~~~~~~~~~~~
    757 
    758 Kakoune ships with some color schemes that are installed to
    759 `../share/kak/colors/`. If `$XDG_CONFIG_HOME/kak/colors/` is present
    760 the builtin command `colorscheme` will offer completion for those
    761 color schemes. If a scheme is duplicated in userspace, it will take
    762 precedence.
    763 
    764 Options
    765 -------
    766 
    767 Kakoune can store named and typed values that can be used both to
    768 customize the core editor behaviour, and to keep data used by extension
    769 scripts.
    770 
    771 See <<doc/pages/options#,`:doc options`>>.
    772 
    773 
    774 Advanced topics
    775 ---------------
    776 
    777 Faces
    778 ~~~~~
    779 
    780 Faces describe how characters are displayed on the screen: color, bold, italic...
    781 
    782 See <<doc/pages/faces#,`:doc faces`>>.
    783 
    784 Registers
    785 ~~~~~~~~~
    786 
    787 Registers are named lists of text. They are used for various purposes,
    788 like storing the last yanked text, or the captured groups associated with the selections.
    789 
    790 See <<doc/pages/registers#,`:doc registers`>>.
    791 
    792 Macros
    793 ~~~~~~
    794 
    795 Kakoune can record and replay a sequence of key presses.
    796 
    797 See <<doc/pages/keys#macros,`:doc keys macros`>>.
    798 
    799 Search selection
    800 ~~~~~~~~~~~~~~~~
    801 
    802 Using the `*` key, you can set the search pattern to the current selection.
    803 See <<doc/pages/keys#searching,`:doc keys searching`>>.
    804 
    805 Regex syntax
    806 ~~~~~~~~~~~~
    807 
    808 Kakoune regex syntax is based on the ECMAScript syntax (ECMA-262 standard).
    809 It always runs on Unicode codepoint sequences, not on bytes.
    810 
    811 See <<doc/pages/regex#,`:doc regex`>>.
    812 
    813 Exec and Eval
    814 ~~~~~~~~~~~~~
    815 
    816 The `execute-keys` and `evaluate-commands` are useful for scripting
    817 in non interactive contexts.
    818 
    819 See <<doc/pages/execeval#,`:doc execeval`>>.
    820 
    821 Insert mode completion
    822 ~~~~~~~~~~~~~~~~~~~~~~
    823 
    824 Kakoune can propose completions while inserting text: filenames, words, lines…
    825 
    826 See <<doc/pages/keys#insert-mode-completion,`:doc keys insert-mode-completion`>>.
    827 
    828 Escape to normal mode
    829 ~~~~~~~~~~~~~~~~~~~~~
    830 
    831 From insert mode, pressing `<a-;>` allows you to execute a single normal mode
    832 command. This provides a few advantages:
    833 
    834  * The selections are not modified: when leaving insert mode using `<esc>` the
    835    selections can change, for example when insert mode was entered with `a` the
    836    cursor will go back one char. Or if on an end of line the cursor will go back
    837    left (if possible).
    838 
    839  * The modes are nested: that means the normal mode can enter prompt (with `:`),
    840    or any other modes (using `:on-key` or `:menu` for example), and these modes
    841    will get back to the insert mode afterwards.
    842 
    843 This feature is tailored for scripting/macros, as it provides a more predictable
    844 behaviour than leaving insert mode with `<esc>`, executing normal mode command
    845 and entering back insert mode (with which binding ?)
    846 
    847 See <<doc/pages/modes#,`:doc modes`>>.
    848 
    849 Highlighters
    850 ~~~~~~~~~~~~
    851 
    852 Manipulation of the displayed text, such as syntax coloration and wrapping
    853 is done through highlighters.
    854 
    855 See <<doc/pages/highlighters#,`:doc highlighters`>>.
    856 
    857 Hooks
    858 ~~~~~
    859 
    860 Commands can be registered to be executed when certain events arise with hooks.
    861 
    862 See <<doc/pages/hooks#,`:doc hooks`>>.
    863 
    864 Key Mapping
    865 ~~~~~~~~~~~
    866 
    867 Custom key shortcuts can be registered through mappings.
    868 
    869 See <<doc/pages/mapping#,`:doc mapping`>>.
    870 
    871 Defining Commands and Aliases
    872 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    873 
    874 New commands can be created using `:define-command`.
    875 
    876 See <<doc/pages/commands#declaring-new-commands,`:doc commands declaring-new-commands`>>.
    877 
    878 They can be given additional short names depending of the scope with `:alias`.
    879 
    880 See <<doc/pages/commands#aliases,`:doc commands aliases`>>.
    881 
    882 Some helper commands are available to define composite commands.
    883 
    884 See <<doc/pages/commands#helpers,`:doc commands helpers`>>.
    885 
    886 FIFO Buffers
    887 ~~~~~~~~~~~
    888 
    889 FIFO buffers are very useful for running some commands asynchronously while
    890 progressively displaying their result in Kakoune.
    891 
    892 See <<doc/pages/buffers#fifo-buffers,`:doc buffers fifo-buffers`>>.
    893 
    894 Credits
    895 -------
    896 
    897 Thanks to https://github.com/p0nce[p0nce] for designing the
    898 https://github.com/mawww/kakoune/blob/master/doc/kakoune_logo.svg[Kakoune
    899 logo].
    900 
    901 And thanks to all the
    902 https://github.com/mawww/kakoune/graphs/contributors[contributors] who help
    903 move the project forward!