Update documentation

8 files changed, 177 insertions, 155 deletions

diff --git a/README.md b/README.md
index e7a2a0d..2418930 100644
--- a/README.md
+++ b/README.md
@@ -7,14 +7,11 @@ 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.
+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
+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).
 
@@ -46,14 +43,14 @@ Run the following in your terminal:
 make install
 ```
 
-Add [`rc`](rc) to your autoload or source [`connect.kak`](rc/connect.kak) and its [modules] manually.
+Add [`rc`](rc) to your autoload or source [`connect.kak`](rc/connect.kak) and its [modules](rc/modules) manually.
 
-## Usage examples
+## Usage
 
 **>**, **$** and **&** are [Kakoune commands][Documentation].
 
-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.
+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.
 
 ### Example 1
 
@@ -89,9 +86,7 @@ $ dolphin
 
 ### Example 4
 
-**Kakoune** – Use [Dolphin’s module] to do the same as example 3:
-
-[dolphin’s module]: rc/modules/dolphin.kak
+**Kakoune** – Same, but with a dedicated [`dolphin`][`dolphin.kak`] command:
 
 ``` kak
 require-module connect-dolphin
@@ -99,7 +94,12 @@ require-module connect-dolphin
 dolphin
 ```
 
-### Example 5
+[`dolphin.kak`]: rc/modules/dolphin.kak
+
+As you can notice by its [content][`dolphin.kak`], the module is fairly simple and seamless.
+We just provide the nicety to have a `dolphin` command from Kakoune.
+
+## Example 5
 
 **Terminal** – Render with [Glow] the current buffer:
 
@@ -131,25 +131,30 @@ Kakoune session: 1█
 
 ### Example 7
 
-**Kakoune** – Detach from the client and generate a file to connect to the session.
+**Kakoune** – Detach from the client and generate a file to connect to the session:
 
 ``` kak
 &
 ```
 
-**In the terminal that spawned the client**
+In the terminal that spawned the client:
 
 ```
 $ sh connect.sh
 @kanto $ █
 ```
 
+---
+
+Learn more about the [commands] and [aliases] in the [documentation].
+
 ## Configuration
 
-## Example configuration
+A typical workflow is mapping <kbd>Control</kbd> + <kbd>q</kbd> to `quit!` and
+use the alias `:a` or `a` to reattach back and forth inside a `kak-shell`
+(or any connected terminal).
 
-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).
+### Example configuration
 
 ``` kak
 # Modules
@@ -175,16 +180,13 @@ map global normal Y ': yank-ring<ret>'
 
 ### Custom connect commands
 
-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.
+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 `%val{config}/connect/commands` and `%val{config}/connect/aliases` folders.
 
 ### Custom environment
 
-By setting the `connect_environment` option, you can specify commands that
-are evaluated before launching/running the programs.  This might be useful if you want to
-change or export environment variables.
+By setting the `connect_environment` option, you can specify shell commands to run before running your program.
+This might be useful, if you want to change or export environment variables.
 
 ``` kak
 set-option global connect_environment %{
@@ -195,14 +197,19 @@ set-option global connect_environment %{
 
 ### Custom prompt
 
-You can modify your shell [prompt][Prompt customization]
-to notify you whenever you are connected to a session.
+You can modify your shell [prompt][Prompt customization] to notify you whenever you are connected to a session.
+
+[Prompt customization]: https://wiki.archlinux.org/index.php/Bash/Prompt_customization
+
+**Example** – for Bash:
 
 ``` bash
