From cf152832e5abc79f16c3b3724eda50a3d03051a0 Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Sat, 6 Jun 2020 10:34:52 +0300 Subject: [PATCH] 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