Fix a few mistakes, allow a2x to compile the page

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
+The name of the project is pronounced "Kak-oon", and is a word taken from a
-a New Caledonia dialect based on french. It means a hard blow, usually a
+New Caledonian dialect based on french. It means a hard blow, usually a punch,
-punch, but generally refers to a blow in which all of one's strength went
+but generally refers to a blow into which which all of one's strength went.
-into doing.
 
 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
+The `boost-regex` library provides use with several features that are heavily
-heavily relied upon across several core scripts, and a few of them are
+relied upon across several core scripts, and a few of them are not available
-not available in the standard `std::regex` implementations. Therefore,
+in the standard `std::regex` implementations. Therefore, until the standard
-until the standard catches up with `boost` in terms of features,
+catches up with `boost` in terms of features, the latter will remain a hard
-the latter will remain a hard -mandatory- dependency.
+-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
+The default build mode (set in the `Makefile` of the `src` directory of the
-of the project) is "debug", which makes it convenient to track issues
+project) is "debug", which makes it convenient to track issues but also
-but also affects performance. To disable the debug mode, recompile the
+affects performance. To disable the debug mode, recompile the project by
-project by setting the `debug` variable in `src/Makefile` to `no`.
+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
+As `Kakoune` doesn't parse the contents of the buffers, there is no builtin
-builtin equivalent for this Vim feature. Use a formatter/prettifier
+equivalent for this Vim feature. Use a formatter/prettifier dedicated to
-dedicated to the language you're using with the help of the `|` key.
+the language you're using with the help of the `|` key.
 
 Example: `%|indent<ret>` 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
+As mentioned in the above question about Vim's `=` key, Kakoune does not
-does not parse the contents of a buffer by itself, which makes it
+parse the contents of a buffer by itself, which makes it impossible for
-impossible for the editor to propose candidates upon completion.
+the editor to propose candidates upon completion.
 
-However, support for such a feature can be achieved through the
+However, support for such a feature can be achieved through the use of a
-use of a dedicated tool, as is the case with `clang` and C code:
+dedicated tool, as is the case with `clang` and C code: you can use the
-you can use the `clang-enable-autocomplete` and `clang-complete`
+`clang-enable-autocomplete` and `clang-complete` builtin commands whenever
-builtin commands whenever editing a C/C++ file, and completion will
+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
+Note that the same features are available for python buffers, with the
-the `jedi` script.
+`jedi` script.
 
 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
+Despite their widespread availability in multiple tools, those shortcuts do
-shortcuts do not fit the paradigm that Kakoune implements, which is
+not fit the paradigm that Kakoune implements, which is based on selections
-based on selections first.
+first.
 
-However, you can easily declare key mappings in your configuration
+However, you can easily declare key mappings in your configuration file
-file to be able to use those control-based shortcuts in insert mode
+to be able to use those control-based shortcuts in insert mode (c.f. the
-(c.f. the "map" command in the "commands" documentation page).
+"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
+(using the `:edit` command and letting the suggestions popup in the menu
-menu beneath) is much more convenient than Vim's, which should fill
+beneath) is much more convenient than Vim's, which should suit basic needs.
-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
+which should in return send an "edit" command followed by the path of the
-of the file you selected to the current Kakoune session (e.g. `echo
+file you selected to the current Kakoune session (e.g. `echo "eval -client
-eval -client $kak_client edit /path/to/file | kak -p $kak_session`).
+$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,
+Supporting custom scopes would add hard dependencies to the project, which
-which is too much of an drawback when balanced against the low cost of
+is too much of an drawback when balanced against the low cost of using
-using an interpreter in a regular shell scope (e.g. `%sh{ python -c
+an interpreter in a regular shell scope (e.g. `%sh{ python -c "..." }`).
-"..." }`), which has a negligible impact on performance.
+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 `<lang>-indent`, which
-allows us to use the `disabled_hooks` variable to disable indentation globally
+allows us to use the `disabled_hooks` variable to disable indentation
-with the following command: `set global disabled_hooks '.+-indent'`
+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
+Similarly to the indentation hooks, the name format followed by the
-hooks is `<lang>-highlight`. You can thus disable syntax highligting using
+highlighting hooks is `<lang>-highlight`. You can thus disable syntax
-the following command: `set global disabled_hooks '.+-highlight'`
+highlighting using the following command: `set global disabled_hooks
+'.+-highlight'`