Improved documentation.

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

3 files changed, 197 insertions, 0 deletions

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