Improve documentation (#395)v2.10.0

9 files changed, 421 insertions, 265 deletions

diff --git a/Cargo.lock b/Cargo.lock
index f1b8067..34501da 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -172,7 +172,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 
 [[package]]
 name = "navi"
-version = "2.9.0"
+version = "2.10.0"
 dependencies = [
  "anyhow 1.0.32 (registry+https://github.com/rust-lang/crates.io-index)",
  "dirs 3.0.1 (registry+https://github.com/rust-lang/crates.io-index)",
diff --git a/Cargo.toml b/Cargo.toml
index fc211d7..094eca2 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "navi"
-version = "2.9.0"
+version = "2.10.0"
 authors = ["Denis Isidoro <denis_isidoro@live.com>"]
 edition = "2018"
 description = "An interactive cheatsheet tool for the command-line"
diff --git a/README.md b/README.md
index 6cc111f..8450db3 100644
--- a/README.md
+++ b/README.md
@@ -4,176 +4,63 @@ An interactive cheatsheet tool for the command-line and application launchers.
 
 ![Terminal demo](https://user-images.githubusercontent.com/3226564/76437136-ddc35900-6397-11ea-823c-d2da7615fe60.gif)
 
-**navi** allows you to browse through cheatsheets (that you may write yourself or download from maintainers) and execute commands. Argument suggestions are prompted to you.
+**navi** allows you to browse through cheatsheets (that you may write yourself or download from maintainers) and execute commands. Suggested values for arguments are dinamically displayed in a list.
 
 #### Pros
-- it will make you type less;
-- it will spare you from knowing CLIs by heart;
-- it will teach you new one-liners.
+- it will make you type less
+- it will spare you from knowing CLIs by heart
+- it will teach you new one-liners
 
 It uses [fzf](https://github.com/junegunn/fzf), [skim](https://github.com/lotabout/skim), or [Alfred](https://www.alfredapp.com/) under the hood and it can be either used as a command or as a shell widget (*à la* Ctrl-R).
 
-![Alfred demo](https://user-images.githubusercontent.com/3226564/80294838-582b1b00-8743-11ea-9eb5-a335d8eed833.gif)
-
 Table of contents
 -----------------
 
    * [Installation](#installation)
-      * [Using Homebrew or Linuxbrew](#using-homebrew-or-linuxbrew)
-      * [Using Gentoo](#using-gentoo)
-      * [Using nix](#using-nix)
-      * [Using cargo](#using-cargo)
-      * [Using install script](#using-install-script)
-      * [Downloading pre-compiled binaries](#downloading-pre-compiled-binaries)
-      * [Building from source](#building-from-source)
-      * [Other package managers](#other-package-managers)
    * [Usage](#usage)
-      * [Shell widget](#shell-widget)
-      * [Alfred](#alfred)
-      * [More options](#more-options)
-   * [Trying out online](#trying-out-online)
-   * [Cheatsheets](#cheatsheets)
-      * [Importing cheatsheets](#importing-cheatsheets)
-      * [Adding your own cheatsheets](#adding-your-own-cheatsheets)
-      * [Submitting cheatsheets](#submitting-cheatsheets)
+   * [Cheatsheet repositories](#cheatsheet-repositories)
    * [Cheatsheet syntax](#cheatsheet-syntax)
-      * [Syntax overview](#syntax-overview)
-      * [Variables](#variables)
-      * [Advanced variable options](#advanced-variable-options)
-      * [Variable dependency](#variable-dependency)
-      * [Multiline snippets](#multiline-snippets)
-      * [Variable as multiple arguments](#variable-as-multiple-arguments)
-   * [List customization](#list-customization)
-   * [Related projects](#related-projects)
+   * [Customization](#customization)
+   * [Using it for shell scripting](#using-it-for-shell-scripting)
+   * [More info](#more-info)
+   * [Trying out online](#trying-out-online)
+   * [Similar tools](#similar-tools)
    * [Etymology](#etymology)
 
 Installation
 ------------
 
-### Using [Homebrew](http://brew.sh/) or [Linuxbrew](http://linuxbrew.sh/)
-
-```sh
-brew install navi
-```
-
-### Using [Gentoo](https://gentoo.org/)
-
-Be sure to [enable](https://wiki.gentoo.org/wiki/Ebuild_repository) the [GURU overlay](https://gpo.zugaina.org/Overlays/guru/app-misc/navi).
-
-```sh
-emerge -a app-misc/navi
-```
+**navi** can be installed with the following package managers:
 
-### Using [nix](https://nixos.org/)
+[![Packaging status](https://repology.org/badge/vertical-allrepos/navi.svg)](https://repology.org/project/navi/versions)
 
+The recommended way to install **navi** is by running: 
 ```sh
-nix-env -iA nixpkgs.navi
-```
-
-### Using [cargo](https://github.com/rust-lang/cargo)
-
-```bash
-cargo install navi
-```
-
-### Using install script
-
-```bash
-bash <(curl -sL https://raw.githubusercontent.com/denisidoro/navi/master/scripts/install)
-
-# alternatively, to set directories:
-# SOURCE_DIR=/opt/navi BIN_DIR=/usr/local/bin bash <(curl -sL https://raw.githubusercontent.com/denisidoro/navi/master/scripts/install)
-```
-
-### Downloading pre-compiled binaries
-
-You can download binaries [here](https://github.com/denisidoro/navi/releases/latest).
-
-### Building from source
-
-```bash
-git clone https://github.com/denisidoro/navi ~/.navi
-cd ~/.navi
-make install 
-
-# alternatively, to set install directory:
-# make BIN_DIR=/usr/local/bin install
+brew install navi
 ```
 
-### Other package managers
-
-You can find **navi** for more package managers by clicking on the image below: 
-
-[![Packaging status](https://repology.org/badge/vertical-allrepos/navi.svg)](https://repology.org/project/navi/versions)
-
-Feel free to be the maintainer of **navi** for any package manager you'd like!
+If `brew` isn't available, you can check [alternative install instructions](docs/installation.md).
 
 Usage
 -----
 
-By running `navi` for the first time, you'll be suggested to download some cheatsheets. By running `navi` again, these cheatsheets will appear.
-
-### Shell widget
-
-You can use **navi** as a widget to your shell. This way, your history is correctly populated and you can edit the command as you wish before executing it. To set it up, add this line to your `.bashrc`-like file:
-```sh
-# bash
-source <(echo "$(navi widget bash)")
-
-# zsh
-source <(echo "$(navi widget zsh)")
-
-# fish
-navi widget fish | source
-```
-
-By default, `Ctrl+G` is assigned to launching **navi**.
-
-### Alfred
-
-This is *experimental*. If you face any issues, please report the issue [here](https://github.com/denisidoro/navi/issues/348).
-
-- make sure you have [Alfred Powerpack](https://www.alfredapp.com/powerpack/);
-- make sure **navi** is up to date;
-- make sure that the `navi` binary is in the `$PATH` determined by `~/.bashrc`;
-- download and install the `.alfredworkflow` for the [latest release](https://github.com/denisidoro/navi/releases/latest).
-
-### More options
+There are 3 ways to use **navi**:
 
-Please refer to `navi --help` for more details.
+- by typing `navi` in the terminal and hitting \<Enter>
+- by invoking it via a [shell widget](docs/installation.md#installing-the-shell-widget) in the terminal
+   - this way, the shell history is correctly populated (e.g. `docker run alpine` instead of `navi`) and you can edit the command as you wish before executing it
+- as an [Alfred workflow](docs/alfred.md)
 
+Cheatsheet repositories
+-----------------------
 
-Trying out online
---------------------
-
-If you don't have access to a Unix shell at the moment and you want to live preview **navi**, head to [this playground](https://www.katacoda.com/denisidoro/scenarios/navi). It'll start a docker container with instructions for you to install and use the tool. Note: login required.
+Running **navi** for the first time will help you download and manage cheatsheets.
 
-
-Cheatsheets
------------
-
-### Importing cheatsheets
-
-You can find cheatsheet repositories with:
-```sh
-navi repo browse
-```
-
-In addition, you can import cheatsheets from any git repository:
-```sh
-navi repo add https://github.com/denisidoro/cheats
-```
-
-### Adding your own cheatsheets
-
-You can either start a git repo with cheatsheets and import it as described above or you can add them directly to [data_dir](https://github.com/soc/dirs-rs#Features)`/navi`.
-
-
-### Submitting cheatsheets
-
-The main repository for cheatsheets is [denisidoro/cheats](https://github.com/denisidoro/cheats). Feel free to open a PR there for me to include your contributions.
-
-In order to add your own repository as a featured cheatsheet repo, please [edit this file](https://github.com/denisidoro/cheats/edit/master/featured_repos.txt). This list will be displayed when `navi repo browse` is run.
+You can also:
+- [browse through featured cheatsheets](docs/cheatsheet_repositories.md#browsing-through-cheatsheet-repositories)
+- [import cheatsheets from git repositories](docs/cheatsheet_repositories.md#importing-cheatsheets)
+- [write your own cheatsheets](#cheatsheet-syntax) (and [share them](docs/cheatsheet_repositories.md#submitting-cheatsheets), if you want)
+- [use cheatsheets from other tools](docs/cheatsheet_repositories.md#using-cheatsheets-from-other-tools), such as [tldr](https://github.com/tldr-pages/tldr) and [cheat.sh](https://github.com/chubin/cheat.sh)
 
 Cheatsheet syntax
 -----------------
@@ -189,136 +76,54 @@ git checkout <branch>
 $ branch: git branch | awk '{print $NF}'
 ```
 
-### Syntax overview
-
-- lines starting with `%` determine the start of a new cheatsheet and should contain tags, useful for searching;
-- lines starting with `#` should be descriptions of commands;
-- lines starting with `;` are ignored. You can use them for metacomments;
-- lines starting with `$` should contain [commands that generate a list of possible values for a given argument](#variables);
-- lines starting with `@` should contain [tags whose associated cheatsheet you want to base on](#extending-cheatsheets);
-- all the other non-empty lines are considered as executable commands.
+The full syntax and examples can be found [here](docs/cheatsheet_syntax.md).
 
-It's irrelevant how many files are used to store cheatsheets. They can be all in a single file if you wish, as long as you split them accordingly with lines starting with `%`.
+Customization
+-------------
 
-### Variables
+You can:
+- [change colors](docs/customization.md#changing-colors)
+- [resize columns](docs/customization.md#changing-colors)
+- [change how search is performed](docs/customization.md#overriding-fzf-options)
 
-The interface prompts for variable names inside brackets (eg `<branch>`). 
+Using it for shell scripting
+----------------------------
 
-Variable names should only include alphanumeric characters and `_`.
-
-If there's a corresponding line starting with `$` for a variable, suggestions will be displayed. Otherwise, the user will be able to type any value for it.
-
-If you hit `<tab>` the query typed will be prefered. If you hit `<enter>` the selection will be prefered.
-
-### Advanced variable options
-
-For lines starting with `$` you can use `---` to customize the behavior of `fzf` or how the value is going to be used:
+Let's say you want to write a bash script that, among other things, asks the user to write the name of a git branch that should be checked out. 
 
+If you already have the [cheatsheet above](#cheatsheet-syntax), then you write the following in your script:
 ```sh
-# This will pick the 3rd column and use the first line as header
-docker rmi <image_id>
-
-# Even though "false/true" is displayed, this will print "0/1"
-echo <mapped>
-
-$ image_id: docker images --- --column 3 --header-lines 1 --delimiter '\s\s+'
-$ mapped: echo 'false true' | tr ' ' '\n' --- --map "[[ $0 == t* ]] && echo 1 || echo 0"
+navi --query "git checkout" --best-match
 ```
 
-The supported parameters are:
-- `--prevent-extra` *(experimental)*: limits the user to select one of the suggestions;
-- `--column <number>`: extracts a single column from the selected result;
-- `--map <bash_code>` *(experimental)*: applies a map function to the selected variable value;
-
-In addition, it's possible to forward the following parameters to `fzf`:
-- `--multi`;
-- `--header-lines <number>`;
-- `--delimiter <regex>`;
-- `--query <text>`;
-- `--filter <text>`;
-- `--header <text>`;
-- `--preview <bash_code>`;
-- `--preview-window <text>`.
-
-### Variable dependency
-
-The command for generating possible inputs can implicitly refer other variables by using the `<varname>` syntax:
+If you want to set the `<branch>` beforehand in your script, you could then write:
 ```sh
-# Should print /my/pictures/wallpapers
-echo "<wallpaper_folder>"
-
-$ pictures_folder: echo "/my/pictures"
-$ wallpaper_folder: echo "<pictures_folder>/wallpapers"
+branch="master" navi --query "git checkout" --best-match
 ```
 
-If you want to make dependencies explicit, you can use the `$varname` syntax:
-```sh
-# If you select "hello" for <x>, the possible values of <y> will be "hello foo" and "hello bar"
-echo <x> <y>
-
-# If you want to ignore the contents of <x> and only print <y>
-: <x>; echo <y>
-
-$ x: echo "hello hi" | tr ' ' '\n'
-$ y: echo "$x foo;$x bar" | tr ';' '\n'
-```
-
-### Extending cheatsheets
-
-With the `@ same tags from other cheatsheet` syntax you can reuse the same variable in multiple cheatsheets. 
-
-```sh
-% dirs, common
-
-$ pictures_folder: echo "/my/pictures"
-
-% wallpapers
-@ dirs, common
-
-# Should print /my/pictures/wallpapers
-echo "<pictures_folder>/wallpapers"
-
-% screenshots
-@ dirs, common
-
-# Should print /my/pictures/screenshots
-echo "<pictures_folder>/screenshots"
-```
-
-### Multiline snippets
+More info
+---------
 
-Commands may be multiline:
+Please run the following command to read more about all possible options:
 ```sh
-# This will output "foo\nyes"
-echo foo
-true \
-   && echo yes \
-   || echo no
+navi --help
 ```
 
-### Variable as multiple arguments
-
-```sh
-# This will result into: cat "file1.json" "file2.json"
-jsons=($(echo "<jsons>"))
-cat "${jsons[@]}"
-
-$ jsons: find . -iname '*.json' -type f -print --- --multi
-```
-
-List customization
-------------------
-
-Lists can be stylized with the [$FZF_DEFAULT_OPTS](https://github.com/junegunn/fzf#layout) environment variable or similar variables/parameters (please refer to `navi --help`). This way, you can change the [color scheme](https://github.com/junegunn/fzf/wiki/Color-schemes), for example.
+In addition, the [/docs](docs) folder includes more information.
 
+Trying out online
+-----------------
 
-Related projects
-----------------
+If you don't have access to a Unix shell at the moment and you want to live preview **navi**, head to [this playground](https://www.katacoda.com/denisidoro/scenarios/navi). It'll start a docker container with instructions for you to install and use the tool. Note: login required.
 
-There are many similar projects out there ([bro](https://github.com/hubsmoke/bro), [eg](https://github.com/srsudar/eg), [cheat.sh](https://github.com/chubin/cheat.sh), [tldr](https://github.com/tldr-pages/tldr), [cmdmenu](https://github.com/amacfie/cmdmenu), [cheat](https://github.com/cheat/cheat), [beavr](https://github.com/denisidoro/beavr), [how2](https://github.com/santinic/how2) and [howdoi](https://github.com/gleitz/howdoi), to name a few).
+Similar tools
+-------------
 
-Most of them provide excellent cheatsheet repositories, but lack a nice UI and argument suggestions.
+There are many similar projects out there ([beavr](https://github.com/denisidoro/beavr), [bro](https://github.com/hubsmoke/bro), [cheat](https://github.com/cheat/cheat), [cheat.sh](https://github.com/chubin/cheat.sh), [cmdmenu](https://github.com/amacfie/cmdmenu), [eg](https://github.com/srsudar/eg), [how2](https://github.com/santinic/how2), [howdoi](https://github.com/gleitz/howdoi) and [tldr](https://github.com/tldr-pages/tldr), to name a few).
 
+They are excellent projects, but **navi** remains unique in the following ways:
+- it's natural to write cheatsheets tailored to your needs
+- arguments are neither hardcoded nor a simple template
 
 Etymology
 ---------
diff --git a/docs/alfred.md b/docs/alfred.md
new file mode 100644
index 0000000..4aa29ce
--- /dev/null
+++ b/docs/alfred.md
@@ -0,0 +1,13 @@
+Alfred
+------
+
+This is *experimental*. If you face any issues, please report the issue [here](https://github.com/denisidoro/navi/issues/348).
+
+![Alfred demo](https://user-images.githubusercontent.com/3226564/80294838-582b1b00-8743-11ea-9eb5-a335d8eed833.gif)
+
+### Instructions
+
+- make sure you have [Alfred Powerpack](https://www.alfredapp.com/powerpack/);
+- make sure **navi** is up to date;
+- make sure that the `navi` binary is in the `$PATH` determined by `~/.bashrc`;
+- download and install the `.alfredworkflow` for the [latest release](https://github.com/denisidoro/navi/releases/latest).
diff --git a/docs/cheatsheet_repositories.md b/docs/cheatsheet_repositories.md
new file mode 100644
index 0000000..15f2f7a
--- /dev/null
+++ b/docs/cheatsheet_repositories.md
@@ -0,0 +1,44 @@
+Cheatsheet repositories
+-----------------------
+
+* [Browsing through cheatsheet repositories](#browsing-through-cheatsheet-repositories)
+* [Importing cheatsheets](#importing-cheatsheets)
+* [Adding your own cheatsheets](#adding-your-own-cheatsheets)
+* [Submitting cheatsheets](#submitting-cheatsheets)
+* [Using cheatsheets from other tools](#using-cheatsheets-from-other-tools)
+
+### Browsing through cheatsheet repositories
+
+You can find cheatsheet repositories with:
+```sh
+navi repo browse
+```
+
+### Importing cheatsheets
+
+You can import cheatsheets from any git repository that includes `.cheat` files:
+```sh
+navi repo add https://github.com/denisidoro/cheats
+```
+
+### Adding your own cheatsheets
+
+You can either start a git repo with cheatsheets and import it as described above or you can add them directly to [data_dir](https://github.com/soc/dirs-rs#Features)`/navi`.
+
+### Submitting cheatsheets
+
+The main repository for cheatsheets is [denisidoro/cheats](https://github.com/denisidoro/cheats). Feel free to open a PR there for me to include your contributions.
+
+In order to add your own repository as a featured cheatsheet repo, please [edit this file](https://github.com/denisidoro/cheats/edit/master/featured_repos.txt). This list will be displayed when `navi repo browse` is run.
+
+### Using cheatsheets from other tools
+
+You can use cheatsheets from [tldr](https://github.com/tldr-pages/tldr) by running:
+```sh
+navi --tldr <query>
+```
+
+You can use cheatsheets from [cheat.sh](https://github.com/chubin/cheat.sh) by running:
+```sh
+navi --cheatsh <query>
+```
diff --git a/docs/cheatsheet_syntax.md b/docs/cheatsheet_syntax.md
new file mode 100644
index 0000000..17c2678
--- /dev/null
+++ b/docs/cheatsheet_syntax.md
@@ -0,0 +1,142 @@
+Cheatsheet syntax
+-----------------
+
+* [Syntax overview](#syntax-overview)
+* [Folder structure](#folder-structure)
+* [Variables](#variables)
+* [Advanced variable options](#advanced-variable-options)
+* [Variable dependency](#variable-dependency)
+* [Multiline snippets](#multiline-snippets)
+* [Variable as multiple arguments](#variable-as-multiple-arguments)
+
+### Syntax overview
+
+Cheatsheets are described in `.cheat` files that look like this:
+
+```sh
+% git, code
+
+# Change branch
+git checkout <branch>
+
+$ branch: git branch | awk '{print $NF}'
+```
+
+Lines starting with:
+- `%`: determine the start of a new cheatsheet and should contain tags
+- `#`: should be descriptions of commands
+- `;`: are ignored. You can use them for metacomments
+- `$`: should contain commands that generate a list of possible values for a given argument [:information_source:](#variables)
+- `@`: should contain tags whose associated cheatsheet you want to base on [:information_source:](#extending-cheatsheets)
+
+All the other non-empty lines are considered as executable commands.
+
+### Folder structure
+
+It's irrelevant how many files are used to store cheatsheets. They can be all in a single file if you wish, as long as you split them accordingly with lines starting with `%`.
+
+### Variables
+
+The interface prompts for variable names inside brackets (eg `<branch>`). 
+
+Variable names should only include alphanumeric characters and `_`.
+
+If there's a corresponding line starting with `$` for a variable, suggestions will be displayed. Otherwise, the user will be able to type any value for it.
+
+If you hit `<tab>` the query typed will be prefered. If you hit `<enter>` the selection will be prefered.
+
+### Advanced variable options
+
+For lines starting with `$` you can use `---` to customize the behavior of `fzf` or how the value is going to be used:
+
+```sh
+# This will pick the 3rd column and use the first line as header
+docker rmi <image_id>
+
+# Even though "false/true" is displayed, this will print "0/1"
+echo <mapped>
+
+$ image_id: docker images --- --column 3 --header-lines 1 --delimiter '\s\s+'
+$ mapped: echo 'false true' | tr ' ' '\n' --- --map "[[ $0 == t* ]] && echo 1 || echo 0"
+```
+
+The supported parameters are:
+- `--prevent-extra` *(experimental)*: limits the user to select one of the suggestions;
+- `--column <number>`: extracts a single column from the selected result;
+- `--map <bash_code>` *(experimental)*: applies a map function to the selected variable value;
+
+In addition, it's possible to forward the following parameters to `fzf`:
+- `--multi`;
+- `--header-lines <number>`;
+- `--delimiter <regex>`;
+- `--query <text>`;
+- `--filter <text>`;
+- `--header <text>`;
+- `--preview <bash_code>`;
+- `--preview-window <text>`.
+
+### Variable dependency
+
+The command for generating possible inputs can implicitly refer other variables by using the `<varname>` syntax:
+```sh
+# Should print /my/pictures/wallpapers
+echo "<wallpaper_folder>"
+
+$ pictures_folder: echo "/my/pictures"
+$ wallpaper_folder: echo "<pictures_folder>/wallpapers"
+```
+
+If you want to make dependencies explicit, you can use the `$varname` syntax:
+```sh
+# If you select "hello" for <x>, the possible values of <y> will be "hello foo" and "hello bar"
+echo <x> <y>
+
+# If you want to ignore the contents of <x> and only print <y>
+: <x>; echo <y>
+
+$ x: echo "hello hi" | tr ' ' '\n'
+$ y: echo "$x foo;$x bar" | tr ';' '\n'
+```
+
+### Extending cheatsheets
+
+With the `@ same tags from other cheatsheet` syntax you can reuse the same variable in multiple cheatsheets. 
+
+```sh
+% dirs, common
+
+$ pictures_folder: echo "/my/pictures"
+
+% wallpapers
+@ dirs, common
+
+# Should print /my/pictures/wallpapers
+echo "<pictures_folder>/wallpapers"
+
+% screenshots
+@ dirs, common
+
+# Should print /my/pictures/screenshots
+echo "<pictures_folder>/screenshots"
+```
+
+### Multiline snippets
+
+Commands may be multiline:
+```sh
+# This will output "foo\nyes"
+echo foo
+true \
+   && echo yes \
+   || echo no
+```
+
+### Variable as multiple arguments
+
+```sh
+# This will result into: cat "file1.json" "file2.json"
+jsons=($(echo "<jsons>"))
+cat "${jsons[@]}"
+
+$ jsons: find . -iname '*.json' -type f -print --- --multi
+```
\ No newline at end of file
diff --git a/docs/customization.md b/docs/customization.md
new file mode 100644
index 0000000..2e3602f
--- /dev/null
+++ b/docs/customization.md
@@ -0,0 +1,58 @@
+Customization
+-------------
+
+* [Changing colors](#changing-colors)
+* [Resizing columns](#resizing-columns)
+* [Overriding fzf options](#overriding-fzf-options)
+
+### Changing colors
+
+You can change the [color scheme](https://github.com/junegunn/fzf/wiki/Color-schemes) by [overriding fzf options](#overriding-fzf-options).
+
+In addition, you can change the text color for each column by setting the following environment variables:
+- `$NAVI_TAG_COLOR`
+- `$NAVI_COMMENT_COLOR`
+- `$NAVI_SNIPPET_COLOR`
+
+The values go [from 0 to 15](https://github.com/redox-os/termion/blob/189222555ef92a29de366f96d2a067b3a920fc24/src/color.rs#L62-L77).
+
+For example, if you add the following your .bashrc-like file, the comment color will be yellow:
+```sh
+export NAVI_COMMENT_COLOR=3
+```
+
+### Resizing columns
+
+You can change the column widths by setting the following environment variables:
+- `$NAVI_TAG_WIDTH`
+- `$NAVI_COMMENT_WIDTH`
+
+The values go from 0 to 100 and represent the percentage the column will occupy.
+
+For example, if you add the following your .bashrc-like file, the comment column will be very small:
+```sh
+export NAVI_COMMENT_WIDTH=5
+```
+
+### Overriding fzf options
+
+Let's say you want to override [$FZF_DEFAULT_OPTS](https://github.com/junegunn/fzf#layout) with `--height 3`.
+
+This can be overridden in the following ways:
+
+```sh
+# if you want to override only when selecting snippets
+navi --fzf-overrides '--height 3'
+
+# alternatively, using an environment variable in your .bashrc-like file:
+export NAVI_FZF_OVERRIDES='--height 3'
+
+# if you want to override only when selecting argument values
+navi --fzf-overrides-var '--height 3'
+
+# alternatively, using an environment variable in your .bashrc-like file:
+export NAVI_FZF_OVERRIDES_VAR='--height 3'
+
+# if you want to override for all cases
+FZF_DEFAULT_OPTS="--height 3" navi
+```
\ No newline at end of file
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 0000000..fbcaf45
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,90 @@
+Installation
+------------
+
+* [Installing the main binary](#installing-the-main-binary)
+    * [Using Homebrew or Linuxbrew](#using-homebrew-or-linuxbrew)
+    * [Using Gentoo](#using-gentoo)
+    * [Using nix](#using-nix)
+    * [Using cargo](#using-cargo)
+    * [Using install script](#using-install-script)
+    * [Downloading pre-compiled binaries](#downloading-pre-compiled-binaries)
+    * [Building from source](#building-from-source)
+    * [Other package managers](#other-package-managers)
+* [Installing the shell widget](#installing-the-shell-widget)
+
+### Installing the main binary
+
+#### Using [Homebrew](http://brew.sh/) or [Linuxbrew](http://linuxbrew.sh/)
+
+```sh
+brew install navi
+```
+
+#### Using [Gentoo](https://gentoo.org/)
+
+Be sure to [enable](https://wiki.gentoo.org/wiki/Ebuild_repository) the [GURU overlay](https://gpo.zugaina.org/Overlays/guru/app-misc/navi).
+
+```sh
+emerge -a app-misc/navi
+```
+
+#### Using [nix](https://nixos.org/)
+
+```sh
+nix-env -iA nixpkgs.navi
+```
+
+#### Using [cargo](https://github.com/rust-lang/cargo)
+
+```bash
+cargo install navi
+```
+
+#### Using install script
+
+```bash
+bash <(curl -sL https://raw.githubusercontent.com/denisidoro/navi/master/scripts/install)
+
+# (optional) to set directories:
+# SOURCE_DIR=/opt/navi BIN_DIR=/usr/local/bin bash <(curl -sL https://raw.githubusercontent.com/denisidoro/navi/master/scripts/install)
+```
+
+#### Downloading pre-compiled binaries
+
+- download the correct binary [here](https://github.com/denisidoro/navi/releases/latest)
+- extract the content to your `$PATH`
+
+#### Building from source
+
+```bash
+git clone https://github.com/denisidoro/navi ~/.navi
+cd ~/.navi
+make install 
+
+# (optional) to set the install directory:
+# make BIN_DIR=/usr/local/bin install
+```
+
+#### Other package managers
+
+You can find **navi** for more package managers by clicking on the image below: 
+
+[![Packaging status](https://repology.org/badge/vertical-allrepos/navi.svg)](https://repology.org/project/navi/versions)
+
+Feel free to be the maintainer of **navi** for any package manager you'd like!
+
+### Installing the shell widget
+
+If you want to use the shell widget, add this line to your `.bashrc`-like file:
+```sh
+# bash
+source <(echo "$(navi widget bash)")
+
+# zsh
+source <(echo "$(navi widget zsh)")
+
+# fish
+navi widget fish | source
+```
+
+By default, `Ctrl+G` is assigned to launching **navi**.
\ No newline at end of file
diff --git a/src/structures/config.rs b/src/structures/config.rs
index ea7759e..2d775f5 100644
--- a/src/structures/config.rs
+++ b/src/structures/config.rs
@@ -17,17 +17,21 @@ fn parse_finder(src: &str) -> Result<FinderChoice, Error> {
     Please refer to https://github.com/denisidoro/navi
 
 EXAMPLES:
-    navi                                   # default behavior
-    navi --print                           # doesn't execute the snippet
-    navi --path '/some/dir:/other/dir'     # uses custom cheats
-    navi query git                         # filters results by "git"
-    navi best 'sql create db'              # uses a snippet as a CLI
-    navi repo add denisidoro/cheats        # imports cheats from github.com/denisidoro/cheats
-    source <(navi widget zsh)              # loads the zsh widget
-    navi --finder 'skim'                   # set which finder is supposed to be used (fzf [default] / skim)
-    navi --fzf-overrides '--with-nth 1,2'  # shows only the comment and tag columns
-    navi --fzf-overrides '--nth 1,2'       # search will consider only the first two columns
-    navi --fzf-overrides '--no-exact'      # looser search algorithm"#)]
+    navi                                     # default behavior
+    navi --print                             # doesn't execute the snippet
+    navi --tldr docker                       # search for docker cheatsheets using tldr
+    navi --cheatsh docker                    # search for docker cheatsheets using cheatsh
+    navi --path '/some/dir:/other/dir'       # uses .cheat files from custom paths
+    navi --query git                         # filters results by "git"
+    navi 'create db' --best-match            # uses a snippet as a CLI
+    name=mydb navi 'create db' --best-match  # same, but set the value for the <name> variable
+    navi repo add denisidoro/cheats          # imports cheats from a git repository
+    source <(navi widget zsh)                # loads the zsh widget
+    navi --finder 'skim'                     # set skim as finder, instead of fzf
+    navi --fzf-overrides '--with-nth 1,2'    # shows only the comment and tag columns
+    navi --fzf-overrides '--no-select-1'     # prevents autoselection in case of single line
+    navi --fzf-overrides '--nth 1,2'         # search will consider only the first two columns
+    navi --fzf-overrides '--no-exact'        # looser search algorithm"#)]
 #[structopt(setting = AppSettings::ColorAuto)]
 #[structopt(setting = AppSettings::ColoredHelp)]
 #[structopt(setting = AppSettings::AllowLeadingHyphen)]
@@ -160,7 +164,7 @@ fn deprecated(syntax: &str) {
             return;
         }
         eprintln!(
-            r"⚠️  The following syntax has been DEPRECATED:
+            r"⚠️ The following syntax has been DEPRECATED:
 navi {}
 
 Please check `navi --help` for more info on how to achieve the same result with the new syntax.