Update documentation

4 files changed, 117 insertions, 117 deletions

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`).
-