Design

Manual++
1

This document describes the design goals for Kakoune, including
rationales.

Interactivity

Unlike Vim, Kakoune does not have an underlying line-oriented editor,
and is always expected to be used in an interactive (i.e. with the
edited text being displayed in real time) fashion. That should not
prevent Kakoune from being used non interactively (executing macro for
example), but priority should be given to ease of interactive use.

Limited scope

Kakoune is a code editor. It is not an IDE, not a file browser, not a
word processor and not a window manager. It should be very efficient at
editing code, and should, as a side effect, be very efficient at editing
text in general.

Composability

Being limited in scope to code edition should not isolate Kakoune from
its environment. On the contrary, Kakoune is expected to run on a
Unix-like system, along with a lot of text-based tools, and should make
it easy to interact with these tools.

For example, sorting lines should be done using the Unix sort command,
not with an internal implementation. Kakoune should make it easy to do
that, hence the | command for piping selected text through a filter.

The modern Unix environment is not limited to text filters, most people
use a graphical interface nowadays, and Kakoune should be able to take
advantage of that, without hindering text mode support. For example
Kakoune supports multiple clients on the same editing session, so that
multiple windows can be used, letting the system window manager handle
its responsibilities such as tiling or tabbing.

Orthogonality

Kakoune features should be as orthogonal as possible, for example, in
Vim, there are multiple ways for modifying the buffer: Through
normal/insert mode, command mode, and Vim scripts. In Kakoune, modifying
the buffer is the normal/insert mode job.

That means there should be clear separation of concerns between modes:

  • normal mode is for manipulating the selection and the selection
    contents.

  • insert mode is for interactive insertion into the buffer.

  • command mode is for non-editing features (opening a file, setting
    options…).

Orthogonality is an ideal, and should not prevent common sense
pragmatism, the gf and ga commands are not strictly selection
manipulation ones, but fit nicely with other goto commands, and hence
are acceptable in normal mode even though they could arguably be moved
to command mode.

Modes should be orthogonal, and commands in modes should be as well. For
example, Vim uses d and x for very similar things: deleting text. In
Kakoune only d exists, and the design ensures that x is not needed.

Speed

Kakoune should be fast, fast to use, as in a lot of editing in a few
keystrokes, and fast to execute.

  • Vim is the benchmark here, most editing tasks should be doable in
    less or the same number of keys.

  • Kakoune be designed with asynchronicity in mind, launching a
    background process and using its result when available should not
    block the editor.

  • Kakoune should be implemented with speed in mind, a slow editor is a
    useless one.

Simplicity

Simplicity is nice, simplicity correlates with orthogonality and speed,
and makes things easier to understand, bugs easier to fix, and code
easier to change.

  • No threading: multithreading is a hard problem, and is not well
    suited to a text editor:

    • Either we want a direct result, and we need to be synchronous
      with the user, so getting a 4x speed up is meaningless, we need
      to have an algorithm which appears instantaneous the user.

    • Or we want an asynchronous result, and then the processing is
      best left to a helper command which can be reused with other
      Unix tools.

  • No binary plugins: shared object by themselves add a lot of
    complexity. Plugins add another interface to Kakoune, and goes
    against orthogonality. The %sh{ … } and socket interface should be
    made good enough for most plugin use cases.

    • It is better to write Kakoune-independent helper tools
      (intelligent code completer, source code navigation programs)
      that can interact with Kakoune through the shell than write them
      in a plugin.

  • No integrated scripting language: for the same reason as binary
    plugins.

  • Limited smartness: Kakoune should not try to be too smart, being
    smart is often unpredictable for the user, and makes things context
    dependent. When Kakoune tries to be smart, it should provide the
    alternative, non smart version (* tries to detect word
    boundaries on the selection, but alt-* permits to avoid this
    behavior).

Unified interactive use and scripting

As both an effect of Orthogonality and Simplicity, normal mode is
not a layer on top of a text editing language layer (normal mode
keys are not bound to text editing commands), normal mode is the
text editing language.

That means there is no delete-selected-text command that d is bound
to, d is the delete selected text command.

This permits to have scripting use case and interactive use cases share
the same text editing language. Both use normal mode to express complex
edition.

Besides promoting simplicity by avoiding the introduction of another
layer, this helps ensure the interactive editing language is as
expressive as possible as we need to make it able to handle complex use
cases, such as indentation hooks.

Language agnostic

Kakoune should not be tailored for writing in a specific programming
language. Support for different languages should be provided by a kak
script file, built-in language support should be avoided.

Self documenting

Kakoune should be able to document its features, live documentation
along with an extensive suggestion/completion system provides the
discoverability which is often lacking in non GUI tools. Documentation
should as much as possible be integrated with the code so that it stays
up to date.

