diff --git a/man/man1/fisher-help.1 b/man/man1/fisher-help.1
index 3ca9994..f6d4e44 100644
--- a/man/man1/fisher-help.1
+++ b/man/man1/fisher-help.1
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "FISHER\-HELP" "1" "January 2016" "" "fisherman"
+.TH "FISHER\-HELP" "1" "February 2016" "" "fisherman"
 .
 .SH "NAME"
 \fBfisher\-help\fR \- Show Help
@@ -43,7 +43,7 @@ my_plugin
 .IP "" 0
 .
 .P
-This will allow you to access help for my_plugin using \fBman(1)\fR\. To add documentation to a \fBfisher(1)\fR command, prepend the keyword \fBfisher\-\fR to the man file, e\.g\., \fBfisher\-\fRmy\-command\.1\. This will allow you to access the man page by \fBfisher help my\-command\fR\.
+Help for my_plugin is now available via \fBman(1)\fR\. To add documentation to a \fBfisher\fR command, prepend the keyword \fBfisher\-\fR to the man file, e\.g\., \fBfisher\-my\-command\.1\fR\. This will teach Fisherman how to access the man page using \fBfisher help my\-command\fR\.
 .
 .P
 There are utilities that can help you generate man pages from other text formats, such as Markdown\. One example is \fBronn(1)\fR\. For an example without using external utilities, see \fIExample\fR in \fBfisher help plugins\fR\.
@@ -52,7 +52,7 @@ There are utilities that can help you generate man pages from other text formats
 .
 .TP
 \fB\-a \-\-all\fR
-List both commands and guides\. This shows all the available documentation\.
+List all available commands and guides\.
 .
 .TP
 \fB\-g \-\-guides[=*bare*]\fR
@@ -64,7 +64,7 @@ List commands\. This is the default behavior of \fBfisher help\fR\. Use \fIbare\
 .
 .TP
 \fB\-u \-\-usage[=*command*]\fR
-Display usage help for \fIcommand\fR\. To supply usage help with a command, \fIcommand\fR must implement a \fB\-h\fR flag\.
+Display usage help for \fIcommand\fR\. To teach Fisherman how to display help for your command, \fIcommand\fR must implement a \fB\-h\fR flag\.
 .
 .TP
 \fB\-h \-\-help\fR
diff --git a/man/man1/fisher-help.md b/man/man1/fisher-help.md
index f119621..6cfbc44 100644
--- a/man/man1/fisher-help.md
+++ b/man/man1/fisher-help.md
@@ -25,14 +25,14 @@ my_plugin
         |-- my_plugin.1
 ```
 
-This will allow you to access help for my_plugin using `man(1)`. To add documentation to a `fisher(1)` command, prepend the keyword `fisher-` to the man file, e.g., `fisher-`my-command.1. This will allow you to access the man page by `fisher help my-command`.
+Help for my_plugin is now available via `man(1)`. To add documentation to a `fisher` command, prepend the keyword `fisher-` to the man file, e.g., `fisher-my-command.1`. This will teach Fisherman how to access the man page using `fisher help my-command`.
 
 There are utilities that can help you generate man pages from other text formats, such as Markdown. One example is `ronn(1)`. For an example without using external utilities, see *Example* in `fisher help plugins`.
 
 ## OPTIONS
 
 * `-a --all`:
-    List both commands and guides. This shows all the available documentation.
+    List all available commands and guides.
 
 * `-g --guides[=*bare*]`:
     List guides / tutorials. Use *bare* to generate easy to parse output.
@@ -41,7 +41,7 @@ There are utilities that can help you generate man pages from other text formats
     List commands. This is the default behavior of `fisher help`. Use *bare* to generate easy to parse output.
 
 * `-u --usage[=*command*]`:
-    Display usage help for *command*. To supply usage help with a command, *command* must implement a `-h` flag.
+    Display usage help for *command*. To teach Fisherman how to display help for your command, *command* must implement a `-h` flag.
 
 * `-h --help`:
     Show usage help.
@@ -66,7 +66,6 @@ fisher help help
 fisher help --commands=bare | fisher help --usage
 ```
 
-
 ## SEE ALSO
 
 man(1)<br>
diff --git a/man/man1/fisher-install.1 b/man/man1/fisher-install.1
index 0f04b3a..811f6ee 100644
--- a/man/man1/fisher-install.1
+++ b/man/man1/fisher-install.1
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "FISHER\-INSTALL" "1" "January 2016" "" "fisherman"
+.TH "FISHER\-INSTALL" "1" "February 2016" "" "fisherman"
 .
 .SH "NAME"
 \fBfisher\-install\fR \- Install Plugins
@@ -24,10 +24,7 @@ fisher \fBinstall\fR \fIowner/repo\fR \.\.\.
 .br
 .
 .SH "DESCRIPTION"
-Install one or more plugins, by name, URL or local path\. If no arguments are given, read the standard input\.
-.
-.P
-If the Git host is not provided, Fisherman will use https://github\.com by default\.
+Install one or more plugins, by name, URL or a local path\. If no arguments are given, read the standard input\.
 .
 .P
 In addition, all of the following \fBowner/repo\fR variations are accepted:
@@ -76,16 +73,16 @@ Shortcuts to other common Git repository hosting services are also available:
 .IP "" 0
 .
 .P
-If a URL is given, the repository is cloned to \fB$fisher_cache\fR the first time and any relevant plugin files are copied to \fB$fisher_config\fR functions, completions, conf\.d and man directories\.
+If a URL is given, the repository is cloned to \fB$fisher_cache\fR the first time and any relevant plugin files are copied to \fB$fisher_config\fR functions, completions, conf\.d, scripts and man directories\.
 .
 .P
-If the plugin already exists in \fB$fisher_cache\fR, the files are copied to \fB$fisher_config\fR\. To update a plugin use \fBfisher update\fR\.
+If the plugin already exists in \fB$fisher_cache\fR, the files are only copied to \fB$fisher_config\fR\. To update a plugin use \fBfisher update\fR\.
 .
 .P
 If the plugin declares dependencies, these will be installed too\. If any of the dependencies are already enabled or downloaded to the cache, they will not be updated to prevent version issues\. See \fIPlugins\fR in \fBfisher help fishfile\fR\.
 .
 .P
-If a plugin includes either a fish_prompt\.fish or fish_right_prompt\.fish, both files are first removed from \fB$fisher_config/functions\fR and then the new ones are copied\.
+If a plugin includes either a \fBfish_prompt\.fish\fR or \fBfish_right_prompt\.fish\fR, both files are first removed from \fB$fisher_config/functions\fR and then the new ones are copied\.
 .
 .SH "OPTIONS"
 .
@@ -101,31 +98,8 @@ Enable quiet mode\.
 \fB\-h\fR \fB\-\-help\fR
 Show usage help\.
 .
-.SH "INSTALL PROCESS"
-Here is the typical install process breakdown for \fIplugin\fR:
-.
-.IP "1." 4
-Check if \fIplugin\fR exists in \fB$fisher_index\fR\. Fail otherwise\.
-.
-.IP "2." 4
-Download \fIplugin\fR to \fB$fisher_cache\fR if not there already\.
-.
-.IP "3." 4
-Copy all \fB*\.fish\fR and \fBfunctions/*\.fish\fR files to \fB$fisher_config/functions\fR\.
-.
-.IP "4." 4
-Copy all \fBcompletions/*\.fish\fR to \fB$fisher_config/completions\fR\.
-.
-.IP "5." 4
-Copy all \fBinit\.fish\fR and \fB*\.config\.fish\fR files to \fB$fisher_config/conf\.d\fR\.
-.
-.IP "6." 4
-Copy all man/man% to \fB$fisher_config/man/man%\fR\.
-.
-.IP "" 0
-.
 .SH "EXAMPLES"
-Here is the directory tree of \fImy_plugin\fR somewhere deep under the sea:
+Here is the directory tree of \fImy_plugin\fR:
 .
 .IP "" 4
 .
@@ -173,10 +147,27 @@ $fisher_config
 .IP "" 0
 .
 .P
-In addition, any \fBinit\.fish\fR or \fB*\.config\.fish\fR files, are copied to \fB$fisher_config/conf\.d\fR and evaluated during the start of the shell\.
+In addition, any \fBinit\.fish\fR and \fB*\.config\.fish\fR files, are copied to \fB$fisher_config/conf\.d\fR and evaluated during the start of the shell\.
 .
 .P
-Notes: \fBinit\.fish\fR files are renamed to \fBmy_plugin\.init\.fish\fR to prevent name collisions\.
+To prevent name collisions, \fBinit\.fish\fR files are renamed to \fBmy_plugin\.init\.fish\fR\.
+.
+.SH "EXAMPLES"
+.
+.IP "\(bu" 4
+Install plugins from multiple sources\.
+.
+.IP "" 0
+.
+.IP "" 4
+.
+.nf
+
+fisher install fishtape simnalamburt/shellder ~/plugins/my_plugin
+.
+.fi
+.
+.IP "" 0
 .
 .SH "SEE ALSO"
 fisher(1)
diff --git a/man/man1/fisher-install.md b/man/man1/fisher-install.md
index a3b05a7..d703302 100644
--- a/man/man1/fisher-install.md
+++ b/man/man1/fisher-install.md
@@ -14,9 +14,7 @@ fisher `install` *owner/repo* ...<br>
 
 ## DESCRIPTION
 
-Install one or more plugins, by name, URL or local path. If no arguments are given, read the standard input.
-
-If the Git host is not provided, Fisherman will use https://github.com by default.
+Install one or more plugins, by name, URL or a local path. If no arguments are given, read the standard input.
 
 In addition, all of the following `owner/repo` variations are accepted:
 
@@ -30,13 +28,13 @@ Shortcuts to other common Git repository hosting services are also available:
 * *gl*/owner/repo `>` https://gitlab.com/owner/repo<br>
 * *omf*/owner/repo `>` https://github.com/oh-my-fish/repo<br>
 
-If a URL is given, the repository is cloned to `$fisher_cache` the first time and any relevant plugin files are copied to `$fisher_config` functions, completions, conf.d and man directories.
+If a URL is given, the repository is cloned to `$fisher_cache` the first time and any relevant plugin files are copied to `$fisher_config` functions, completions, conf.d, scripts and man directories.
 
-If the plugin already exists in `$fisher_cache`, the files are copied to `$fisher_config`. To update a plugin use `fisher update`.
+If the plugin already exists in `$fisher_cache`, the files are only copied to `$fisher_config`. To update a plugin use `fisher update`.
 
 If the plugin declares dependencies, these will be installed too. If any of the dependencies are already enabled or downloaded to the cache, they will not be updated to prevent version issues. See *Plugins* in `fisher help fishfile`.
 
-If a plugin includes either a fish_prompt.fish or fish_right_prompt.fish, both files are first removed from `$fisher_config/functions` and then the new ones are copied.
+If a plugin includes either a `fish_prompt.fish` or `fish_right_prompt.fish`, both files are first removed from `$fisher_config/functions` and then the new ones are copied.
 
 ## OPTIONS
 
@@ -49,20 +47,9 @@ If a plugin includes either a fish_prompt.fish or fish_right_prompt.fish, both f
 * `-h` `--help`:
     Show usage help.
 
-## INSTALL PROCESS
-
-Here is the typical install process breakdown for *plugin*:
-
-1. Check if *plugin* exists in `$fisher_index`. Fail otherwise.
-2. Download *plugin* to `$fisher_cache` if not there already.
-3. Copy all `*.fish` and `functions/*.fish` files to `$fisher_config/functions`.
-4. Copy all `completions/*.fish` to `$fisher_config/completions`.
-5. Copy all `init.fish` and `*.config.fish` files to `$fisher_config/conf.d`.
-5. Copy all man/man% to `$fisher_config/man/man%`.
-
 ## EXAMPLES
 
-Here is the directory tree of *my_plugin* somewhere deep under the sea:
+Here is the directory tree of *my_plugin*:
 
 ```
 my_plugin
@@ -96,9 +83,17 @@ $fisher_config
     |-- my_plugin/...
 ```
 
-In addition, any `init.fish` or `*.config.fish` files, are copied to `$fisher_config/conf.d` and evaluated during the start of the shell.
+In addition, any `init.fish` and `*.config.fish` files, are copied to `$fisher_config/conf.d` and evaluated during the start of the shell.
 
-Notes: `init.fish` files are renamed to `my_plugin.init.fish` to prevent name collisions.
+To prevent name collisions, `init.fish` files are renamed to `my_plugin.init.fish`.
+
+## EXAMPLES
+
+* Install plugins from multiple sources.
+
+```fisher
+fisher install fishtape simnalamburt/shellder ~/plugins/my_plugin
+```
 
 ## SEE ALSO
 