-PS1='$(~/.local/share/kak/connect/prompt) $ '
+PS1="\$(~/.local/share/kak/connect/prompt)$PS1"
 ```
 
-[Prompt customization]: https://wiki.archlinux.org/index.php/Bash/Prompt_customization
+See [`share/kak/connect/prompt`].
+
+[`share/kak/connect/prompt`]: share/kak/connect/prompt
 
 ## Documentation
 
@@ -217,13 +224,17 @@ 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
+
+<!---->
+
+- [FAQ]
+- [Recipes]
+- [Integration with other tools]
+
+[FAQ]: docs/faq.md
+[Recipes]: docs/recipes.md
+[Integration with other tools]: docs/integration.md
diff --git a/docs/faq.md b/docs/faq.md
new file mode 100644
index 0000000..3892d27
--- /dev/null
+++ b/docs/faq.md
@@ -0,0 +1,70 @@
+# FAQ
+
+## What is the difference between _>_ and _$_?
+
+The `>` or `connect-terminal` command runs its arguments (by default your shell) inside a connected terminal,
+while `$` or `connect-shell` simply runs its arguments in a connected environment.
+
+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 is the purpose of _&_?
+
+The `&` or `connect-detach` command detaches (closes) the current client
+(leaving you in a terminal if you launched Kakoune there) and
+creates a file named `connect.sh` that you can execute with `sh`
+to start a shell connected to that client’s server.
+
+**Notes**
+
+- The file is automatically erased after being sourced.
+- The Kakoune server is deleted if you detach the last client and you didn’t start it in daemon mode.
+- The implementation uses the `quit!` command.
+
+### What is _kak-shell_?
+
+`kak-shell` is a program to start an interactive shell (or a program) connected to a session, in the same way [nix-shell] does.
+
+[nix-shell]: https://nixos.org/nix/manual#sec-nix-shell
+
+Initially, it displays the list of active sessions and asks you to choose one.
+
+**Illustration**
+
+```
+$ 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 does not exists, the session will be started 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 can run `kak-shell lazygit` to run [lazygit] connected to an arbitrary session.
+
+[lazygit]: https://github.com/jesseduffield/lazygit
+
+## What is the difference between commands and modules?
+
+The term [module][Modules] is used for small program integrations for Kakoune
+(which are implemented as Kakoune’s modules).
+
+The term [command][Commands] is used for small binaries that can be used by a connected application.
+
+[Commands]: ../rc/connect/commands
+[Modules]: ../rc/modules
+
+## Why do all connect commands start with _:_?
+
+The **:** is the key used to access the prompt menu inside Kakoune.
+Because the commands usually resemble Kakoune commands,
+prepending them with **:** is a good way to reuse our muscle memory,
+and it makes it very simple to differentiate them from traditional commands
+(think of `pwd` vs. `:pwd`).
diff --git a/docs/integration.md b/docs/integration.md
index bd95413..64e18c5 100644
--- a/docs/integration.md
+++ b/docs/integration.md
@@ -1,6 +1,6 @@
-# Integration with other apps
+# Integration with other tools
 
-connect.kak is also framework for developing your own plugins.
+connect.kak is also a framework for developing your own plugins.
 
 ## Plugins that use or can work with connect.kak
 
@@ -12,33 +12,38 @@ connect.kak is also framework for developing your own plugins.
 
 ## 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.
+Integration with other applications usually comes from writing a small program,
+typically a shell script, and prefixed with **:** (e.g. `:dolphin`) by convention.
+Plugins can register their paths to the `connect_paths` option to add their utilities,
+and the same programs can be called inside Kakoune using the `>` or `$` commands (e.g. `> :yank-ring`).
+Usually, plugin authors also provide a Kakoune command for them (e.g. `yank-ring`).
 
 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.
+[Commands]: ../rc/connect/commands
 
----
+- [`:send`]: Send commands to the client.
+- [`:attach`]: Reattach to the session.
+- [`:get`]: Get a value from a client.  Example: `:get -quoting shell %val{selections}`.
 
