try to improve clarity of shell function install process

1 files changed, 23 insertions, 6 deletions

diff --git a/website/docs/install.md b/website/docs/install.md
index 14fc81d..1bdc06e 100644
--- a/website/docs/install.md
+++ b/website/docs/install.md
@@ -65,24 +65,33 @@ broot is convenient to find a directory then `cd` to it, which is done using <kb
 
 But broot needs a companion function in the shell in order to be able to change directory.
 
+## Automatic shell function installation
+
+This is normally the easiest solution and it's safe.
+
 When you start broot, it checks whether the `br` shell function seems to have been installed (or
 to have been refused). If needed, and if the used shell seems compatible (supported shells today are bash, zsh and fish),
 then broot asks the permission to register this shell function.
 
+When it's done, you can do just `br` to launch broot, and typing <kbd>alt</kbd><kbd>enter</kbd> will cd for you.
+
+## Retry the automatic installation
+
 If you have messed with the configuration files, you might want to have the shell function reinstalled.
 
 In order to do this, either remove all broot config files, or launch `broot --install`.
 
-When it's done, you can do just `br` to launch broot, and typing <kbd>alt</kbd><kbd>enter</kbd> will cd for you.
+You can also use the `--install` argument when you first refused and then decided you want it installed.
 
-# Fix the colors
+## Manual shell function installation
 
-Broot's initial colors ensure that everything is readable whathever your settings.
-But you may want to have something more similar to your usual terminal colors, or maybe to define the whole skin.
+If you prefer to manage the function sourcing yourself, or to automate the installation your way, or if you use an unsupported configuration, you still can get some help of broot:
 
-You should probably have a look at [changing the skin](../skins) as your next step.
+`broot --print-shell-function bash` (you can replace `bash` with either `zsh` or `fish`) outputs a recommended shell function.
 
-# `br` alias for Nushell
+`broot --set-install-state installed` tells broot the `br` function is installed (other possible values are `undefined` and `refused`).
+
+## `br` alias for Nushell
 
 As a shortcut for [Nushell](https://www.nushell.sh/), define the following alias:
 
@@ -98,3 +107,11 @@ key = "alt-c"
 shortcut = "pp"
 execution = ":print_path"
 ```
+
+# Fix the colors
+
+Broot's initial colors ensure that everything is readable whathever your settings.
+But you may want to have something more similar to your usual terminal colors, or maybe to define the whole skin.
+
+You should probably have a look at [changing the skin](../skins) as your next step.
+