From 32c68113c1deb0f9cda018d3e060815323e3e573 Mon Sep 17 00:00:00 2001 From: Trevor Dixon Date: Thu, 29 Dec 2016 13:31:17 +0100 Subject: [PATCH] Minor punctuation and grammar improvements --- doc/design.asciidoc | 78 ++++++++++++++++++++++----------------------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/doc/design.asciidoc b/doc/design.asciidoc index eb022e8e97..49aa4bd89a 100644 --- a/doc/design.asciidoc +++ b/doc/design.asciidoc @@ -9,20 +9,20 @@ 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 +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, +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 it's +Being limited in scope to code editing should not isolate Kakoune from its environment. On the contrary, Kakoune is expected to run on an Unix-like system, along with a lot of text-based tools, and should make it easy to interact with these tools. @@ -31,34 +31,34 @@ 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 pipping 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 -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 it's responsibilities such +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 is multiple ways for modifying the buffer: Through normal/insert +Kakoune features should be as orthogonal as possible. For example, in Vim, +there are multiple ways to modify 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. + * Normal mode is for manipulating the selection and the selection contents. - * insert mode is for interactive insertion into the buffer. + * Insert mode is for interactive insertion into the buffer. - * command mode is for non-editing features (opening a file, setting + * 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. +Orthogonality is an ideal, and should not prevent common sense pragmatism. +The +gf+ and +ga+ commands are not strictly selection manipulation ones, +but they fit nicely with other +goto+ commands, hence they 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 @@ -67,35 +67,35 @@ 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 +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 + * 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 it's result when available should not block the editor. + * Kakoune is 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 + * 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 +Simplicity is nice. It 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 + * *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 + 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 + * *No binary plugins*: shared objects 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. @@ -106,31 +106,31 @@ things easier to understand, bugs easier to fix, and code easier to change. * *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). + * *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 an alternative, 'non + smart' version (e.g. +\*+ tries to detect word boundaries on the selection, + but +alt-*+ permits to avoid this behavior). 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. +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 +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. +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 it's commands close to Vim -ones if there is no compelling reasons to change. However self consistency -is more important than Vim compatibility. +Kakoune is inspired by Vim, and should try to keep its commands close to Vim's +if there is no compelling reason to change. However, self-consistency is more +important than Vim compatibility.