Improved documentation.

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

4 files changed, 264 insertions, 74 deletions

diff --git a/README.md b/README.md
index 28ddc3c..e7a2a0d 100644
--- a/README.md
+++ b/README.md
@@ -7,6 +7,19 @@ Leverage the client-server architecture of [Kakoune] to connect programs to clie
 [![connect.kak](https://img.youtube.com/vi_webp/jca2N-cE_mM/maxresdefault.webp)](https://youtube.com/playlist?list=PLdr-HcjEDx_k-Y_9uSV0YAUCNHzqHjmz3 "YouTube – connect.kak")
 [![YouTube Play Button](https://www.iconfinder.com/icons/317714/download/png/16)](https://youtube.com/playlist?list=PLdr-HcjEDx_k-Y_9uSV0YAUCNHzqHjmz3) · [connect.kak](https://youtube.com/playlist?list=PLdr-HcjEDx_k-Y_9uSV0YAUCNHzqHjmz3)
 
+The objective of connect.kak is
+to synchronize external applications with Kakoune clients easily.
+A typical use case is opening a file browser and
+having it open the files in the Kakoune client.
+Another very typical use case is connecting a terminal.
+
+connect.kak provides basic [commands] to interact with the connected client interactively
+or to write your own scripts
+(check [`:batch`], which is an integration crafted from the rest of the commands)
+as well as a set of officially supported [modules] (Kakoune commands to programs).
+
+[`:batch`]: https://github.com/alexherbo2/batch.kak/blob/master/rc/connect/commands/:batch
+
 ## Dependencies
 
 - [prelude.kak]
@@ -33,24 +46,24 @@ Run the following in your terminal:
 make install
 ```
 
-Add [`rc`](rc) to your autoload or source [`connect.kak`](rc/connect.kak) and its [modules](rc/modules) manually.
+Add [`rc`](rc) to your autoload or source [`connect.kak`](rc/connect.kak) and its [modules] manually.
 
-## Usage
+## Usage examples
 
 **>**, **$** and **&** are [Kakoune commands][Documentation].
 
-The **:** prefixes all [connect.kak shell commands][Commands],
-and usually have an [alias][Aliases] on a single key – `:[e]dit` and `:[o]pen` for example.
+The colon (**:**) prefixes all [connect.kak shell commands][Commands],
+which usually have an [alias][Aliases] of a single key – `:[e]dit` and `:[o]pen` for example.
 
 ### Example 1
 
-**Kakoune** – Open a new terminal:
+**Kakoune** – Launch a new connected terminal:
 
 ``` kak
 >
 ```
 
-**Terminal** – Open all `.txt` files:
+**Terminal** – Open all `.txt` files in the connected client:
 
 ``` sh
 :e *.txt
@@ -58,7 +71,7 @@ and usually have an [alias][Aliases] on a single key – `:[e]dit` and `:[o]pen`
 
 ### Example 2
 
-**Terminal** – Same in a new client:
+**Terminal** – Open all `.txt` files in a new client:
 
 ``` sh
 :o *.txt
@@ -66,7 +79,7 @@ and usually have an [alias][Aliases] on a single key – `:[e]dit` and `:[o]pen`
 
 ### Example 3
 
-**Kakoune** – Open [Dolphin]:
+**Kakoune** – Launch a connected [Dolphin] instance:
 
 ``` kak
 $ dolphin
@@ -76,7 +89,9 @@ $ dolphin
 
 ### Example 4
 
-**Kakoune** – Same with [modules]:
+**Kakoune** – Use [Dolphin’s module] to do the same as example 3:
+
+[dolphin’s module]: rc/modules/dolphin.kak
 
 ``` kak
 require-module connect-dolphin
@@ -86,7 +101,17 @@ dolphin
 
 ### Example 5
 
-**Terminal** – Manage sessions:
+**Terminal** – Render with [Glow] the current buffer:
+
+``` sh
+glow `:it`
+```
+
+[Glow]: https://github.com/charmbracelet/glow
+
+### Example 6
+
+**Terminal** – Run a shell connected to an arbitrary session from your terminal:
 
 ``` sh
 kak-shell
@@ -104,22 +129,28 @@ Kakoune session: 1█
 @kanto $ :a█
 ```
 
-## Example 6
+### Example 7
 
-**Terminal** – [Glow] the current buffer:
+**Kakoune** – Detach from the client and generate a file to connect to the session.
 
-``` sh
-glow `:it`
+``` kak
+&
 ```
 
-[Glow]: https://github.com/charmbracelet/glow
-
----
+**In the terminal that spawned the client**
 
-Learn more about the [commands] and [aliases] in the [documentation].
+```
+$ sh connect.sh
+@kanto $ █
+```
 
 ## Configuration
 
+## Example configuration
+
+A typical workflow is mapping `<c-q>` to `quit!` and use the alias `:a`/`a` to
+reattach back and forth inside a `kak-shell` (or any connected terminal).
+
 ``` kak
 # Modules
 require-module connect-fzf
@@ -142,46 +173,17 @@ map global normal <c-q> ': quit!<ret>'
 map global normal Y ': yank-ring<ret>'
 ```
 
-### Turn Kakoune into an IDE
+### Custom connect commands
 
-``` kak
-define-command ide -params 0..1 -docstring 'ide [session-name]: Turn Kakoune into an IDE' %{
-  # Session name
-  try %{
-    rename-session %arg{1}
-  }
-
-  # Main client
-  rename-client main
-  set-option global jumpclient main
-
-  # Tools client
-  new %{
-    rename-client tools
-    set-option global toolsclient tools
-  }
-
-  # Docs client
-  new %{
-    rename-client docs
-    set-option global docsclient docs
-  }
-
-  # Project drawer
-  dolphin
-
-  # Git
-  > lazygit
-
-  # Terminal
-  >
-}
-```
+You can also define your own connect [commands] and [aliases] and
+locate them in a path set in the `connect_paths` option.
+By default, it is set to your
+`$XDG_CONFIG_HOME/kak/connect/commands` and `$XDG_CONFIG_HOME/kak/connect/aliases` folders.
 
 ### Custom environment
 
 By setting the `connect_environment` option, you can specify commands that
-are run before the shell is executed.  This might be useful, if you want to
+are evaluated before launching/running the programs.  This might be useful if you want to
 change or export environment variables.
 
 ``` kak
@@ -191,32 +193,17 @@ set-option global connect_environment %{
 }
 ```
 
-### Custom connect commands
-
-You can also define your own connect commands by setting the `connect_paths` option.
-By default, it is set to your `$XDG_CONFIG_HOME/kak/connect/commands` and `$XDG_CONFIG_HOME/kak/connect/aliases`.
-See [commands] and [aliases] for examples.
-
-### Change directory
-
-In complement to `:cd!` which syncs the client to your current working directory,
-you can do the opposite.
-
-Add to your bashrc:
-
-``` bash
-if [ "$IN_KAKOUNE_CONNECT" = 1 ]; then
-  alias :cd='cd `:pwd`'
-  alias :cd?='cd `:bwd`'
-fi
-```
-
 ### Custom prompt
 
+You can modify your shell [prompt][Prompt customization]
+to notify you whenever you are connected to a session.
+
 ``` bash
 PS1='$(~/.local/share/kak/connect/prompt) $ '
 ```
 
+[Prompt customization]: https://wiki.archlinux.org/index.php/Bash/Prompt_customization
+
 ## Documentation
 
 [Documentation]: #documentation
@@ -230,7 +217,13 @@ PS1='$(~/.local/share/kak/connect/prompt) $ '
 - [Commands]
 - [Aliases]
 - [Modules]
-
+- [Extra documentation for users][user-extra-documentation]
+- [Recipes]
+- [Integration with other tools][integration]
+ 
 [Commands]: rc/connect/commands
 [Aliases]: rc/connect/aliases
 [Modules]: rc/modules
+[user-extra-documentation]: docs/user-extra-documentation.md
+[recipes]: docs/recipes.md
+[integration]: docs/integration.md
diff --git a/docs/integration.md b/docs/integration.md
new file mode 100644
index 0000000..bd95413
--- /dev/null
+++ b/docs/integration.md
@@ -0,0 +1,44 @@
+# Integration with other apps
+
+connect.kak is also framework for developing your own plugins.
+
+## Plugins that use or can work with connect.kak
+
+- [yank-ring.kak]
+- [batch.kak]
+
+[yank-ring.kak]: https://github.com/alexherbo2/yank-ring.kak
+[batch.kak]: https://github.com/alexherbo2/batch.kak
+
+## Interacting with Kakoune
+
+Integration with other applications usually comes from writing a small program
+(typically a shell script).
+Plugin’s can add folders to the `connect_paths` option to add their utilities,
+and the same programs can be called inside Kakoune
+using the commands `>` or `$` ([Example][yank-ring.kak]).
+Though it's common for plugin’s authors to provide wrappers inside a module.
+
+The basic [commands] for plugin crafting are:
+
+- [`:get`]: Gets the result of a Kakoune’s `echo` command from the client.
+- [`:send`]: Sends commands to the client.
+
+---
+
+- [`:it`]: Prints the current buffer.
+- [`:ls`] and [`:buffer`]: Show the list of buffers or change buffers.
+- [`:attach`]: Starts a client connected to the session.
+- [`:edit`] and [`:edit-wait`]: Open files in the client.
+`:edit-wait` does the same but waits for user confirmation
+(useful for applications that check the return value of the editor, like git).
+
+[commands]:   ../rc/connect/commands/
+[`:attach`]: ../rc/connect/commands/:attach
+[`:buffer`]: ../rc/connect/commands/:buffer
+[`:edit`]: ../rc/connect/commands/:edit
+[`:edit-wait`]: ../rc/connect/commands/:edit-wait
+[`:get`]: ../rc/connect/commands/:get
+[`:it`]: ../rc/connect/commands/:it
+[`:ls`]: ../rc/connect/commands/:ls
+[`:send`]: ../rc/connect/commands/:send
diff --git a/docs/recipes.md b/docs/recipes.md
new file mode 100644
index 0000000..3b29a8d
--- /dev/null
+++ b/docs/recipes.md
@@ -0,0 +1,76 @@
+# Recipes
+
+## Appending Kakoune’s shell prompt to the usual prompt
+
+If you are using `bash`, you can add the following lines to your `.bashrc`.
+
+``` sh
+if [ -e ~/.local/share/kak/connect/prompt ]; then
+    PS1="\$(~/.local/share/kak/connect/prompt)$PS1"
+fi
+```
+
+## Working with headless sessions with `kak-shell`
+
+`kak-shell :attach` lets your run a client connected to a session,
+just like `kak -c <session id>`.
+But with `kak-shell :attach` you have a list of all the active sessions
+and you can also create a new named session which starts in headless mode,
+which is very useful for detaching and reattaching continually.
+
+Therefore, `kak-shell :attach` replaces `kak -c <session id>` and `kak -d -s <session id>`
+and can serve to spawn a client in whatever situation you are.
+
+**Tip**: You can alias `kak-shell` to something like `ks`,
+and you’d only need to type `ks :a`.
+
+## Turn Kakoune into an IDE
+
+``` kak
+define-command ide -params 0..1 -docstring 'ide [session-name]: Turn Kakoune into an IDE' %{
+  # Session name
+  try %{
+    rename-session %arg{1}
+  }
+
+  # Main client
+  rename-client main
+  set-option global jumpclient main
+
+  # Tools client
+  new %{
+    rename-client tools
+    set-option global toolsclient tools
+  }
+
+  # Docs client
+  new %{
+    rename-client docs
+    set-option global docsclient docs
+  }
+
+  # Project drawer
+  dolphin
+
+  # Git
+  > lazygit
+
+  # Terminal
+  >
+}
+```
+
+### Change directory
+
+In complement to `:cd!` which syncs the client to your current working directory,
+you can do the opposite.
+
+Add to your `.bashrc`:
+
+``` bash
+if [ "$IN_KAKOUNE_CONNECT" = 1 ]; then
+  alias :cd='cd `:pwd`'
+  alias :cd?='cd `:bwd`'
+fi
+```
+
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`).
+