From cf152832e5abc79f16c3b3724eda50a3d03051a0 Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Sat, 6 Jun 2020 10:34:52 +0300 Subject: [PATCH 01/15] doc faq: Split questions into subsections --- doc/pages/faq.asciidoc | 234 +++++++++++++++++++++-------------------- 1 file changed, 121 insertions(+), 113 deletions(-) diff --git a/doc/pages/faq.asciidoc b/doc/pages/faq.asciidoc index b97856d2..a62d9fc6 100644 --- a/doc/pages/faq.asciidoc +++ b/doc/pages/faq.asciidoc @@ -1,12 +1,14 @@ = FAQ -== How to pronounce the name of the project and what does it mean ? +== The project + +=== How to pronounce the name of the project and what does it mean ? The name of the project is pronounced "Kak-oon", and is a word taken from a New Caledonian dialect based on French. It means a hard blow, usually a punch, but generally refers to a blow into which all of one's strength went. -== Is there going to be a Windows port of Kakoune ? +=== Is there going to be a Windows port of Kakoune ? As many features provided by UNIX systems would be missing, or if anything much less efficient on a Windows system, the incentive to porting the @@ -15,18 +17,20 @@ project to this operating system is pretty low. Moreover, you can get pretty decent performance by using Kakoune on Cygwin (which is officially supported). -== Can I use Kakoune as a pager ? +== Interfacing + +=== Can I use Kakoune as a pager ? Kakoune can be used as a pager, either by setting the `PAGER` environment variable to `kak`, or by writing data directly to its standard input using a shell pipeline. -== Are there any non-console based frontends available ? +=== Are there any non-console based frontends available ? No graphical frontend is currently officially maintained, you can however try experimental community-developed ones. -== Why are colors misrendered in my Kakoune clients ? +=== Why are colors misrendered in my Kakoune clients ? The most probable cause for that is a very widespread practice that consists in setting the `TERM` environment variable in the shell's configuration file. @@ -34,7 +38,7 @@ This variable should be set by the terminal emulator, and not overridden with an arbitrary value, otherwise it might interfere with general UI rendering on the terminal's window. -== I'm using `tmux` and colors look weird +=== I'm using `tmux` and colors look weird If you're using a tool that doesn't support "palette switching", colors will still be slightly off: they are being rounded down to values supported by the @@ -59,118 +63,14 @@ $ tic /path/to/kakoune/contrib/tmux-256color.terminfo Finally, quit all existing sessions (`tmux kill-server`), and restart `tmux`. -== Why does leaving insert mode take more than half a second in `tmux` ? +=== Why does leaving insert mode take more than half a second in `tmux` ? Upon hitting the escape key, `tmux` waits for a short period of time to determine whether it's part of a function or a meta key sequence. In order to fix this "lag", set the waiting period in your `tmux` configuration file to a short time, e.g. 25ms: `set -sg escape-time 25` -== How do I automatically indent code, as Vim does with `=` ? - -As `Kakoune` doesn't parse the contents of the buffers, there is no builtin -equivalent for this Vim feature. Use a formatter/prettifier dedicated to -the language you're using with the help of the `|` key. - -Example: `%|indent` to indent an entire buffer with C code. - -Note that some languages have a default formatter set, which you can use -with the `:format` command. - -== Can Kakoune automatically complete the parameters of my functions ? - -As mentioned in the above question about Vim's `=` key, Kakoune does not -parse the contents of a buffer by itself, which makes it impossible for -the editor to propose candidates upon completion. - -However, support for such a feature can be achieved through the use of a -dedicated tool, as is the case with `clang` and C code: you can use the -`clang-enable-autocomplete` and `clang-complete` builtin commands whenever -editing a C/C++ file, and completion will work on function parameters. - -Note that the same features are available for Python buffers, with the -`jedi` script. - -== Why aren't widely known command line shortcuts such as or available in Kakoune ? - -Despite their widespread availability in multiple tools, those shortcuts do -not fit the paradigm that Kakoune implements, which is based on selections -first. - -However, you can easily declare key mappings in your configuration file -to be able to use those control-based shortcuts in insert mode. -(See <>) - -== How can I explore the filesystem the way Vim's NerdTree does ? - -The builtin file completion engine used when opening a file for editing -(using the `:edit` command and letting the suggestions popup in the menu -beneath) is much more convenient than Vim's, which should suit basic needs. - -However, if you need an actual explorer to interact with the editor, -you can create a Kakoune script that will spawn the tool in question, -which should in return send an "edit" command followed by the path of the -file you selected to the current Kakoune session (e.g. `echo "eval -client -$kak_client edit /path/to/file" | kak -p $kak_session`). - -== Why aren't there other scopes similar to `%sh{}` e.g. python ? - -Supporting custom scopes would add hard dependencies to the project, which -is too much of a drawback when balanced against the low cost of using -an interpreter in a regular shell scope (e.g. `%sh{ python -c "..." }`). -The shell scope allows users to spawn any interpreter they want, for a minimal -cost in terms of performance, it is therefore the reason why it's the only -one available by default. - -== What shell is used to expand `%sh{}` scopes ? - -The server expands shell scopes using the `sh` binary, stored in one of the -directories where all the POSIX standard utilities can be found -this list -of directories is stored in a system configuration variable, and queried -by Kakoune at startup. - -In most distributions, `/bin/sh` will end up being used. - -== Can I disable auto-indentation completely ? - -All the indentation hooks are conventionally named `-indent`, which -allows us to use the `disabled_hooks` variable to disable indentation -globally with the following command: `set global disabled_hooks '.+-indent'` - -== How to enable syntax highlighting ? - -The mimetype of the files opened in new buffers is detected using the -`file` command, and syntax highlighting enabled automatically when -possible. - -== My file seems to be highlighted with the wrong colors, I thought syntax highlighting was detected automatically ? - -The `file` utility has several shortcomings, such as detecting the -wrong mimetype for a file containing data with different syntax, e.g. -a Python script containing hardcoded HTML templates detected as an HTML -file. - -Kakoune does its best at detecting file types (using known extensions -for a given format for instance), but not much can be done about those -ambiguous cases. You might consider writing a custom `$HOME/.magic` file -if needed. - -== Can I disable syntax highlighting completely ? - -Similarly to the indentation hooks, the name format followed by the -highlighting hooks is `-highlight`. You can thus disable syntax -highlighting using the following command: `set global disabled_hooks -'.+-highlight'` - -== Why does a dot `.` in a regex select newline characters ? - -Data in buffers is a stream of characters, and newlines do not receive special -treatment compared to other characters, with regards to regex matching. In -order to select data in a line without any trailing newline characters, one could -use the `[^\n]+` pattern, which is arguably a good compromise when -balanced against the ability to select data over several lines. - -== Can I split the window to display different buffers in them ? +=== Can I split the window to display different buffers in them ? As a fairly compliant follower of the UNIX philosophy, Kakoune does not try to implement features that are best handled by separate, dedicated @@ -184,7 +84,115 @@ In order to open buffers in the same window simultaneously using `tmux` and simply use the `:new` command to spawn new clients as you would have otherwise in an X11 environment. -== Why does `a` extend the current selection, but `i` leaves it untouched ? +== Generic functionalities + +=== How can I explore the filesystem the way Vim's NerdTree does ? + +The builtin file completion engine used when opening a file for editing +(using the `:edit` command and letting the suggestions popup in the menu +beneath) is much more convenient than Vim's, which should suit basic needs. + +However, if you need an actual explorer to interact with the editor, +you can create a Kakoune script that will spawn the tool in question, +which should in return send an "edit" command followed by the path of the +file you selected to the current Kakoune session (e.g. `echo "eval -client +$kak_client edit /path/to/file" | kak -p $kak_session`). + +=== How do I automatically indent code, as Vim does with `=` ? + +As `Kakoune` doesn't parse the contents of the buffers, there is no builtin +equivalent for this Vim feature. Use a formatter/prettifier dedicated to +the language you're using with the help of the `|` key. + +Example: `%|indent` to indent an entire buffer with C code. + +Note that some languages have a default formatter set, which you can use +with the `:format` command. + +=== Can Kakoune automatically complete the parameters of my functions ? + +As mentioned in the above question about Vim's `=` key, Kakoune does not +parse the contents of a buffer by itself, which makes it impossible for +the editor to propose candidates upon completion. + +However, support for such a feature can be achieved through the use of a +dedicated tool, as is the case with `clang` and C code: you can use the +`clang-enable-autocomplete` and `clang-complete` builtin commands whenever +editing a C/C++ file, and completion will work on function parameters. + +Note that the same features are available for Python buffers, with the +`jedi` script. + +=== Why aren't widely known command line shortcuts such as or available in Kakoune ? + +Despite their widespread availability in multiple tools, those shortcuts do +not fit the paradigm that Kakoune implements, which is based on selections +first. + +However, you can easily declare key mappings in your configuration file +to be able to use those control-based shortcuts in insert mode. +(See <>) + +=== Can I disable auto-indentation completely ? + +All the indentation hooks are conventionally named `-indent`, which +allows us to use the `disabled_hooks` variable to disable indentation +globally with the following command: `set global disabled_hooks '.+-indent'` + +=== How to enable syntax highlighting ? + +The mimetype of the files opened in new buffers is detected using the +`file` command, and syntax highlighting enabled automatically when +possible. + +=== My file seems to be highlighted with the wrong colors, I thought syntax highlighting was detected automatically ? + +The `file` utility has several shortcomings, such as detecting the +wrong mimetype for a file containing data with different syntax, e.g. +a Python script containing hardcoded HTML templates detected as an HTML +file. + +Kakoune does its best at detecting file types (using known extensions +for a given format for instance), but not much can be done about those +ambiguous cases. You might consider writing a custom `$HOME/.magic` file +if needed. + +=== Can I disable syntax highlighting completely ? + +Similarly to the indentation hooks, the name format followed by the +highlighting hooks is `-highlight`. You can thus disable syntax +highlighting using the following command: `set global disabled_hooks +'.+-highlight'` + +== The editing language + +=== Why aren't there other scopes similar to `%sh{}` e.g. python ? + +Supporting custom scopes would add hard dependencies to the project, which +is too much of a drawback when balanced against the low cost of using +an interpreter in a regular shell scope (e.g. `%sh{ python -c "..." }`). +The shell scope allows users to spawn any interpreter they want, for a minimal +cost in terms of performance, it is therefore the reason why it's the only +one available by default. + +=== What shell is used to expand `%sh{}` scopes ? + +The server expands shell scopes using the `sh` binary, stored in one of the +directories where all the POSIX standard utilities can be found -this list +of directories is stored in a system configuration variable, and queried +by Kakoune at startup. + +In most distributions, `/bin/sh` will end up being used. + +=== Why does a dot `.` in a regex select newline characters ? + +Data in buffers is a stream of characters, and newlines do not receive special +treatment compared to other characters, with regards to regex matching. In +order to select data in a line without any trailing newline characters, one could +use the `[^\n]+` pattern, which is arguably a good compromise when +balanced against the ability to select data over several lines. + +=== Why does `a` extend the current selection, but `i` leaves it untouched ? Selections are ranges of characters whose delimiters are an "anchor" and a "cursor", and inserting characters is always done before the cursor in From 79428da9b502744d0f5e5663bdb5faa17bc7c28b Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Sat, 6 Jun 2020 10:44:10 +0300 Subject: [PATCH 02/15] doc faq: Document locale issues --- doc/pages/faq.asciidoc | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/doc/pages/faq.asciidoc b/doc/pages/faq.asciidoc index a62d9fc6..9bc6ec9a 100644 --- a/doc/pages/faq.asciidoc +++ b/doc/pages/faq.asciidoc @@ -63,6 +63,45 @@ $ tic /path/to/kakoune/contrib/tmux-256color.terminfo Finally, quit all existing sessions (`tmux kill-server`), and restart `tmux`. +=== Why do I see weird special characters (~T~@~U) around Clippy? + +You need a UTF-8 compliant locale, in order to render special characters. + +The way to do so might vary from distribution to another, but an easy way +to verify that your locale is set correctly is to run the following command: + +---- +$ locale +---- + +The output should look similar to the following (with eventually another +language set instead of `en_US`): + +---- +LANG=en_US.UTF-8 +LC_CTYPE="en_US.UTF-8" +LC_NUMERIC="en_US.UTF-8" +LC_TIME="en_US.UTF-8" +LC_COLLATE="en_US.UTF-8" +LC_MONETARY="en_US.UTF-8" +LC_MESSAGES="en_US.UTF-8" +LC_PAPER="en_US.UTF-8" +LC_NAME="en_US.UTF-8" +LC_ADDRESS="en_US.UTF-8" +LC_TELEPHONE="en_US.UTF-8" +LC_MEASUREMENT="en_US.UTF-8" +LC_IDENTIFICATION="en_US.UTF-8" +LC_ALL= +---- + +You can also run the project's test suite, which should display errors if +your locale doesn't support UTF-8 rendering: + +---- +$ cd kakoune +$ make test +---- + === Why does leaving insert mode take more than half a second in `tmux` ? Upon hitting the escape key, `tmux` waits for a short period of time to From d17e7adc920150f011de9b79e1dc2dbd7d6b120f Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Sat, 6 Jun 2020 11:18:19 +0300 Subject: [PATCH 03/15] doc faq: Document how to get debug information --- doc/pages/faq.asciidoc | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/doc/pages/faq.asciidoc b/doc/pages/faq.asciidoc index 9bc6ec9a..fd58f095 100644 --- a/doc/pages/faq.asciidoc +++ b/doc/pages/faq.asciidoc @@ -125,6 +125,35 @@ have otherwise in an X11 environment. == Generic functionalities +=== Something is wrong, how can I get more debug information? + +You can get quite a lot of information out of the editor at runtime. One +way is through the `:debug` command, which will print out statistics and +state data into the `\*debug*` buffer: + +---- +:debug +---- + +Another way is to set flags on the `debug` option: + +---- +:set global debug +---- + +Make sure to read all possible values suggested by the completion engine, +as you type out both commands in a prompt. + +If you want to troubleshoot a crash, you need to compile the editor with +debug symbols enabled: + +---- +$ make debug=yes +---- + +The resulting binary should produce a stacktrace that you can, afterwards, +post in an issue in unmangled form (c.f. `c++filt`). + === How can I explore the filesystem the way Vim's NerdTree does ? The builtin file completion engine used when opening a file for editing From 0737375b616e1d0f337bb0aa521bb863a192b0a6 Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Wed, 10 Jun 2020 12:23:46 +0300 Subject: [PATCH 04/15] doc faq: Rephrase invalid note about `:format` --- doc/pages/faq.asciidoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/pages/faq.asciidoc b/doc/pages/faq.asciidoc index fd58f095..31e9901d 100644 --- a/doc/pages/faq.asciidoc +++ b/doc/pages/faq.asciidoc @@ -174,8 +174,9 @@ the language you're using with the help of the `|` key. Example: `%|indent` to indent an entire buffer with C code. -Note that some languages have a default formatter set, which you can use -with the `:format` command. +Note that you can also set the `formatcmd` option, used by the `format` +command to handle formatting in the current buffer without further +interaction. === Can Kakoune automatically complete the parameters of my functions ? From 55383afb4d783c619318b01485699590e60d3ea1 Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Wed, 10 Jun 2020 12:29:52 +0300 Subject: [PATCH 05/15] doc faq: Mention the Language Server Protocol --- doc/pages/faq.asciidoc | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/doc/pages/faq.asciidoc b/doc/pages/faq.asciidoc index 31e9901d..73763876 100644 --- a/doc/pages/faq.asciidoc +++ b/doc/pages/faq.asciidoc @@ -189,8 +189,13 @@ dedicated tool, as is the case with `clang` and C code: you can use the `clang-enable-autocomplete` and `clang-complete` builtin commands whenever editing a C/C++ file, and completion will work on function parameters. -Note that the same features are available for Python buffers, with the -`jedi` script. +Other language-support scripts implement this functionality in a similar way, +for example the `jedi` script for Python buffers. + +Another way to get automatic parameter completion that doesn't depend on +built-in support in Kakoune is through the +https://microsoft.github.io/language-server-protocol/[Language Server Protocol], +for which you can find implementations that interact with the editor. === Why aren't widely known command line shortcuts such as or available in Kakoune ? From ad122aec4e8e7361eea6de7f85ab80fe5eae5288 Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Wed, 10 Jun 2020 12:32:06 +0300 Subject: [PATCH 06/15] doc faq: Mention "readline shortcuts" in prompts --- doc/pages/faq.asciidoc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/pages/faq.asciidoc b/doc/pages/faq.asciidoc index 73763876..c1a2f6bf 100644 --- a/doc/pages/faq.asciidoc +++ b/doc/pages/faq.asciidoc @@ -207,6 +207,9 @@ However, you can easily declare key mappings in your configuration file to be able to use those control-based shortcuts in insert mode. (See <>) +Also note that a subset of "readline shortcuts" is implemented for command +prompts. + === Can I disable auto-indentation completely ? All the indentation hooks are conventionally named `-indent`, which From cb5e00537844374ddf4622656184c411f04a190b Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Wed, 10 Jun 2020 12:37:43 +0300 Subject: [PATCH 07/15] doc faq: Mention `(?S)` --- doc/pages/faq.asciidoc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/pages/faq.asciidoc b/doc/pages/faq.asciidoc index c1a2f6bf..a9f2d6b7 100644 --- a/doc/pages/faq.asciidoc +++ b/doc/pages/faq.asciidoc @@ -269,6 +269,9 @@ order to select data in a line without any trailing newline characters, one coul use the `[^\n]+` pattern, which is arguably a good compromise when balanced against the ability to select data over several lines. +You can instruct the regex engine to stop matching newline characters with +`.` by disabling the appropriate flag (`(?S)`). + === Why does `a` extend the current selection, but `i` leaves it untouched ? Selections are ranges of characters whose delimiters are an "anchor" and From 61094a97e2518f05ead37eddc5653c5bb2d370a1 Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Wed, 10 Jun 2020 12:38:54 +0300 Subject: [PATCH 08/15] doc faq: Fix the prose --- doc/pages/faq.asciidoc | 53 +++++++++++++++++++++--------------------- 1 file changed, 26 insertions(+), 27 deletions(-) diff --git a/doc/pages/faq.asciidoc b/doc/pages/faq.asciidoc index a9f2d6b7..3b765800 100644 --- a/doc/pages/faq.asciidoc +++ b/doc/pages/faq.asciidoc @@ -6,16 +6,16 @@ The name of the project is pronounced "Kak-oon", and is a word taken from a New Caledonian dialect based on French. It means a hard blow, usually a punch, -but generally refers to a blow into which all of one's strength went. +but generally refers to a strike into which all of one's strength went. === Is there going to be a Windows port of Kakoune ? -As many features provided by UNIX systems would be missing, or if anything -much less efficient on a Windows system, the incentive to porting the -project to this operating system is pretty low. +As many features provided by UNIX systems would be missing, or albeit much +less efficient, on a Windows system, the incentive to porting the project +to this operating system is low. -Moreover, you can get pretty decent performance by using Kakoune on Cygwin -(which is officially supported). +Moreover, you can achieve pretty decent performance by using Kakoune on +Cygwin (which is officially supported). == Interfacing @@ -32,17 +32,17 @@ try experimental community-developed ones. === Why are colors misrendered in my Kakoune clients ? -The most probable cause for that is a very widespread practice that consists -in setting the `TERM` environment variable in the shell's configuration file. -This variable should be set by the terminal emulator, and not overridden with -an arbitrary value, otherwise it might interfere with general UI rendering on -the terminal's window. +The most probable cause for colors being misrendered is a widespread practice +that consists in setting the `TERM` environment variable in the shell's +configuration file. This variable should be set by the terminal emulator, +and not overridden with an arbitrary value, otherwise it might interfere +with general UI rendering on the terminal's window. === I'm using `tmux` and colors look weird If you're using a tool that doesn't support "palette switching", colors will still be slightly off: they are being rounded down to values supported by the -regular color palette by Kakoune. Fortunately, on recent versions of `tmux` +regular color palette of Kakoune. Fortunately, on recent versions of `tmux` (>=2.6), you can work around that by using the following configuration settings: @@ -74,8 +74,8 @@ to verify that your locale is set correctly is to run the following command: $ locale ---- -The output should look similar to the following (with eventually another -language set instead of `en_US`): +The output should look similar to the following (with your own +language/country code set, instead of `en_US`): ---- LANG=en_US.UTF-8 @@ -114,7 +114,7 @@ to a short time, e.g. 25ms: `set -sg escape-time 25` As a fairly compliant follower of the UNIX philosophy, Kakoune does not try to implement features that are best handled by separate, dedicated tools. Window splitting in terminals is a prime example of that -concept, where the editor provides commands to interact with several +concept, whereby the editor provides commands to interact with several terminal multiplexers (e.g. `tmux`), as opposed to emulating their functionalities. @@ -158,7 +158,7 @@ post in an issue in unmangled form (c.f. `c++filt`). The builtin file completion engine used when opening a file for editing (using the `:edit` command and letting the suggestions popup in the menu -beneath) is much more convenient than Vim's, which should suit basic needs. +beneath) is more convenient than Vim's, which should suit basic needs. However, if you need an actual explorer to interact with the editor, you can create a Kakoune script that will spawn the tool in question, @@ -218,21 +218,20 @@ globally with the following command: `set global disabled_hooks '.+-indent'` === How to enable syntax highlighting ? -The mimetype of the files opened in new buffers is detected using the +The MIME type of the files opened in new buffers is detected using the `file` command, and syntax highlighting enabled automatically when possible. === My file seems to be highlighted with the wrong colors, I thought syntax highlighting was detected automatically ? The `file` utility has several shortcomings, such as detecting the -wrong mimetype for a file containing data with different syntax, e.g. +wrong MIME type for a file containing data with different syntax, e.g. a Python script containing hardcoded HTML templates detected as an HTML file. -Kakoune does its best at detecting file types (using known extensions -for a given format for instance), but not much can be done about those -ambiguous cases. You might consider writing a custom `$HOME/.magic` file -if needed. +Kakoune does its best to detect file types (using known extensions for a +given format for instance), but not much can be done about those ambiguous +cases. You might consider writing a custom `$HOME/.magic` file if needed. === Can I disable syntax highlighting completely ? @@ -254,10 +253,10 @@ one available by default. === What shell is used to expand `%sh{}` scopes ? -The server expands shell scopes using the `sh` binary, stored in one of the -directories where all the POSIX standard utilities can be found -this list -of directories is stored in a system configuration variable, and queried -by Kakoune at startup. +The server expands shell scopes using the `sh` binary, located in one of +the directories containing all the POSIX standard utilities. This list of +directories is stored in a system configuration variable, and queried by +Kakoune at startup. In most distributions, `/bin/sh` will end up being used. @@ -275,7 +274,7 @@ You can instruct the regex engine to stop matching newline characters with === Why does `a` extend the current selection, but `i` leaves it untouched ? Selections are ranges of characters whose delimiters are an "anchor" and -a "cursor", and inserting characters is always done before the cursor in +a "cursor", and inserting characters is always done before the anchor in insert mode. Consequently, using the append primitive (`a`) nudges the cursor forward to From b72493bbbb1cd6a41499c6bc16e06b832795c0af Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Wed, 10 Jun 2020 14:49:46 +0300 Subject: [PATCH 09/15] doc faq: Document `-buffer *` --- doc/pages/faq.asciidoc | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/doc/pages/faq.asciidoc b/doc/pages/faq.asciidoc index 3b765800..b3adf856 100644 --- a/doc/pages/faq.asciidoc +++ b/doc/pages/faq.asciidoc @@ -282,3 +282,16 @@ make room for characters, effectively extending the current selection since the anchor remains immobile, even when the anchor and the cursor are at the same location. By opposition, using the insert primitive (`i`) merely adds characters before the cursor, which never modifies the current selection. + +=== How to apply changes to all open buffers? + +The `:exec` and `:eval` commands can apply changes to a comma-separated +list of buffers, passed as argument to the `-buffer` flag. + +In order to the editor figure out which buffers are open, the special value +`*` is accepted as a wildcard. For example, in order to reload all open +buffers: + +---- +:eval -buffer * e! +---- From 1761c4e059ba06519a4d2c7319ae3918513c5a6b Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Thu, 11 Jun 2020 10:17:10 +0300 Subject: [PATCH 10/15] doc faq: Remove space leading question marks --- doc/pages/faq.asciidoc | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/doc/pages/faq.asciidoc b/doc/pages/faq.asciidoc index b3adf856..2f60bdb2 100644 --- a/doc/pages/faq.asciidoc +++ b/doc/pages/faq.asciidoc @@ -25,12 +25,12 @@ Kakoune can be used as a pager, either by setting the `PAGER` environment variable to `kak`, or by writing data directly to its standard input using a shell pipeline. -=== Are there any non-console based frontends available ? +=== Are there any non-console based frontends available? No graphical frontend is currently officially maintained, you can however try experimental community-developed ones. -=== Why are colors misrendered in my Kakoune clients ? +=== Why are colors misrendered in my Kakoune clients? The most probable cause for colors being misrendered is a widespread practice that consists in setting the `TERM` environment variable in the shell's @@ -102,14 +102,14 @@ $ cd kakoune $ make test ---- -=== Why does leaving insert mode take more than half a second in `tmux` ? +=== Why does leaving insert mode take more than half a second in `tmux`? Upon hitting the escape key, `tmux` waits for a short period of time to determine whether it's part of a function or a meta key sequence. In order to fix this "lag", set the waiting period in your `tmux` configuration file to a short time, e.g. 25ms: `set -sg escape-time 25` -=== Can I split the window to display different buffers in them ? +=== Can I split the window to display different buffers in them? As a fairly compliant follower of the UNIX philosophy, Kakoune does not try to implement features that are best handled by separate, dedicated @@ -154,7 +154,7 @@ $ make debug=yes The resulting binary should produce a stacktrace that you can, afterwards, post in an issue in unmangled form (c.f. `c++filt`). -=== How can I explore the filesystem the way Vim's NerdTree does ? +=== How can I explore the filesystem the way Vim's NerdTree does? The builtin file completion engine used when opening a file for editing (using the `:edit` command and letting the suggestions popup in the menu @@ -166,7 +166,7 @@ which should in return send an "edit" command followed by the path of the file you selected to the current Kakoune session (e.g. `echo "eval -client $kak_client edit /path/to/file" | kak -p $kak_session`). -=== How do I automatically indent code, as Vim does with `=` ? +=== How do I automatically indent code, as Vim does with `=`? As `Kakoune` doesn't parse the contents of the buffers, there is no builtin equivalent for this Vim feature. Use a formatter/prettifier dedicated to @@ -178,7 +178,7 @@ Note that you can also set the `formatcmd` option, used by the `format` command to handle formatting in the current buffer without further interaction. -=== Can Kakoune automatically complete the parameters of my functions ? +=== Can Kakoune automatically complete the parameters of my functions? As mentioned in the above question about Vim's `=` key, Kakoune does not parse the contents of a buffer by itself, which makes it impossible for @@ -197,7 +197,7 @@ built-in support in Kakoune is through the https://microsoft.github.io/language-server-protocol/[Language Server Protocol], for which you can find implementations that interact with the editor. -=== Why aren't widely known command line shortcuts such as or available in Kakoune ? +=== Why aren't widely known command line shortcuts such as or available in Kakoune? Despite their widespread availability in multiple tools, those shortcuts do not fit the paradigm that Kakoune implements, which is based on selections @@ -210,19 +210,19 @@ to be able to use those control-based shortcuts in insert mode. Also note that a subset of "readline shortcuts" is implemented for command prompts. -=== Can I disable auto-indentation completely ? +=== Can I disable auto-indentation completely? All the indentation hooks are conventionally named `-indent`, which allows us to use the `disabled_hooks` variable to disable indentation globally with the following command: `set global disabled_hooks '.+-indent'` -=== How to enable syntax highlighting ? +=== How to enable syntax highlighting? The MIME type of the files opened in new buffers is detected using the `file` command, and syntax highlighting enabled automatically when possible. -=== My file seems to be highlighted with the wrong colors, I thought syntax highlighting was detected automatically ? +=== My file seems to be highlighted with the wrong colors, I thought syntax highlighting was detected automatically? The `file` utility has several shortcomings, such as detecting the wrong MIME type for a file containing data with different syntax, e.g. @@ -233,7 +233,7 @@ Kakoune does its best to detect file types (using known extensions for a given format for instance), but not much can be done about those ambiguous cases. You might consider writing a custom `$HOME/.magic` file if needed. -=== Can I disable syntax highlighting completely ? +=== Can I disable syntax highlighting completely? Similarly to the indentation hooks, the name format followed by the highlighting hooks is `-highlight`. You can thus disable syntax @@ -242,7 +242,7 @@ highlighting using the following command: `set global disabled_hooks == The editing language -=== Why aren't there other scopes similar to `%sh{}` e.g. python ? +=== Why aren't there other scopes similar to `%sh{}` e.g. python? Supporting custom scopes would add hard dependencies to the project, which is too much of a drawback when balanced against the low cost of using @@ -251,7 +251,7 @@ The shell scope allows users to spawn any interpreter they want, for a minimal cost in terms of performance, it is therefore the reason why it's the only one available by default. -=== What shell is used to expand `%sh{}` scopes ? +=== What shell is used to expand `%sh{}` scopes? The server expands shell scopes using the `sh` binary, located in one of the directories containing all the POSIX standard utilities. This list of @@ -260,7 +260,7 @@ Kakoune at startup. In most distributions, `/bin/sh` will end up being used. -=== Why does a dot `.` in a regex select newline characters ? +=== Why does a dot `.` in a regex select newline characters? Data in buffers is a stream of characters, and newlines do not receive special treatment compared to other characters, with regards to regex matching. In @@ -271,7 +271,7 @@ balanced against the ability to select data over several lines. You can instruct the regex engine to stop matching newline characters with `.` by disabling the appropriate flag (`(?S)`). -=== Why does `a` extend the current selection, but `i` leaves it untouched ? +=== Why does `a` extend the current selection, but `i` leaves it untouched? Selections are ranges of characters whose delimiters are an "anchor" and a "cursor", and inserting characters is always done before the anchor in From 442aae1cef917478313093028fdea149c0ffadcc Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Thu, 11 Jun 2020 10:30:46 +0300 Subject: [PATCH 11/15] doc faq: Fix the prose --- doc/pages/faq.asciidoc | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/doc/pages/faq.asciidoc b/doc/pages/faq.asciidoc index 2f60bdb2..bcad010e 100644 --- a/doc/pages/faq.asciidoc +++ b/doc/pages/faq.asciidoc @@ -10,9 +10,9 @@ but generally refers to a strike into which all of one's strength went. === Is there going to be a Windows port of Kakoune ? -As many features provided by UNIX systems would be missing, or albeit much -less efficient, on a Windows system, the incentive to porting the project -to this operating system is low. +As many features provided by UNIX systems are missing or less efficient on +a Windows system, the incentive to porting the project to this operating +system is low. Moreover, you can achieve pretty decent performance by using Kakoune on Cygwin (which is officially supported). @@ -114,7 +114,7 @@ to a short time, e.g. 25ms: `set -sg escape-time 25` As a fairly compliant follower of the UNIX philosophy, Kakoune does not try to implement features that are best handled by separate, dedicated tools. Window splitting in terminals is a prime example of that -concept, whereby the editor provides commands to interact with several +concept, where the editor provides commands to interact with several terminal multiplexers (e.g. `tmux`), as opposed to emulating their functionalities. @@ -157,7 +157,7 @@ post in an issue in unmangled form (c.f. `c++filt`). === How can I explore the filesystem the way Vim's NerdTree does? The builtin file completion engine used when opening a file for editing -(using the `:edit` command and letting the suggestions popup in the menu +(using the `:edit` command and letting the suggestions pop up in the menu beneath) is more convenient than Vim's, which should suit basic needs. However, if you need an actual explorer to interact with the editor, @@ -174,9 +174,8 @@ the language you're using with the help of the `|` key. Example: `%|indent` to indent an entire buffer with C code. -Note that you can also set the `formatcmd` option, used by the `format` -command to handle formatting in the current buffer without further -interaction. +You can also set the `formatcmd` option and use the `:format` command to +format the entire buffer. === Can Kakoune automatically complete the parameters of my functions? @@ -288,9 +287,9 @@ characters before the cursor, which never modifies the current selection. The `:exec` and `:eval` commands can apply changes to a comma-separated list of buffers, passed as argument to the `-buffer` flag. -In order to the editor figure out which buffers are open, the special value -`*` is accepted as a wildcard. For example, in order to reload all open -buffers: +In order to let the editor figure out which buffers are open, the special +value `*` is accepted as a wildcard. For example, in order to reload all +open buffers: ---- :eval -buffer * e! From accc619c0f88561ee9fda57bb8870db0657eef98 Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Fri, 26 Jun 2020 11:12:25 +0300 Subject: [PATCH 12/15] doc faq: Document hook disabling with `\i` --- doc/pages/faq.asciidoc | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/doc/pages/faq.asciidoc b/doc/pages/faq.asciidoc index bcad010e..5dbed3b5 100644 --- a/doc/pages/faq.asciidoc +++ b/doc/pages/faq.asciidoc @@ -294,3 +294,16 @@ open buffers: ---- :eval -buffer * e! ---- + +=== Why is the text I pasted into a buffer completely mangled? + +In order to assist users with writing code, some buffers come with hooks that +automatically indent the text inserted. Pasting the contents of the clipboard +into a buffer in insert mode triggers this indentation functionality, +resulting into mangled text. + +To prevent that from happening: + +* disable hooks and enter insert mode with `\i` +* insert text into the buffer (e.g. paste the clipboard's contents) +* exit insert-mode, restoring hooks with `` From a84e3aeb859641cb8f0fc47261427c7a98a136dd Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Tue, 21 Jul 2020 09:08:35 +0300 Subject: [PATCH 13/15] doc faq: Document beam cursors being inconsistent --- doc/pages/faq.asciidoc | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/doc/pages/faq.asciidoc b/doc/pages/faq.asciidoc index 5dbed3b5..956bec57 100644 --- a/doc/pages/faq.asciidoc +++ b/doc/pages/faq.asciidoc @@ -239,6 +239,19 @@ highlighting hooks is `-highlight`. You can thus disable syntax highlighting using the following command: `set global disabled_hooks '.+-highlight'` +=== Can the cursor be rendered as a beam? + +Rendering the cursor as a beam is a common feature of other modal editors, +it however doesn't fit within Kakoune's selection-first paradigm. + +There is a selection on screen at all times, containing either data selected +by the user, or a newline character when the buffer is empty. + +A selection is bound by an anchor and a cursor. They can overlap, but +ultimately must both be placed *over* a character. A beam cursor placed +*between* two characters doesn't fulfil that requirement, and is thus +not allowed. + == The editing language === Why aren't there other scopes similar to `%sh{}` e.g. python? From e0193f23db15d411557624b6642e65c4ddbf14c8 Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Tue, 21 Jul 2020 17:36:45 +0300 Subject: [PATCH 14/15] doc faq: Fix the prose --- doc/pages/faq.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/pages/faq.asciidoc b/doc/pages/faq.asciidoc index 956bec57..8fff155c 100644 --- a/doc/pages/faq.asciidoc +++ b/doc/pages/faq.asciidoc @@ -286,7 +286,7 @@ You can instruct the regex engine to stop matching newline characters with === Why does `a` extend the current selection, but `i` leaves it untouched? Selections are ranges of characters whose delimiters are an "anchor" and -a "cursor", and inserting characters is always done before the anchor in +a "cursor", and inserting characters is always done before the cursor in insert mode. Consequently, using the append primitive (`a`) nudges the cursor forward to From 2192e3845a38286e1524724506159c36e8035f5f Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Mon, 10 Aug 2020 12:23:35 +0300 Subject: [PATCH 15/15] doc faq: Document the frugal scripting language --- doc/pages/faq.asciidoc | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/doc/pages/faq.asciidoc b/doc/pages/faq.asciidoc index 8fff155c..9ad20133 100644 --- a/doc/pages/faq.asciidoc +++ b/doc/pages/faq.asciidoc @@ -254,6 +254,22 @@ not allowed. == The editing language +=== The scripting language lacks keywords, when are you going to expand it? + +The scripting language is the smallest subset of statements/keywords that +allows users to write plugins, commands, mappings. + +It's not intended to be a one-stop generic interface, but rather a glue +between core Kakoune instructions and complex logic. + +Other editors generally come up with their own language or leverage existing +ones (for example, VimL, LUA), whereas Kakoune interacts with the shell, +through `%sh{…}` scopes. + +As arbitrary Kakoune data (options, selection etc.) can be shared with +shell scopes through environment variables, users are free to process this +data with pure shell scripting, or whatever interpreter they desire. + === Why aren't there other scopes similar to `%sh{}` e.g. python? Supporting custom scopes would add hard dependencies to the project, which