faq.asciidoc (12975B)
1 = FAQ 2 3 == The project 4 5 === How to pronounce the name of the project and what does it mean ? 6 7 The name of the project is pronounced "Kak-oon", and is a word taken from a 8 New Caledonian dialect based on French. It means a hard blow, usually a punch, 9 but generally refers to a strike into which all of one's strength went. 10 11 === Is there going to be a Windows port of Kakoune ? 12 13 As many features provided by UNIX systems are missing or less efficient on 14 a Windows system, the incentive to porting the project to this operating 15 system is low. 16 17 Moreover, you can achieve pretty decent performance by using Kakoune on 18 Cygwin (which is officially supported). 19 20 == Interfacing 21 22 === Can I use Kakoune as a pager ? 23 24 Kakoune can be used as a pager, either by setting the `PAGER` environment 25 variable to `kak`, or by writing data directly to its standard input using a 26 shell pipeline. 27 28 === Are there any non-console based frontends available? 29 30 No graphical frontend is currently officially maintained, you can however 31 try experimental community-developed ones. 32 33 === Why are colors misrendered in my Kakoune clients? 34 35 The most probable cause for colors being misrendered is a widespread practice 36 that consists in setting the `TERM` environment variable in the shell's 37 configuration file. This variable should be set by the terminal emulator, 38 and not overridden with an arbitrary value, otherwise it might interfere 39 with general UI rendering on the terminal's window. 40 41 === I'm using `tmux` and colors look weird 42 43 If you're using a tool that doesn't support "palette switching", colors will 44 still be slightly off: they are being rounded down to values supported by the 45 regular color palette of Kakoune. Fortunately, on recent versions of `tmux` 46 (>=2.6), you can work around that by using the following configuration 47 settings: 48 49 .~/.tmux.conf 50 ---- 51 set -g default-terminal "tmux-256color" 52 set -ga terminal-overrides ",*col*:Tc" 53 ---- 54 55 Note: `\*col*` is a regular expression that matches your terminal's `$TERM` 56 value, modify it if necessary, e.g. `xterm-termite`. 57 58 Next, run the following command to create a local `terminfo` override: 59 60 ---- 61 $ tic /path/to/kakoune/contrib/tmux-256color.terminfo 62 ---- 63 64 Finally, quit all existing sessions (`tmux kill-server`), and restart `tmux`. 65 66 === Why do I see weird special characters (~T~@~U) around Clippy? 67 68 You need a UTF-8 compliant locale, in order to render special characters. 69 70 The way to do so might vary from distribution to another, but an easy way 71 to verify that your locale is set correctly is to run the following command: 72 73 ---- 74 $ locale 75 ---- 76 77 The output should look similar to the following (with your own 78 language/country code set, instead of `en_US`): 79 80 ---- 81 LANG=en_US.UTF-8 82 LC_CTYPE="en_US.UTF-8" 83 LC_NUMERIC="en_US.UTF-8" 84 LC_TIME="en_US.UTF-8" 85 LC_COLLATE="en_US.UTF-8" 86 LC_MONETARY="en_US.UTF-8" 87 LC_MESSAGES="en_US.UTF-8" 88 LC_PAPER="en_US.UTF-8" 89 LC_NAME="en_US.UTF-8" 90 LC_ADDRESS="en_US.UTF-8" 91 LC_TELEPHONE="en_US.UTF-8" 92 LC_MEASUREMENT="en_US.UTF-8" 93 LC_IDENTIFICATION="en_US.UTF-8" 94 LC_ALL= 95 ---- 96 97 You can also run the project's test suite, which should display errors if 98 your locale doesn't support UTF-8 rendering: 99 100 ---- 101 $ cd kakoune 102 $ make test 103 ---- 104 105 === Why does leaving insert mode take more than half a second in `tmux`? 106 107 Upon hitting the escape key, `tmux` waits for a short period of time to 108 determine whether it's part of a function or a meta key sequence. In order 109 to fix this "lag", set the waiting period in your `tmux` configuration file 110 to a short time, e.g. 25ms: `set -sg escape-time 25` 111 112 === Can I split the window to display different buffers in them? 113 114 As a fairly compliant follower of the UNIX philosophy, Kakoune does not 115 try to implement features that are best handled by separate, dedicated 116 tools. Window splitting in terminals is a prime example of that 117 concept, where the editor provides commands to interact with several 118 terminal multiplexers (e.g. `tmux`), as opposed to emulating their 119 functionalities. 120 121 In order to open buffers in the same window simultaneously using `tmux` 122 (or one of the supported multiplexers), run Kakoune in a `tmux` session, 123 and simply use the `:new` command to spawn new clients as you would 124 have otherwise in an X11 environment. 125 126 == Generic functionalities 127 128 === Something is wrong, how can I get more debug information? 129 130 You can get quite a lot of information out of the editor at runtime. One 131 way is through the `:debug` command, which will print out statistics and 132 state data into the `\*debug*` buffer: 133 134 ---- 135 :debug <command> 136 ---- 137 138 Another way is to set flags on the `debug` option: 139 140 ---- 141 :set global debug <flags> 142 ---- 143 144 Make sure to read all possible values suggested by the completion engine, 145 as you type out both commands in a prompt. 146 147 If you want to troubleshoot a crash, you need to compile the editor with 148 debug symbols enabled: 149 150 ---- 151 $ make debug=yes 152 ---- 153 154 The resulting binary should produce a stacktrace that you can, afterwards, 155 post in an issue in unmangled form (c.f. `c++filt`). 156 157 === How can I explore the filesystem the way Vim's NerdTree does? 158 159 The builtin file completion engine used when opening a file for editing 160 (using the `:edit` command and letting the suggestions pop up in the menu 161 beneath) is more convenient than Vim's, which should suit basic needs. 162 163 However, if you need an actual explorer to interact with the editor, 164 you can create a Kakoune script that will spawn the tool in question, 165 which should in return send an "edit" command followed by the path of the 166 file you selected to the current Kakoune session (e.g. `echo "eval -client 167 $kak_client edit /path/to/file" | kak -p $kak_session`). 168 169 === How do I automatically indent code, as Vim does with `=`? 170 171 As `Kakoune` doesn't parse the contents of the buffers, there is no builtin 172 equivalent for this Vim feature. Use a formatter/prettifier dedicated to 173 the language you're using with the help of the `|` key. 174 175 Example: `%|indent<ret>` to indent an entire buffer with C code. 176 177 You can also set the `formatcmd` option and use the `:format` command to 178 format the entire buffer. 179 180 === Can Kakoune automatically complete the parameters of my functions? 181 182 As mentioned in the above question about Vim's `=` key, Kakoune does not 183 parse the contents of a buffer by itself, which makes it impossible for 184 the editor to propose candidates upon completion. 185 186 However, support for such a feature can be achieved through the use of a 187 dedicated tool, as is the case with `clang` and C code: you can use the 188 `clang-enable-autocomplete` and `clang-complete` builtin commands whenever 189 editing a C/C++ file, and completion will work on function parameters. 190 191 Other language-support scripts implement this functionality in a similar way, 192 for example the `jedi` script for Python buffers. 193 194 Another way to get automatic parameter completion that doesn't depend on 195 built-in support in Kakoune is through the 196 https://microsoft.github.io/language-server-protocol/[Language Server Protocol], 197 for which you can find implementations that interact with the editor. 198 199 === Why aren't widely known command line shortcuts such as <c-w> or <c-u> available in Kakoune? 200 201 Despite their widespread availability in multiple tools, those shortcuts do 202 not fit the paradigm that Kakoune implements, which is based on selections 203 first. 204 205 However, you can easily declare key mappings in your configuration file 206 to be able to use those control-based shortcuts in insert mode. 207 (See <<mapping#,`:doc mapping`>>) 208 209 Also note that a subset of "readline shortcuts" is implemented for command 210 prompts. 211 212 === Can I disable auto-indentation completely? 213 214 All the indentation hooks are conventionally named `<lang>-indent`, which 215 allows us to use the `disabled_hooks` variable to disable indentation 216 globally with the following command: `set global disabled_hooks '.+-indent'` 217 218 === How to enable syntax highlighting? 219 220 The MIME type of the files opened in new buffers is detected using the 221 `file` command, and syntax highlighting enabled automatically when 222 possible. 223 224 === My file seems to be highlighted with the wrong colors, I thought syntax highlighting was detected automatically? 225 226 The `file` utility has several shortcomings, such as detecting the 227 wrong MIME type for a file containing data with different syntax, e.g. 228 a Python script containing hardcoded HTML templates detected as an HTML 229 file. 230 231 Kakoune does its best to detect file types (using known extensions for a 232 given format for instance), but not much can be done about those ambiguous 233 cases. You might consider writing a custom `$HOME/.magic` file if needed. 234 235 === Can I disable syntax highlighting completely? 236 237 Similarly to the indentation hooks, the name format followed by the 238 highlighting hooks is `<lang>-highlight`. You can thus disable syntax 239 highlighting using the following command: `set global disabled_hooks 240 '.+-highlight'` 241 242 === Can the cursor be rendered as a beam? 243 244 Rendering the cursor as a beam is a common feature of other modal editors, 245 it however doesn't fit within Kakoune's selection-first paradigm. 246 247 There is a selection on screen at all times, containing either data selected 248 by the user, or a newline character when the buffer is empty. 249 250 A selection is bound by an anchor and a cursor. They can overlap, but 251 ultimately must both be placed *over* a character. A beam cursor placed 252 *between* two characters doesn't fulfil that requirement, and is thus 253 not allowed. 254 255 == The editing language 256 257 === The scripting language lacks keywords, when are you going to expand it? 258 259 The scripting language is the smallest subset of statements/keywords that 260 allows users to write plugins, commands, mappings. 261 262 It's not intended to be a one-stop generic interface, but rather a glue 263 between core Kakoune instructions and complex logic. 264 265 Other editors generally come up with their own language or leverage existing 266 ones (for example, VimL, LUA), whereas Kakoune interacts with the shell, 267 through `%sh{…}` scopes. 268 269 As arbitrary Kakoune data (options, selection etc.) can be shared with 270 shell scopes through environment variables, users are free to process this 271 data with pure shell scripting, or whatever interpreter they desire. 272 273 === Why aren't there other scopes similar to `%sh{}` e.g. python? 274 275 Supporting custom scopes would add hard dependencies to the project, which 276 is too much of a drawback when balanced against the low cost of using 277 an interpreter in a regular shell scope (e.g. `%sh{ python -c "..." }`). 278 The shell scope allows users to spawn any interpreter they want, for a minimal 279 cost in terms of performance, it is therefore the reason why it's the only 280 one available by default. 281 282 === What shell is used to expand `%sh{}` scopes? 283 284 The server expands shell scopes using the `sh` binary, located in one of 285 the directories containing all the POSIX standard utilities. This list of 286 directories is stored in a system configuration variable, and queried by 287 Kakoune at startup. 288 289 In most distributions, `/bin/sh` will end up being used. 290 291 === Why does a dot `.` in a regex select newline characters? 292 293 Data in buffers is a stream of characters, and newlines do not receive special 294 treatment compared to other characters, with regards to regex matching. In 295 order to select data in a line without any trailing newline characters, one 296 could use the `\N+` pattern, which is arguably a good compromise when 297 balanced against the ability to select data over several lines. 298 299 You can instruct the regex engine to stop matching newline characters with 300 `.` by disabling the appropriate flag (`(?S)`). 301 302 === Why does `a` extend the current selection, but `i` leaves it untouched? 303 304 Selections are ranges of characters whose delimiters are an "anchor" and 305 a "cursor", and inserting characters is always done before the cursor in 306 insert mode. 307 308 Consequently, using the append primitive (`a`) nudges the cursor forward to 309 make room for characters, effectively extending the current selection since 310 the anchor remains immobile, even when the anchor and the cursor are at the 311 same location. By opposition, using the insert primitive (`i`) merely adds 312 characters before the cursor, which never modifies the current selection. 313 314 === How to apply changes to all open buffers? 315 316 The `:exec` and `:eval` commands can apply changes to a comma-separated 317 list of buffers, passed as argument to the `-buffer` flag. 318 319 In order to let the editor figure out which buffers are open, the special 320 value `*` is accepted as a wildcard. For example, in order to reload all 321 open buffers: 322 323 ---- 324 :eval -buffer * e! 325 ---- 326 327 === Why is the text I pasted into a buffer completely mangled? 328 329 In order to assist users with writing code, some buffers come with hooks that 330 automatically indent the text inserted. Pasting the contents of the clipboard 331 into a buffer in insert mode triggers this indentation functionality, 332 resulting into mangled text. 333 334 To prevent that from happening: 335 336 * disable hooks and enter insert mode with `\i` 337 * insert text into the buffer (e.g. paste the clipboard's contents) 338 * exit insert-mode, restoring hooks with `<esc>`