From bd30df58bf98ba7fada3df18cb9803e973e13693 Mon Sep 17 00:00:00 2001 From: Maxime Coste Date: Fri, 3 Apr 2015 18:42:12 +0100 Subject: [PATCH] Reorganize README --- README.asciidoc | 625 +++++++++++++++++++++++++++--------------------- 1 file changed, 346 insertions(+), 279 deletions(-) diff --git a/README.asciidoc b/README.asciidoc index 0b486b2b..52765436 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -2,6 +2,8 @@ :logo: https://rawgit.com/mawww/kakoune/master/doc/kakoune_logo.svg :travis-img: https://travis-ci.org/mawww/kakoune.svg :travis-url: https://travis-ci.org/mawww/kakoune +:icons: font +:toc: right TL;DR ----- @@ -46,7 +48,7 @@ see http://vimeo.com/82711574 Join us on freenode IRC +#Kakoune+ Features --------- +~~~~~~~~ * Multiple selections as a central way of interacting * Powerful selection manipulation primitives @@ -72,8 +74,11 @@ Features - Supports multiple languages in the same buffer - Highlight a buffer differently in different windows +Getting started +--------------- + Building --------- +~~~~~~~~ Kakoune dependencies are: @@ -91,7 +96,7 @@ src directory, this will setup an initial $XDG_CONFIG_HOME/kak directory. See the _Kakrc_ section for more information. Installing ----------- +~~~~~~~~~~ In order to install kak on your system, rather than running it directly from it's source directory, type *make install*, you can specify the +PREFIX+ and @@ -108,26 +113,28 @@ a symbolic link to the $PREFIX/share/kak/rc directory. ln -s /usr/share/kak/rc ~/.config/kak/autoload ---------------------------------------------- -Homebrew (OSX) -~~~~~~~~~~~~~~ - +[TIP] +.Homebrew (OSX) +==== ----------------------------------------------------------------------------------------------- brew install --HEAD https://raw.githubusercontent.com/mawww/kakoune/homebrew/contrib/kakoune.rb ----------------------------------------------------------------------------------------------- +==== -Fedora 20/21/22/Rawhide & Epel 7 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - +[TIP] +.Fedora 20/21/22/Rawhide & Epel 7 +==== Use the https://copr.fedoraproject.org/coprs/jkonecny/kakoune/[copr] repository. --------------------------------- dnf copr enable jkonecny/kakoune dnf install kakoune --------------------------------- +==== -Arch Linux -~~~~~~~~~ - +[TIP] +.Arch Linux +==== A PKGBUILD https://aur.archlinux.org/packages/kakoune-git[kakoune-git] to install Kakoune is available in the https://wiki.archlinux.org/index.php/Arch_User_Repository[AUR]. @@ -135,17 +142,19 @@ to install Kakoune is available in the https://wiki.archlinux.org/index.php/Arch # For example build and install Kakoune via yaourt yaourt -Sy kakoune-git -------------------------------- +==== -Exherbo -~~~~~~~ - +[TIP] +.Exherbo +==== -------------------------------- cave resolve -x repository/mawww cave resolve -x kakoune -------------------------------- +==== Running -------- +~~~~~~~ Just running *kak* launch a new kak session with a client on local terminal. *kak* accepts some switches: @@ -173,8 +182,37 @@ defaulting to $HOME/.config), and finally $XDG_CONFIG_HOME/kak/kakrc. The common pattern is to add links to $XDG_CONFIG_HOME/kak/autoload to the scripts in $PREFIX/share/kak/rc that the user wants sourced at kak launch. -Basic Movement --------------- +Basic Interaction +----------------- + +Selections +~~~~~~~~~~ + +The main concept in Kakoune is the selection. A selection is an inclusive, +directed range of character. A selection has two ends, the anchor and the +cursor. + +There is always at least one selection, and a selection is always at least +one character (in which case the anchor and cursor of the selections are +on the same character). + +Normal Mode +~~~~~~~~~~~ + +In normal mode, keys are not inserted directly inside the buffer, but are editing +commands. These commands provides ways to manipulate either the selections themselves, +or the selected text. + +Insert Mode +~~~~~~~~~~~ + +When entering insert mode, keys are now directly inserted before each selections +cursor. A few additional keys are supported, like arrow keys to move around, however +their use is not encouraged. You can go back to normal mode by pressing the ++ +key. + +Movement +~~~~~~~~ * +h+: select the character on the right of selection end * +j+: select the character below the selection end @@ -218,13 +256,13 @@ A word is a sequence of alphanumeric characters or underscore, a WORD is a sequence of non whitespace characters. Appending ---------- +~~~~~~~~~ for most selection commands, using shift permits to extend current selection instead of replacing it. for example, +wWW+ selects 3 consecutive words Using Counts ------------- +~~~~~~~~~~~~ Most selection commands also support counts, which are entered before the command itself. @@ -233,19 +271,19 @@ for example, +3W+ selects 3 consecutive words and +3w+ select the third word on the right of selection end. Changes -------- +~~~~~~~ - * +i+: insert before current selection - * +a+: insert after current selection + * +i+: enter insert mode before current selection + * +a+: enter insert mode after current selection * +d+: yank and delete current selection - * +c+: yank and delete current selection and insert + * +c+: yank and delete current selection and enter insert mode * +.+: repeat last insert mode change (+i+, +a+, or +c+, including the inserted text) - * +I+: insert at current selection begin line start - * +A+: insert at current selection end line end - * +o+: insert in a new line below current selection end - * +O+: insert in a new line above current selection begin + * +I+: enter insert mode at current selection begin line start + * +A+: enter insert mode at current selection end line end + * +o+: enter insert mode in a new line below current selection end + * +O+: enter insert mode in a new line above current selection begin * +y+: yank selections * +p+: paste after current selection end @@ -299,7 +337,7 @@ Changes independently. Goto Commands -------------- +~~~~~~~~~~~~~ Commands begining with g are used to goto certain position and or buffer: @@ -319,7 +357,7 @@ Commands begining with g are used to goto certain position and or buffer: * +g.+: go to last buffer modifiction position View commands -------------- +~~~~~~~~~~~~~ Some commands, all begining with v permit to manipulate the current view. @@ -333,7 +371,7 @@ view. * +vl+: scroll the window count columns right Jump list ---------- +~~~~~~~~~ Some commands, like the goto commands, buffer switch or search commands, push the previous selections to the client's jump list. It is possible @@ -344,7 +382,7 @@ to forward or backward in the jump list using: * +control-s+: save current selections Multi Selection ---------------- +~~~~~~~~~~~~~~~ Kak was designed from the start to handle multiple selections. One way to get a multiselection is via the +s+ key. @@ -380,7 +418,7 @@ not containing a match. Selections whose shell command returns 0 will be kept, other will be dropped. Object Selection ----------------- +~~~~~~~~~~~~~~~~ Some keys allow you to select a text object: @@ -414,48 +452,16 @@ object you want. For nestable objects, a count can be used in order to specify which surrounding level to select. -Registers ---------- +Commands +-------- -registers are named list of text. They are used for various purpose, like -storing the last yanked test, or the captures groups associated with the -selections. +When pressing +:+ in normal mode, Kakoune will open a prompt to enter a command. -While in insert mode, ctrl-r followed by a register name (one character) -inserts it. - -For example, ctrl-r followed by " will insert the currently yanked text. -ctrl-r followed by 2 will insert the second capture group from the last regex -selection. - -Registers are lists, instead of simply text in order to interact well with -multiselection. Each selection have it's own captures, or yank buffer. - -Macros ------- - -Kakoune can record and replay a sequence of key press. - -When pressing the +Q+ key, followed by an alphabetic key for the macro name, -Kakoune begins macro recording: every pressed keys will be added to the -macro until the +Q+ key is pressed again. - -To replay a macro, use the +q+ key, followed by the macro name. - -Search selection ----------------- - -Using the +*+ key, you can set the search pattern to the current selection. -This tries to be intelligent. It will for example detect if current selection -begins and/or end at word boundaries, and set the search pattern accordingly. - -with +alt-*+ you can set the search pattern to the current seletion without -Kakoune trying to be smart. +Commands are used for non editing tasks, such as opening a buffer, writing the +current one, quitting, etc... Basic Commands --------------- - -Commands are entered using +:+. +~~~~~~~~~~~~~~ * +e[dit] [ []]+: open buffer on file, go to given line and column. If file is already opened, just switch to this file. @@ -482,42 +488,8 @@ Commands are entered using +:+. +:nop %sh{ echo echo tchou }+ will not, but both will execute the shell command. -Exec and Eval -------------- - -the +:exec+ and +:eval+ commands can be used for running Kakoune commands. -+:exec+ keys as if they were pressed, whereas +:eval+ executes it's given -paremeters as if they were entered in the command prompt. By default, -they do their execution in the context of the current client. - -Some parameters provide a way to change the context of execution: - - * +-client +: execute in the context of the client named - * +-try-client +: execute in the context of the client named - if such client exists, or else in the current context. - * +-draft+: execute in a copy of the context of the selected client - modifications to the selections or input state will not affect - the client. This permits to make some modification to the buffer - without modifying the user's selection. - * +-itersel+ (requires +-draft+): execute once per selection, in a - context with only the considered selection. This permits to avoid - cases where the selections may get merged. - * +-buffer +: execute in the context of each buffers in the - comma separated list - * +-no-hooks+: disable hook execution while executing the keys/commands - -The execution stops when the last key/command is reached, or an error -is raised. - -key parameters gets concatenated, so the following commands are equivalent. - ----------------------- -:exec otest1 -:exec o test 1 ----------------------- - String syntax -------------- +~~~~~~~~~~~~~ When entering a command, parameters are separated by whitespace (shell like), if you want to give parameters with spaces, you should quote them. @@ -527,7 +499,7 @@ Kakoune support three string syntax: * +\'strings\'+: uninterpreted strings, you can use \' to escape the separator, every other char is itself. - * +"strings"+: expended strings, % strings (see %sh, %opt or %reg) contained + * +"strings"+: expanded strings, % strings (see %sh, %opt or %reg) contained are expended. Use \% to escape a % inside them, and \\ to escape a slash. * +%\{strings\}+: these strings are very useful when entering commands @@ -539,6 +511,121 @@ Kakoune support three string syntax: the matching }])> and the delimiters are not escapable but are nestable. for example +%{ roger {}; }+ is a valid string, +%{ marcel \}+ as well. +Expansions +^^^^^^^^^^ + +A special kind of +%\{strings\}+ can be used, with a type between ++%+ and the opening delimiter (which cannot be alphanumeric). These +strings are expanded according to their type. + +For example +%opt{autoinfo}+ is of type 'opt'. opt expansions are replaced +by the value of the given option (here +autoinfo+). + +Supported types are: + + * +sh+: shell expansion, similar to posix shell $(...) construct, see the + Shell expansion section for more details. + * +reg+: register expansion, will be replaced by the content of the given + register. + * +opt+: option expansion, will be replaced with the value of the given + option + * +val+: value expansion, gives access to the environment variable available + to the Shell expansion. The +kak_+ prefix is not used there. + +for example you can display last search pattern with + +------------- +:echo %reg{/} +------------- + +Shell expansion +^^^^^^^^^^^^^^^ + +The +%sh{...}+ expansion replaces it's content with the output of the shell +commands in it, it is similar to the shell $(...) syntax and is evaluated +only when needed. + +for example: %sh{ ls } is replaced with the output of the ls command. + +Some of Kakoune state is available through environment variables: + + * +kak_selection+: content of the main selection + * +kak_selections+: content of the selection separated by colons, colons in + the selection contents are escapted with a backslash. + * +kak_bufname+: name of the current buffer + * +kak_buflist+: the current buffer list, each buffer seperated by a colon + * +kak_timestamp+: timestamp of the current buffer, the timestamp is an + integer value which is incremented each time the buffer is modified. + * +kak_runtime+: directory containing the kak binary + * +kak_opt_+: value of option + * +kak_reg_+: value of register + * +kak_socket+: filename of session socket (/tmp/kak-) + * +kak_client+: name of current client + * +kak_cursor_line+: line of the end of the main selection + * +kak_cursor_column+: column of the end of the main selection (in byte) + * +kak_cursor_char_column+: column of the end of the main selection (in character) + * +kak_hook_param+: filtering text passed to the currently executing hook + +Note that in order to make only needed information available, Kakoune needs +to find the environment variable reference in the shell script executed. +Hence +%sh{ ./script.sh }+ with +script.sh+ referencing an environment +variable will not work. + +for example you can print informations on the current file in the status +line using: + +------------------------------- +:echo %sh{ ls -l $kak_bufname } +------------------------------- + +Kakrc +----- + +The kakrc file in +../share/kak/kakrc+ (relative to the +kak+ binary) +is a list of kak commands to be executed at startup. + +The current behaviour is to execute local user commands in the file +$HOME/.config/kak/kakrc and in all files in $HOME/.config/kak/autoload +directory + +Place links to the files in +rc/+ in your autoload directory in order to +execute them on startup, or use the runtime command (which sources relative +to the kak binary) to load them on demand. + +Existing commands files are: + + * *rc/kakrc.kak*: provides kak commands files autodetection and highlighting + * *rc/cpp.kak*: provides C/CPP files autodetection and highlighting and the + +:alt+ command for switching from C/CPP file to h/hpp one. + * *rc/asciidoc.kak*: provides asciidoc files autodetection and highlighting + * *rc/diff.kak*: provides patches/diff files autodetection and highlighting + * *rc/git.kak*: provides various git format highlighting (commit message editing, + interactive rebase) + * *rc/git-tools.kak*: provides some git integration, like +:git-blame+, +:git-show+ + or +:git-diff-show+ + * *rc/make.kak*: provides the +:make+ and +:errjump+ commands along with + highlighting for compiler output. + * *rc/man.kak*: provides the +:man+ command + * *rc/grep.kak*: provides the +:grep+ and +:gjump+ commands along with highlighting + for grep output. + * *rc/ctags.kak*: provides the +:tag+ command to jump on a tag definition using + exuberant ctags files, this script requires the *readtags* binary, available + in the exuberant ctags package but not installed by default. + * *rc/client.kak*: provides the +:new+ command to launch a new client on the current + session, if tmux is detected, launch the client in a new tmux split, else + launch in a new terminal emulator. + * *rc/clang.kak*: provides the +:clang-enable-autocomplete+ command for C/CPP + insert mode completion support. This requires the clang++ compiler to be + available. You can use the +clang_options+ option to specify switches to + be passed to the compiler. + +Certain command files defines options, such as +grepcmd+ (for +:grep+) +makecmd+ +(for +:make+) or +termcmd+ (for +:new+). + +Some options are shared with commands. +:grep+ and +:make+ honor the +toolsclient+ option, +if specified, to open their buffer in it rather than the current client. man honor +the +docsclient+ option for the same purpose. + Options ------- @@ -560,9 +647,9 @@ Options are typed, their type can be Options value can be changed using the +set+ commands: --------------------------------------------------------------- +------------------------------------------------------------------------------ :set [global,buffer,window]