<<<<<<< HEAD = image:{logo}[K,30,30,link="{website}",title="Kakoune logo by p0nce"] Kakoune image:{travis-img}[link="{travis-url}"] image:{irc-img}[link="{irc-url}"] ifdef::env-github,env-browser[:outfilesuffix: .asciidoc] :logo: https://rawgit.com/mawww/kakoune/master/doc/kakoune_logo.svg :website: http://kakoune.org :travis-img: https://travis-ci.org/mawww/kakoune.svg?branch=master :travis-url: https://travis-ci.org/mawww/kakoune :irc-img: https://img.shields.io/badge/IRC-%23kakoune-blue.svg :irc-url: https://webchat.freenode.net/?channels=kakoune :icons: font :toc: right :pp: ++

TL;DR

{website}

Modal editor -- Faster as in fewer keystrokes -- Multiple selections -- Orthogonal design

git clone http://github.com/mawww/kakoune.git cd kakoune/src make ./kak

See http://github.com/mawww/golf for kakoune solutions to vimgolf challenges, regularly beating the best Vim solution.

See the link:doc/design.asciidoc[design document] for more information on Kakoune philosophy and design.

:numbered:

Introduction

Kakoune is a code editor that implements Vi's "keystrokes as a text editing language" model. As it's also a modal editor, it is somewhat similar to the Vim editor (after which Kakoune was originally inspired).

Kakoune can operate in two modes, normal and insertion. In insertion mode, keys are directly inserted into the current buffer. In normal mode, keys are used to manipulate the current selection and to enter insertion mode.

Kakoune has a strong focus on interactivity, most commands provide immediate and incremental results, while still being competitive (as in keystroke count) with Vim.

Kakoune works on selections, which are oriented, inclusive range of characters, selections have an anchor and a cursor character. Most commands move both of them, except when extending selection where the anchor character stays fixed and the cursor one moves around.

See http://vimeo.com/82711574

Join us on freenode IRC #Kakoune

Features

 * Multiple selections as a central way of interacting
 * Powerful selection manipulation primitives
   - Select all regex matches in current selections
   - Keep selections containing/not containing a match for a given regex
   - Split current selections with a regex
   - Text objects (paragraph, sentence, nestable blocks)
 * Powerful text manipulation primitives
   - Align selections
   - Rotate selection contents
   - Case manipulation
   - Indentation
   - Piping each selection to external filter
 * Client-Server architecture
   - Multiple clients on the same editing session
   - Use tmux or your X11 window manager to manage windows
 * Simple interaction with external programs
 * Automatic contextual help
 * Automatic as you type completion
 * Macros
 * Hooks
 * Syntax Highlighting
   - Supports multiple languages in the same buffer
   - Highlight a buffer differently in different windows

Screenshots

[[screenshot-i3]] .Kakoune in i3 image::doc/screenshot-i3.gif[Kakoune in i3]

[[screenshot-tmux]] .Kakoune in tmux image::doc/screenshot-tmux.gif[Kakoune in tmux]

Getting started

Building

Kakoune dependencies are:

 * A {cpp}14 compliant compiler (GCC >= 5 or clang >= 3.9) along with its
   associated {cpp} standard library (libstdc{pp} or libc{pp})
 * ncurses with wide-characters support (>= 5.3, generally referred to as libncursesw)

To build, just type *make* in the src directory.
To generate man pages, type *make man* in the src directory.

Kakoune can be built on Linux, MacOS, and Cygwin. Due to Kakoune relying heavily
on being in a Unix-like environment, no native Windows version is planned.

Installing

In order to install kak on your system, rather than running it directly from its source directory, type make install, you can specify the PREFIX and DESTDIR if needed.

[TIP] .Homebrew (macOS) or Linuxbrew

brew install kakoune

====

[TIP] .Fedora supported versions and Rawhide

Use the https://copr.fedoraproject.org/coprs/jkonecny/kakoune/[copr] repository.

dnf copr enable jkonecny/kakoune dnf install kakoune

====

[TIP] .Arch Linux

Kakoune is found in the https://www.archlinux.org/packages/community/x86_64/kakoune/[repositories].

pacman -S kakoune

====

[TIP] .Gentoo

Kakoune is found in portage as https://packages.gentoo.org/packages/app-editors/kakoune[app-editors/kakoune]