diff --git a/man/man1/fisher-search.1 b/man/man1/fisher-search.1
index 214132f..44ea85b 100644
--- a/man/man1/fisher-search.1
+++ b/man/man1/fisher-search.1
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "FISHER\-SEARCH" "1" "January 2016" "" "fisherman"
+.TH "FISHER\-SEARCH" "1" "February 2016" "" "fisherman"
 .
 .SH "NAME"
 \fBfisher\-search\fR \- Search Plugin Index
@@ -64,11 +64,11 @@ See \fIIndex\fR in \fBfisher help tour\fR for more information about the index\.
 .
 .TP
 \fB\-\-<field>[=match]\fR
-Display index records where \fB<field>\fR==\fImatch\fR\. \fIfield\fR can be any of \fBname\fR, \fBurl\fR, \fBinfo\fR, \fBtag/s\fR or \fBauthor\fR\. If \fImatch\fR is not given, display only the given \fIfield\fR from every record in the index\. Use \fB!=\fR to negate the query\.
+Display index records where \fIfield\fR equals \fImatch\fR\. \fIfield\fR can be any of \fBname\fR, \fBurl\fR, \fBinfo\fR, \fBtag/s\fR or \fBauthor\fR\. If \fImatch\fR is not given, display only the given \fIfield\fR from every record in the index\. Use \fB!=\fR to negate the query\.
 .
 .TP
 \fB\-\-<field>[~/regex/]\fR
-Same as \fB\-\-<field>[=regex]\fR, but with a Regular Expression instead of an exact match\. Use \fB!~\fR to negate the query\.
+Same as \fB\-\-<field>[=regex]\fR, but using Regular Expressions instead of exact matching\. Use \fB!~\fR to negate the query\.
 .
 .TP
 \fB\-a \-\-and\fR
@@ -87,7 +87,7 @@ Enable quiet mode\.
 Show help\.
 .
 .SH "OUTPUT"
-The default behavior is to print the result set to standard output in their original format\.
+Search prints the result records in their original format by default\.
 .
 .IP "" 4
 .
@@ -105,27 +105,27 @@ bucaran
 .IP "" 0
 .
 .P
-Search is designed for easy parsing when using the filters: \fB\-\-name\fR, \fB\-\-url\fR, \fB\-\-info\fR, \fB\-\-tags\fR, \fB\-\-author\fR\.
+To allow for easier parsing, Search will print results records in the same line when using one or more of the following options: \fB\-\-name\fR, \fB\-\-url\fR, \fB\-\-info\fR, \fB\-\-tags\fR, \fB\-\-author\fR\.
 .
 .IP "" 4
 .
 .nf
 
-fisher search shark \-\-name \-\-url
+fisher search shark \-\-name \-\-url \-\-author
 
-shark;https://github\.com/bucaran/shark
+shark;https://github\.com/fishery/shark;bucaran
 .
 .fi
 .
 .IP "" 0
 .
 .P
-The result set above consists of single line per record, and each record consists of one or more of the given fields separated by a semicolon \fB\';\'\fR\.
+The result set above consists of single line per record, and each record consists of one or more of the specified fields separated by semicolons \fB\';\'\fR\.
 .
 .SH "EXAMPLES"
 .
 .IP "\(bu" 4
-Display plugins by name and format into multiple columns\.
+Display plugins by name and format the result into multiple columns\.
 .
 .IP "" 0
 .
diff --git a/man/man1/fisher-search.md b/man/man1/fisher-search.md
index bef0a60..b4b565f 100644
--- a/man/man1/fisher-search.md
+++ b/man/man1/fisher-search.md
@@ -1,13 +1,5 @@
-usage: fisher search [<plugins>] [--and|--or] [--quiet] [--help]
-
-     --field[=value]  Filter by url, name, info, author or tags
-              -o --or  Join query with OR operator
-             -a --and  Join query with AND operator
-           -q --quiet  Enable quiet mode
-            -h --help  Show usage help
-
 fisher-search(1) -- Search Plugin Index
-==========================================
+=======================================
 
 ## SYNOPSIS
 
@@ -41,14 +33,13 @@ author
 
 See *Index* in `fisher help tour` for more information about the index.
 
-
 ## OPTIONS
 
 * `--<field>[=match]`:
-    Display index records where `<field>`==*match*. *field* can be any of `name`, `url`, `info`, `tag/s` or `author`. If *match* is not given, display only the given *field* from every record in the index. Use `!=` to negate the query.
+    Display index records where *field* equals *match*. *field* can be any of `name`, `url`, `info`, `tag/s` or `author`. If *match* is not given, display only the given *field* from every record in the index. Use `!=` to negate the query.
 
 * `--<field>[~/regex/]`:
-    Same as `--<field>[=regex]`, but with a Regular Expression instead of an exact match. Use `!~` to negate the query.
+    Same as `--<field>[=regex]`, but using Regular Expressions instead of exact matching. Use `!~` to negate the query.
 
 * `-a --and`:
     Join the query with a logical AND operator.
@@ -64,9 +55,9 @@ See *Index* in `fisher help tour` for more information about the index.
 
 ## OUTPUT
 
-The default behavior is to print the result set to standard output in their original format.
+Search prints the result records in their original format by default.
 
-```
+```fish
 fisher search shark
 shark
 https://github.com/bucaran/shark
@@ -75,39 +66,39 @@ chart tool graph sparkline
 bucaran
 ```
 
-Search is designed for easy parsing when using the filters: `--name`, `--url`, `--info`, `--tags`, `--author`.
+To allow for easier parsing, Search will print results records in the same line when using one or more of the following options: `--name`, `--url`, `--info`, `--tags`, `--author`.
 
-```
-fisher search shark --name --url
+```fish
+fisher search shark --name --url --author
 
-shark;https://github.com/bucaran/shark
+shark;https://github.com/fishery/shark;bucaran
 ```
 
-The result set above consists of single line per record, and each record consists of one or more of the given fields separated by a semicolon `';'`.
+The result set above consists of single line per record, and each record consists of one or more of the specified fields separated by semicolons `';'`.
 
 ## EXAMPLES
 
-* Display plugins by name and format into multiple columns.
+* Display plugins by name and format the result into multiple columns.
 
-```
+```fish
 fisher search --name | column
 ```
 
 * Display plugins by URL, sans *https://github.com/* and format into multiple columns.
 
-```
+```fish
 fisher search --field=url | sed 's|https://github.com/||' | column
 ```
 
 * Display remote plugins, i.e, those in the index, but *not* in the cache.
 
-```
+```fis
 fisher_search --and --name!=(fisher --list=bare)
 ```
 
 * Search all plugins whose name does not start with the letter `s`.
 
-```
+```fish
 fisher search --name!~/^s/
 ```
 
diff --git a/man/man1/fisher-uninstall.1 b/man/man1/fisher-uninstall.1
index 70b7544..3c3634d 100644
--- a/man/man1/fisher-uninstall.1
+++ b/man/man1/fisher-uninstall.1
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "FISHER\-UNINSTALL" "1" "January 2016" "" "fisherman"
+.TH "FISHER\-UNINSTALL" "1" "February 2016" "" "fisherman"
 .
 .SH "NAME"
 \fBfisher\-uninstall\fR \- Uninstall Plugins
@@ -29,7 +29,7 @@ fisher \fBuninstall\fR \fIowner/repo\fR \.\.\.
 .br
 .
 .SH "DESCRIPTION"
-Uninstall one or more plugins, by name, URL or local path\. If no arguments are given, read the standard input\. This process is the inverse of Install\. See \fBfisher help install\fR\.
+Uninstall one or more plugins, by name, URL or a local path\. If no arguments are given, read the standard input\. This process is the inverse of Install\. See \fBfisher help install\fR\.
 .
 .P
 Uninstall does not remove any copies of the given plugin in \fB$fisher_cache\fR\. To erase the copy from the cache, use the \fB\-\-force\fR option\.
diff --git a/man/man1/fisher-uninstall.md b/man/man1/fisher-uninstall.md
index 0f5d758..ab525d1 100644
--- a/man/man1/fisher-uninstall.md
+++ b/man/man1/fisher-uninstall.md
@@ -1,5 +1,5 @@
 fisher-uninstall(1) -- Uninstall Plugins
-==================================================
+========================================
 
 ## SYNOPSIS
 
@@ -15,7 +15,7 @@ fisher `uninstall` *owner/repo* ...<br>
 
 ## DESCRIPTION
 
-Uninstall one or more plugins, by name, URL or local path. If no arguments are given, read the standard input. This process is the inverse of Install. See `fisher help install`.
+Uninstall one or more plugins, by name, URL or a local path. If no arguments are given, read the standard input. This process is the inverse of Install. See `fisher help install`.
 
 Uninstall does not remove any copies of the given plugin in `$fisher_cache`. To erase the copy from the cache, use the `--force` option.
 
@@ -36,7 +36,7 @@ Uninstall does not remove any dependencies installed with other plugins. This be
 
 * Uninstall all plugins and flush the cache.
 
-```
+```fish
 fisher --list | fisher uninstall --force
 ```
 
diff --git a/man/man1/fisher-update.1 b/man/man1/fisher-update.1
index ec461df..500b155 100644
--- a/man/man1/fisher-update.1
+++ b/man/man1/fisher-update.1
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "FISHER\-UPDATE" "1" "January 2016" "" "fisherman"
+.TH "FISHER\-UPDATE" "1" "February 2016" "" "fisherman"
 .
 .SH "NAME"
 \fBfisher\-update\fR \- Update Fisherman and Plugins
@@ -26,7 +26,10 @@ fisher \fBupdate\fR \fIowner/repo\fR \.\.\.
 .br
 .
 .SH "DESCRIPTION"
-Update one or more plugins, by name, URL or local path\. If no arguments are given, update Fisherman itself\. If you try to update a plugin that is currently disabled, but in the cache, it will be updated and then enabled\. Use a dash \fB\-\fR to read from the standard input\.
+Update one or more plugins, by name, URL or a local path\. If no arguments are given, update Fisherman to the latest release\. If you try to update a plugin that is currently disabled, but present in the cache, it will be updated and then enabled\. Use a dash \fB\-\fR to read from the standard input\.
+.
+.P
+One exception to the process described above is updating a prompt which is not the current one\. In this case the repository is updated, but it will not be activated as that is probably not what the user wants\.
 .
 .P
 If a plugin is missing dependencies, they will be installed\. If any dependencies are already installed they will not be updated\. See \fBPlugins\fR in \fBfisher help fishfile\fR\.
@@ -59,7 +62,7 @@ fisher update
 .IP "" 0
 .
 .IP "\(bu" 4
-Update all plugins in the cache\.
+Update all the plugins in the cache\.
 .
 .IP "" 0
 .
diff --git a/man/man1/fisher-update.md b/man/man1/fisher-update.md
index e7249c6..47c0e0c 100644
--- a/man/man1/fisher-update.md
+++ b/man/man1/fisher-update.md
@@ -14,7 +14,9 @@ fisher `update` *owner/repo* ...<br>
 
 ## DESCRIPTION
 
-Update one or more plugins, by name, URL or local path. If no arguments are given, update Fisherman itself. If you try to update a plugin that is currently disabled, but in the cache, it will be updated and then enabled. Use a dash `-` to read from the standard input.
+Update one or more plugins, by name, URL or a local path. If no arguments are given, update Fisherman to the latest release. If you try to update a plugin that is currently disabled, but present in the cache, it will be updated and then enabled. Use a dash `-` to read from the standard input.
+
+One exception to the process described above is updating a prompt which is not the current one. In this case the repository is updated, but it will not be activated as that is probably not what the user wants.
 
 If a plugin is missing dependencies, they will be installed. If any dependencies are already installed they will not be updated. See `Plugins` in `fisher help fishfile`.
 
@@ -34,7 +36,7 @@ If a plugin is missing dependencies, they will be installed. If any dependencies
 fisher update
 ```
 
