xenia/home
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Edit high-level design doc for ease of reading

Browse Source 
- Some run-ons, comma splices, and parentheticals broken into
  more sentences
- Minor fixes like mismatched singular/plurals
- Some word choices tuned for nuances of meaning
This commit is contained in:
Kevin Conner 2021-03-17 22:10:20 -04:00
parent d29535ec0d
commit b207f9a435
1 changed files with 62 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

127
doc/design.asciidoc
View File

@ -1,50 +1,50 @@
Kakoune design Kakoune design
============== ==============
This document describes the design goals for Kakoune, including rationales. This document describes the design goals for Kakoune, including rationale.
Interactivity Interactivity
------------- -------------
Unlike Vim, Kakoune does not have an underlying line-oriented editor, and Unlike Vim, Kakoune does not have an underlying line-oriented editor. It is
is always expected to be used in an interactive (i.e. with the edited text always expected to be used in an interactive fashion, displaying edited text in
being displayed in real time) fashion. That should not prevent Kakoune from real time. That should not prevent Kakoune from being used non-interactively
being used non interactively (executing macro for example), but priority (executing a macro for example), but priority should be given to ease of
should be given to ease of interactive use. interactive use.
Limited scope Limited scope
------------- -------------
Kakoune is a code editor. It is not an IDE, not a file browser, not a word 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, 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. As a side effect, it should be very efficient at editing text in general.
Composability Composability
------------- -------------
Being limited in scope to code edition should not isolate Kakoune from its Being limited in scope to code editing should not isolate Kakoune from its
environment. On the contrary, Kakoune is expected to run on a Unix-like 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 system alongside a lot of text-based tools, and should make it easy to
interact with these tools. interact with these tools.
For example, sorting lines should be done using the Unix sort command, not 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, with an internal implementation. Kakoune should make it easy to do that,
hence the +|+ command for piping selected text through a filter. hence the +|+ command for piping selected text through a filter.
The modern Unix environment is not limited to text filters, most people use 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 a graphical interface nowadays, and Kakoune should be able to take advantage
of that, without hindering text mode support. For example Kakoune supports of that without hindering text mode support. For example, Kakoune enables
multiple clients on the same editing session, so that multiple windows can multiple windows by supporting many clients on the same editing session,
be used, letting the system window manager handle its responsibilities such not by reimplementing tiling and tabbing. Those responsibilities are left
as tiling or tabbing. to the system window manager.
Orthogonality Orthogonality
------------- -------------
Kakoune features should be as orthogonal as possible, for example, in Vim, Kakoune features should be as orthogonal as possible. For example, in Vim,
there are multiple ways for modifying the buffer: Through normal/insert there are many ways to modify the buffer: Through normal/insert
mode, command mode, and Vim scripts. In Kakoune, modifying the buffer is the mode, command mode, and Vim scripts. In Kakoune, modifying the buffer is
normal/insert mode job. only the job of normal/insert mode.
That means there should be clear separation of concerns between modes: That means there should be clear separation of concerns between modes:
@ -55,101 +55,98 @@ That means there should be clear separation of concerns between modes:
* command mode is for non-editing features (opening a file, setting * command mode is for non-editing features (opening a file, setting
options...). options...).
Orthogonality is an ideal, and should not prevent common sense pragmatism, Orthogonality is an ideal; it should not forbid common sense pragmatism.
the +gf+ and +ga+ commands are not strictly selection manipulation ones, The +gf+ and +ga+ commands are not strictly selection manipulation commands,
but fit nicely with other +goto+ commands, and hence are acceptable in but they do fit nicely with other +goto+ commands, so they are acceptable in
normal mode even though they could arguably be moved to command mode. 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 Modes should be orthogonal, as should commands within modes. For
example, Vim uses +d+ and +x+ for very similar things: deleting text. In example, Vim uses both +d+ and +x+ to delete text, with minor differences. In
Kakoune only +d+ exists, and the design ensures that +x+ is not needed. Kakoune only +d+ exists, and the design ensures that +x+ is not needed.
Speed Speed
----- -----
Kakoune should be fast, fast to use, as in a lot of editing in a few Kakoune should be fast -- fast to use, as in a lot of editing in a few
keystrokes, and fast to execute. keystrokes, and fast to execute.
* Vim is the benchmark here, most editing tasks should be doable in less * Vim is the benchmark here. Most editing tasks should be doable in fewer
or the same number of keys. or the same number of keystrokes as Vim.
* Kakoune be designed with asynchronicity in mind, launching a background * Kakoune is designed with asynchronicity in mind. Launching a background
process and using its result when available should not block the editor. 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 * Kakoune should be implemented with speed in mind. A slow editor is a
useless one. useless one.
Simplicity Simplicity
---------- ----------
Simplicity is nice, simplicity correlates with orthogonality and speed, and makes Simplicity is nice. Simplicity correlates with orthogonality and speed. It makes
things easier to understand, bugs easier to fix, and code easier to change. 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 * *No threading*: multithreading is a hard problem and is not well suited
to a text editor: to a text editor:
- Either we want a direct result, and we need to be synchronous with - When we want a direct result, we need to be synchronous with
the user, so getting a 4x speed up is meaningless, we need to have an the user. A 4x speed improvement is meaningless; we need to have an
algorithm which appears instantaneous the user. algorithm which appears instantaneous the user.
- Or we want an asynchronous result, and then the processing is best left - When we want an asynchronous result, the processing is best left
to a helper command which can be reused with other Unix tools. to a helper command which can be reused with other Unix tools.
* *No binary plugins*: shared object by themselves add a lot of * *No binary plugins*: shared objects by themselves add a lot of
complexity. Plugins add another interface to Kakoune, and goes against complexity. Plugins add another interface to Kakoune and go against
orthogonality. The +%sh{ ... }+ and socket interface should be made good orthogonality. The +%sh{ ... }+ and socket interfaces should be made good
enough for most plugin use cases. enough for most plugin use cases.
- It is better to write Kakoune-independent helper tools (intelligent - Rather than writing a plugin for intelligent code completion or source
code completer, source code navigation programs) that can interact with code navigation, it is better to write an independent helper tool that can
Kakoune through the shell than write them in a plugin. interact with Kakoune through the shell.
* *No integrated scripting language*: for the same reason as binary plugins. * *No integrated scripting language*: for the same reason as binary plugins.
* *Limited smartness*: Kakoune should not try to be too smart, being smart * *Limited smartness*: Kakoune should not try to be too smart. Being smart
is often unpredictable for the user, and makes things context dependent. is often unpredictable for the user and makes things context-dependent.
When Kakoune tries to be smart, it should provide the alternative, 'non When Kakoune tries to be smart, it should provide the alternative,
smart' version (+\*+ tries to detect word boundaries on the selection, but 'non-smart' version. For instance, +\*+ tries to detect word boundaries on
+alt-*+ permits to avoid this behavior). the selection, but +alt-*+ opts out of this behavior.
Unified interactive use and scripting Unified interactive use and scripting
------------------------------------- -------------------------------------
As both an effect of Orthogonality and Simplicity, normal mode is *not* As an effect of both Orthogonality and Simplicity, normal mode is not
a layer on top of a text editing language layer (normal mode keys are a layer of keys bound to a text editing language layer. Normal mode *is*
*not* bound to text editing commands), normal mode *is* the text editing the text editing language.
language.
That means there is no +delete-selected-text+ command that +d+ is bound That means there is no +delete-selected-text+ command that +d+ is bound
to, +d+ *is* the +delete selected text+ command. to. +d+ *is* the +delete selected text+ command.
This permits to have scripting use case and interactive use cases share This permits both scripting and interactive use cases to share the same text
the same text editing language. Both use normal mode to express complex editing language. Both use normal mode to express complex editing.
edition.
Besides promoting simplicity by avoiding the introduction of another Besides promoting simplicity by avoiding the introduction of another
layer, this helps ensure the interactive editing language is as expressive layer, this helps ensure the interactive editing language is expressive
as possible as we need to make it able to handle complex use cases, enough to handle complex use cases, such as indentation hooks.
such as indentation hooks.
Language agnostic Language-agnostic
----------------- -----------------
Kakoune should not be tailored for writing in a specific programming Kakoune should not be tailored for writing in a specific programming
language. Support for different languages should be provided by a kak script language. Support for different languages should be provided by a kak script
file, built-in language support should be avoided. file. Built-in language support should be avoided.
Self documenting Self-documenting
---------------- ----------------
Kakoune should be able to document its features, live documentation along Kakoune should be able to document its features. Live documentation, along
with an extensive suggestion/completion system provides the discoverability with an extensive suggestion/completion system, provides the discoverability
which is often lacking in non GUI tools. Documentation should as much as which is often lacking in non-GUI tools. As much as possible, documentation
possible be integrated with the code so that it stays up to date. should be integrated with the code so that it stays up to date.
Vim compatibility Vim compatibility
----------------- -----------------
Kakoune is inspired by Vim, and should try to keep its commands close to Kakoune is inspired by Vim and should try to keep its commands similar to
Vim's if there are no compelling reasons to change. However self-consistency Vim's if there are no compelling reasons to deviate. However, self-consistency
is more important than Vim compatibility. is more important than Vim compatibility.