-- [`: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/
+[`:send`]: ../rc/connect/commands/:send
 [`: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
+
+<!---->
+
+- [`:edit`]: Open files.
+- [`:buffer`]: Open buffer.
+- [`:fifo`]: Send to fifo buffer the output of the given command, or read from **stdin** if available.  Example: `:fifo make`.
+
+[`:edit`]: ../rc/connect/commands/:edit
+[`:buffer`]: ../rc/connect/commands/:buffer
+[`:fifo`]: ../rc/connect/commands/:fifo
+
+<!---->
+
+- [`:it`]: Get the current buffer path.
+- [`:ls`]: List buffers.
+
 [`: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
index 3b29a8d..ef46475 100644
--- a/docs/recipes.md
+++ b/docs/recipes.md
@@ -1,28 +1,31 @@
 # Recipes
 
-## Appending Kakoune’s shell prompt to the usual prompt
+## Custom prompt
 
-If you are using `bash`, you can add the following lines to your `.bashrc`.
+You can modify your shell [prompt][Prompt customization] to notify you whenever you are connected to a session.
 
-``` sh
-if [ -e ~/.local/share/kak/connect/prompt ]; then
-    PS1="\$(~/.local/share/kak/connect/prompt)$PS1"
-fi
+[Prompt customization]: https://wiki.archlinux.org/index.php/Bash/Prompt_customization
+
+**Example** – for Bash:
+
+``` bash
+PS1="\$(~/.local/share/kak/connect/prompt)$PS1"
 ```
 
+See [`share/kak/connect/prompt`].
+
+[`share/kak/connect/prompt`]: ../share/kak/connect/prompt
+
 ## 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.
+`kak-shell :attach` lets you run a client connected to a session, just like the plain `kak -c <session-name>`.
+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>`
+Therefore, `kak-shell :attach` replaces `kak -c <session-name>` and `kak -d -s <session-name>`
 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`.
+**Tip**: Alias `kak-shell` to `ks` and connect to a session with `ks a`.
 
 ## Turn Kakoune into an IDE
 
@@ -60,12 +63,12 @@ define-command ide -params 0..1 -docstring 'ide [session-name]: Turn Kakoune int
 }
 ```
 
-### Change directory
+## Change directory
 
 In complement to `:cd!` which syncs the client to your current working directory,
 you can do the opposite.
 
-Add to your `.bashrc`:
+Add to your bashrc:
 
 ``` bash
 if [ "$IN_KAKOUNE_CONNECT" = 1 ]; then
@@ -73,4 +76,3 @@ if [ "$IN_KAKOUNE_CONNECT" = 1 ]; then
   alias :cd?='cd `:bwd`'
 fi
 ```
-
diff --git a/docs/user-extra-documentation.md b/docs/user-extra-documentation.md
deleted file mode 100644
index 9348726..0000000
--- a/docs/user-extra-documentation.md
+++ /dev/null
@@ -1,77 +0,0 @@
-# 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`).
-
diff --git a/rc/connect/commands/:fifo b/rc/connect/commands/:fifo
index 4e65907..ea2ede0 100755
--- a/rc/connect/commands/:fifo
+++ b/rc/connect/commands/:fifo
@@ -7,6 +7,11 @@ trap 'rm buffer.fifo' EXIT
 
 # Send to fifo buffer the output of the given command,
 # or read from stdin if available.
+#
+# Example:
+#
+# :fifo make
+#
 if test $# -gt 0; then
   "$@" > buffer.fifo 2>&1 &
 elif test ! -t 0; then
diff --git a/rc/connect/commands/:get b/rc/connect/commands/:get
index 13bf2fc..288841e 100755
--- a/rc/connect/commands/:get
+++ b/rc/connect/commands/:get
@@ -1,6 +1,11 @@
 #!/bin/sh
 
-# Get a value from a client
+# Get a value from a client.
+#
+# Example:
+#
+# :get -quoting shell %val{selections}
+#
 mkfifo connect.fifo
 trap 'rm connect.fifo' EXIT
 :send echo -to-file "$PWD/connect.fifo" "$@"
diff --git a/rc/connect/commands/:it b/rc/connect/commands/:it
index 17cc516..56da647 100755
--- a/rc/connect/commands/:it
+++ b/rc/connect/commands/:it
@@ -1,3 +1,4 @@
 #!/bin/sh
 
+# Get the current buffer path.
 :get %val{buffile}