Vim compatibility

Kakoune is inspired by Vim, and should try to keep its commands close to
Vim’s if there are no compelling reasons to change. However
self-consistency is more important than Vim compatibility.

2 Likes
2

Again @robertmeta a refactor of current content any improvements that could be made?

Kakoune design

The rationale and design goals for Kakoune.

Interactivity

The expectation is to apply Kakoune in an interactive fashion, displaying
modified text in real time as Kakoune doesn’t have an underlying line-oriented
editor. While Kakoune doesn’t prevent non-interactive usage for example
executing a macro, the priority is for ease-of-interaction.

Scope

Textual emendation.

Limitations

Kakoune is limited to general text modification as an effective and efficient
code editor for Unix-like systems.

Composability

Limitations don’t preclude Kakoune from coexisting and interacting alongside
other text-based tools nor the environment in which its invoked.

Kakoune should make it easy to do just that, hence the | command for piping
selected text through a filter. A classic example is using the Unix sort
command to arrange lines and not with an internal Kakoune implementation.

The modern Unix environment isn’t limited to text filters. Most people use a
graphical interface nowadays, and Kakoune should be able to take advantage of
that without hindering text mode support. For example, Kakoune enables multiple
windows by supporting many clients on the same editing session, not by
re-implementing tiling and tabbing. A system window manager should handle those
responsibilities.

Orthogonality

In Kakoune, modifying the buffer is the job of normal ⟂ insert mode. Kakoune
features should remain orthogonal as possible.

Meaning a clear separation of concerns between modes:

  • normal mode is for manipulating the selection and the selection contents.

  • insert mode is for interactive insertion into the buffer.

  • command mode is for non-editing features (opening a file, setting
    options…).

Orthogonality as idealism doesn’t forbid pragmatism. The gf and ga commands
aren’t strictly selection manipulation commands, but they do fit nicely with
other goto commands. So, there acceptable both in normal mode and arguably
command mode.

Modes and their sub-commands should be orthogonal. For example, Vim uses both
d and x to delete text, with minor differences. Kakoune design ensures no
need for x and only d exists.

Speed

Kakoune should be fast. A fast to use and fast to execute editing process in
fewer keystrokes.

  • With Vim as the benchmark, most editing tasks meet either fewer or the same
    number of keystrokes.

  • Kakounes’ design has asynchronous tasks in mind. Launching a background
    process and using its result where available shouldn’t block the editor.

  • Kakoune philosophy is with speed in mind. A slow editor is unbearable.

Simplicity

Simplicity is nice. Simplicity correlates with orthogonality and speed. It’s easier
to; understand, fix bugs, and to change code.

  • No threading: multi-threading is a hard problem and is not well suited
    to a text editor:

    • When we want a direct result, we need to be synchronous with the user. A 4x
      speed improvement is meaningless: we need to have an algorithm which appears
      instantaneous the user.

    • When we want an asynchronous result, the processing is best left to a helper
      command which can be reused with other Unix tools.

  • No binary plugins: shared objects by themselves add complexity. Plugins add
    another interface to Kakoune and go against orthogonality. Most plugins should
    be able to use the %sh{ ... } and socket interfaces.

    • Rather than writing a plugin for intelligent code completion or source code
      navigation, it’s better to write an independent helper tool that can interact
      with Kakoune through the shell.

  • No integrated scripting language: for the same reason as binary plugins.

  • Limited smartness: Kakoune shouldn’t try to be too smart. An overly perceptive
    editor is often unpredictable for the user and makes things context-dependent.
    When Kakoune tries to be smart, it should provide the alternative,
    ‘unperceptive’ version. For instance, \* attempts to detect word boundaries on
    the selection, but alt-* opts out of this behavior.

Unified interactive use and scripting

Promotion of simplicity combined with an orthogonal design permits both
scripting and interactive use cases to share the same text editing language and
avoids the introduction of another layer.

That means there’s no delete-selected-text command and what’s bound to the d
key is the delete selected text command. Normal mode isn’t a layer of keys
bound to a text editing language layer. Normal mode is the text editing
language. This helps to ensure the interactive editing language is expressive
enough to handle complex use cases, such as indentation hooks.

Language-agnostic

Kakoune doesn’t tailor its writing for a specific programming language. Built-in
language support should be avoided. Kakoune script files should provide support
for different languages.

Self-documenting

Kakoune should be self documenting. Where possible, documentation should be
integrated with the code so it stays up to date. Live documentation, along with
an extensive suggestion and completion system, provides the discoverability in
Kakoune.

Vim compatibility

As Kakoune is Vim inspired its commands are Vim’s if no compelling reasons to
deviate. However, pragmatism of self-consistency over Vim congruency is a Kakoune
design rationale.

2 Likes