Move the user manual into the repository, extracted from the wiki.

docs/README.md

@@ -0,0 +1,6 @@
+# Project documents
+
+This document is the entry-point for all documents related to the project.
+
+- [A user manual](man), explaing how to use every parts of the project.
+- [A design section](design), explaining different part of the project.

docs/man/Grammar-workflow-updates.md

@@ -0,0 +1,25 @@
+If you do not want to get into the rabbit hole of writing your own grammars and queries, you will most likely want to
+reuse datasets from other projects, such as the GitHub repositories of the grammars themselves (for instance,
+[tree-sitter-rust] for Rust), [Neovim] or [Helix].
+
+Whatever you decide to use, you need to update the [config.toml](Configuration) file according to the languages,
+grammars and queries. **However**, as explained in the linked section, 99% of people will just be satisfied with the
+default settings shipped with `kak-tree-sitter`’s `config.toml`, which you can find at the root of the repository;
+[here](https://github.com/phaazon/kak-tree-sitter/blob/master/config.toml).
+
+This file is not included with the releases of `kak-tree-sitter` nor `ktsctl`, which means that you need to keep it in
+sync if you want to add support for new languages or fix grammars and queries you have already installed
+(`ktsctl -fci rust` should be enough to update the Rust runtime files after updating `config.toml`).
+
+# A note for release channels
+
+Release channels ([AUR], [brew], etc.) have the right to ship the `config.toml` file (or any of their liking) along with
+both binaries. It is highly recommended that they follow SemVer (if they bundle `kak-tree-sitter v0.4.3`, they should be
+named `kak-tree-sitter-0.4.3` for instance). However, adding an extra number for the bump of the `config.toml` could be
+a good idea (so `kak-tree-sitter-0.4.3-1`, `kak-tree-sitter-0.4.3-2`, etc.).
+
+[tree-sitter-rust]: https://github.com/tree-sitter/tree-sitter-rust/tree/master/queries
+[Neovim]: https://github.com/nvim-treesitter/nvim-treesitter/tree/master/queries
+[Helix]: https://github.com/helix-editor/helix/tree/master/runtime/queries
+[AUR]: https://aur.archlinux.org
+[brew]: https://brew.sh

docs/man/JSX.md

@@ -0,0 +1,51 @@
+JSX grammars and queries are a bit weird, as they are not part of a specific language (i.e. `kts_lang`), but can work
+with Javascript, Typescript, etc. For this reason, extra setup is required. This page explains how to setup your
+configuration.
+
+> Note: this grammar / query set is incompatible with `javascript`. If you plan on using both Javascript and JSX, you
+> should only install the `jsx` grammar, as it also can work with regular Javascript files. See below for the setup.
+
+* [Fetch the grammar and queries](#fetch-the-grammar-and-queries)
+* [Patch the grammar](#fetch-the-grammar)
+* [Compile and install](#compile-and-install)
+* [Useful hook](#useful-hook)
+
+# Fetch the grammar and queries
+
+```bash
+ktsctl -f jsx
+```
+
+# Patch the grammar
+
+This is the tricky part. You need to replace all `javascript` occurrences with `jsx`. Go in
+`$XDG_DATA_DIR/ktsctl/grammars/javascript` (or `$TMPDIR/ktsctl/grammars/javascript` on macOS if you do not have the XDG
+environment variables), and run this:
+
+```bash
+grep -rl 'javascript' . | xargs sed -i '' -e 's/javascript/jsx/g'
+```
+
+# Compile and install
+
+Simply compile and install normally as you would do with `ktsctl`:
+
+```bash
+ktsctl -ci jsx
+```
+
+# Useful hook
+
+If you still want to work with regular Javascript files, then you need to tell Kakoune to interpret them as if they were
+using the JSX grammars. You can do it with a simple hook translating `kts_lang=javascript` to `kts_lang=jsx`, such as:
+
+```bash
+hook global BufSetOption kts_lang=(javascript|typescript) %{
+  eval %sh{
+    case $kak_bufname in
+      (*\.jsx) echo "set-option buffer kts_lang jsx";;
+      (*\.tsx) echo "set-option buffer kts_lang tsx";;
+    esac
+  }
+}
+```

docs/man/README.md

@@ -0,0 +1,14 @@
+# User manual
+
+This is the official user manual. You may want to visit the following links to know more.
+
+- [Getting started](getting-started.md)
+- [How to install](how-to-install.md)
+- [Usage](usage.md)
+- [Configuration](configuration.md)
+- [ktsctl](ktsctl.md)
+- [Features](features.md)
+  - [Highlighting](highlighting.md)
+  - [Text-objects](text-objects.md)
+- [Tweaking](tweaking.md)
+- [Frequently Asked Questions](faq.md)

docs/man/commands.md

@@ -0,0 +1,29 @@
+# Commands
+
+Commands are separated into three categories:
+
+- [Controlling kak-tree-sittter](#controlling-kak-tree-sitter)
+- [Highlighting](#highlighting)
+- [Text-objects](#text-objects)
+
+## Controlling kak-tree-sitter
+
+| Command                             | Description                                                                                                          |
+| -------                             | -----------                                                                                                          |
+| `kak-tree-sitter-req-enable`        | Send a request to enable integration with `kak-tree-sitter`.                                                         |
+| `kak-tree-sitter-req-stop`          | Send a request to make `kak-tree-sitter` quit.                                                                       |
+| `kak-tree-sitter-req-reload`        | Send a request to make `kak-tree-sitter` reload its configuration, grammars and queries.                             |
+| `kak-tree-sitter-set-lang` (hidden) | Hidden function used to set `%opt{kts_lang}`. See [Kakoune interaction](Kakoune-interaction) for further information |
+
+## Highlighting
+
+| Command                            | Description                                     |
+| -------                            | -----------                                     |
+| `kak-tree-sitter-highlight-buffer` | Force a highlight request on the current buffer |
+
+## Text-objects
+
+| Command                                                 | Description                                                                                                                  |
+| -------                                                 | -----------                                                                                                                  |
+| `kak-tree-sitter-req-text-objects <text-object> <mode>` | Alter every selections by matching `<text-object>` according to `<mode>`. See [the text-objects section](./Text-objects.md). |
+| `kak-tree-sitter-req-object-text-objects <text-object>` | Alter every selections by matching `<text-object>` in _object_ mode. See [the text-objects section](./Text-objects.md).      |

docs/man/configuration.md

@@ -0,0 +1,65 @@
+# Configuration
+
+Both `kak-tree-sitter` and `ktsctl` ship with a default configuration. It is possible to override the default
+configuration via the user configuration.
+
+The `$XDG_CONFIG_HOME/kak-tree-sitter/config.toml` contains the user configuration of both `kak-tree-sitter` and
+`ktsctl`, which is shared. If you want to tweak something, you can have a look at the
+[default configuration file](https://github.com/phaazon/kak-tree-sitter/blob/master/default-config.toml) to know which
+path and values to pick from.
+
+> The user and default configurations get merged, so you do not have to copy the default configuration to tweak it.
+
+# Option paths
+
+## `highlight.groups`
+
+The `highlight` section currently contains a single list, `groups`, which is used to list every capture groups used by
+language queries. If you install a language with queries containing new capture groups not already listed there, you
+need to add them at the end of the list.
+
+> Please consider contributing if you find a hole / missing capture group.
+
+## `language`
+
+The `language` table contains language-keyed configuration — e.g. `language.rust`. Every language-keyed configuration
+contains more objects.
+
+- `remove_default_highlighter`, for removing the default highlighter set by the Kakoune distribution when enabling
+  kak-tree-sitter support in a buffer.
+- `grammar`, for defining a grammar.
+- `queries`, for defining the language queries.
+
+### `language.<lang>.remove_default_higlighter`
+
+> Default value: `true`
+ 
+Remove the default highlighter set by the Kakoune “standard library” (i.e. `window/<lang>`). For instance, for `rust`
+filetypes, the default highlighter is `window/rust`. Setting this option to `true` will remove this highlighter, which
+is almost always wanted (otherwise, the highlighting from KTS might not be applied properly).
+
+Some languages might have an incomplete tree-sitter support; in such a case, you might not want to remove the default
+highlighter. Set this option to `false` in such cases, then.
+
+### `language.<lang>.grammar`
+
+This section contains various information about how to fetch, compile and link a grammar:
+
+- `url`: the URL to fetch from. Will use `git clone`.
+- `pin`: _pin ref_, such as a commit, branch name or tag. **Highly recommended** to prevent breakage.
+- `path`: path where to find the various source files. Should always be `src` but can require adjustments for
+  monorepositories.
+- `compile`: compile command to use. Should always be `cc`.
+- `compile_args`: arguments to pass to `compile` to compile the grammar.
+- `compile_flags`: optimization / debug flags.
+- `link`: link command to use. Should alwas be `cc`.
+- `link_args`: arguments to pass to `link` to link the grammar.
+- `link_flags`: optimization / debug / additional libraries to link flags.
+
+### `language.<lang>.queries`
+
+This section provides the required data to know how to fetch queries.
+
+- `url`: the URL to fetch from. Will use `git clone`.
+- `pin`: _pin ref_, such as a commit, branch name or tag. **Highly recommended** to prevent breakage.
+- `path`: path where to find the queries (the `.scm` files) directory.

docs/man/faq.md

@@ -0,0 +1,18 @@
+# Frequently Asked Questions
+
+## I don’t want to deal with options; give me a oneliner to install a language
+
+```sh
+ktsctl -fci yaml
+```
+
+## How do I install all the languages at once?
+
+This is currently, unfortunately, not supported. You will have to run `ktsctl -fci` for all the languages you want.
+See [#30](https://github.com/phaazon/kak-tree-sitter/issues/30).
+
+## Something broke and there is no highlighting anymore
+
+You can have a look at the log files in `$XDG_RUNTIME_DIR/kak-tree-sitter/{stdout.txt,stderr.txt}` and open an issue.
+If the server crashed, you can simply restart a server; it will automatically recollect all the live Kakoune sessions
+and should work again.

docs/man/features.md

@@ -0,0 +1,11 @@
+# Features
+
+This document presents features planned by the project and their status.
+
+| Feature           | Description                                                                                | Status          | Available since | CLI flag to enable                                      |
+| ---               | ---                                                                                        | ---             | ---             | ---                                                     |
+| Highlighting      | Asynchronous automatic highlighting of session buffers.                                    | **Implemented** | `v0.2`          | `--with-highlighting`                                   |
+| Text-objects      | Modify Kakoune selections with text-objects (`function.inside`, `parameter.around`, etc.). | **Implemented** | `v0.6`          | Default, and `--with-text-objects` for additional setup |
+| Indents           | Automatically indent your buffer.                                                          | Not started     |                 | `--with-indenting`                                      |
+| Indent guidelines | Display a guideline showing the level of indentation left to lines.                        | Not started     |                 | `--with-indent-guidelines`                              |
+

docs/man/getting-started.md

@@ -0,0 +1,70 @@
+# Getting started
+
+Welcome! If you are reading this page, it is likely it is the first time you hear about this project. First and
+foremost, thank you for considering using this project. This section will provide you with a bunch of explanations about
+how the project is made, how it works, what you should expect and what you should not.
+
+## Prerequisites
+
+As the name implies, this is project that bridges [tree-sitter] and [Kakoune]. You do not have to know anything about
+the former, but obviously, you need to have [Kakoune] installed. The rest is handled by this project.
+
+## What is this?
+
+This project bridges [tree-sitter] and [Kakoune] via a server, that can be run on the CLI or inside [Kakoune] as a
+daemon. The server is unique to your machine, so it doesn’t matter that you start it from several Kakoune sessions, only
+one server will be up (this is implemented via a _PID file_). When the server is up, it remains up until the last
+session exits (if started from within Kakoune), or when you send it the `SIGINT` signal (_Ctrl-C_) if started on the
+CLI.
+
+When the server is started from Kakoune, it will install some commands and hooks to be able to communicate with the
+server. The configuration allows to decide which commands, hooks, user-modes etc. you want to have installed.
+
+A running server will wait for a session to communicate with it requests, and will reply asynchronously. That prevents
+your editor from freezing and allows the server to maintain a state / view of your per-session buffers. Because it uses
+[tree-sitter] under the hood, it will parse the content of your buffers as _trees_, allowing for fast operations.
+
+> Several features are supported / will be supported. You can refer to the [Features](features.md) document to know more
+> about what you can do with the [tree-sitter] integration.
+
+In order to work, the server requires some runtime resources to be around. This project doesn’t ship with those
+resources, and you are free to use whichever sources you want. Two main kind of resources are needed:
+
+- _Grammars_, which are C dynamic libraries loaded at runtime by the server and used to parse your buffer and operate on
+  trees.
+- _Queries_, which are [scm] strings allowing to _query_ parsed trees with a Lisp-like syntax. We use those to, mostly,
+  unify the type of queries to all languages/grammars, such as highlighting, text-objects, indents, etc.
+
+You can either find those resources yourself, or use the provided controller companion of the server that provides that
+for free for you. See the [ktsctl](ktsctl.md) document.
+
+## What you should expect
+
+The project was made in a way that supports most of the features that are natively available in other editors regarding
+[tree-sitter], such as [Helix]. It tries to be frustration-free, shipping with a default sane configuration; you should
+and will probably never modify the configuration, but if you need to, you can. The server and the [Kakoune] side of the
+project is made in a way that puts performance at top priority. Because we are using a UNIX approach, we try to minimize
+as much as possible process starts, memory writes, etc., approaching as much as possible memory-to-memory communication.
+Finally, the controller should do everything for you, provided you instruct what you want. You are you not required to
+know _anything_ about [tree-sitter], nor how a query works or even how to compile a grammar. We do that for you. Just
+focus on what’s important; your own projects.
+
+## What you should not expect
+
+The server is mostly about _transformations_. It doesn’t ship with _data_. Hence, you will not get grammars and queries
+shipped with the binary by default. It is important that you understand that; it works out of the box, but you still
+need to tell it what you want at first.
+
+Colorschemes support is hard. Using this project won’t automatically make your colorscheme look super nice. You will
+have to adapt and use a new, [tree-sitter]-powered colorscheme. The community tries its best to provide more and more
+colorschemes. You shall want to visit the [Colorscheme](colorscheme.md) document for further information.
+
+## What’s the next thing to read?
+
+Now that you are aware about what the project is, what it is not, and the prerequisites, you may want to go to
+[How to install](how-to-install.md).
+
+[tree-sitter]: https://tree-sitter.github.io/tree-sitter/
+[Kakoune]: https://kakoune.org/
+[scm]: https://en.wikipedia.org/wiki/SCM_(Scheme_implementation)
+[Helix]: https://helix-editor.com