-* Update all plugins in the cache.
+* Update all the plugins in the cache.
 
 ```
 fisher --list | fisher update -
diff --git a/man/man1/fisher.1 b/man/man1/fisher.1
index 608fd7e..eebc95c 100644
--- a/man/man1/fisher.1
+++ b/man/man1/fisher.1
@@ -18,31 +18,27 @@
 .br
 .
 .SH "DESCRIPTION"
-Fisherman is a plugin manager and CLI toolkit for \fBfish(1)\fR to help you build powerful utilities and share your code easily\.
+Fisherman is a blazing fast, modern plugin manager for \fBfish(1)\fR\.
 .
 .P
-The following commands are available out of the box: \fIinstall\fR, \fIuninstall\fR, \fIupdate\fR, \fIsearch\fR and \fIhelp\fR\. See \fBfisher help <command>\fR for information about each command\.
+The following commands are available: \fIinstall\fR, \fIuninstall\fR, \fIupdate\fR, \fIsearch\fR and \fIhelp\fR\. See \fBfisher help <command>\fR for information about each command\.
 .
 .SH "OPTIONS"
 .
 .TP
-\fB\-\-list[=bare|enabled|disabled]\fR
-List plugins according to the given category\. List plugins in the cache by default\. Enabled plugins are prepended with a \fB*\fR character\. To list plugins without the \fB*\fR character use \fB\-\-list=bare\fR\.
-.
-.TP
-\fB\-f \-\-file=fishfile\fR
-Read \fIfishfile\fR and display its contents\. If \fIfishfile\fR is null or an empty string, your user \fIfishfile\fR in \fB$fisher_file\fR will be shown instead\. Use a dash \fB\-\fR to read from the standard input\. Other formats such as the Oh My Fish! bundle files are supported as well\.
+\fB\-\-list[=bare|url|all|enabled|disabled|theme|file]\fR
+List local plugins according to a given option\. Plugins are prepended with a legend character to indicate their kind\. \fB*\fR for enabled plugins, \fB>\fR for the currently enabled prompt and \fB|\fR for symbolic links\. To list plugins without the legend use \fB\-\-list=bare\fR\. Use a dash \fB\-\fR to read from the standard input\.
 .
 .TP
 \fB\-v \-\-version\fR
-Show version information\. Fisherman\'s current version can be found in the VERSION file at the root of the project\. The version scheme is based in \fBSemantic Versioning\fR and uses Git annotated tags to track releases\.
+Show version information\. Fisherman\'s current version can be found in the VERSION file at the root of the project\. The version scheme is based in \fBSemantic Versioning\fR and uses Git annotated tags to track each release\.
 .
 .TP
 \fB\-h \-\-help\fR
 Show usage help\.
 .
 .SH "CUSTOM COMMANDS"
-A Fisherman command is a function that you invoke using the \fBfisher\fR CLI utility\. By convention, any function like \fBfisher_<my_command>\fR is recognized as a Fisherman command\. You can create plugins that add new commands this way\. See \fBfisher help commands\fR and \fBfisher help plugins\fR for more information\.
+A Fisherman command is a regular function that can be invoked using the \fBfisher\fR command\. By convention, any function like \fBfisher_<my_command>\fR is recognized as a Fisherman command\. You can create plugins that add new commands this way\. See \fBfisher help commands\fR and \fBfisher help plugins\fR for more information\.
 .
 .SH "EXAMPLES"
 .
@@ -55,21 +51,37 @@ Install plugins\.
 .
 .nf
 
-fisher install fishtape shark
+fisher install fishtape shark get
 .
 .fi
 .
 .IP "" 0
 .
-.TP
-Install plugins from a \fIfishfile\fR or bundle:
-
+.IP "\(bu" 4
+Install plugins from a \fIfishfile\fR or bundle\.
+.
+.IP "" 0
 .
 .IP "" 4
 .
 .nf
 
-fisher \-\-file=path/to/bundle | fisher install
+fisher \-\-list=path/to/bundle | fisher install
+.
+.fi
+.
+.IP "" 0
+.
+.IP "\(bu" 4
+Install a plugin if inside a plugin project\.
+.
+.IP "" 0
+.
+.IP "" 4
+.
+.nf
+
+fisher install \.
 .
 .fi
 .
diff --git a/man/man1/fisher.md b/man/man1/fisher.md
index 30108ea..8aef3c3 100644
--- a/man/man1/fisher.md
+++ b/man/man1/fisher.md
@@ -9,40 +9,43 @@ fisher(1) -- Fish Plugin Manager
 
 ## DESCRIPTION
 
-Fisherman is a plugin manager and CLI toolkit for `fish(1)` to help you build powerful utilities and share your code easily.
+Fisherman is a blazing fast, modern plugin manager for `fish(1)`.
 
-The following commands are available out of the box: *install*, *uninstall*, *update*, *search* and *help*. See `fisher help <command>` for information about each command.
+The following commands are available: *install*, *uninstall*, *update*, *search* and *help*. See `fisher help <command>` for information about each command.
 
 ## OPTIONS
 
-*  `--list[=bare|enabled|disabled]`:
-    List plugins according to the given category. List plugins in the cache by default. Enabled plugins are prepended with a `*` character. To list plugins without the `*` character use `--list=bare`.
-
-* `-f --file=fishfile`:
-    Read *fishfile* and display its contents. If *fishfile* is null or an empty string, your user *fishfile* in `$fisher_file` will be shown instead. Use a dash `-` to read from the standard input. Other formats such as the Oh My Fish! bundle files are supported as well.
+*  `--list[=bare|url|all|enabled|disabled|theme|file]`:
+    List local plugins according to a given option. Plugins are prepended with a legend character to indicate their kind. `*` for enabled plugins, `>` for the currently enabled prompt and `|` for symbolic links. To list plugins without the legend use `--list=bare`. Use a dash `-` to read from the standard input.
 
 * `-v --version`:
-    Show version information. Fisherman's current version can be found in the VERSION file at the root of the project. The version scheme is based in `Semantic Versioning` and uses Git annotated tags to track releases.
+    Show version information. Fisherman's current version can be found in the VERSION file at the root of the project. The version scheme is based in `Semantic Versioning` and uses Git annotated tags to track each release.
 
 * `-h --help`:
     Show usage help.
 
 ## CUSTOM COMMANDS
 
-A Fisherman command is a function that you invoke using the `fisher` CLI utility. By convention, any function like `fisher_<my_command>` is recognized as a Fisherman command. You can create plugins that add new commands this way. See `fisher help commands` and `fisher help plugins` for more information.
+A Fisherman command is a regular function that can be invoked using the `fisher` command. By convention, any function like `fisher_<my_command>` is recognized as a Fisherman command. You can create plugins that add new commands this way. See `fisher help commands` and `fisher help plugins` for more information.
 
 ## EXAMPLES
 
 * Install plugins.
 
-```
-fisher install fishtape shark
+```fish
+fisher install fishtape shark get
 ```
 
-* Install plugins from a *fishfile* or bundle:
+* Install plugins from a *fishfile* or bundle.
 
+```fish
+fisher --list=path/to/bundle | fisher install
 ```
-fisher --file=path/to/bundle | fisher install
+
+* Install a plugin if inside a plugin project.
+
+```fish
+fisher install .
 ```
 
 ## AUTHORS
diff --git a/man/man1/getopts.1 b/man/man1/getopts.1
index 0ab27bc..c602d5e 100644
--- a/man/man1/getopts.1
+++ b/man/man1/getopts.1
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "GETOPTS" "1" "January 2016" "" "fisherman"
+.TH "GETOPTS" "1" "February 2016" "" "fisherman"
 .
 .SH "NAME"
 \fBgetopts\fR \- Parse CLI options
@@ -15,10 +15,10 @@
 .br
 .
 .SH "DESCRIPTION"
-getopts is a command line parser, designed to process command line arguments based in the POSIX Utility Syntax Guidelines\. If no arguments are given getopts returns \fB1\fR\.
+\fBGetopts\fR is a command line parser implemented in \fBawk(1)\fR, designed to process command line arguments in the easiest way possible\.
 .
 .SH "USAGE"
-In the following example:
+The best way to understand how \fBgetopts\fR work is by studying a simple example\.
 .
 .IP "" 4
 .
@@ -31,7 +31,7 @@ getopts \-ab1 \-\-foo=bar baz
 .IP "" 0
 .
 .P
-And its output:
+And its output\.
 .
 .IP "" 4
 .
@@ -137,9 +137,3 @@ The getopts described in this document is \fInot\fR equivalent to the getopts \f
 .
 .SH "AUTHORS"
 Jorge Bucaran \fIj@bucaran\.me\fR\.
-.
-.SH "SEE ALSO"
-POSIX Utility Syntax Guidelines [goo\.gl/yrgQn9]
-.
-.br
-
diff --git a/man/man1/getopts.md b/man/man1/getopts.md
index 344fb6f..28cd095 100644
--- a/man/man1/getopts.md
+++ b/man/man1/getopts.md
@@ -8,17 +8,17 @@ getopts(1) -- Parse CLI options
 
 ## DESCRIPTION
 
-getopts is a command line parser, designed to process command line arguments based in the POSIX Utility Syntax Guidelines. If no arguments are given getopts returns `1`.
+`Getopts` is a command line parser implemented in `awk(1)`, designed to process command line arguments in the easiest way possible.
 
 ## USAGE
 
-In the following example:
+The best way to understand how `getopts` work is by studying a simple example.
 
 ```
 getopts -ab1 --foo=bar baz
 ```
 
-And its output:
+And its output.
 
 ```
 a
@@ -102,7 +102,3 @@ end
 ## AUTHORS
 
 Jorge Bucaran <j@bucaran.me>.
-
-## SEE ALSO
-
-POSIX Utility Syntax Guidelines [goo.gl/yrgQn9]<br>
diff --git a/man/man1/wait.1 b/man/man1/wait.1
index 5228b60..1b89cdc 100644
--- a/man/man1/wait.1
+++ b/man/man1/wait.1
@@ -13,25 +13,25 @@
 \fBwait\fR \fIcommands\fR [\fB\-\-time\fR=interval] [\fB\-\-log\fR=file] [\fB\-\-format\fR=format] [\fB\-\-help\fR]
 .
 .SH "DESCRIPTION"
-Run \fIcommands\fR as a background process and wait until the job has finished\. Any output to standard error indicates \fBwait\fR to return \fB1\fR once is done\. While it waits, a customizable spinner is displayed in the command line\.
+Run \fIcommands\fR in the background and wait until the job has finished\. Any output to standard error indicates \fBwait\fR to return \fB1\fR\. While it waits, a customizable spinner is displayed in the command line\.
 .
 .SH "OPTIONS"
 .
 .TP
 \fB\-s \-\-spin=style|string\fR
-Set spinner style\. See \fBStyles\fR for styles and details to customize the spinner characters\.
+Set the spinner style\. See \fBStyles\fR for styles and details on how to customize the spinner tokens\.
 .
 .TP
 \fB\-t \-\-time=interval\fR
-Set spinner transition time delay in \fIseconds\fR\. A large value will refresh the spinner more slowly\. You may use decimal numbers to represent smaller numbers\.
+Set spinner transition time delay in \fIseconds\fR\. A large value will refresh the spinner more slowly\. You may use decimal numbers to represent smaller numbers\. The default interval is \fB0\.02\fR\.
 .
 .TP
 \fB\-l \-\-log=file\fR
-Output standard error to given \fIfile\fR\.
+Write the standard error output to a given \fIfile\fR\.
 .
 .TP
 \fB\-f \-\-format=format\fR
-Use given \fIformat\fR to display the spinner\. The default format is \fB"\er@"\fR where \fB@\fR represents the spinner token and \fB\er\fR a carriage return, used to refresh / erase the line\.
+Use the given \fIformat\fR to display the spinner\. The default format is \fB"\er@"\fR where \fB@\fR represents the spinner token and \fB\er\fR a carriage return, used to refresh (erase) the line\.
 .
 .TP
 \fB\-h \-\-help\fR
@@ -48,13 +48,13 @@ bar1~3
 .IP "" 0
 .
 .P
-If no style is given in \fB\-\-spin=<style>\fR, \fBmixer\fR is used by default\. If you don\'t want to display any spinners, use \fB\-\-spin=""\fR\.
+If no style is given, \fBmixer\fR is used by default\. If you don\'t want to display any spinners, use \fB\-\-spin=""\fR\.
 .
 .SS "CUSTOMIZATION"
 In addition to the default styles, you can specify a string of character tokens to be used each per spinner refresh cycle\.
 .
 .P
-For example \fB\-\-spin=12345\fR will display the numbers from 1 to 5, and \fB\-\-spin=\. \-\-format=@\fR an increasing sequence of dots and \fB@\fR represents the spinner character\.
+For example \fB\-\-spin=12345\fR will display the numbers from 1 to 5, and \fB\-\-spin=\. \-\-format=@\fR an increasing sequence of dots\.
 .
 .SS "PROGRESS BARS"
 Display a progress bar with a percent indicator using \fB\-\-spin=bar1~3\fR:
@@ -71,7 +71,7 @@ bar3: \.\.\.\.\.\.\. \fInum\fR%
 .IP "" 0
 .
 .SH "EXAMPLES"
-Run a lengthy operation as a background job and display a spinning pipe character until it is finished\.
+Run commands in the background and display a spinning pipe while until finished\.
 .
 .IP "" 4
 .
@@ -84,7 +84,7 @@ wait \-\-spin=pipe "curl \-sS $URL"
 .IP "" 0
 .
 .P
-Output any errors to \fIdebug\.txt\fR\.
+Write the standard error output to \fIdebug\.txt\fR\.
 .
 .IP "" 4
 .
diff --git a/man/man1/wait.md b/man/man1/wait.md
index 1c41d05..395747a 100644
--- a/man/man1/wait.md
+++ b/man/man1/wait.md
@@ -8,21 +8,21 @@ wait(1) -- Run commands and wait with a spin
 
 ## DESCRIPTION
 
-Run *commands* as a background process and wait until the job has finished. Any output to standard error indicates `wait` to return `1` once is done. While it waits, a customizable spinner is displayed in the command line.
+Run *commands* in the background and wait until the job has finished. Any output to standard error indicates `wait` to return `1`. While it waits, a customizable spinner is displayed in the command line.
 
 ## OPTIONS
 
 * `-s --spin=style|string`:
-    Set spinner style. See `Styles` for styles and details to customize the spinner characters.
+    Set the spinner style. See `Styles` for styles and details on how to customize the spinner tokens.
 
 * `-t --time=interval`:
-    Set spinner transition time delay in *seconds*. A large value will refresh the spinner more slowly. You may use decimal numbers to represent smaller numbers.
+    Set spinner transition time delay in *seconds*. A large value will refresh the spinner more slowly. You may use decimal numbers to represent smaller numbers. The default interval is `0.02`.
 
 * `-l --log=file`:
-    Output standard error to given *file*.
+    Write the standard error output to a given *file*.
 
 * `-f --format=format`:
-    Use given *format* to display the spinner. The default format is `"\r@"` where `@` represents the spinner token and `\r` a carriage return, used to refresh / erase the line.
+    Use the given *format* to display the spinner. The default format is `"\r@"` where `@` represents the spinner token and `\r` a carriage return, used to refresh (erase) the line.
 
 * `-h --help`:
     Show usage help.
@@ -32,13 +32,13 @@ Run *commands* as a background process and wait until the job has finished. Any
 * arc, star, pipe, ball, flip, mixer, caret
 * bar1~3
 
-If no style is given in `--spin=<style>`, `mixer` is used by default. If you don't want to display any spinners, use `--spin=""`.
+If no style is given, `mixer` is used by default. If you don't want to display any spinners, use `--spin=""`.
 
 ### CUSTOMIZATION
 
 In addition to the default styles, you can specify a string of character tokens to be used each per spinner refresh cycle.
 
-For example `--spin=12345` will display the numbers from 1 to 5, and `--spin=. --format=@` an increasing sequence of dots and `@` represents the spinner character.
+For example `--spin=12345` will display the numbers from 1 to 5, and `--spin=. --format=@` an increasing sequence of dots.
 
 ### PROGRESS BARS
 
@@ -50,13 +50,13 @@ Display a progress bar with a percent indicator using `--spin=bar1~3`:
 
 ## EXAMPLES
 
-Run a lengthy operation as a background job and display a spinning pipe character until it is finished.
+Run commands in the background and display a spinning pipe while until finished.
 
 ```
 wait --spin=pipe "curl -sS $URL"
 ```
 
-Output any errors to *debug.txt*.
+Write the standard error output to *debug.txt*.
 
 ```
 if not wait --spin=pipe --log=debug.txt "curl -sS $URL"
