Add a basic FAQ

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 <c-w> or <c-u> 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.