From 3d80ce5f8e8917dad1f7c260c869e472fa6fcc2c Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Tue, 23 Aug 2016 07:47:07 +0300 Subject: [PATCH 1/5] Add a basic FAQ --- doc/manpages/faq.asciidoc | 92 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 doc/manpages/faq.asciidoc diff --git a/doc/manpages/faq.asciidoc b/doc/manpages/faq.asciidoc new file mode 100644 index 000000000..cb9468044 --- /dev/null +++ b/doc/manpages/faq.asciidoc @@ -0,0 +1,92 @@ +Frequently Asked Questions +-------------------------- + +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 performant on a Windows system, the incentive to porting the +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 you get rid of the `boost` dependency and just use std::regex ? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The `boost-regex` library provides use with several features that are +heavily relied upon across several core scripts, and a few of them are +not available in the standard `std::regex` implementations. Therefore, +until the standard catches up with `boost` in terms of features, +the latter will remain a hard -mandatory- dependency. + +Kakoune is very slow on big files, what can I do about it ? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The default build mode (set in the `Makefile` of the `src` directory +of the project) is "debug", which makes it convenient to track issues +but also affects performance. To disable the debug mode, recompile the +project by setting the `debug` variable in `src/Makefile` to `no`. + +Can I use Kakoune as a pager ? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +. + +Are there any non-console based frontends available ? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +No graphical frontend is currently officially maintained, you can however try experimental community-developed ones. + +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 (e.g. `indent` for C). + +Can Kakoune automatically complete the parameters of my functions ? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As mentioned in the above question about Vim's `==` command, 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 + +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 +(c.f. the "map" command in the "commands" documentation page). + +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 fill +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 except for `%sh{}` e.g. python ? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Supporting custom scopes would add hard dependencies to the project, +which is too much of an drawback when balanced against the low cost of +using an interpreter in a regular shell scope (e.g. `%sh{ python -c +"..." }`), which has a negligible impact on performance. From 59bb543bb5742b134a8af827b6c1a7dfd7bebb5a Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Thu, 22 Sep 2016 21:01:46 +0300 Subject: [PATCH 2/5] Add more questions, complete some answers --- doc/manpages/faq.asciidoc | 41 ++++++++++++++++++++++++++++++++++----- 1 file changed, 36 insertions(+), 5 deletions(-) diff --git a/doc/manpages/faq.asciidoc b/doc/manpages/faq.asciidoc index cb9468044..8a917283b 100644 --- a/doc/manpages/faq.asciidoc +++ b/doc/manpages/faq.asciidoc @@ -1,6 +1,14 @@ Frequently Asked Questions -------------------------- +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 Caledonia dialect based on french. It means a hard blow, usually a +punch, but generally refers to a blow in which all of one's strength went +into doing. + Is there going to be a Windows port of Kakoune ? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -36,19 +44,25 @@ Can I use Kakoune as a pager ? Are there any non-console based frontends available ? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -No graphical frontend is currently officially maintained, you can however try experimental community-developed ones. +No graphical frontend is currently officially maintained, you can however +try experimental community-developed ones. -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 the language you're using (e.g. `indent` for C). +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 `==` command, Kakoune +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. @@ -56,7 +70,10 @@ 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 +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 ? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -90,3 +107,17 @@ Supporting custom scopes would add hard dependencies to the project, which is too much of an drawback when balanced against the low cost of using an interpreter in a regular shell scope (e.g. `%sh{ python -c "..." }`), which has a negligible impact on performance. + +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'` + +Can I disable syntax highligting completely ? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Similarly to the indentation hooks, the named format followed by the highligting +hooks is `-highlight`. You can thus disable syntax highligting using +the following command: `set global disabled_hooks '.+-highlight'` From 9848e1f4babfd33593c81e10cc62a69e39330261 Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Fri, 23 Sep 2016 13:50:10 +0300 Subject: [PATCH 3/5] Fix a few mistakes, allow `a2x` to compile the page --- doc/manpages/faq.asciidoc | 110 ++++++++++++++++++++------------------ 1 file changed, 59 insertions(+), 51 deletions(-) diff --git a/doc/manpages/faq.asciidoc b/doc/manpages/faq.asciidoc index 8a917283b..ca7f5b4a5 100644 --- a/doc/manpages/faq.asciidoc +++ b/doc/manpages/faq.asciidoc @@ -1,13 +1,16 @@ -Frequently Asked Questions --------------------------- +KAKOUNE(1) +========== + +NAME +---- +faq - a 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 Caledonia dialect based on french. It means a hard blow, usually a -punch, but generally refers to a blow in which all of one's strength went -into doing. +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 which all of one's strength went. Is there going to be a Windows port of Kakoune ? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -22,19 +25,23 @@ Moreover, you can get pretty decent performance by using Kakoune on Cygwin Can you get rid of the `boost` dependency and just use std::regex ? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The `boost-regex` library provides use with several features that are -heavily relied upon across several core scripts, and a few of them are -not available in the standard `std::regex` implementations. Therefore, -until the standard catches up with `boost` in terms of features, -the latter will remain a hard -mandatory- dependency. +The `boost-regex` library provides use with several features that are heavily +relied upon across several core scripts, and a few of them are not available +in the standard `std::regex` implementations. Therefore, until the standard +catches up with `boost` in terms of features, the latter will remain a hard +-mandatory- dependency. Kakoune is very slow on big files, what can I do about it ? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The default build mode (set in the `Makefile` of the `src` directory -of the project) is "debug", which makes it convenient to track issues -but also affects performance. To disable the debug mode, recompile the -project by setting the `debug` variable in `src/Makefile` to `no`. +The default build mode (set in the `Makefile` of the `src` directory of the +project) is "debug", which makes it convenient to track issues but also +affects performance. To disable the debug mode, recompile the project by +setting the `debug` variable in `src/Makefile` to `no`. + +Note that if your distribution provides a "kakoune" package, the program should +already be built in non-debug mode (if you still experience slowness, please +report the issue on the bug tracker). Can I use Kakoune as a pager ? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -50,9 +57,9 @@ try experimental community-developed ones. 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. +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. @@ -62,62 +69,63 @@ 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. +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. +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. +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. +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 -(c.f. the "map" command in the "commands" documentation page). +However, you can easily declare key mappings in your configuration file +to be able to use those control-based shortcuts in insert mode (c.f. the +"map" command in the "commands" documentation page). 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 fill -basic needs. +(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`). +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 except for `%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 an drawback when balanced against the low cost of -using an interpreter in a regular shell scope (e.g. `%sh{ python -c -"..." }`), which has a negligible impact on performance. +Supporting custom scopes would add hard dependencies to the project, which +is too much of an 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. 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'` +allows us to use the `disabled_hooks` variable to disable indentation +globally with the following command: `set global disabled_hooks '.+-indent'` -Can I disable syntax highligting completely ? +Can I disable syntax highlighting completely ? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Similarly to the indentation hooks, the named format followed by the highligting -hooks is `-highlight`. You can thus disable syntax highligting using -the following command: `set global disabled_hooks '.+-highlight'` +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'` From b0d8e1a23051598f41b186c55ea321ea271be570 Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Tue, 11 Oct 2016 14:40:20 +0300 Subject: [PATCH 4/5] Answer the pager question in the FAQ document --- doc/manpages/faq.asciidoc | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/doc/manpages/faq.asciidoc b/doc/manpages/faq.asciidoc index ca7f5b4a5..42c5980db 100644 --- a/doc/manpages/faq.asciidoc +++ b/doc/manpages/faq.asciidoc @@ -46,7 +46,12 @@ report the issue on the bug tracker). Can I use Kakoune as a pager ? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -. +Kakoune can be used as a pager, either by setting the `EDITOR` environment +variable to `kak`, or by writing data directly to its standard input using a +shell pipeline. However, since the program relies on several heavy dynamic +libraries (`boost` being one of them), it will be slightly less pratical +than other regular pagers (such as `less` or `more`) which have a minimal +amount of runtime dependencies. Are there any non-console based frontends available ? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 70fd03679b889227e9ef733e303102a5648be2b1 Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Wed, 12 Oct 2016 09:36:42 +0300 Subject: [PATCH 5/5] Add a warning about setting `$TERM` manually, fix some typos --- doc/manpages/faq.asciidoc | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/doc/manpages/faq.asciidoc b/doc/manpages/faq.asciidoc index 42c5980db..6bb4d2462 100644 --- a/doc/manpages/faq.asciidoc +++ b/doc/manpages/faq.asciidoc @@ -16,7 +16,7 @@ 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 performant on a Windows system, the incentive to porting the +much less efficient on a Windows system, the incentive to porting the project to this operating system is pretty low. Moreover, you can get pretty decent performance by using Kakoune on Cygwin @@ -49,7 +49,7 @@ Can I use Kakoune as a pager ? Kakoune can be used as a pager, either by setting the `EDITOR` environment variable to `kak`, or by writing data directly to its standard input using a shell pipeline. However, since the program relies on several heavy dynamic -libraries (`boost` being one of them), it will be slightly less pratical +libraries (`boost` being one of them), it will be slightly less practical than other regular pagers (such as `less` or `more`) which have a minimal amount of runtime dependencies. @@ -59,6 +59,19 @@ 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 ? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. + +Note that if you're using `tmux`, the proper -official- way to get Kakoune to +work is to add the following line to your `tmux` configuration file: +`set -sg default-terminal screen-256color` + How do I automatically indent code, as Vim does with `=` ? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~