diff --git a/man/man5/fisher-fishfile.5 b/man/man5/fisher-fishfile.5
index 10448eb..8737ee1 100644
--- a/man/man5/fisher-fishfile.5
+++ b/man/man5/fisher-fishfile.5
@@ -7,13 +7,13 @@
 \fBfisher\-fishfile\fR \- Fishfile Format
 .
 .SH "SYNOPSIS"
-A \fIfishfile\fR lets you share plugin configurations across multiple installations, allows plugins to declare dependencies, and prevent information loss in case of system failure\.
+Fishfiles let you share plugin configurations across multiple installations, let plugins declare dependencies and teach Fisherman what plugins are currently enabled / disabled when using \fBfisher \-\-list\fR\.
 .
 .P
-Fisherman also keeps a user \fIfishfile\fR in \fB$fisher_file\fR which is automatically updated as you install or uninstall plugins\.
+Your fishfile is stored in \fB$fisher_config/fishfile\fR by default, but you can customize this location overriding the \fB$fisher_file\fR variable in your fish configuration file\.
 .
 .SH "USAGE"
-Fishfiles are plain text, manifest files that list one or more plugins by their name, URL or path to a local project\.
+Fishfiles list one or more plugins by their name, URL or path to a local project\.
 .
 .P
 Here is an example:
@@ -22,28 +22,29 @@ Here is an example:
 .
 .nf
 
-# my plugins
-shark
-fishtape
+# Ahoy!
 
-# other links
-oh\-my\-fish/bobthefish
+gitio
+fishtape
+shark
+get
+some_user/her_plugin
 .
 .fi
 .
 .IP "" 0
 .
 .P
-To read fishfiles use \fBfisher \-\-file=fishfile\fR\. This will read \fIfishfile\fR sequentially, writing its contents to the standard output\. Oh My Fish! bundle files are supported as well\.
+A fishfile may contain any amount of whitespace and comments\.
 .
 .P
-If \fIfishfile\fR is null or an empty string, the global \fIfishfile\fR in \fB$fisher_file\fR will be used\. Use a dash \fB\-\fR to force read from standard input\.
+If you need to parse a fishfile to list its plugins, for example, to pipe the input into \fBfisher install\fR or \fBfisher update\fR, you can use \fBfisher \-\-list=path/to/fishfile\fR\. Notice that Oh My Fish! bundle file syntax is also supported\.
 .
 .SH "PLUGINS"
-Plugins may declare any number of dependencies to other plugins in a fishfile at the root of their project\.
+Plugins may list any number of dependencies to other plugins in a fishfile at the root of the project\.
 .
 .P
-By default, when Fisherman installs a plugin, it will also fetch and install its dependencies\. If a dependency is already installed, it will not be updated as this could potentially break other plugins using an older version\. For the same reason, uninstalling a plugin does not remove its dependencies\.
+When a plugin is installed, its dependencies are downloaded for the first time\. If a dependency is already installed, it is not updated in order to prevent breaking other plugins using a different version\. Currently, uninstalling a plugin does not remove any its dependencies either\.
 .
 .P
 To understand this behavior, it helps to recall the shell\'s single scope for functions\. The lack of private functions means that, it is \fInot\fR possible to single\-lock a specific dependency version\. See also \fBFlat Tree\fR in \fBfisher help tour\fR\.
diff --git a/man/man5/fisher-fishfile.md b/man/man5/fisher-fishfile.md
index 658ca51..998da66 100644
--- a/man/man5/fisher-fishfile.md
+++ b/man/man5/fisher-fishfile.md
@@ -3,34 +3,35 @@ fisher-fishfile(5) -- Fishfile Format
 
 ## SYNOPSIS
 
-A *fishfile* lets you share plugin configurations across multiple installations, allows plugins to declare dependencies, and prevent information loss in case of system failure.
+Fishfiles let you share plugin configurations across multiple installations, let plugins declare dependencies and teach Fisherman what plugins are currently enabled / disabled when using `fisher --list`.
 
-Fisherman also keeps a user *fishfile* in `$fisher_file` which is automatically updated as you install or uninstall plugins.
+Your fishfile is stored in `$fisher_config/fishfile` by default, but you can customize this location overriding the `$fisher_file` variable in your fish configuration file.
 
 ## USAGE
 
-Fishfiles are plain text, manifest files that list one or more plugins by their name, URL or path to a local project.
+Fishfiles list one or more plugins by their name, URL or path to a local project.
 
 Here is an example:
 
 ```
-# my plugins
-shark
-fishtape
+# Ahoy!
 
-# other links
-oh-my-fish/bobthefish
+gitio
+fishtape
+shark
+get
+some_user/her_plugin
 ```
 
-To read fishfiles use `fisher --file=fishfile`. This will read *fishfile* sequentially, writing its contents to the standard output. Oh My Fish! bundle files are supported as well.
+A fishfile may contain any amount of whitespace and comments.
 
-If *fishfile* is null or an empty string, the global *fishfile* in `$fisher_file` will be used. Use a dash `-` to force read from standard input.
+If you need to parse a fishfile to list its plugins, for example, to pipe the input into `fisher install` or `fisher update`, you can use `fisher --list=path/to/fishfile`. Notice that Oh My Fish! bundle file syntax is also supported.
 
 ## PLUGINS
 
-Plugins may declare any number of dependencies to other plugins in a fishfile at the root of their project.
+Plugins may list any number of dependencies to other plugins in a fishfile at the root of the project.
 
-By default, when Fisherman installs a plugin, it will also fetch and install its dependencies. If a dependency is already installed, it will not be updated as this could potentially break other plugins using an older version. For the same reason, uninstalling a plugin does not remove its dependencies.
+When a plugin is installed, its dependencies are downloaded for the first time. If a dependency is already installed, it is not updated in order to prevent breaking other plugins using a different version. Currently, uninstalling a plugin does not remove any its dependencies either.
 
 To understand this behavior, it helps to recall the shell's single scope for functions. The lack of private functions means that, it is *not* possible to single-lock a specific dependency version. See also `Flat Tree` in `fisher help tour`.
 
diff --git a/man/man7/fisher-commands.7 b/man/man7/fisher-commands.7
index 9bcda6b..585c115 100644
--- a/man/man7/fisher-commands.7
+++ b/man/man7/fisher-commands.7
@@ -1,13 +1,23 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "FISHER\-COMMANDS" "7" "January 2016" "" "fisherman"
+.TH "FISHER\-COMMANDS" "7" "February 2016" "" "fisherman"
 .
 .SH "NAME"
 \fBfisher\-commands\fR \- Creating Fisherman Commands
 .
 .SH "SYNOPSIS"
-This document describes how to add new commands to Fisherman\. A Fisherman command is a function that you can invoke like \fBfisher command\fR [\fIoptions\fR]\.
+This document describes how to add new commands to Fisherman\. A Fisherman command is a function that you can invoke using the \fBfisher\fR CLI, for example:
+.
+.IP "" 4
+.
+.nf
+
+fisher my_command [*options*]
+.
+.fi
+.
+.IP "" 0
 .
 .SH "DESCRIPTION"
 To add a command, create a function \fBfisher_<my_command>\fR:
@@ -16,7 +26,7 @@ To add a command, create a function \fBfisher_<my_command>\fR:
 .
 .nf
 
-function fisher_hello \-d "Friendly command"
+function fisher_hello \-d "Hello, how are you?"
     echo hello
 end
 .
@@ -25,10 +35,10 @@ end
 .IP "" 0
 .
 .P
-Make sure it works: \fBfisher hello\fR\.
+Test it works: \fBfisher hello\fR\.
 .
 .P
-To make this function available to the current and future fish sessions, add it to \fB$XDG_CONFIG_HOME/fish/functions\fR:
+To make this function available to future fish sessions, add it to \fB$XDG_CONFIG_HOME/fish/functions\fR:
 .
 .IP "" 4
 .
@@ -41,7 +51,23 @@ funcsave fisher_hello
 .IP "" 0
 .
 .P
-You may also choose to save this function to \fB$fisher_config/functions\fR\.
+You can also create a local plugin and install it with Fisherman:
+.
+.IP "" 4
+.
+.nf
+
+mkdir fisher_hello
+cd fisher_hello
+functions fisher_hello > fisher_hello\.fish
+fisher install \.
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The method described above will create a symbolic link to the \fBfisher_hello\fR directory and \fBfisher_hello\.fish\fR inside \fB$fisher_config/functions\fR\.
 .
 .SH "EXAMPLES"
 The following example implements a command to retrieve plugin information and format the output into columns\.
@@ -57,6 +83,7 @@ function fisher_info \-d "Display information about plugins"
             printf "    \-h \-\-help  Show usage help\en"
             return
     end
+
     for item in $argv
         fisher search $item \-\-name \-\-info
     end | sed \-E \'s/;/: /\' | column
diff --git a/man/man7/fisher-commands.md b/man/man7/fisher-commands.md
index d6b9fc8..cd5d646 100644
--- a/man/man7/fisher-commands.md
+++ b/man/man7/fisher-commands.md
@@ -3,34 +3,46 @@ fisher-commands(7) -- Creating Fisherman Commands
 
 ## SYNOPSIS
 
-This document describes how to add new commands to Fisherman. A Fisherman command is a function that you can invoke like `fisher command` [*options*].
+This document describes how to add new commands to Fisherman. A Fisherman command is a function that you can invoke using the `fisher` CLI, for example:
 
+```fish
+fisher my_command [*options*]
+```
 
 ## DESCRIPTION
 
 To add a command, create a function `fisher_<my_command>`:
 
-```
-function fisher_hello -d "Friendly command"
+```fish
+function fisher_hello -d "Hello, how are you?"
     echo hello
 end
 ```
 
-Make sure it works: `fisher hello`.
+Test it works: `fisher hello`.
 
-To make this function available to the current and future fish sessions, add it to `$XDG_CONFIG_HOME/fish/functions`:
+To make this function available to future fish sessions, add it to `$XDG_CONFIG_HOME/fish/functions`:
 
-```
+```fish
 funcsave fisher_hello
 ```
 
