Overhaul

1 files changed, 52 insertions, 103 deletions

diff --git a/README.md b/README.md
index 710788e..90cfd90 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,6 @@
 # connect.kak
 
-###### [Installation](#installation) | [Usage](#usage) | [Configuration](#configuration) | [Documentation](#documentation) | [Contributing](CONTRIBUTING)
-
-Connect a program to [Kakoune] clients.
+Leverage the client-server architecture of [Kakoune] to connect programs to clients.
 
 [Kakoune]: https://kakoune.org
 
@@ -12,71 +10,72 @@ Connect a program to [Kakoune] clients.
 ## Dependencies
 
 - [prelude.kak]
-- [terminal-mode.kak]
 
 [prelude.kak]: https://github.com/alexherbo2/prelude.kak
-[terminal-mode.kak]: https://github.com/alexherbo2/terminal-mode.kak
 
-### Suggestion
+### Optional integrations
 
 - [explore.kak]
+- [terminal-mode.kak]
 - [yank-ring.kak]
 
 [explore.kak]: https://github.com/alexherbo2/explore.kak
+[terminal-mode.kak]: https://github.com/alexherbo2/terminal-mode.kak
 [yank-ring.kak]: https://github.com/alexherbo2/yank-ring.kak
 
 ## Installation
 
+Run the following in your terminal:
+
+``` sh
+make install
+```
+
 Add [`rc`](rc) to your autoload or source [`connect.kak`](rc/connect.kak) and its [modules](rc/modules) manually.
 
-### Start an interactive shell
+## Usage
 
-Add [`kak-shell`] to your path.
+### Example 1
 
-[`kak-shell`]: bin/kak-shell
+**Kakoune** – Open a new terminal:
 
-### Add to desktop
+``` kak
+>
+```
 
-1. Copy [`kakoune-connect.desktop`] to `$XDG_DATA_HOME/applications`.
-2. Copy [Kakoune’s logo] to `$XDG_DATA_HOME/icons/hicolor/scalable/apps/kakoune.svg`.
-3. Add [`kak-desktop`] to your path.
-4. Open `$XDG_CONFIG_HOME/mimeapps.list` and add the following MIME type association:
+**Terminal** – Open all `.txt` files:
 
+``` sh
+:e *.txt
 ```
-[Default Applications]
-text/plain=kakoune-connect.desktop
-text/xml=kakoune-connect.desktop
+
+### Example 2
+
+**Kakoune** – Open [Dolphin]:
+
+``` kak
+$ dolphin
 ```
 
-Add more entries to your liking.
+[Dolphin]: https://dolphin.kde.org
 
-[`kakoune-connect.desktop`]: share/applications/kakoune-connect.desktop
-[`kak-desktop`]: bin/kak-desktop
-[Kakoune’s logo]: https://github.com/mawww/kakoune/blob/master/doc/kakoune_logo.svg
+### Example 3
 
-### Prompt
+**Kakoune** – Same with [modules]:
 
-1. Copy the [`prompt`] to `$XDG_DATA_HOME/kak/connect/prompt`.
-2. Depending on your shell:
+``` kak
+require-module connect-dolphin
 
-``` bash
-PS1='$($XDG_DATA_HOME/kak/connect/prompt) $ '
+dolphin
 ```
 
-[`prompt`]: share/kak/connect/prompt
-
-## Usage
+### Example 4
 
-Connect a terminal with `:connect-terminal`.
-Open files with the `edit` shell command or your favorite program;
-buffers with the `buffer` shell command…
+**Terminal** – Manage sessions:
 
-You can start an interactive shell (or a program) connected to a session – in the same way [nix-shell] does – with `kak-shell`.
-By default, the connections occur in the same terminal window (try `:fzf-files` or `:fzf-buffers` to see);
-you can change the terminal settings with `,tcr` (for _user mode_ – _terminal_ – _connect_ – _reset_),
-which resets the detach option and prompts you to choose a windowing system ([X11], [tmux], etc.).
-You can change it at your will with `,t`.
-The [terminal-mode.kak] interface is similar to [i3’s split commands].
+``` sh
+kak-shell
+```
 
 **Illustration**
 
@@ -87,15 +86,9 @@ Kakoune sessions:
 2 johto
 + create new session
 Kakoune session: 1█
-client0 at kanto $ edit
-:fzf-files
+@kanto $ :a█
 ```
 
