kakoune

Fork of kakoune, an acceptable text editor
git clone git://git.laack.co/kakoune.git
Log | Files | Refs

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>`