-You may also choose to save this function to `$fisher_config/functions`.
+You can also create a local plugin and install it with Fisherman:
+
+```fish
+mkdir fisher_hello
+cd fisher_hello
+functions fisher_hello > fisher_hello.fish
+fisher install .
+```
+
+The method described above will create a symbolic link to the `fisher_hello` directory and `fisher_hello.fish` inside `$fisher_config/functions`.
 
 ## EXAMPLES
 
 The following example implements a command to retrieve plugin information and format the output into columns.
 
-```
+```fish
 function fisher_info -d "Display information about plugins"
     switch "$argv"
         case -h --help
@@ -38,6 +50,7 @@ function fisher_info -d "Display information about plugins"
             printf "    -h --help  Show usage help\n"
             return
     end
+
     for item in $argv
         fisher search $item --name --info
     end | sed -E 's/;/: /' | column
diff --git a/man/man7/fisher-config.7 b/man/man7/fisher-config.7
index a0a2817..24cf9d9 100644
--- a/man/man7/fisher-config.7
+++ b/man/man7/fisher-config.7
@@ -1,43 +1,47 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "FISHER\-CONFIG" "7" "January 2016" "" "fisherman"
+.TH "FISHER\-CONFIG" "7" "February 2016" "" "fisherman"
 .
 .SH "NAME"
 \fBfisher\-config\fR \- Fisherman Configuration
 .
 .SH "SYNOPSIS"
-This document describes how to use the available configuration options to customize Fisherman\.
+This document describes how to use Fisherman configuration variables\.
 .
 .SH "DESCRIPTION"
 Your fish user configuration, usually located in \fB$XDG_CONFIG_HOME/fish/config\.fish\fR is updated after installing Fisherman to add the global variables \fB$fisher_home\fR and \fB$fisher_config\fR\.
 .
 .P
-\fB$fisher_home\fR is the directory where you downloaded Fisherman\. This location can be anywhere you like\. If you changed this location after installing Fisherman, you need to update \fB$fisher_home\fR as well\.
+\fB$fisher_home\fR is the directory where Fisherman is downloaded to a
 .
 .P
-\fB$fisher_config\fR is the user configuration directory and the location of your user \fIfishfile\fR, \fIcache\fR directory and where plugins get installed to\. This location must be different from \fB$fisher_home\fR\. The default location is \fB$XDG_CONFIG_HOME/fisherman\fR\.
+\fB$fisher_config\fR is the user configuration directory and the
 .
 .P
-You can also customize the debug log path, cache location, index source URL, command aliases, and other options via \fB$fisher_*\fR variables\.
+Using the following variables, you can customize the locations of the cache, index URL, fishfile, create command aliases, etc\.
 .
 .SH "VARIABLES"
 .
 .TP
 \fB$fisher_home\fR
-The home directory\. This is the path where you downloaded Fisherman\.
+The home directory\. If you installed Fisherman using the recommended method \fBcurl \-sL install\.fisherman\.sh | fish\fR, the location will be \fB$XDG_DATA_HOME/fisherman\fR\. If you clone Fisherman and run \fBmake\fR yourself, \fB$fisher_home\fR will the current working directory\.
 .
 .TP
 \fB$fisher_config\fR
-The user configuration directory\. \fB$XDG_CONFIG_HOME/fisherman\fR by default\. This directory is where the \fIcache\fR, \fIfunctions\fR and \fIcompletions\fR directories are located\.
+The user configuration directory\. This is default location of your user \fIfishfile\fR, Fisherman \fIkey_bindings\.fish\fR file and the \fIcache\fR, \fIfunctions\fR, \fIcompletions\fR, \fIconf\.d\fR and \fIscripts\fR directories\. \fB$XDG_CONFIG_HOME/fisherman\fR by default\.
+.
+.TP
+\fB$fisher_file\fR
+This file keeps a list of what plugins you have installed and are currently enabled\. \fB$fisher_cofig/fishfile\fR by default\. See \fBfisher help fishfile\fR for details\.
 .
 .TP
 \fB$fisher_cache\fR
-The cache directory\. Plugins are first downloaded here and installed to \fB$fisher_config/functions\fR afterwards\. The cache is \fB$fisher_config/cache\fR by default\.
+The cache directory\. Plugins are downloaded first here and installed to \fB$fisher_config/functions\fR afterwards\. The cache is \fB$fisher_config/cache\fR by default\.
 .
 .TP
 \fB$fisher_index\fR
-Index source URL or file\. To use a different index set this to a file or URL\. Redirect urls are not supported due to security and performance concerns\. The underlying request and fetch mechanism is based in \fBcurl(1)\fR\. See also \fBIndex\fR in \fBfisher help tour\fR\.
+The URL to the index database\. To use a different index set this to a file or URL\. Redirect URLs are currently not supported due to security and performance concerns\. The underlying request and fetch mechanism is based in \fBcurl(1)\fR\.
 .
 .TP
 \fB$fisher_alias command=alias[,\.\.\.] [command2=alias[,\.\.\.]]\fR
@@ -60,20 +64,5 @@ set fisher_alias install=i,in,inst update=up
 .
 .IP "" 0
 .
-.IP "\(bu" 4
-Set \fB$fisher_index\fR to a custom database\.
-.
-.IP "" 0
-.
-.IP "" 4
-.
-.nf
-
-set fisher_index https://raw\.\.\./owner/repo/master/index2\.txt
-.
-.fi
-.
-.IP "" 0
-.
 .SH "SEE ALSO"
 fisher help tour
diff --git a/man/man7/fisher-config.md b/man/man7/fisher-config.md
index df7d21c..725c26f 100644
--- a/man/man7/fisher-config.md
+++ b/man/man7/fisher-config.md
@@ -3,34 +3,34 @@ fisher-config(7) -- Fisherman Configuration
 
 ## SYNOPSIS
 
-This document describes how to use the available configuration options to customize Fisherman.
+This document describes how to use Fisherman configuration variables.
 
 ## DESCRIPTION
 
 Your fish user configuration, usually located in `$XDG_CONFIG_HOME/fish/config.fish` is updated after installing Fisherman to add the global variables `$fisher_home` and `$fisher_config`.
 
-`$fisher_home` is the directory where you downloaded Fisherman. This location can be anywhere you like. If you changed this location after installing Fisherman, you need to update `$fisher_home` as well.
+`$fisher_home` is the directory where Fisherman is downloaded to a
 
-`$fisher_config` is the user configuration directory and the location of your user *fishfile*, *cache* directory and where plugins get installed to. This location must be different from `$fisher_home`. The default location is `$XDG_CONFIG_HOME/fisherman`.
+`$fisher_config` is the user configuration directory and the
 
-You can also customize the debug log path, cache location, index source URL, command aliases, and other options via `$fisher_*` variables.
+Using the following variables, you can customize the locations of the cache, index URL, fishfile, create command aliases, etc.
 
 ## VARIABLES
 
 * `$fisher_home`:
-    The home directory. This is the path where you downloaded Fisherman.
+    The home directory. If you installed Fisherman using the recommended method `curl -sL install.fisherman.sh | fish`, the location will be `$XDG_DATA_HOME/fisherman`. If you clone Fisherman and run `make` yourself, `$fisher_home` will the current working directory.
 
 * `$fisher_config`:
-    The user configuration directory. `$XDG_CONFIG_HOME/fisherman` by default. This directory is where the *cache*, *functions* and *completions* directories are located.
-
-* `$fisher_cache`:
-    The cache directory. Plugins are first downloaded here and installed to `$fisher_config/functions` afterwards. The cache is `$fisher_config/cache` by default.
-
-* `$fisher_index`:
-    Index source URL or file. To use a different index set this to a file or URL. Redirect urls are not supported due to security and performance concerns. The underlying request and fetch mechanism is based in `curl(1)`. See also `Index` in `fisher help tour`.
+    The user configuration directory. This is default location of your user *fishfile*, Fisherman *key_bindings.fish* file and the *cache*, *functions*, *completions*, *conf.d* and *scripts* directories. `$XDG_CONFIG_HOME/fisherman` by default.
 
 * `$fisher_file`:
-    This file keeps a list of what plugins you have installed and are currently enabled. `$fisher_cofig/fishfile` by default.
+    This file keeps a list of what plugins you have installed and are currently enabled. `$fisher_cofig/fishfile` by default. See `fisher help fishfile` for details.
+
+* `$fisher_cache`:
+    The cache directory. Plugins are downloaded first here and installed to `$fisher_config/functions` afterwards. The cache is `$fisher_config/cache` by default.
+
+* `$fisher_index`:
+    The URL to the index database. To use a different index set this to a file or URL. Redirect URLs are currently not supported due to security and performance concerns. The underlying request and fetch mechanism is based in `curl(1)`.
 
 * `$fisher_alias command=alias[,...] [command2=alias[,...]]`:
     Use this variable to define custom aliases for fisher commands. See `Examples` below.
