Improved documentation.

Extended the plugin description and the examples.
Created a docs folder with the files faq.md, integration.md and recipes.md.

1 files changed, 77 insertions, 0 deletions

diff --git a/docs/user-extra-documentation.md b/docs/user-extra-documentation.md
new file mode 100644
index 0000000..9348726
--- /dev/null
+++ b/docs/user-extra-documentation.md
@@ -0,0 +1,77 @@
+# Extra documentation for users
+
+## FAQ
+
+### What’s the difference between `>` and `$`?
+
+`>` or `connect-terminal` runs its argument
+(which by default is your shell)
+inside a terminal,
+while `$` or `connect-shell` simply runs its argument.
+
+Some programs must be run inside a terminal,
+while others spawn their own graphical window.
+Use `>` for the first type and `$` for the second.
+
+### What’s the purpose of `&` or `connect-detach`?
+
+`connect-detach` detaches (closes) the current client
+(leaving you in a terminal if you launched Kakoune there) and
+creates a file named `connect.sh` which you can run with `sh connect.sh`
+to start a shell connected to that client’s server.
+The file is automatically erased when it’s sourced.
+
+**Note 1**: The Kakoune server is deleted if you detach the last client and
+you didn’t start it in daemon mode.
+
+**Note 2**: The implementation uses Kakoune’s `quit!` command instead of `quit`.
+
+### What is `kak-shell`?
+
+`kak-shell` is inspired by [nix-shell].
+
+It lets you run a program (by default your shell) connected to a session.
+Initially, it displays the list of active sessions and asks you to choose one.
+
+```
+$ kak-shell
+Kakoune sessions:
+1 kanto
+2 johto
++ create new session
+Kakoune session: 1█
+@kanto $ :a█
+```
+
+If you enter a number _i_, it will try to connect to the _i_-th entry.
+Otherwise, it will interpret the entry as a session name and connect to it.
+If the session is not running, it will start it in daemon mode.
+
+Apart from running a connected shell, you can use `kak-shell` to run
+commands in the context of the session.
+For example, you could run `kak-shell tig` to run [tig] connected to an arbitrary session.
+
+[tig]: https://github.com/jonas/tig
+[nix-shell]: https://nixos.org/nix/manual#sec-nix-shell
+
+---
+
+## Conventions and design decisions
+
+### What’s the difference between [commands] and [modules]?
+
+The term module is used for small program integrations for Kakoune
+(which are implemented as Kakoune’s modules).
+The term command is used for small binaries that can be used by a connected application.
+
+[commands]: ../rc/connect/commands
+[modules]:  ../rc/modules
+
+### Why do all [commands] start with a colon (`:`)?
+
+The colon is the key used to access the prompt menu inside Kakoune.
+Because the commands usually resemble Kakoune commands,
+prepending them with a colon is a good way to reuse our muscle memory,
+and it makes it very simple to differentiate them from traditional commands
+(think of `pwd` versus `:pwd`).
+