[TIP] .Exherbo

cave resolve -x repository/mawww cave resolve -x kakoune

====

[TIP] .openSUSE

kakoune can be found in the https://build.opensuse.org/package/show/editors/kakoune[editors] devel project. Make sure to adjust the link below to point to the repository of your openSUSE version.

#Example for Tumbleweed: sudo zypper addrepo http://download.opensuse.org/repositories/editors/openSUSE_Factory/editors.repo sudo zypper refresh sudo zypper install kakoune

====

[TIP] .Ubuntu

Building on Ubuntu 16.04. Make sure you have .local/bin in your path to make the kak binary available from your shell.

sudo apt install libncursesw5-dev pkg-config git clone https://github.com/mawww/kakoune.git && cd kakoune/src make PREFIX=$HOME/.local make install

====

[TIP] .FreeBSD

Kakoune is available in the official ports tree as https://www.freshports.org/editors/kakoune[editors/kakoune].

A binary package is also available and can be installed with

pkg install kakoune

====

[TIP] .Solus

Kakoune is available in the Solus stable repository.

It can be installed with

eopkg install kakoune

====

[TIP] .Void

Kakoune is available in the repositories.

It can be installed with

xbps-install -S kakoune

====

[TIP] .Termux

Kakoune is available in the repositories.

It can be installed with

pkg install kakoune

====

Running

Just running *kak* launch a new kak session with a client on local terminal.
Run *kak -help* to discover the valid <<doc/kak.1#options,command line flags>>.

Configuration
^^^^^^^^^^^^^

There are two directories containing Kakoune's scripts:

* `runtime`: located in `../share/kak/` relative to the `kak` binary
  contains the system scripts, installed with Kakoune.
* `userconf`: located in `$XDG_CONFIG_HOME/kak/`, which will fallback
  to `$HOME/.config/kak/` if `$XDG_CONFIG_HOME` is not set, containing
  the user configuration.

Unless `-n` is specified, Kakoune will load its startup script located
at `${runtime}/kakrc` relative to the `kak` binary. This startup script
is responsible for loading the user configuration.

First, Kakoune will search recursively for `.kak` files in the `autoload`
directory. It will first look for an `autoload` directory at
`${userconf}/autoload` and will fallback to `${runtime}/autoload` if
it does not exist.

Once all those files are loaded, Kakoune will try to source
`${runtime}/kakrc.local` which is expected to contain distribution provided
configuration.

And finally, the user configuration will be loaded from `${userconf}/kakrc`.

NOTE: If you create a user `autoload` directory in `${userconf}/autoload`,
the system one at `${runtime}/autoload` will not be loaded anymore. You can
add a symbolic link to it (or to individual scripts) inside
`${userconf}/autoload` to keep loading system scripts.

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 provide ways to manipulate either the selections themselves,
or the selected text.

Insert Mode

======= :toc: macro :toc-title: Features

hakoune: add README

Hakoune

 _           _                          
