chore(docs): update README.md, Cargo desc, installation

CONFIGURATION.md

@@ -0,0 +1,241 @@
+# Configuration
+
+If you want to customize how is shown your tmux-copyrat hints those all available
+parameters to set your perfect profile.
+
+NOTE: for changes to take effect, you'll need to source again your `.tmux.conf` file.
+
+- [@copyrat-key](#thumbs-key)
+- [@copyrat-alphabet](#thumbs-alphabet)
+- [@copyrat-reverse](#thumbs-reverse)
+- [@copyrat-unique](#thumbs-unique)
+- [@copyrat-position](#thumbs-position)
+- [@copyrat-regexp-N](#thumbs-regexp-N)
+- [@copyrat-command](#thumbs-command)
+- [@copyrat-upcase-command](#thumbs-upcase-command)
+- [@copyrat-bg-color](#thumbs-bg-color)
+- [@copyrat-fg-color](#thumbs-fg-color)
+- [@copyrat-hint-bg-color](#thumbs-hint-bg-color)
+- [@copyrat-hint-fg-color](#thumbs-hint-fg-color)
+- [@copyrat-select-fg-color](#thumbs-select-fg-color)
+- [@copyrat-select-bg-color](#thumbs-select-bg-color)
+- [@copyrat-contrast](#thumbs-contrast)
+
+### @thumbs-key
+
+`default: space`
+
+Choose which key is used to enter in thumbs mode.
+
+For example:
+
+```
+set -g @thumbs-key F
+```
+
+### @thumbs-alphabet
+
+`default: qwerty`
+
+Choose which set of characters is used to build hints. Review all [available alphabets](#Alphabets)
+
+For example:
+
+```
+set -g @thumbs-alphabet dvorak-homerow
+```
+
+### @thumbs-reverse
+
+`default: disabled`
+
+Choose in which direction you want to assign hints. Useful to get shorter hints closer to the cursor.
+
+For example:
+
+```
+set -g @thumbs-reverse
+```
+
+### @thumbs-unique
+
+`default: disabled`
+
+Choose if you want to assign the same hint for the same text spans.
+
+For example:
+
+```
+set -g @thumbs-unique
+```
+
+### @thumbs-position
+
+`default: left`
+
+Choose where do you want to show the hint in the text spans. Options (left, right).
+
+For example:
+
+```
+set -g @thumbs-position right
+```
+
+### @thumbs-regexp-N
+
+Add extra patterns to match. This parameter can have multiple instances.
+
+For example:
+
+```
+set -g @thumbs-regexp-1 '[a-z]+@[a-z]+.com' # Match emails
+set -g @thumbs-regexp-2 '[a-f0-9]{2}:[a-f0-9]{2}:[a-f0-9]{2}:[a-f0-9]{2}:[a-f0-9]{2}:[a-f0-9]{2}:' # Match MAC addresses
+```
+
+### @thumbs-command
+
+`default: 'tmux set-buffer {}'`
+
+Choose which command execute when you press a hint. `tmux-thumbs` will replace `{}` with the picked hint.
+
+For example:
+
+```
+set -g @thumbs-command 'echo -n {} | pbcopy'
+```
+
+### @thumbs-upcase-command
+
+`default: 'tmux set-buffer {} && tmux paste-buffer'`
+
+Choose which command execute when you press a upcase hint. `tmux-thumbs` will replace `{}` with the picked hint.
+
+For example:
+
+```
+set -g @thumbs-upcase-command 'echo -n {} | pbcopy'
+```
+
+### @thumbs-bg-color
+
+`default: black`
+
+Sets the background color for spans
+
+For example:
+
+```
+set -g @thumbs-bg-color blue
+```
+
+### @thumbs-fg-color
+
+`default: green`
+
+Sets the foreground color for spans
+
+For example:
+
+```
+set -g @thumbs-fg-color green
+```
+
+### @thumbs-hint-bg-color
+
+`default: black`
+
+Sets the background color for hints
+
+For example:
+
+```
+set -g @thumbs-hint-bg-color blue
+```
+
+### @thumbs-hint-fg-color
+
+`default: yellow`
+
+Sets the foreground color for hints
+
+For example:
+
+```
+set -g @thumbs-hint-fg-color green
+```
+
+### @thumbs-select-fg-color
+
+`default: blue`
+
+Sets the foreground color for selection
+
+For example:
+
+```
+set -g @thumbs-select-fg-color red
+```
+
+### @thumbs-select-bg-color
+
+`default: black`
+
+Sets the background color for selection
+
+For example:
+
+```
+set -g @thumbs-select-bg-color red
+```
+
+### @thumbs-contrast
+
+`default: 0`
+
+Displays hint character in square brackets for extra visibility.
+
+For example:
+
+```
+set -g @thumbs-contrast 1
+```
+
+#### Colors
+
+This is the list of available colors:
+
+- black
+- red
+- green
+- yellow
+- blue
+- magenta
+- cyan
+- white
+- default
+
+#### Alphabets
+
+This is the list of available alphabets:
+
+- `qwerty`: asdfqwerzxcvjklmiuopghtybn
+- `qwerty-homerow`: asdfjklgh
+- `qwerty-left-hand`: asdfqwerzcxv
+- `qwerty-right-hand`: jkluiopmyhn
+- `azerty`: qsdfazerwxcvjklmuiopghtybn
+- `azerty-homerow`: qsdfjkmgh
+- `azerty-left-hand`: qsdfazerwxcv
+- `azerty-right-hand`: jklmuiophyn
+- `qwertz`: asdfqweryxcvjkluiopmghtzbn
+- `qwertz-homerow`: asdfghjkl
+- `qwertz-left-hand`: asdfqweryxcv
+- `qwertz-right-hand`: jkluiopmhzn
+- `dvorak`: aoeuqjkxpyhtnsgcrlmwvzfidb
+- `dvorak-homerow`: aoeuhtnsid
+- `dvorak-left-hand`: aoeupqjkyix
+- `dvorak-right-hand`: htnsgcrlmwvz
+- `colemak`: arstqwfpzxcvneioluymdhgjbk
+- `colemak-homerow`: arstneiodh
+- `colemak-left-hand`: arstqwfpzxcv
+- `colemak-right-hand`: neioluymjhk
+

Cargo.toml

@@ -3,7 +3,8 @@ name = "copyrat"
 version = "0.4.1"
 authors = ["graelo <graelo@graelo.cc>"]
 edition = "2021"
-description = "This is tmux-copycat on Rust steroids."
+
+description = "A tmux plugin for copy-pasting within tmux panes."
 repository = "https://github.com/graelo/tmux-copyrat"
 keywords = ["rust", "tmux", "tmux-plugin", "tmux-copycat"]
 license = "MIT"

INSTALLATION.md

@@ -0,0 +1,100 @@
+# Installation
+
+## A note on extending tmux functionality
+
+Extending [tmux] functionality is easy: it boils down to adding key-bindings
+which call internal commands or external programs that you provide.
+
+The minimalistic way to add functionality is simply to add your key-bindings
+directly inside `~/.tmux.conf`. I don't do this because it ends up being messy,
+but it's still an option described below.
+
+In contrast, the most flexible way to extend is via plugins. You declare your
+bindings in a plugin file often located in
+`~/.tmux/plugins/your-plugin-dir/plugin-file.tmux`, and optionally provide your
+external programs in the same folder or elsewhere. You then simply ask tmux to
+_run_ your plugin file by adding `run-shell
+~/.tmux/plugins/your-plugin-dir/plugin-file.tmux` inside your `tmux.conf`. Your
+key-bindings will be registered on tmux initial start.
+
+[TPM], the tmux plugin manager, is an integrated way of doing the same. It adds
+a level of indirection: when tmux first starts, it runs TPM, which asks tmux to
+_run_ all the plugin files in `~/.tmux/plugins/**/` as executables.
+When run, each plugin file registers their key-bindings with tmux. TPM also has
+an installation mechanism for plugins.
+
+
+## Minimalistic installation
+
+As described above, a valid option is to ignore the [`copyrat.tmux`] plugin
+file simply add a few key bindings to tmux. You just have to create
+key-bindings which launch the `tmux-copyrat` binary with its command line
+options. Notice you probably need the absolute path to the binary.
+
+However, when creating your bindings, avoid using `run-shell` to run `tmux-copyrat`
+because by design tmux launches processes without attaching them to a pty.
+Take inspiration from [`copyrat.tmux`] for correct syntax.
+
+
+## Standard installation (recommended)
+
+The easiest way to install is to copy the config file [`copyrat.tmux`] into `~/.tmux/plugins/tmux-copyrat/` and tell tmux to source it either via
+
+- sourcing it directly from your `~/.tmux.conf`: you simply add the line `source-file ~/.tmux/plugins/tmux-copyrat/copyrat.tmux`
+- or, if you use [TPM], registering it with TPM in your `~/.tmux.conf`: you simply add the line
+
+
+```tmux
+set -g @tpm_plugins '              \
+  tmux-plugins/tpm                 \
+  tmux-plugins/tmux-copyrat        \  <- line added
+  tmux-plugins/tmux-yank           \
+  ...
+```
+
+
+second style of tmux integration is more declarative: you configure the tmux key bindings to pass none or very few command line arguments to `tmux-copyrat`, and ask `tmux-copyrat` to query back tmux for the rest of the configuration.
+
+
+
+## Tmux integration
+
+Clone the repo:
+
+```
+git clone https://github.com/graelo/tmux-copyrat ~/.tmux/plugins/tmux-copyrat
+```
+
+Compile it with [cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html):
+
+```
+cd ~/.tmux/plugins/tmux-copyrat
+cargo build --release
+```
+
+Source it in your `.tmux.conf`:
+
+```
+run-shell ~/.tmux/plugins/tmux-copyrat/copyrat.tmux
+```
+
+Reload TMUX conf by running:
+
+```
+tmux source-file ~/.tmux.conf
+```
+
+## Using Tmux Plugin Manager
+
+You can add this line to your list of [TPM](https://github.com/tmux-plugins/tpm) plugins in `.tmux.conf`:
+
+```
+set -g @plugin 'graelo/tmux-copyrat'
+```
+
+To be able to install the plugin just hit <kbd>prefix</kbd> + <kbd>I</kbd>. You should now be able to use
+the plugin!
+
+[`copyrat.tmux`]: https://raw.githubusercontent.com/graelo/tmux-copyrat/main/copyrat.tmux
+[tmux]: https://tmux.github.io
+[TPM]: https://github.com/tmux-plugins/tpm