@@ -43,12 +43,6 @@ You can also customize the debug log path, cache location, index source URL, com
 set fisher_alias install=i,in,inst update=up
 ```
 
-* Set `$fisher_index` to a custom database.
-
-```
-set fisher_index https://raw.../owner/repo/master/index2.txt
-```
-
 ## SEE ALSO
 
 fisher help tour
diff --git a/man/man7/fisher-faq.7 b/man/man7/fisher-faq.7
index 46e459b..b0dabe9 100644
--- a/man/man7/fisher-faq.7
+++ b/man/man7/fisher-faq.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "FISHER\-FAQ" "7" "January 2016" "" "fisherman"
+.TH "FISHER\-FAQ" "7" "February 2016" "" "fisherman"
 .
 .SH "NAME"
 \fBfisher\-faq\fR \- Frequently Asked Questions
@@ -110,35 +110,11 @@ See \fB$fisher_home/config\.fish\fR for the full code\.
 .SS "How is Fisherman faster than Oh My Fish and other systems?"
 Fisherman ameliorates the slow shell start problem using a flat dependency tree instead of loading a directory hierarchy per plugin\. This also means that Fisherman performance does not decline depending on the number of plugins installed\. See also \fBFlat Tree\fR in \fBfisher help tour\fR\.
 .
-.SS "Why don\'t you contribute your improvements back to Oh My Fish?"
-I have contributed back to Oh My Fish extensively\. See also Oh My Fish history for August 27, 2015 when another project, Wahoo, was entirely merged with Oh My Fish\.
-.
-.P
-In addition, Fisherman was built from the ground up using a completely different design, implementation and set of principles\.
-.
-.P
-Some features include: UNIX familiarity, minimalistic design, flat tree structure, unified plugin architecture, external self\-managed database, cache system, dependency manifest file and compatibility with Oh My Fish, etc\. See \fBfisher help tour\fR\.
-.
 .SS "How can I upgrade from an existing Oh My Fish or Wahoo installation?"
-Install Fisherman\.
-.
-.IP "" 4
-.
-.nf
-
-git clone https://github\.com/fisherman/fisherman
-cd fisherman
-make
-.
-.fi
-.
-.IP "" 0
+Remove the \fB$OMF_PATH\fR and \fB$OMF_CONFIG\fR variables from your \fBconfig\.fish\fR\.
 .
 .P
-You can now safely remove Oh My Fish \fB$OMF_PATH\fR and \fB$OMF_CONFIG\fR\.
-.
-.P
-Backup dotfiles and other sensitive data first\.
+Backup dotfiles and other sensitive data\.
 .
 .IP "" 4
 .
@@ -150,17 +126,14 @@ rm \-rf {$OMF_PATH,$OMF_CONFIG}
 .
 .IP "" 0
 .
-.SS "I changed my prompt with <code>fish_config</code> and now I can\'t use any Fisherman theme, what do I do?"
-\fBfish_config\fR persists the prompt to \fBXDG_CONFIG_HOME/fish/functions/fish_prompt\.fish\fR\. That file takes precedence over Fisherman prompts that installs to \fB$fisher_config/functions\fR\. To use Fisherman prompts remove the \fBfish_promt\.fish\fR inside \fBXDG_CONFIG_HOME/fish/functions\fR\.
-.
 .P
-Assuming \fBXDG_CONFIG_HOME\fR is \fB~/\.config\fR in your system:
+Install Fisherman\.
 .
 .IP "" 4
 .
 .nf
 
-rm ~/\.config/fish/functions/fish_prompt\.fish
+curl \-sL install\.fisherman\.sh | fish
 .
 .fi
 .
@@ -204,6 +177,4 @@ chsh \-s /bin/another/shell
 .fi
 .
 .IP "" 0
-.
-.SS "Why is this FAQ similar to the Oh My Fish FAQ?"
-Because it was written by the same author of Fisherman and Wahoo and some of the questions and answers simply overlap\.
+
diff --git a/man/man7/fisher-faq.md b/man/man7/fisher-faq.md
index bde3837..7267a60 100644
--- a/man/man7/fisher-faq.md
+++ b/man/man7/fisher-faq.md
@@ -5,17 +5,14 @@ fisher-faq(7) -- Frequently Asked Questions
 
 This document attempts to answer some of Fisherman most frequently asked questions. Feel free to create a new issue in the Fisherman issue tracker if your question is not answered here.
 
-
 ### What is Fisherman?
 
 Fisherman is a plugin manager for fish that lets you share and reuse code, prompts and configurations easily.
 
-
 ### What do I need to know to use Fisherman?
 
 Nothing. You can continue using your shell as usual. When you are ready to learn more just type `fisher help` or `fisher help tour`.
 
-
 ### How do I access the documentation?
 
 Fisherman documentation is based in UNIX `man(1)` pages. For basic usage and command enter `fisher help`. For help about a specific *command*, enter `fisher help <command>`. The following guides are also available:
@@ -27,21 +24,18 @@ fisher help `plugins`: Creating Fisherman Plugins<br>
 fisher help `commands`: Creating Fisherman Commands<br>
 fisher help `fishfile`: Fishfile Format<br>
 
-
 ### What are Fisherman plugins?
 
 Plugins are written in fish and extend the shell core functionality, run initialization code, add completions or documentations to other commands, etc. See `fisher help plugins`.
 
 Plugins may list any number of dependencies to other plugins using a *fishfile*.
 
-
 ### What is a Fishfile?
 
 A plain text file that lists what plugins you have installed or a plugin's dependencies to other plugins.
 
 Fishfiles let you share plugin configurations across multiple installations, allow plugins to declare dependencies, and prevent information loss in case of system failure. See also `fisher help fishfile`.
 
-
 ### What kind of Fisherman plugins are there?
 
 There is no technical distinction between plugins, themes, commands, etc., but there is a *conceptual* difference.
@@ -56,7 +50,6 @@ There is no technical distinction between plugins, themes, commands, etc., but t
 
 See `fisher help plugins` and `fisher help commands`.
 
-
 ### Does Fisherman support Oh My Fish plugins and themes?
 
 Yes. To install either a plugin or theme use their URL:
@@ -67,7 +60,6 @@ fisher install omf/plugin-{rbenv,tab} omf/theme-scorphish
 
 You can use the same mechanism to install any valid plugin from any given URL. See also `Compatibility` in `fisher help tour`.
 
-
 ### What does Fisherman do exactly every time I create a new shell session?
 
 Essentially, add Fisherman functions and completions to the `$fish_{function,complete}_path` and evaluate files that follow the convention `*.config.fish`.
@@ -83,50 +75,26 @@ end
 
 See `$fisher_home/config.fish` for the full code.
 
-
 ### How is Fisherman faster than Oh My Fish and other systems?
 
 Fisherman ameliorates the slow shell start problem using a flat dependency tree instead of loading a directory hierarchy per plugin. This also means that Fisherman performance does not decline depending on the number of plugins installed. See also `Flat Tree` in `fisher help tour`.
 
-### Why don't you contribute your improvements back to Oh My Fish?
-
-I have contributed back to Oh My Fish extensively. See also Oh My Fish history for August 27, 2015 when another project, Wahoo, was entirely merged with Oh My Fish.
-
-In addition, Fisherman was built from the ground up using a completely different design, implementation and set of principles.
-
-Some features include: UNIX familiarity, minimalistic design, flat tree structure, unified plugin architecture, external self-managed database, cache system, dependency manifest file and compatibility with Oh My Fish, etc. See `fisher help tour`.
-
-
 ### How can I upgrade from an existing Oh My Fish or Wahoo installation?
 
-Install Fisherman.
+Remove the `$OMF_PATH` and `$OMF_CONFIG` variables from your `config.fish`.
 
-```
-git clone https://github.com/fisherman/fisherman
-cd fisherman
-make
-```
-
-You can now safely remove Oh My Fish `$OMF_PATH` and `$OMF_CONFIG`.
-
-Backup dotfiles and other sensitive data first.
+Backup dotfiles and other sensitive data.
 
 ```fish
 rm -rf {$OMF_PATH,$OMF_CONFIG}
 ```
 
-
-### I changed my prompt with `fish_config` and now I can't use any Fisherman theme, what do I do?
-
-`fish_config` persists the prompt to `XDG_CONFIG_HOME/fish/functions/fish_prompt.fish`. That file takes precedence over Fisherman prompts that installs to `$fisher_config/functions`. To use Fisherman prompts remove the `fish_promt.fish` inside `XDG_CONFIG_HOME/fish/functions`.
-
-Assuming `XDG_CONFIG_HOME` is `~/.config` in your system:
+Install Fisherman.
 
 ```
-rm ~/.config/fish/functions/fish_prompt.fish
+curl -sL install.fisherman.sh | fish
 ```
 
-
 ### How do I use fish as my default shell?
 
 Add Fish to `/etc/shells`:
@@ -146,8 +114,3 @@ To switch back to another shell.
 ```sh
 chsh -s /bin/another/shell
 ```
-
-
-### Why is this FAQ similar to the Oh My Fish FAQ?
-
-Because it was written by the same author of Fisherman and Wahoo and some of the questions and answers simply overlap.
diff --git a/man/man7/fisher-plugins.7 b/man/man7/fisher-plugins.7
index 4522bdd..ee99cf5 100644
--- a/man/man7/fisher-plugins.7
+++ b/man/man7/fisher-plugins.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "FISHER\-PLUGINS" "7" "January 2016" "" "fisherman"
+.TH "FISHER\-PLUGINS" "7" "February 2016" "" "fisherman"
 .
 .SH "NAME"
 \fBfisher\-plugins\fR \- Creating Fisherman Plugins
@@ -15,21 +15,21 @@ There is no technical distinction between any of the terms aforementioned, but t
 .SH "DEFINITIONS"
 .
 .IP "\(bu" 4
-\fBStandalone Utilities\fR: Plugins that define one or more functions, meant to be used at the command line\.
+\fBStandalone Utilities\fR: Plugins that define one or more functions\.
 .
 .IP "\(bu" 4
-\fBPrompts / Themes\fR: Plugins that modify the appearance of the fish prompt by defining a \fBfish_prompt\fR and / or \fBfish_right_prompt\fR functions\.
+\fBPrompts / Themes\fR: Plugins that modify the appearance of the fish prompt by defining a \fBfish_prompt\fR / \fBfish_right_prompt\fR function/s\.
 .
 .IP "\(bu" 4
-\fBExtension Commands\fR: Plugins that extend Fisherman default commands\. An extension plugin must define one or more functions like \fBfisher_<my_command>\fR\. For specific information about commands, see \fBfisher help commands\fR and then return to this guide\.
+\fBExtension Commands\fR: Plugins that extend Fisherman default commands\. An extension plugin must define one or more functions like \fBfisher_<my_command>\fR\. For specific information about commands, see \fBfisher help commands\fR\.
 .
 .IP "\(bu" 4
-\fBConfiguration Plugins\fR: Plugins that include one or more \fBmy_plugin\.config\.fish\fR files\. Files that follow this convention are evaluated at the start of the session\.
+\fBConfiguration Plugins\fR: Plugins that include one or more \fBmy_plugin\.config\.fish\fR files\. Files that follow this convention are evaluated at the start of the session\. If a file does not follow the \fB<my_plugin>\.config\.fish\fR convention, it must be added to \fBconf\.d/*\.fish\fR and the \fB<my_plugin>\fR name will be prepended to the file during the installation process\.
 .
 .IP "" 0
 .
 .P
-The following tree is that of a plugin that displays the characteristics of all the plugins described above\.
+An example plugin that follows several of the conventions proposed above\.
 .
 .IP "" 4
 .
@@ -41,20 +41,37 @@ my_plugin
 |\-\- fish_prompt\.fish
 |\-\- fish_right_prompt\.fish
 |\-\- my_plugin\.config\.fish
-|\-\- functions/
+|\-\- functions
 |   |\-\- my_plugin_helper\.fish
-|\-\- completions/
+|\-\- conf\.d
+|   |\-\- *\.fish
+|\-\- completions
 |   |\-\- my_plugin\.fish
-|\-\- man/
-    |\-\- man1/
+|\-\- man
+    |\-\- man1
         |\-\- my_plugin\.1
 .
 .fi
 .
 .IP "" 0
 .
+.SH "DEPENDENCIES"
+A plugin may list any number of dependencies to other plugins using a \fIfishfile\fR, see \fBfisher help fishfile\fR\.
+.
 .P
-Plugins may list any number of dependencies to other plugins using a \fIfishfile\fR, see \fBfisher help fishfile\fR\.
+For example, if \fB<my_plugin>\fR depends on \fB<your_plugin>\fR, add this dependency into a fishfile at the root of the project:
+.
+.IP "" 4
+.
+.nf
+
+cat > my_plugin/fishfile
+your_plugin
+CTRL^D
+.
+.fi
+.
+.IP "" 0
 .
 .P
 Plugins may also define completions using \fBcomplete(1)\fR and provide documentation in the form of \fBman(1)\fR pages\.
diff --git a/man/man7/fisher-plugins.md b/man/man7/fisher-plugins.md
index a3f32d9..ed57233 100644
--- a/man/man7/fisher-plugins.md
+++ b/man/man7/fisher-plugins.md
@@ -9,15 +9,15 @@ There is no technical distinction between any of the terms aforementioned, but t
 
 ## DEFINITIONS
 
-* `Standalone Utilities`: Plugins that define one or more functions, meant to be used at the command line.
+* `Standalone Utilities`: Plugins that define one or more functions.
 
-* `Prompts / Themes`: Plugins that modify the appearance of the fish prompt by defining a `fish_prompt` and / or `fish_right_prompt` functions.
+* `Prompts / Themes`: Plugins that modify the appearance of the fish prompt by defining a `fish_prompt` / `fish_right_prompt` function/s.
 
-* `Extension Commands`: Plugins that extend Fisherman default commands. An extension plugin must define one or more functions like `fisher_<my_command>`. For specific information about commands, see `fisher help commands` and then return to this guide.
+* `Extension Commands`: Plugins that extend Fisherman default commands. An extension plugin must define one or more functions like `fisher_<my_command>`. For specific information about commands, see `fisher help commands`.
 
-* `Configuration Plugins`: Plugins that include one or more `my_plugin.config.fish` files. Files that follow this convention are evaluated at the start of the session.
+* `Configuration Plugins`: Plugins that include one or more `my_plugin.config.fish` files. Files that follow this convention are evaluated at the start of the session. If a file does not follow the `<my_plugin>.config.fish` convention, it must be added to `conf.d/*.fish` and the `<my_plugin>` name will be prepended to the file during the installation process.
 
-The following tree is that of a plugin that displays the characteristics of all the plugins described above.
+An example plugin that follows several of the conventions proposed above.
 
 ```
 my_plugin
@@ -26,16 +26,28 @@ my_plugin
 |-- fish_prompt.fish
 |-- fish_right_prompt.fish
 |-- my_plugin.config.fish
-|-- functions/
+|-- functions
 |   |-- my_plugin_helper.fish
-|-- completions/
+|-- conf.d
+|   |-- *.fish
+|-- completions
 |   |-- my_plugin.fish
-|-- man/
-    |-- man1/
+|-- man
+    |-- man1
         |-- my_plugin.1
 ```
 
-Plugins may list any number of dependencies to other plugins using a *fishfile*, see `fisher help fishfile`.
+## DEPENDENCIES
+
+A plugin may list any number of dependencies to other plugins using a *fishfile*, see `fisher help fishfile`.
+
+For example, if `<my_plugin>` depends on `<your_plugin>`, add this dependency into a fishfile at the root of the project:
+
+```
+cat > my_plugin/fishfile
+your_plugin
+CTRL^D
+```
 
 Plugins may also define completions using `complete(1)` and provide documentation in the form of `man(1)` pages.
 
@@ -43,10 +55,9 @@ Plugins may also define completions using `complete(1)` and provide documentatio
 
 This section walks you through creating *wtc*, a stand-alone plugin based in *github.com/ngerakines/commitment* random commit message generator.
 
-
 * Navigate to your preferred workspace and create the plugin's directory and Git repository:
 
-```
+```fish
 mkdir -p my/workspace/wtc; and cd my/workspace/wtc
 git init
 git remote add origin https://github.com/<owner>/wtc
@@ -54,7 +65,7 @@ git remote add origin https://github.com/<owner>/wtc
 
 * Add the implementation.
 
-```
+```fish
 cat > wtc.fish
 
 function wtc -d "Generate a random commit message"
@@ -71,7 +82,7 @@ end
 
 * Add completions. *wtc* is simple enough that you could get away without `__fisher_parse_help`, but more complex utilities, or utilities whose CLI evolves over time, can benefit using automatic completion generation. Note that in order to use `__fisher_parse_help`, your command must provide a `--help` option that prints usage information to standard output.
 
-```
+```fish
 mkdir completions
 cat > completions/wtc.fish
 
@@ -84,7 +95,7 @@ end
 
 * Add basic documentation. Fisherman uses standard manual pages for displaying help information. There are utilities that can help you generate man pages from other text formats, such as Markdown. One example is `ronn(1)`. For this example, type will do:
 
-```
+```fish
 mkdir -p man/man1
 cat > man/man1/wtc.1
 
@@ -102,7 +113,7 @@ cat > man/man1/wtc.1
 
 * Commit changes and push to the remote repository.
 
-```
+```fish
 git add --all
 git commit -m "What the commit? 1.0"
 git push origin master
@@ -110,7 +121,7 @@ git push origin master
 
 * Install with Fisherman. If you would like to submit your package for registration install the `submit` plugin or send a pull request to the main index repository in *https://github.com/fisherman/index*. See `Index` in `fisher help tour`.
 
-```
+```fish
 fisher install github/*owner*/wtc
 wtc
 (\ /)