| |         | |                         
| |__   __ _| | _____  _   _ _ __   ___ 
| '_ \ / _` | |/ / _ \| | | | '_ \ / _ \
| | | | (_| |   < (_) | |_| | | | |  __/
|_| |_|\__,_|_|\_\___/ \__,_|_| |_|\___|

Hakoune is a friendly fork of the http://kakoune.org[Kakoune] text editor offering 6 extra independent features. It aims to remain compatible and up to date with the original project.

This code repository is structured as a collection of git branches:

• vanilla: ref to https://github.com/mawww/kakoune[mawww/master] branch. It's regularly pulled from upstream and serves as the platform to rebase the other branches.
• hakoune: this is the complete edition, with all feature-branches merged-in.

Distribution packages with prebuilt binaries are not provided. You have to build from the source:

cd src && make && make install

Feel free to use the full hakoune branch or cherry-pick only the patches you want to craft your own customized experience.

toc::[]

TUI

layout branch

This branch lets you add extra UI bars (lines) around the editor. They can be useful to display a permanent buffer list bar, grep result counters, git status, registers contents…

To do so, add a new ncurses_layout value to the option ui_options. It's a comma separated list of zone names describing the UI appearance from top to bottom. Default value is main,status, meaning that the status bar is displayed below the main editing zone.

main and status are mandatory names reserved by Hakoune. If specified, additional zone names must refer to existing string typed options.

For example: decl str foo hello set global ui_options 'ncurses_assistant=cat:ncurses_layout=foo,main,status' will add a bar on top of the screen displaying hello. Then it's up to you to replace hello with a more meaningful value in periodical hooks. This string can contain markup, like the classic echo command.

PR: https://github.com/mawww/kakoune/pull/1942[#1942] - Mar 2018 - open

[[layout]] .Buffers list bar with current buffer highlighted. image::doc/screenshots/layout.png[Kakoune with layout]

recorded-keys branch

During macro recording (Q), the recorded keys are displayed in the status line.

Issue: https://github.com/mawww/kakoune/pull/1273[#1273] - Mar 2017 - open

[[recorded-keys]] .Recorded keys displayed at the bottom image::doc/screenshots/recorded-keys.png[Kakoune with recorded keys]

status-selections branch

This branch adds a new selection_count value and removes selections info from the {{mode_info}} expansion in the modelinefmt option.

The benefit is that you are now in control of displaying selections info as you want and when you want. For instance, displaying the number of current selections is valuable in search mode.

e.g. part of modelinefmt may contain {StatusLineInfo}#%reg{#}/%val{selection_count}{Default}

Keys

upper-registers branch

This branch adds a distinct behavior between lowercase and uppercase registers:

• "ay yanks the current selection(s) in the a register (as usual).
• "Ay appends the current selection(s) to the content of the a register.

PR: https://github.com/mawww/kakoune/pull/1630[#1630] - Oct 2017 - open

count-repeat branch

This feature lets you prefix the . (repeat last insert) and <a-.> (repeat last select) with a count.

Examples:

• ihello<esc>5. first insert hello and then insert it again 5 more times.
• fe3<a-.> select to next e and then select to the 3rd e.

The "and then" concept above is nice, because you can take a break after the insert or select operations. It fixes many workflow scenarios when you say to yourself: "oops, I forgot to prefix this f by a count :(". With this feature: "No worries, I can still do it afterwards :)"

PR: https://github.com/mawww/kakoune/issues/1602[#1602] - Sep 2017 - open

goto-matching branch

This branch binds the gm keys to go to the next matching character (the closing } if the cursor is on a {). The g<a-m> does the same for the previous matching character.

map global goto m '<esc>m;' -docstring 'matching next char'
map global goto <a-m> '<esc><a-m>;' -docstring 'matching previous char'

PR: https://github.com/mawww/kakoune/issues/1151[#1151] - Jan 2017 - closed

Obsolete features

The following features are now available in native Kakoune.

rotate-content-backward branch

This branch provides the reverse operation of the builtin <a-"> (rotate content forward). Thie problem is " is already reserved for register handling. In order to avoid breaking compatibility with existing scripts, the rotate-content-backward primitive is bound to <c-k>, which is free by default.

It seems a weird choice at first but here's the trick:

map global normal <ret> '<a-">' -docstring 'rotate selections content forward'

Currently <ret> is a synonym for <c-j> because of crazy terminal protocol legacy. So we obtain a nice symmetry with a up (k) and down (j) keys mnemonic for backward/forward.

<<<<<<< HEAD String syntax and expansions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Values, options and shell context can be interpolated in strings.

See <<doc/pages/expansions#,:doc expansions>>.

Configuration & Autoloading

Kakrc

If not launched with the `-n` switch, Kakoune will source the
`../share/kak/kakrc` file relative to the `kak` binary, which
will source additional files:

If the `$XDG_CONFIG_HOME/kak/autoload` directory exists, load every
`*.kak` files in it, and load recursively any subdirectory.

If it does not exist, falls back to the site wide autoload directory
in `../share/kak/autoload/`.

After that, if it exists, source the `$XDG_CONFIG_HOME/kak/kakrc` file
which should be used for user configuration.

In order to continue autoloading site-wide files with a local autoload
directory, just add a symbolic link to `../share/kak/autoload/` into
your local autoload directory.

Color Schemes

Kakoune ships with some color schemes that are installed to ../share/kak/colors/. If $XDG_CONFIG_HOME/kak/colors/ is present the builtin command colorscheme will offer completion for those color schemes. If a scheme is duplicated in userspace, it will take precedence.

Options

Kakoune can store named and typed values that can be used both to customize the core editor behaviour, and to keep data used by extension scripts.

See <<doc/pages/options#,:doc options>>.

Advanced topics

Faces

Faces describe how characters are displayed on the screen: color, bold, italic...

See <<doc/pages/faces#,`:doc faces`>>.

Registers

Registers are named lists of text. They are used for various purposes, like storing the last yanked text, or the captured groups associated with the selections.

See <<doc/pages/registers#,:doc registers>>.

Macros

Kakoune can record and replay a sequence of key presses.

See <<doc/pages/keys#macros,`:doc keys macros`>>.

Search selection

Using the * key, you can set the search pattern to the current selection. See <<doc/pages/keys#searching,:doc keys searching>>.

Regex syntax

Kakoune regex syntax is based on the ECMAScript syntax (ECMA-262 standard).
It always run on Unicode codepoint sequences, not on bytes.

See <<doc/pages/regex#,`:doc regex`>>.

Exec and Eval

The execute-keys and evaluate-commands are useful for scripting in non interactive contexts.

See <<doc/pages/execeval#,:doc execeval>>.

Insert mode completion

Kakoune can propose completions while inserting text: filenames, words, lines…

See <<doc/pages/keys#insert-mode-completion,`:doc keys insert-mode-completion`>>.

Escape to normal mode
~~~~~~~~~~~~~~~~~~~~~

From insert mode, pressing `<a-;>` allows you to execute a single normal mode
command. This provides a few advantages:

 * The selections are not modified: when leaving insert mode using `<esc>` the
   selections can change, for example when insert mode was entered with `a` the
   cursor will go back one char. Or if on an end of line the cursor will go back
   left (if possible).

 * The modes are nested: that means the normal mode can enter prompt (with `:`),
   or any other modes (using `:on-key` or `:menu` for example), and these modes
   will get back to the insert mode afterwards.

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
~~~~~~~~~~~~

Manipulation of the displayed text, such as syntax coloration and wrapping
is done through highlighters.

See <<doc/pages/highlighters#,`:doc highlighters`>>.

Hooks
~~~~~

Commands can be registered to be executed when certain events arise with hooks.

See <<doc/pages/hooks#,`:doc hooks`>>.

Key Mapping
~~~~~~~~~~~

Custom key shortcuts can be registered through mappings.

See <<doc/pages/mapping#,`:doc mapping`>>.

Defining Commands
~~~~~~~~~~~~~~~~~

New commands can be created using `:define-command`.

See <<doc/pages/commands#declaring-new-commands,`:doc commands declaring-new-commands`>>.

Some helper commands are available to define composite commands.

See <<doc/pages/commands#helpers,`:doc commands helpers`>>.

Aliases
~~~~~~~

With `:alias` commands can be given additional names. Aliases are scoped, so
that an alias can refer to one command for a buffer, and to another for another
buffer. The following command defines `<alias>` as an alias for `<command>`:

--------------------------------
:alias <scope> <alias> <command>
--------------------------------

`<scope>` can be one of `global`, `buffer` or `window`.

-------------------------------------
:unalias <scope> <alias> [<expected>]
-------------------------------------

Will remove the given alias in the given scope. If `<expected>` is specified
the alias will only be removed if its current value is `<expected>`.

FIFO Buffers
~~~~~~~~~~~

FIFO buffers are very useful for running some commands asynchronously while
progressively displaying their result in Kakoune.

See <<doc/pages/buffers#fifo-buffers,`:doc buffers fifo-buffers`>>.

Menus
~~~~~

When a menu is displayed, you can use `j`, `<c-n>` or `<tab>` to select the next
entry, and `k`, `<c-p>` or `<shift-tab>` to select the previous one.

Using the `/` key, you can enter some regex in order to restrict available choices
to the matching ones.

Credits
-------

Thanks to https://github.com/p0nce[p0nce] for designing the
https://github.com/mawww/kakoune/blob/master/doc/kakoune_logo.svg[Kakoune
logo].

And thanks to all the
https://github.com/mawww/kakoune/graphs/contributors[contributors] who help
move the project forward!
=======
PR: https://github.com/mawww/kakoune/issues/1210[#1210] - Feb 2017 - closed
Commit: https://github.com/mawww/kakoune/commit/ec7f3738ee08fa3c2e095d29dcb61eab37ba434f[ec7f37]
>>>>>>> hakoune: add README