-[nix-shell]: https://nixos.org/nix/manual#sec-nix-shell
-[X11]: https://x.org
-[tmux]: https://github.com/tmux/tmux
-[i3’s split commands]: https://i3wm.org/docs/userguide.html#OrientationSplit
-
 ## Configuration
 
 ``` kak
@@ -120,73 +113,29 @@ map global normal <c-q> ': quit!<ret>'
 map global normal Y ': yank-ring<ret>'
 ```
 
-By setting the option `connect_environment`, you can specify commands that
+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
-change or export environment variables:
+change or export environment variables.
 
 ``` kak
 set-option global connect_environment %{
   SHELL=elvish
-  export GIT_EDITOR='kak -c "$KAKOUNE_SESSION"'
-  export LYEDITOR='edit %(file)s +%(line)s:%(column)s'
+  export GIT_EDITOR=:attach
 }
 ```
 
-## Documentation
-
-### Kakoune
-
-Defined in [`connect.kak`](rc/connect.kak).
-
-#### Commands
-
-- `connect-terminal` (alias: `t`): Connect a terminal.
-- `connect-shell` (alias: `$`): Connect a shell.
-- `connect-detach` (alias: `d`): Write the given shell command to your connect data path and detach the client.
-
-#### Options
-
-- `connect_attach`: Attach to terminal.  Default is `no`.
-- `connect_data_path`: Path to connect data.  Default is `$XDG_DATA_HOME/kak/connect` or `~/.local/share/kak/connect`.
-
-#### Modules
+### Custom prompt
 
-Defined in [`modules`](rc/modules).
-
-- `connect-broot`
-- `connect-dmenu`
-- `connect-dolphin`
-- `connect-fzf`
-- `connect-lf`
-- `connect-nnn`
-- `connect-rofi`
-- `connect-wofi`
-
-### Shell
-
-#### Commands
-
-Defined in [`commands`](rc/paths/commands) and [`aliases`](rc/paths/aliases).
-
-- `edit` (alias: `e`): Open files.
-- `buffer` (alias: `b`): Open buffers.  With no argument, list buffers instead.
-- `attach` (alias: `a`): Attach a command ran from Kakoune with `:connect-detach`.
-- `it`: Get the current buffer.
-- `send`: Send a command.
-- `get`: Get a property.
-- `cd!`: Sync the Kakoune working directory to your current working directory.
-
-#### Environment variables
+``` bash
+PS1='$(~/.local/share/kak/connect/prompt) $ '
+```
 
-Defined in [`env`](rc/env).
+## Documentation
 
-- `IN_KAKOUNE_CONNECT`: Determine whether the shell is connected to a Kakoune session.
-- `KAKOUNE_SESSION`: Kakoune session.
-- `KAKOUNE_CLIENT`: Kakoune client.
-- `KAKOUNE_CONNECT_SCRIPT`: Path to connect script, used by `:connect-detach` for writing shell commands.
-- `KAKOUNE_CONNECT_ATTACH`: Whether to attach to terminal.
-- `EDITOR`: Editor to be used.  Default is `edit`.
-- `VISUAL`: Visual editor to be used.  Default is `edit`.
-- `GIT_EDITOR`: [Git] editor to be used.  Default is `edit -wait`.
+- [Commands]
+- [Aliases]
+- [Modules]
 
-[Git]: https://git-scm.com
+[Commands]: rc/paths/commands
+[Aliases]: rc/paths/aliases
+[Modules]: rc/modules