@@ -118,7 +129,6 @@ wtc
 (> <) Bunny approves these changes.
 ```
 
-
 ## SEE ALSO
 
 man(1)<br>
diff --git a/man/man7/fisher-tour.7 b/man/man7/fisher-tour.7
index f772180..cc73d79 100644
--- a/man/man7/fisher-tour.7
+++ b/man/man7/fisher-tour.7
@@ -7,19 +7,19 @@
 \fBfisher\-tour\fR \- Fisherman Tour
 .
 .SH "DESCRIPTION"
-Fisherman is a blazing fast, modern plugin manager for Fish\.
+Fisherman is a blazing fast, modern plugin manager for \fBfish(1)\fR\.
 .
 .P
-Fisherman uses a flat tree structure that adds no cruft to your shell, making it as fast as no Fisherman\. The cache mechanism lets you query the index offline and enable or disable plugins as you wish\.
+Fisherman runs virtually no initialization code, making it as fast as no Fisherman\. The cache mechanism lets you query the index offline and enable or disable plugins as you wish\.
 .
 .P
-Other features include dependency management, great plugin search capabilities and full compatibility with Tackle, Oh My Fish! and Wahoo themes and packages\.
+Other features include dependency management, excellent test coverage, plugin search capabilities and full compatibility with Tackle, Oh My Fish! and Wahoo themes and plugins\.
 .
 .P
 This document describes Fisherman features and their implementation details\. For usage and command help see \fBfisher(1)\fR\.
 .
 .SH "FLAT TREE"
-The configuration directory structure is optimized to help your shell start new sessions as quickly as possible, regardless of the numbers of plugins or prompts enabled at any given time\. An old saying goes that Fisherman is as fast as no Fisherman\.
+The configuration directory structure is optimized to help your shell start new sessions as quickly as possible, regardless of the numbers of plugins or prompts enabled at any given time\.
 .
 .P
 To explain how this is possible, we need to make a digression and discuss function scope first\. In fish, all functions share the same scope and you can use only one name per function\.
@@ -49,19 +49,19 @@ end
 \fIfoo\fR and \fIbar\fR are available immediately at the command line prompt and both print their names\. But there is a catch, calling \fIfoo\fR at least once will create a new \fIbar\fR function, effectively erasing the previous \fIbar\fR definition\. Subsequent calls to \fIbar\fR will print nothing\.
 .
 .P
-By convention, functions that start with any number of underscores are \fIintentionally\fR private, but there is no mechanism that prevents you from calling them at any time once loaded\.
+By convention, functions that start with any number of underscores are \fIintentionally\fR private, but there is no mechanism that prevents you from calling them once they are loaded\.
 .
 .P
 With this in mind, it\'s possible to improve the slow shell start problem using a \fIflat\fR tree structure whose path is loaded only once\.
 .
 .P
-The overhead of juggling multiple path hierarchies in a per\-plugin basis yields no benefits as everything is shared in the same scope\.
+The overhead of juggling multiple path hierarchies in a per\-plugin basis yields no benefits as everything is shared inside the same scope\.
 .
 .P
 Loading a path simply means adding the desired location to the \fB$fish_function_path\fR array\. See also \fBfunctions(1)\fR\.
 .
 .P
-Here is a snapshot of a typical configuration path with a single plugin and prompt:
+Here is a snapshot of an example Fisherman configuration path with a single plugin and prompt:
 .
 .IP "" 4
 .
@@ -86,10 +86,10 @@ $fisher_config
 .IP "" 0
 .
 .P
-If you are already familiar in the way fish handles your user configuration, you will find the above structure similar to \fB$XDG_CONFIG_HOME/fish\fR\. See \fBInitialization Files\fR in \fBhelp fish\fR to learn more about fish configuration\.
+If you are already familiar in the way Fish handles your user configuration, you will find the above structure similar to \fB$XDG_CONFIG_HOME/fish\fR\. See \fBInitialization Files\fR in \fBhelp fish\fR to learn more about fish configuration\.
 .
 .P
-\fBconf\.d\fR, short for configuration directory, is used for initialization files, i\.e\., files that should run at the start of the shell\. Files that follow the naming convention \fB<name>\.config\.fish\fR are added there\.
+\fBconf\.d\fR, short for configuration directory, is used for initialization files, i\.e\., files that should run at the start of the shell\. Files that follow the naming convention \fB<my_plugin>\.config\.fish\fR are added there\. If a file does not follow the \fB<my_plugin>\.config\.fish\fR convention, \fB<my_plugin>\fR will be added during the installation process\.
 .
 .SS "PLUGINS"
 Plugins are components that extend and add features to your shell\. To see what plugins are available use \fBfisher search\fR\. You can also type \fBfisher install\fR and hit \fItab\fR once to get formatted plugin information\. The same works for \fBfisher update\fR and \fBfisher uninstall\fR\.
@@ -98,10 +98,10 @@ Plugins are components that extend and add features to your shell\. To see what
 To learn how to create plugins, see \fBfisher help plugins\fR\.
 .
 .P
-You can install a plugin by their name, URL or path to a local project\.
+You can install a plugin by their name, URL or by indicating the path to a local plugin project\.
 .
 .P
-If you use a \fIname\fR, this must be listed in the index database\. See \fBIndex\fR\.
+In order to install a plugin by \fIname\fR, it must be already published in the index database\. See \fBIndex\fR\.
 .
 .IP "" 4
 .
@@ -179,19 +179,19 @@ Shortcuts to other common Git repository hosting services are also available:
 Because of Fisherman\'s flat tree model, there is no technical distinction between plugins or prompts\. Installing a prompt is equivalent to switching themes in other systems\. The interface is always \fIinstall\fR, \fIupdate\fR or \fIuninstall\fR\.
 .
 .P
-Throughout this document and other Fisherman manuals you will find the term prompt when referring to the \fIconcept\fR of a theme, i\.e\., a plugin that defines a \fBfish_prompt\fR and / or \fBfish_right_prompt\fR functions\.
+Throughout this document and other Fisherman manuals you will find the term prompt when referring to the \fIconcept\fR of a theme, i\.e\., a plugin that defines a \fBfish_prompt\fR / \fBfish_right_prompt\fR function/s\.
 .
 .SS "INDEX"
-You can install, update and uninstall plugins by name, querying the Fisherman index, or by URL using several of the variations described in \fBPlugins\fR\. The index is a plain text flat database \fIindependent\fR from Fisherman\. You can use a custom index file by setting \fB$fisher_index\fR to your own file or URL\. Redirection urls are not supported due to security and performance concerns\. See \fBfisher help config\fR\.
+You can install, update and uninstall plugins by their name, querying the Fisherman index\. The index is a plain text flat database independently managed\. You can use a custom index file by setting \fB$fisher_index\fR to your own file or URL\. Redirection URLs are currently not supported due to security and performance concerns\. See \fBfisher help config\fR\.
 .
 .P
-A copy of the index is downloaded each time a query happens\. This keeps the index up to date and allows you to search the database offline\.
+A copy of the index is downloaded each time a search query takes place, \fB$fisher_update_interval\fR seconds since the last update\. \fB$fisher_update_interval\fR is 10 seconds by default if not set\. This helps keeping the index up to date and allows you to search the database offline\.
 .
 .P
-The index is a list of records, each consisting of the following fields:
+The index itself is a list of records, each consisting of the following fields:
 .
 .IP "\(bu" 4
-\fBname\fR, \fBurl\fR, \fBinfo\fR, \fBauthor\fR and one or more \fBtags\fR\.
+\fBname\fR, \fBurl\fR, \fBinfo\fR, one or more \fBtags\fR and \fBauthor\fR\.
 .
 .IP "" 0
 .
@@ -204,8 +204,8 @@ Fields are separated by a new line \fB\'\en\'\fR\. Tags are separated by one \fI
 
 shark
 https://github\.com/bucaran/shark
-Sparklines for your Fish
-graph spark data
+Fantastic Sparkline Generator
+chart tool report sparkline graph
 bucaran
 .
 .fi
@@ -229,7 +229,7 @@ fisher install submit
 For usage see the bundled documentation \fBfisher help submit\fR\.
 .
 .P
-You can also submit a new plugin manually and create a pull request\.
+You can also submit a new plugin manually and create a pull request in the index repository (github\.com/fisherman/fisher\-index):
 .
 .IP "" 4
 .
@@ -245,20 +245,17 @@ open http://github\.com
 .
 .IP "" 0
 .
-.P
-Now you can create a new pull request in the upstream repository\.
-.
 .SS "CACHE"
-Downloaded plugins are tracked as Git repositories under \fB$fisher_cache\fR\. See \fBfisher help config\fR to find out about other Fisherman configuration variables\.
+Downloaded plugins are stored as Git repositories under \fB$fisher_cache\fR\. See \fBfisher help config\fR to find out about other Fisherman configuration variables\.
 .
 .P
-When you install or uninstall a plugin, Fisherman downloads the repository to the cache and copies only the relevant files from the cache to the loaded function and / or completion path\. In addition, man pages are added to the corresponding man directory and if a Makefile is detected, the command \fBmake\fR is run\.
-.
-.P
-The cache also provides a location for a local copy of the Index\.
+When you install or uninstall a plugin, Fisherman downloads the repository to the cache and copies only the relevant files from the cache to the loaded function and / or completion path\. In this sense, this location works also like an intermediate \fBstage\fR\. In addition, manual pages are added to the corresponding man directory and if a Makefile is also detected, the command \fBmake\fR is run\.
 .
 .SS "FISHFILES"
-Dependency manifest file, or fishfiles for short, let you share plugin configurations across multiple installations, allow plugins to declare dependencies, and prevent information loss in case of system failure\. See \fBfisher help fishfile\fR\.
+Fishfiles let you share plugin configurations across multiple installations, let plugins declare dependencies and teach Fisherman what plugins are currently enabled / disabled when using \fBfisher \-\-list\fR\.
+.
+.P
+Your fishfile is stored in \fB$fisher_config/fishfile\fR by default, but you can customize its location setting \fB$fisher_file\fR in your user fish configuration file\.
 .
 .P
 Here is an example fishfile inside \fB$fisher_config\fR:
@@ -267,12 +264,11 @@ Here is an example fishfile inside \fB$fisher_config\fR:
 .
 .nf
 
-# my plugins
+# Ahoy! This is my Fishfile
 gitio
 fishtape
-
-# my links
-github/bucaran/shark
+shark
+get
 .
 .fi
 .
@@ -281,14 +277,11 @@ github/bucaran/shark
 .P
 The fishfile updates as you install / uninstall plugins\. See also \fBfisher help install\fR or \fBfisher help uninstall\fR\.
 .
-.P
-Plugins may list any number of dependencies to other plugins in a fishfile at the root of each project\. By default, when Fisherman installs a plugin, it will also fetch and install its dependencies\. If a dependency is already installed, it will not be updated as this could potentially break other plugins using an older version\. For the same reasons, uninstalling a plugin does not remove its dependencies\. See \fBfisher help update\fR\.
-.
 .SS "CONFIGURATION"
-Fisherman allows a high level of configuration using \fB$fisher_*\fR variables\. You can customize the home and configuration directories, debug log file, cache location, index source URL, command aliases, etc\. See \fBfisher help config\fR\.
+Fisherman allows a high level of configuration using \fB$fisher_*\fR variables\. You can customize the home and configuration directories, cache and fishfile location, index source URL, command aliases, etc\. See \fBfisher help config\fR\.
 .
 .P
-You can also extend Fisherman by adding new commands and ship them as plugins as well\. Fisherman automatically adds completions to \fIcommands\fR based in the function \fIdescription\fR and usage help if provided\. See \fBfisher help help\fR and \fBfisher help commands\fR\.
+You can also extend Fisherman by adding new commands and ship them as plugins\. Fisherman automatically adds completions to \fIcommands\fR based in the function \fIdescription\fR and usage help if provided\. See \fBfisher help help\fR and \fBfisher help commands\fR\.
 .
 .P
 To add completions to standalone utility plugins, use \fBcomplete(1)\fR\.
@@ -303,22 +296,22 @@ Most commands read the standard input by default when no options are given and p
 Fisherman also ships with a CLI options parser and a background job wait spinner that you can use to implement your own commands CLI\. See \fBgetopts(1)\fR and \fBwait(1)\fR\.
 .
 .SH "COMPATIBILITY"
-Fisherman supports Oh My Fish! (Wahoo) themes and plugins by default, but some features are turned off due to performance considerations\.
+Fisherman supports Oh My Fish! themes and plugins, but some features are turned off by default for performance reasons\.
 .
 .P
-Oh My Fish! evaluates every \fI\.fish\fR file inside the root directory of every plugin during initialization\. This is necessary in order to register any existing \fBinit\fR events and invoke them using fish \fBemit(1)\fR\.
+Oh My Fish! evaluates every \fI\.fish\fR file inside the root directory for every plugin installed during shell start\. This is necessary in order to load any existing \fBinit\fR event functions and immediately invoke them using fish \fBemit(1)\fR\.
 .
 .P
 Since it is not possible to determine whether a file defines an initialization event without evaluating its contents first, Oh My Fish! sources all \fB*\.fish\fR files and then emits events for each plugin\.
 .
 .P
-Not all plugins opt in the initialization mechanism, therefore support for this behavior is turned off by default\. If you would like Fisherman to behave like Oh My Fish! at the start of every session, install the \fBomf\fR compatibility plugin\.
+Not all plugins opt in the initialization mechanism, therefore support for this behavior is turned off by default\. If you would like Fisherman to behave like Oh My Fish! at the start of the shell session, install the \fBlegacy\fR compatibility plugin\.
 .
 .IP "" 4
 .
 .nf
 
-fisher install omf
+fisher install legacy
 .
 .fi
 .
diff --git a/man/man7/fisher-tour.md b/man/man7/fisher-tour.md
index f807727..c3ce395 100644
--- a/man/man7/fisher-tour.md
+++ b/man/man7/fisher-tour.md
@@ -3,17 +3,17 @@ fisher-tour(7) -- Fisherman Tour
 
 ## DESCRIPTION
 
-Fisherman is a blazing fast, modern plugin manager for Fish.
+Fisherman is a blazing fast, modern plugin manager for `fish(1)`.
 
-Fisherman uses a flat tree structure that adds no cruft to your shell, making it as fast as no Fisherman. The cache mechanism lets you query the index offline and enable or disable plugins as you wish.
+Fisherman runs virtually no initialization code, making it as fast as no Fisherman. The cache mechanism lets you query the index offline and enable or disable plugins as you wish.
 
-Other features include dependency management, great plugin search capabilities and full compatibility with Tackle, Oh My Fish! and Wahoo themes and packages.
+Other features include dependency management, excellent test coverage, plugin search capabilities and full compatibility with Tackle, Oh My Fish! and Wahoo themes and plugins.
 
 This document describes Fisherman features and their implementation details. For usage and command help  see `fisher(1)`.
 
 ## FLAT TREE
 
-The configuration directory structure is optimized to help your shell start new sessions as quickly as possible, regardless of the numbers of plugins or prompts enabled at any given time. An old saying goes that Fisherman is as fast as no Fisherman.
+The configuration directory structure is optimized to help your shell start new sessions as quickly as possible, regardless of the numbers of plugins or prompts enabled at any given time.
 
 To explain how this is possible, we need to make a digression and discuss function scope first. In fish, all functions share the same scope and you can use only one name per function.
 
@@ -33,33 +33,35 @@ end
 
 *foo* and *bar* are available immediately at the command line prompt and both print their names. But there is a catch, calling *foo* at least once will create a new *bar* function, effectively erasing the previous *bar* definition. Subsequent calls to *bar* will print nothing.
 
-By convention, functions that start with any number of underscores are *intentionally* private, but there is no mechanism that prevents you from calling them at any time once loaded.
+By convention, functions that start with any number of underscores are *intentionally* private, but there is no mechanism that prevents you from calling them once they are loaded.
 
 With this in mind, it's possible to improve the slow shell start problem using a *flat* tree structure whose path is loaded only once.
 
-The overhead of juggling multiple path hierarchies in a per-plugin basis yields no benefits as everything is shared in the same scope.
+The overhead of juggling multiple path hierarchies in a per-plugin basis yields no benefits as everything is shared inside the same scope.
 
 Loading a path simply means adding the desired location to the `$fish_function_path` array. See also `functions(1)`.
 
-Here is a snapshot of a typical configuration path with a single plugin and prompt:
+Here is a snapshot of an example Fisherman configuration path with a single plugin and prompt:
 
-    $fisher_config
-    |-- cache/
-    |-- conf.d/
-    |-- |-- my_plugin.config.fish
-    |-- functions/
-    |   |-- my_plugin.fish
-    |   |-- fish_prompt.fish
-    |   |-- fish_right_prompt.fish
-    |-- completions/
-    |   |-- my_plugin.fish
-    |-- man/
-        |-- man1/
-            |-- my_plugin.1
+```
+$fisher_config
+|-- cache/
+|-- conf.d/
+|-- |-- my_plugin.config.fish
+|-- functions/
+|   |-- my_plugin.fish
+|   |-- fish_prompt.fish
+|   |-- fish_right_prompt.fish
+|-- completions/
+|   |-- my_plugin.fish
+|-- man/
+    |-- man1/
+        |-- my_plugin.1
+```
 
-If you are already familiar in the way fish handles your user configuration, you will find the above structure similar to `$XDG_CONFIG_HOME/fish`. See `Initialization Files` in `help fish` to learn more about fish configuration.
+If you are already familiar in the way Fish handles your user configuration, you will find the above structure similar to `$XDG_CONFIG_HOME/fish`. See `Initialization Files` in `help fish` to learn more about fish configuration.
 
-`conf.d`, short for configuration directory, is used for initialization files, i.e., files that should run at the start of the shell. Files that follow the naming convention `<name>.config.fish` are added there.
+`conf.d`, short for configuration directory, is used for initialization files, i.e., files that should run at the start of the shell. Files that follow the naming convention `<my_plugin>.config.fish` are added there. If a file does not follow the `<my_plugin>.config.fish` convention, `<my_plugin>` will be added during the installation process.
 
 ### PLUGINS
 
@@ -67,9 +69,9 @@ Plugins are components that extend and add features to your shell. To see what p
 
 To learn how to create plugins, see `fisher help plugins`.
 
-You can install a plugin by their name, URL or path to a local project.
+You can install a plugin by their name, URL or by indicating the path to a local plugin project.
 
-If you use a *name*, this must be listed in the index database. See `Index`.
+In order to install a plugin by *name*, it must be already published in the index database. See `Index`.
 
 ```
 fisher install shark
@@ -97,25 +99,25 @@ Shortcuts to other common Git repository hosting services are also available:
 
 Because of Fisherman's flat tree model, there is no technical distinction between plugins or prompts. Installing a prompt is equivalent to switching themes in other systems. The interface is always *install*, *update* or *uninstall*.
 
-Throughout this document and other Fisherman manuals you will find the term prompt when referring to the *concept* of a theme, i.e., a plugin that defines a `fish_prompt` and / or `fish_right_prompt` functions.
+Throughout this document and other Fisherman manuals you will find the term prompt when referring to the *concept* of a theme, i.e., a plugin that defines a `fish_prompt` / `fish_right_prompt` function/s.
 
 ### INDEX
 
-You can install, update and uninstall plugins by name, querying the Fisherman index, or by URL using several of the variations described in `Plugins`. The index is a plain text flat database *independent* from Fisherman. You can use a custom index file by setting `$fisher_index` to your own file or URL. Redirection urls are not supported due to security and performance concerns. See `fisher help config`.
+You can install, update and uninstall plugins by their name, querying the Fisherman index. The index is a plain text flat database independently managed. You can use a custom index file by setting `$fisher_index` to your own file or URL. Redirection URLs are currently not supported due to security and performance concerns. See `fisher help config`.
 
-A copy of the index is downloaded each time a query happens. This keeps the index up to date and allows you to search the database offline.
+A copy of the index is downloaded each time a search query takes place, `$fisher_update_interval` seconds since the last update. `$fisher_update_interval` is 10 seconds by default if not set. This helps keeping the index up to date and allows you to search the database offline.
 
-The index is a list of records, each consisting of the following fields:
+The index itself is a list of records, each consisting of the following fields:
 
-* `name`, `url`, `info`, `author` and one or more `tags`.
+* `name`, `url`, `info`, one or more `tags` and `author`.
 
 Fields are separated by a new line `'\n'`. Tags are separated by one *space*. Here is a sample record:
 
 ```
 shark
 https://github.com/bucaran/shark
-Sparklines for your Fish
-graph spark data
+Fantastic Sparkline Generator
+chart tool report sparkline graph
 bucaran
 ```
 
@@ -127,7 +129,7 @@ fisher install submit
 
 For usage see the bundled documentation `fisher help submit`.
 
-You can also submit a new plugin manually and create a pull request.
+You can also submit a new plugin manually and create a pull request in the index repository (github.com/fisherman/fisher-index):
 
 ```
 git clone https://github.com/fisherman/fisher-index
@@ -137,41 +139,36 @@ git push origin master
 open http://github.com
 ```
 
-Now you can create a new pull request in the upstream repository.
-
 ### CACHE
 
-Downloaded plugins are tracked as Git repositories under `$fisher_cache`. See `fisher help config` to find out about other Fisherman configuration variables.
+Downloaded plugins are stored as Git repositories under `$fisher_cache`. See `fisher help config` to find out about other Fisherman configuration variables.
 
-When you install or uninstall a plugin, Fisherman downloads the repository to the cache and copies only the relevant files from the cache to the loaded function and / or completion path. In addition, man pages are added to the corresponding man directory and if a Makefile is detected, the command `make` is run.
-
-The cache also provides a location for a local copy of the Index.
+When you install or uninstall a plugin, Fisherman downloads the repository to the cache and copies only the relevant files from the cache to the loaded function and / or completion path. In this sense, this location works also like an intermediate `stage`. In addition, manual pages are added to the corresponding man directory and if a Makefile is also detected, the command `make` is run.
 
 ### FISHFILES
 
-Dependency manifest file, or fishfiles for short, let you share plugin configurations across multiple installations, allow plugins to declare dependencies, and prevent information loss in case of system failure. See `fisher help fishfile`.
+Fishfiles let you share plugin configurations across multiple installations, let plugins declare dependencies and teach Fisherman what plugins are currently enabled / disabled when using `fisher --list`.
+
+Your fishfile is stored in `$fisher_config/fishfile` by default, but you can customize its location setting `$fisher_file` in your user fish configuration file.
 
 Here is an example fishfile inside `$fisher_config`:
 
 ```
-# my plugins
+# Ahoy! This is my Fishfile
 gitio
 fishtape
-
-# my links
-github/bucaran/shark
+shark
+get
 ```
 
 The fishfile updates as you install / uninstall plugins. See also `fisher help install` or `fisher help uninstall`.
 
-Plugins may list any number of dependencies to other plugins in a fishfile at the root of each project. By default, when Fisherman installs a plugin, it will also fetch and install its dependencies. If a dependency is already installed, it will not be updated as this could potentially break other plugins using an older version. For the same reasons, uninstalling a plugin does not remove its dependencies. See `fisher help update`.
-
 
 ### CONFIGURATION
 
-Fisherman allows a high level of configuration using `$fisher_*` variables. You can customize the home and configuration directories, debug log file, cache location, index source URL, command aliases, etc. See `fisher help config`.
+Fisherman allows a high level of configuration using `$fisher_*` variables. You can customize the home and configuration directories, cache and fishfile location, index source URL, command aliases, etc. See `fisher help config`.
 
-You can also extend Fisherman by adding new commands and ship them as plugins as well. Fisherman automatically adds completions to *commands* based in the function *description* and usage help if provided. See `fisher help help` and `fisher help commands`.
+You can also extend Fisherman by adding new commands and ship them as plugins. Fisherman automatically adds completions to *commands* based in the function *description* and usage help if provided. See `fisher help help` and `fisher help commands`.
 
 To add completions to standalone utility plugins, use `complete(1)`.
 
@@ -185,7 +182,7 @@ Fisherman also ships with a CLI options parser and a background job wait spinner
 
 ## COMPATIBILITY
 
-Fisherman supports Oh My Fish! themes and plugins by default, but some features are turned off due to performance considerations.
+Fisherman supports Oh My Fish! themes and plugins, but some features are turned off by default for performance reasons.
 
 Oh My Fish! evaluates every *.fish* file inside the root directory for every plugin installed during shell start. This is necessary in order to load any existing `init` event functions and immediately invoke them using fish `emit(1)`.