diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3f16449..0a95840 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,13 @@
# Change Log
+## [1.2.0][v120] - TBA
+
+* Merge tutorial and CLI documentation into one document.
+
+* Update README with new simplified documentation.
+
+* Tweak fisher help menu to highlight command aliases.
+
## [1.2.0][v120] - 2016-03-08
* Introduce set_color_custom function that prompts can define to customize *fish_color_* variables. The current color palette is saved to $fisher_config/fish_colors and restored when the prompt is disabled / uninstalled #144.
diff --git a/Makefile b/Makefile
index e6b4278..3125996 100644
--- a/Makefile
+++ b/Makefile
@@ -10,8 +10,7 @@ FISHER_FILE := $(FISHER_CONFIG)/fishfile
MAN := $(FISHER_HOME)/man
MAN1 := $(wildcard $(MAN)/man1/*.md)
-MAN7 := $(wildcard $(MAN)/man7/*.md)
-DOCS := $(MAN1:%.md=%.1) $(MAN7:%.md=%.7)
+DOCS := $(MAN1:%.md=%.1)
INDEX := $(FISHER_CACHE)/.index
VERSION = `cat $(FISHER_HOME)/VERSION`
@@ -57,7 +56,7 @@ $(FISHER_CACHE):
$(FISHER_FILE):
touch $@
-%.1 %.7: %.md
+%.1 : %.md
-@if type ronn 2>/dev/null 1>&2; then \
ronn --manual=fisherman --roff $? 1>&2 2> /dev/null;\
fi;\
diff --git a/README.md b/README.md
index 6363e4c..b9cc730 100644
--- a/README.md
+++ b/README.md
@@ -14,12 +14,7 @@
-
-**Fisherman** is a blazing fast, modern plugin manager for [fish].
-
-
- ▸ **[Get Started]**
- ▸ **[Plugins]**
+**[Fisherman]** is a blazing fast, modern plugin manager for [fish].
```fish
curl -sL get.fisherman.sh | fish
@@ -27,6 +22,485 @@ curl -sL get.fisherman.sh | fish
[![play]][play-link]
+If you don't have Fish, you need to install it too. Install instructions can be found here.
+
+## Setup
+
+Download Fisherman using Git and setup your system automatically. See [other] install options.
+
+```fish
+curl -sL get.fisherman.sh | fish
+```
+
+## CLI
+
+The Fisherman CLI consists of the following commands: *install*, *update*, *uninstall*, *list*, *search* and *help*.
+
+Fisherman knows the following aliases too: *i* for install, *u* for update, *l* for list, *s* for search and *h* for help.
+
+### Examples
+
+* Update Fisherman.
+
+```fish
+fisher update
+```
+
+* Install plugins.
+
+```fish
+fisher install fishtape shark get
+```
+
+* Install a plugin from a local directory.
+
+```fish
+fisher install ./path/to/plugin
+```
+
+* Install a plugin from a URL.
+
+```fish
+fisher install owner/repo
+```
+
+* Install a plugin from a Gist URL.
+
+```fish
+fisher install gist.github.com/owner/1f40e1c6e0551b2666b2
+```
+
+* Update plugins.
+
+```fish
+fisher update shark get
+```
+
+* Uninstall plugins.
+
+```fish
+fisher uninstall fishtape debug
+```
+
+* Uninstall plugins and remove them from the cache.
+
+```fish
+fisher uninstall fishtape debug -f
+```
+
+* Show the documentation.
+
+```fish
+fisher help
+```
+
+## List and search
+
+The list command displays all the plugins you have installed. The search command queries the index to show what's available to install.
+
+* List installed plugins.
+
+```
+fisher list
+ debug
+* fishtape
+> shellder
+* spin
+@ wipe
+```
+
+The legend consists of:
+
+* `*` The plugin is currently enabled
+* `>` The plugin is a prompt
+* `@` The plugin is a symbolic link
+
+
+* Search the index.
+
+```
+fisher search
+ ...
+* debug Conditional debug logger
+ errno POSIX error code/string translator
+* fishtape TAP producing test runner
+ flash Flash-inspired, thunder prompt
+ fzf Efficient keybindings for fzf
+ get Press any key to continue
+ ...
+> shellder Powerline prompt optimized for speed
+ ...
+```
+
+* Get detailed information about a plugin.
+
+```
+fisher search shellder
+> shellder by simnalamburt
+Powerline prompt optimized for speed
+github.com/simnalamburt/shellder
+```
+
+* Search plugins using tags.
+
+```
+fisher search --tag={git,test}
+ ...
+* fishtape TAP producing test runner
+ git-branch-name Get the name of the current Git branch
+ git-is-repo Test if the current directory is a Git repo
+ git-is-dirty Test if there are changes not staged for commit
+ git-is-stashed Test if there are changes in the stash
+ ...
+```
+
+## Plumbing
+
+Fisherman commands are pipe aware. Plumb one with another to create complex functionality.
+
+* Update all the plugins in the cache.
+
+```fish
+fisher list | fisher update -
+```
+
+* Enable all the plugins that are currently disabled.
+
+```fish
+fisher list --disabled | fisher install
+```
+
+* Uninstall all the plugins and remove them from the cache.
+
+```fish
+fisher list | fisher uninstall --force
+```
+
+## Dotfiles
+
+When you install a plugin, Fisherman updates a file known as *fishfile* to track what plugins are currently enabled.
+
+* Customize the location of the fishfile.
+
+```fish
+set -g fisher_file ~/.dotfiles/fishfile
+```
+
+## Flat Tree
+
+Fisherman merges the directory trees of all the plugins it installs into a single flat tree. Since the flat tree is loaded only once at the start of the shell, Fisherman performs equally well, regardless of the number of plugins installed.
+
+The following illustrates an example Fisherman configuration path with a single plugin and prompt.
+
+```
+$fisher_config
+|-- cache/
+|-- conf.d/
+| `-- my_plugin.config.fish
+|-- fishfile
+|-- functions/
+| |-- my_plugin.fish
+| |-- fish_prompt.fish
+| `-- fish_right_prompt.fish
+|-- completions/
+| `-- my_plugin.fish
+`-- man/
+ `-- man1/
+ `-- my_plugin.1
+```
+
+## Index
+
+The index is a plain text database that lists Fisherman official plugins.
+
+The index is a list of records, each consisting of the following fields: *name*, *url*, *info*, one or more *tags* and *author*.
+
+Fields are separated by a new line `\n`. Tags are separated by one *space*.
+
+```
+z
+https://github.com/fishery/fish-z
+Pure-fish z directory jumping
+z search cd jump
+jethrokuan
+```
+
+If you have a plugin you would like to submit to the index, use the submit plugin.
+
+```
+fisher install submit
+fisher submit my_plugin
+```
+
+Otherwise, submit the plugin manually by creating a pull request in the index repository *https://github.com/fisherman/fisher-index*.
+
+```
+git clone https://github.com/fisherman/fisher-index
+cd index
+echo "$name\n$url\n$info\n$tags\n$author\n\n" >> index
+git push origin master
+```
+
+## Fishfile
+
+Fisherman keeps track of a special file known as *fishfile* to know what plugins are currently enabled.
+
+```
+# My Fishfile
+gitio
+fishtape
+shark
+get
+shellder
+```
+
+This file is automatically updated as you install and uninstall plugins.
+
+## Variables
+
+* $fisher_home
+ The home directory. If you installed Fisherman using the recommended method `curl -sL install.fisherman.sh | fish`, the location ought to be *XDG_DATA_HOME/fisherman*. If you clone Fisherman and run make yourself, the current working directory is used by default.
+
+* $fisher_config
+ The configuration directory. This is default location of the *fishfile*, *key_bindings.fish*, *cache*, *functions*, *completions* and *conf.d* directories. The default location is *XDG_CONFIG_HOME/fisherman*.
+
+* $fisher_file
+ See FISHFILE above.
+
+* $fisher_cache
+ The cache directory. Plugins are downloaded to this location.
+
+* $fisher_alias *command*=*alias*[,*alias2*] ...
+ Use this variable to customize Fisherman command aliases.
+
+## Plugins
+
+Plugins can be utilities, prompts, commands or snippets.
+
+### Utilities
+
+Utilities are plugins that define one or more functions which are mean to be used in the CLI directly by the user.
+
+This example walks you through creating *wtc*, a plugin based in [ngerakines/commitment](https://github/ngerakines/commitment) random commit message generator.
+
+* Create a directory and initialize a Git repository.
+
+```fish
+mkdir wtc
+cd wtc
+git init
+git remote add origin https://github.com//wtc
+```
+
+* Add the wtc function.
+
+```fish
+function wtc -d "Generate a random commit message"
+ switch "$argv"
+ case -h --help
+ printf "Usage: wtc [--help]\n\n"
+ printf " -h --help Show usage help\n"
+ return
+ end
+ curl -s whatthecommit.com/index.txt
+end
+```
+
+* Install the plugin.
+
+```fish
+fisher install .
+wtc
+(\ /)
+(O.o)
+(> <) Bunny approves these changes.
+```
+
+* Commit changes and push to your remote origin when you are done.
+
+```fish
+git add --all
+git commit -m "What the commit?"
+git push origin master
+```
+
+### Submit
+
+To submit wtc to the official index.
+
+```fish
+fisher install submit
+fisher submit
+```
+
+This will create a PR in the Fisherman index repository. Once the PR is approved, Fisherman users will be able to install wtc if they have the latest index.
+
+```fish
+fisher install wtc
+```
+
+See `fisher help submit` for more submit options.
+
+### Completions
+
+Create a completions directory and add a completions file.
+
+```fish
+mkdir completions
+cat > completions/wtc.fish
+complete --command wtc --short h --long help --description "Show usage help"
+^
+```
+
+Alternatively, use `__fisher_complete` to create completions from wtc usage output.
+
+```
+wtc --help | __fisher_complete wtc
+```
+
+### Docs
+
+Create a man/man1 directory and add a man(1) page for wtc.
+
+There are utilities that can help you generate man pages from various text formats. For example, pandoc(1) and ronn(1).
+
+To create a man page manually.
+
+```fish
+mkdir -p man/man1
+cat > man/man1/wtc.1
+
+ .TH man 1 "Today" "1.0" "wtc man page"
+ .SH NAME
+ wtc \- Generate a random commit message
+ .SH SYNOPSIS
+ wtc [--help]
+ .SH OPTIONS
+ -h, --help: Display help information.
+ .SH SEE ALSO
+ https://github.com/ngerakines/commitment
+^C
+```
+
+### Dependencies
+
+A plugin can list dependencies to other plugins using a *fishfile*.
+
+Create a new file in the root of your project and add the name or URL of your desired dependencies.
+
+```fish
+cat > fishfile
+my_plugin
+https://github.com/owner/another_plugin
+^D
+```
+
+### Prompts
+
+Prompts, also known as themes, are plugins that modify the appearance of the shell prompt and modify fish syntax colors.
+
+Create a `fish_prompt` function.
+
+```fish
+function fish_prompt
+ printf "%s (%s) >> " (prompt_pwd) Fisherman
+end
+~ (Fisherman) >> type here
+```
+
+To add a right prompt, create a `fish_right_prompt` function.
+
+```fish
+function fish_right_prompt
+ printf "%s" (date +%H:%M:%S)
+end
+```
+
+Save the functions to a directory and install the prompt as a plugin.
+
+```fish
+mkdir my_prompt
+cd my_prompt
+functions fish_prompt > fish_prompt.fish
+functions fish_right_prompt > fish_right_prompt.fish
+fisher install .
+```
+
+Customize the colors fish uses for syntax highlighting.
+
+```fish
+function set_color_custom
+ set -U fish_color_normal normal
+ set -U fish_color_command yellow
+ set -U fish_color_param white
+end
+functions set_color_custom > set_color_custom.fish
+fisher update .
+```
+
+### Commands
+
+Commands are plugins that extend the Fisherman CLI adding new `fisher `.
+
+Create a function `fisher_`
+
+```fish
+function fisher_time -d "Say hello"
+ printf "It's %s\n" (date +%H:%M)
+end
+```
+
+Test it works
+
+```fish
+fisher time
+It's 6:30
+```
+
+Make it a plugin
+
+
+```fish
+fisher install fisher_time
+```
+
+This creates a new directory fisher_time in the current working directory and installs the plugin.
+
+The following example implements a command to format plugin information into columns.
+
+```fish
+function fisher_info -d "Display information about plugins"
+ switch "$argv"
+ case -h --help
+ printf "Usage: fisher info [...]\n\n"
+ printf " -h --help Show usage help\n"
+ return
+ end
+
+ for item in $argv
+ fisher search $item --name --info
+ end | sed -E 's/;/: /' | column
+end
+
+fisher install fisher_info
+```
+
+### Snippets
+
+Snippets are plugins that run code at the start of the shell. Snippets must be placed inside a sub directory named conf.d.
+
+The following example implements the fish_postexec hook to display the runtime of the last command in milliseconds.
+
+```fish
+mkdir -p runtime/conf.d
+cd runtime
+cat > conf.d/fish_postexec.fish
+function fish_postexec --on-event fish_postexec
+ printf "%sms\n" $CMD_DURATION > /dev/stderr
+end
+^D
+fisher install ./postexec
+```
[travis-link]: https://travis-ci.org/fisherman/fisherman
[travis-badge]: https://img.shields.io/travis/fisherman/fisherman.svg?style=flat-square
@@ -43,3 +517,6 @@ curl -sL get.fisherman.sh | fish
[Get Started]: https://github.com/fisherman/fisherman/wiki
[Plugins]: http://fisherman.sh/#search
[fish]: https://github.com/fish-shell/fish-shell
+
+[other]: https://github.com/fisherman/fisherman/wiki/Installing-Fisherman#notes
+[Fisherman]: http://fisherman.sh
diff --git a/completions/fisher.fish b/completions/fisher.fish
index 3c011a5..b087ec4 100644
--- a/completions/fisher.fish
+++ b/completions/fisher.fish
@@ -1,16 +1,11 @@
set -l IFS ";"
complete -xc fisher
-
+complete -c fisher -a "fisherman" -d "Update Fisherman" -n "__fish_seen_subcommand_from update"
+complete -c fisher -a "tutorial" -d "An introduction to Fisherman" -n "__fish_seen_subcommand_from help"
complete -c fisher -n "__fish_use_subcommand" -s h -l help -d "Show usage help"
complete -c fisher -n "__fish_use_subcommand" -s v -l version -d "Show version information"
-complete -c fisher -a "fisherman" -d "Update Fisherman" -n "__fish_seen_subcommand_from update"
-
-__fisher_help_guides | while read -l guide info
- complete -c fisher -n "__fish_seen_subcommand_from help" -a $guide -d "$info"
-end
-
__fisher_help_commands | while read -l command info
complete -c fisher -n "__fish_use_subcommand" -a $command -d "$info"
complete -c fisher -n "__fish_seen_subcommand_from help" -a $command -d "$info"
diff --git a/functions/__fisher_help_guides.fish b/functions/__fisher_help_guides.fish
deleted file mode 100644
index 7271775..0000000
--- a/functions/__fisher_help_guides.fish
+++ /dev/null
@@ -1,4 +0,0 @@
-function __fisher_help_guides
- sed -nE 's/(fisher-)?(.+)\([0-9]\) -- (.+)/\2;\3/p' \
- {$fisher_home,$fisher_config}/man/man{5,7}/fisher*.md | sort -r
-end
diff --git a/functions/fisher.fish b/functions/fisher.fish
index f52e0ef..7ddffe6 100644
--- a/functions/fisher.fish
+++ b/functions/fisher.fish
@@ -33,7 +33,7 @@ function fisher -d "Fish plugin manager"
case \*
if test -z "$fisher_alias"
- set fisher_alias install=i update=u search=s list=l help=h
+ set -g fisher_alias install=i update=u search=s list=l help=h
end
printf "%s\n" $fisher_alias | sed 's/[=,]/ /g' | while read -la alias
@@ -66,27 +66,21 @@ function fisher -d "Fish plugin manager"
sed 's/^/fisher version /' $fisher_home/VERSION
case help
- if test -z "$value"
- set value commands
- end
-
printf "Usage: fisher [] [--help] [--version]\n\n"
- switch commands
- case $value
- printf "Available Commands:\n"
- fisher_help --commands=bare
- echo
- end
+ set -l color (set_color $fish_color_command -u)
+ set -l color_normal (set_color normal)
- switch guides
- case $value
- printf "Other Documentation:\n"
- fisher_help --guides=bare
- echo
- end
+ printf "Available Commands:\n"
- printf "Use 'fisher help -g' to list guides and other documentation.\n"
- printf "See 'fisher help ' to access a man page.\n"
+ fisher_help --commands=bare | sed -E "
+ s/ (h)/ $color\1$color_normal/
+ s/ (i)/ $color\1$color_normal/
+ s/ (l)/ $color\1$color_normal/
+ s/ (s)/ $color\1$color_normal/
+ s/ (u)p/ $color\1$color_normal"p"/
+ "
+
+ printf "\nUse fisher help to access a man page.\n"
end
end
diff --git a/functions/fisher_help.fish b/functions/fisher_help.fish
index eb31379..f823a8d 100644
--- a/functions/fisher_help.fish
+++ b/functions/fisher_help.fish
@@ -13,14 +13,6 @@ function fisher_help -d "Show help"
set option man
set value $2
- case a all
- set option guides commands
- set value $2
-
- case g guides
- set option $option guides
- set value $2
-
case commands
set option $option commands
set value $2
@@ -30,10 +22,7 @@ function fisher_help -d "Show help"
set value $value $2
case h
- printf "Usage: fisher help [] [--all] [--guides] [--help]\n\n"
- printf " -a --all List all the documentation\n"
- printf " -g --guides List available guides\n"
- printf " -h --help Show usage help\n"
+ printf "Usage: fisher help [] [--help]\n"
return
case \*
@@ -68,14 +57,8 @@ function fisher_help -d "Show help"
return
end
- begin
- if contains -- commands $option
- __fisher_help_commands
- end
-
- if contains -- guides $option
- __fisher_help_guides
- end
- end | sed 's/^/ /;s/;/'\t'/' | column -ts\t
+ if contains -- commands $option
+ __fisher_help_commands
+ end | sed 's/^/ /;s/;/'\t'/' | column -ts\t
end
end
diff --git a/man/man1/fisher-tutorial.1 b/man/man1/fisher-tutorial.1
new file mode 120000
index 0000000..ba5e5c8
--- /dev/null
+++ b/man/man1/fisher-tutorial.1
@@ -0,0 +1 @@
+/Users/bucaran/c/fisherman/fisherman/man/man1/fisher.1
\ No newline at end of file
diff --git a/man/man1/fisher.1 b/man/man1/fisher.1
index ca23b4b..1352ef3 100644
--- a/man/man1/fisher.1
+++ b/man/man1/fisher.1
@@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
-.TH "FISHER" "1" "February 2016" "" "fisherman"
+.TH "FISHER" "1" "March 2016" "" "fisherman"
.
.SH "NAME"
\fBfisher\fR \- Fish plugin manager
@@ -15,7 +15,7 @@ fisher \fIcommand\fR [\fIarguments\fR] [\-\-version] [\-\-help]
Fisherman is a plugin manager for fish\.
.
.P
-The Fisherman CLI consists of the following commands: \fIinstall\fR, \fIupdate\fR, \fIuninstall\fR, \fIlist\fR, \fIsearch\fR and \fIhelp\fR\.
+The CLI consists of the following commands: \fIinstall\fR, \fIupdate\fR, \fIuninstall\fR, \fIlist\fR, \fIsearch\fR and \fIhelp\fR\.
.
.SH "USAGE"
Run a command\.
@@ -44,7 +44,7 @@ fisher help
.IP "" 0
.
.P
-Fisherman knows the following aliases by default: \fIi\fR for install, \fIu\fR for update, \fIl\fR for list, \fIs\fR for search and \fIh\fR for help\.
+Fisherman knows the following too: \fIi\fR for install, \fIu\fR for update, \fIl\fR for list, \fIs\fR for search and \fIh\fR for help\.
.
.SH "OPTIONS"
.
@@ -57,41 +57,7 @@ Show version information\. Fisherman follows Semantic Versioning and uses Git an
Show usage help\.
.
.SH "EXAMPLES"
-.
-.IP "\(bu" 4
-Install plugins\.
-.
-.IP "" 0
-.
-.IP "" 4
-.
-.nf
-
-fisher install fishtape shark get
-.
-.fi
-.
-.IP "" 0
-.
-.IP "\(bu" 4
-Install a plugin as a symbolic link\.
-.
-.IP "" 0
-.
-.IP "" 4
-.
-.nf
-
-fisher install \./path/to/plugin
-.
-.fi
-.
-.IP "" 0
-.
-.IP "\(bu" 4
-Update Fisherman to the latest version\.
-.
-.IP "" 0
+Update Fisherman\.
.
.IP "" 4
.
@@ -103,26 +69,100 @@ fisher update
.
.IP "" 0
.
-.IP "\(bu" 4
-Search the Fisherman index\.
-.
-.IP "" 0
+.P
+Install plugins\.
.
.IP "" 4
.
.nf
-fisher search
+fisher install fishtape shark get
.
.fi
.
.IP "" 0
.
-.IP "\(bu" 4
-Show all the documentation\.
+.P
+Install a plugin from a local directory\.
+.
+.IP "" 4
+.
+.nf
+
+fisher install \./path/to/plugin
+.
+.fi
.
.IP "" 0
.
+.P
+Install a plugin from a URL\.
+.
+.IP "" 4
+.
+.nf
+
+fisher install owner/repo
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Install a plugin from a Gist URL\.
+.
+.IP "" 4
+.
+.nf
+
+fisher install gist\.github\.com/owner/1f40e1c6e0551b2666b2
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Update plugins\.
+.
+.IP "" 4
+.
+.nf
+
+fisher update shark get
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Uninstall plugins\.
+.
+.IP "" 4
+.
+.nf
+
+fisher uninstall fishtape debug
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Uninstall plugins and remove them from the cache\.
+.
+.IP "" 4
+.
+.nf
+
+fisher uninstall fishtape debug \-f
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Show all the documentation\.
+.
.IP "" 4
.
.nf
@@ -133,9 +173,159 @@ fisher help \-\-all
.
.IP "" 0
.
-.SH "CONCEPTS"
+.SH "LIST AND SEARCH"
+The list command displays all the plugins you have installed\. The search command queries the index to show what\'s available to install\.
.
-.SS "FLAT TREE"
+.P
+List installed plugins\.
+.
+.IP "" 4
+.
+.nf
+
+fisher list
+ debug
+* fishtape
+> shellder
+* spin
+@ wipe
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The legend consists of:
+.
+.P
+\fB*\fR The plugin is currently enabled
+.
+.br
+\fB>\fR The plugin is a prompt
+.
+.br
+\fB@\fR The plugin is a symbolic link
+.
+.br
+.
+.P
+Search the index\.
+.
+.IP "" 4
+.
+.nf
+
+fisher search
+ \.\.\.
+* debug Conditional debug logger
+ errno POSIX error code/string translator
+* fishtape TAP producing test runner
+ flash Flash\-inspired, thunder prompt
+ fzf Efficient keybindings for fzf
+ get Press any key to continue
+ \.\.\.
+> shellder Powerline prompt optimized for speed
+ \.\.\.
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Get detailed information about a plugin\.
+.
+.IP "" 4
+.
+.nf
+
+fisher search shellder
+> shellder by simnalamburt
+Powerline prompt optimized for speed
+github\.com/simnalamburt/shellder
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Search plugins using tags\.
+.
+.IP "" 4
+.
+.nf
+
+fisher search \-\-tag={git,test}
+ \.\.\.
+* fishtape TAP producing test runner
+ git\-branch\-name Get the name of the current Git branch
+ git\-is\-repo Test if the current directory is a Git repo
+ git\-is\-dirty Test if there are changes not staged for commit
+ git\-is\-stashed Test if there are changes in the stash
+ \.\.\.
+.
+.fi
+.
+.IP "" 0
+.
+.SH "PLUMBING"
+Fisherman commands are pipe aware\. Plumb one with another to create complex functionality\.
+.
+.P
+Update all the plugins in the cache\.
+.
+.IP "" 4
+.
+.nf
+
+fisher list | fisher update \-
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Enable all the plugins that are currently disabled\.
+.
+.IP "" 4
+.
+.nf
+
+fisher list \-\-disabled | fisher install
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Uninstall all the plugins and remove them from the cache\.
+.
+.IP "" 4
+.
+.nf
+
+fisher list | fisher uninstall \-\-force
+.
+.fi
+.
+.IP "" 0
+.
+.SH "DOTFILES"
+When you install a plugin, Fisherman updates a file known as \fIfishfile\fR to track what plugins are currently enabled\.
+.
+.P
+To customize its location:
+.
+.IP "" 4
+.
+.nf
+
+set \-g fisher_file ~/\.dotfiles/fishfile
+.
+.fi
+.
+.IP "" 0
+.
+.SH "FLAT TREE"
Fisherman merges the directory trees of all the plugins it installs into a single flat tree\. Since the flat tree is loaded only once at the start of the shell, Fisherman performs equally well, regardless of the number of plugins installed\.
.
.P
@@ -164,42 +354,7 @@ $fisher_config
.
.IP "" 0
.
-.SS "PLUGINS"
-To install plugins, type fisher install and press \fItab\fR once to list all the available plugins\. Similarly, use fisher update / uninstall and press \fItab\fR to see what plugins you can update or uninstall\.
-.
-.P
-To search plugins use fisher search \fIname\fR\. You can by a specific field using fisher search \-\-\fIfield\fR=\fImatch\fR\.
-.
-.IP "" 4
-.
-.nf
-
-fisher search \-\-tag={*keywords*}
-.
-.fi
-.
-.IP "" 0
-.
-.P
-or
-.
-.IP "" 4
-.
-.nf
-
-fisher search \-\-name=*name*
-.
-.fi
-.
-.IP "" 0
-.
-.P
-See fisher help search for advanced options\.
-.
-.P
-To learn how to create plugins enter fisher help tutorial\.
-.
-.SS "INDEX"
+.SH "INDEX"
The index is a plain text database that lists Fisherman official plugins\.
.
.P
@@ -223,7 +378,7 @@ jethrokuan
.IP "" 0
.
.P
-If you have a plugin you would like to submit to the index, use the submit plugin\.
+If you have a plugin to submit to the index, use the \fIsubmit\fR plugin\.
.
.IP "" 4
.
@@ -252,7 +407,7 @@ git push origin master
.
.IP "" 0
.
-.SS "FISHFILE"
+.SH "FISHFILE"
Fisherman keeps track of a special file known as \fIfishfile\fR to know what plugins are currently enabled\.
.
.IP "" 4
@@ -273,7 +428,7 @@ shellder
.P
This file is automatically updated as you install and uninstall plugins\.
.
-.SS "VARIABLES"
+.SH "VARIABLES"
.
.TP
$fisher_home
@@ -295,6 +450,379 @@ The cache directory\. Plugins are downloaded to this location\.
$fisher_alias \fIcommand\fR=\fIalias\fR[,\fIalias2\fR] \.\.\.
Use this variable to customize Fisherman command aliases\.
.
+.SH "PLUGINS"
+Plugins can be utilities, prompts, commands or snippets\.
+.
+.SS "UTILITIES"
+Utilities are plugins that define one or more functions which are mean to be used in the CLI directly by the user\.
+.
+.P
+This example walks you through creating \fIwtc\fR, a plugin based in \fIgithub/ngerakines/commitment\fR random commit message generator\.
+.
+.P
+Create a directory and initialize a Git repository\.
+.
+.IP "" 4
+.
+.nf
+
+mkdir wtc
+cd wtc
+git init
+git remote add origin https://github\.com//wtc
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Add the wtc function\.
+.
+.IP "" 4
+.
+.nf
+
+function wtc \-d "Generate a random commit message"
+ switch "$argv"
+ case \-h \-\-help
+ printf "Usage: wtc [\-\-help]\en\en"
+ printf " \-h \-\-help Show usage help\en"
+ return
+ end
+ curl \-s whatthecommit\.com/index\.txt
+end
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Install the plugin\.
+.
+.IP "" 4
+.
+.nf
+
+fisher install \.
+wtc
+(\e /)
+(O\.o)
+(> <) Bunny approves these changes\.
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Commit changes and push to your remote origin when you are done\.
+.
+.IP "" 4
+.
+.nf
+
+git add \-\-all
+git commit \-m "What the commit?"
+git push origin master
+.
+.fi
+.
+.IP "" 0
+.
+.P
+To submit wtc to the official index\.
+.
+.IP "" 4
+.
+.nf
+
+fisher install submit
+fisher submit
+.
+.fi
+.
+.IP "" 0
+.
+.P
+This will create a PR in the Fisherman index repository\. Once the PR is approved, Fisherman users will be able to install wtc if they have the latest index\.
+.
+.IP "" 4
+.
+.nf
+
+fisher install wtc
+.
+.fi
+.
+.IP "" 0
+.
+.P
+See \fBfisher help submit\fR for more submit options\.
+.
+.P
+Create a completions directory and add a completions file\.
+.
+.IP "" 4
+.
+.nf
+
+mkdir completions
+cat > completions/wtc\.fish
+complete \-\-command wtc \-\-short h \-\-long help \-\-description "Show usage help"
+^
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Alternatively, use \fB__fisher_complete\fR to create completions from wtc usage output\.
+.
+.IP "" 4
+.
+.nf
+
+wtc \-\-help | __fisher_complete wtc
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Create a man/man1 directory and add a man(1) page for wtc\.
+.
+.P
+There are utilities that can help you generate man pages from various text formats\. For example, pandoc(1) and ronn(1)\.
+.
+.P
+To create a man page manually\.
+.
+.IP "" 4
+.
+.nf
+
+mkdir \-p man/man1
+cat > man/man1/wtc\.1
+
+ \.TH man 1 "Today" "1\.0" "wtc man page"
+ \.SH NAME
+ wtc \e\- Generate a random commit message
+ \.SH SYNOPSIS
+ wtc [\-\-help]
+ \.SH OPTIONS
+ \-h, \-\-help: Display help information\.
+ \.SH SEE ALSO
+ https://github\.com/ngerakines/commitment
+^C
+.
+.fi
+.
+.IP "" 0
+.
+.P
+A plugin can list dependencies to other plugins using a \fIfishfile\fR\.
+.
+.P
+Create a new file in the root of your project and add the name or URL of your desired dependencies\.
+.
+.IP "" 4
+.
+.nf
+
+cat > fishfile
+my_plugin
+https://github\.com/owner/another_plugin
+^D
+.
+.fi
+.
+.IP "" 0
+.
+.SS "PROMPTS"
+Prompts, also known as themes, are plugins that modify the appearance of the shell prompt and modify fish syntax colors\.
+.
+.P
+Create a \fBfish_prompt\fR function\.
+.
+.IP "" 4
+.
+.nf
+
+function fish_prompt
+ printf "%s (%s) >> " (prompt_pwd) Fisherman
+end
+~ (Fisherman) >> type here
+.
+.fi
+.
+.IP "" 0
+.
+.P
+To add a right prompt, create a \fBfish_right_prompt\fR function\.
+.
+.IP "" 4
+.
+.nf
+
+function fish_right_prompt
+ printf "%s" (date +%H:%M:%S)
+end
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Save the functions to a directory and install the prompt as a plugin\.
+.
+.IP "" 4
+.
+.nf
+
+mkdir my_prompt
+cd my_prompt
+functions fish_prompt > fish_prompt\.fish
+functions fish_right_prompt > fish_right_prompt\.fish
+fisher install \.
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Customize the colors fish uses for syntax highlighting\.
+.
+.IP "" 4
+.
+.nf
+
+function set_color_custom
+ set \-U fish_color_normal #\.\.\.
+ set \-U fish_color_command #\.\.\.
+ set \-U fish_color_param #\.\.\.
+ set \-U fish_color_redirection #\.\.\.
+ set \-U fish_color_comment #\.\.\.
+ set \-U fish_color_error #\.\.\.
+ set \-U fish_color_escape #\.\.\.
+ set \-U fish_color_operator #\.\.\.
+ set \-U fish_color_end #\.\.\.
+ set \-U fish_color_quote #\.\.\.
+ set \-U fish_color_autosuggestion #\.\.\.
+ set \-U fish_color_valid_path #\.\.\.
+ set \-U fish_color_cwd #\.\.\.
+ set \-U fish_color_cwd_root #\.\.\.
+ set \-U fish_color_match #\.\.\.
+ set \-U fish_color_search_match #\.\.\.
+ set \-U fish_color_selection #\.\.\.
+ set \-U fish_pager_color_prefix #\.\.\.
+ set \-U fish_pager_color_completion #\.\.\.
+ set \-U fish_pager_color_description #\.\.\.
+ set \-U fish_pager_color_progress #\.\.\.
+ set \-U fish_color_history_current #\.\.\.
+end
+functions set_color_custom > set_color_custom\.fish
+fisher update \.
+.
+.fi
+.
+.IP "" 0
+.
+.SS "COMMANDS"
+Commands are plugins that extend the Fisherman CLI adding new \fBfisher \fR\.
+.
+.P
+Create a function \fBfisher_\fR
+.
+.IP "" 4
+.
+.nf
+
+function fisher_time \-d "Say hello"
+ printf "It\'s %s\en" (date +%H:%M)
+end
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Test it works
+.
+.IP "" 4
+.
+.nf
+
+fisher time
+It\'s 6:30
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Make it a plugin
+.
+.IP "" 4
+.
+.nf
+
+fisher install fisher_time
+.
+.fi
+.
+.IP "" 0
+.
+.P
+This creates a new directory fisher_time in the current working directory and installs the plugin\.
+.
+.P
+The following example implements a command to format plugin information into columns\.
+.
+.IP "" 4
+.
+.nf
+
+function fisher_info \-d "Display information about plugins"
+ switch "$argv"
+ case \-h \-\-help
+ printf "Usage: fisher info [\.\.\.]\en\en"
+ printf " \-h \-\-help Show usage help\en"
+ return
+ end
+
+ for item in $argv
+ fisher search $item \-\-name \-\-info
+ end | sed \-E \'s/;/: /\' | column
+end
+
+fisher install fisher_info
+.
+.fi
+.
+.IP "" 0
+.
+.SS "SNIPPETS"
+Snippets are plugins that run code at the start of the shell\. Snippets must be placed inside a sub directory named conf\.d\.
+.
+.P
+The following example implements the fish_postexec hook to display the runtime of the last command in milliseconds\.
+.
+.IP "" 4
+.
+.nf
+
+mkdir \-p runtime/conf\.d
+cd runtime
+cat > conf\.d/fish_postexec\.fish
+function fish_postexec \-\-on\-event fish_postexec
+ printf "%sms\en" $CMD_DURATION > /dev/stderr
+end
+^D
+fisher install \./postexec
+.
+.fi
+.
+.IP "" 0
+.
.SH "AUTHORS"
Fisherman was created by Jorge Bucaran :: @bucaran :: \fIj@bucaran\.me\fR\.
.
diff --git a/man/man1/fisher.md b/man/man1/fisher.md
index e97f80f..b41614b 100644
--- a/man/man1/fisher.md
+++ b/man/man1/fisher.md
@@ -9,7 +9,7 @@ fisher *command* [*arguments*] [--version] [--help]
Fisherman is a plugin manager for fish.
-The Fisherman CLI consists of the following commands: *install*, *update*, *uninstall*, *list*, *search* and *help*.
+The CLI consists of the following commands: *install*, *update*, *uninstall*, *list*, *search* and *help*.
## USAGE
@@ -25,7 +25,7 @@ Get help about a command.
fisher help
```
-Fisherman knows the following aliases by default: *i* for install, *u* for update, *l* for list, *s* for search and *h* for help.
+Fisherman knows the following too: *i* for install, *u* for update, *l* for list, *s* for search and *h* for help.
## OPTIONS
@@ -37,39 +37,152 @@ Fisherman knows the following aliases by default: *i* for install, *u* for updat
## EXAMPLES
-* Install plugins.
-
-```fish
-fisher install fishtape shark get
-```
-
-* Install a plugin as a symbolic link.
-
-```fish
-fisher install ./path/to/plugin
-```
-
-* Update Fisherman to the latest version.
+Update Fisherman.
```fish
fisher update
```
-* Search the Fisherman index.
+Install plugins.
```fish
-fisher search
+fisher install fishtape shark get
```
-* Show all the documentation.
+Install a plugin from a local directory.
+
+```fish
+fisher install ./path/to/plugin
+```
+
+Install a plugin from a URL.
+
+```fish
+fisher install owner/repo
+```
+
+Install a plugin from a Gist URL.
+
+```fish
+fisher install gist.github.com/owner/1f40e1c6e0551b2666b2
+```
+
+Update plugins.
+
+```
+fisher update shark get
+```
+
+Uninstall plugins.
+
+```
+fisher uninstall fishtape debug
+```
+
+Uninstall plugins and remove them from the cache.
+
+```
+fisher uninstall fishtape debug -f
+```
+
+Show all the documentation.
```fish
fisher help --all
```
-## CONCEPTS
+## LIST AND SEARCH
-### FLAT TREE
+The list command displays all the plugins you have installed. The search command queries the index to show what's available to install.
+
+List installed plugins.
+
+```
+fisher list
+ debug
+* fishtape
+> shellder
+* spin
+@ wipe
+```
+
+The legend consists of:
+
+`*` The plugin is currently enabled
+`>` The plugin is a prompt
+`@` The plugin is a symbolic link
+
+Search the index.
+
+```
+fisher search
+ ...
+* debug Conditional debug logger
+ errno POSIX error code/string translator
+* fishtape TAP producing test runner
+ flash Flash-inspired, thunder prompt
+ fzf Efficient keybindings for fzf
+ get Press any key to continue
+ ...
+> shellder Powerline prompt optimized for speed
+ ...
+```
+
+Get detailed information about a plugin.
+
+```
+fisher search shellder
+> shellder by simnalamburt
+Powerline prompt optimized for speed
+github.com/simnalamburt/shellder
+```
+
+Search plugins using tags.
+
+```
+fisher search --tag={git,test}
+ ...
+* fishtape TAP producing test runner
+ git-branch-name Get the name of the current Git branch
+ git-is-repo Test if the current directory is a Git repo
+ git-is-dirty Test if there are changes not staged for commit
+ git-is-stashed Test if there are changes in the stash
+ ...
+```
+
+## PLUMBING
+
+Fisherman commands are pipe aware. Plumb one with another to create complex functionality.
+
+Update all the plugins in the cache.
+
+```fish
+fisher list | fisher update -
+```
+
+Enable all the plugins that are currently disabled.
+
+```fish
+fisher list --disabled | fisher install
+```
+
+Uninstall all the plugins and remove them from the cache.
+
+```fish
+fisher list | fisher uninstall --force
+```
+
+## DOTFILES
+
+When you install a plugin, Fisherman updates a file known as *fishfile* to track what plugins are currently enabled.
+
+To customize its location:
+
+```fish
+set -g fisher_file ~/.dotfiles/fishfile
+```
+
+## FLAT TREE
Fisherman merges the directory trees of all the plugins it installs into a single flat tree. Since the flat tree is loaded only once at the start of the shell, Fisherman performs equally well, regardless of the number of plugins installed.
@@ -92,27 +205,7 @@ $fisher_config
`-- my_plugin.1
```
-### PLUGINS
-
-To install plugins, type fisher install and press *tab* once to list all the available plugins. Similarly, use fisher update / uninstall and press *tab* to see what plugins you can update or uninstall.
-
-To search plugins use fisher search *name*. You can by a specific field using fisher search --*field*=*match*.
-
-```fish
-fisher search --tag={*keywords*}
-```
-
-or
-
-```fish
-fisher search --name=*name*
-```
-
-See fisher help search for advanced options.
-
-To learn how to create plugins enter fisher help tutorial.
-
-### INDEX
+## INDEX
The index is a plain text database that lists Fisherman official plugins.
@@ -128,7 +221,7 @@ z search cd jump
jethrokuan
```
-If you have a plugin you would like to submit to the index, use the submit plugin.
+If you have a plugin to submit to the index, use the *submit* plugin.
```
fisher install submit
@@ -144,7 +237,7 @@ echo "$name\n$url\n$info\n$tags\n$author\n\n" >> index
git push origin master
```
-### FISHFILE
+## FISHFILE
Fisherman keeps track of a special file known as *fishfile* to know what plugins are currently enabled.
@@ -159,7 +252,7 @@ shellder
This file is automatically updated as you install and uninstall plugins.
-### VARIABLES
+## VARIABLES
* $fisher_home:
The home directory. If you installed Fisherman using the recommended method `curl -sL install.fisherman.sh | fish`, the location ought to be *XDG_DATA_HOME/fisherman*. If you clone Fisherman and run make yourself, the current working directory is used by default.
@@ -176,6 +269,255 @@ This file is automatically updated as you install and uninstall plugins.
* $fisher_alias *command*=*alias*[,*alias2*] ...:
Use this variable to customize Fisherman command aliases.
+
+## PLUGINS
+
+Plugins can be utilities, prompts, commands or snippets.
+
+### UTILITIES
+
+Utilities are plugins that define one or more functions which are mean to be used in the CLI directly by the user.
+
+This example walks you through creating *wtc*, a plugin based in *github/ngerakines/commitment* random commit message generator.
+
+Create a directory and initialize a Git repository.
+
+```fish
+mkdir wtc
+cd wtc
+git init
+git remote add origin https://github.com//wtc
+```
+
+Add the wtc function.
+
+```fish
+function wtc -d "Generate a random commit message"
+ switch "$argv"
+ case -h --help
+ printf "Usage: wtc [--help]\n\n"
+ printf " -h --help Show usage help\n"
+ return
+ end
+ curl -s whatthecommit.com/index.txt
+end
+```
+
+Install the plugin.
+
+```fish
+fisher install .
+wtc
+(\ /)
+(O.o)
+(> <) Bunny approves these changes.
+```
+
+Commit changes and push to your remote origin when you are done.
+
+```fish
+git add --all
+git commit -m "What the commit?"
+git push origin master
+```
+
+#### SUBMIT
+
+To submit wtc to the official index.
+
+```fish
+fisher install submit
+fisher submit
+```
+
+This will create a PR in the Fisherman index repository. Once the PR is approved, Fisherman users will be able to install wtc if they have the latest index.
+
+```fish
+fisher install wtc
+```
+
+See `fisher help submit` for more submit options.
+
+#### COMPLETIONS
+
+Create a completions directory and add a completions file.
+
+```fish
+mkdir completions
+cat > completions/wtc.fish
+complete --command wtc --short h --long help --description "Show usage help"
+^
+```
+
+Alternatively, use `__fisher_complete` to create completions from wtc usage output.
+
+```
+wtc --help | __fisher_complete wtc
+```
+
+#### DOCS
+
+Create a man/man1 directory and add a man(1) page for wtc.
+
+There are utilities that can help you generate man pages from various text formats. For example, pandoc(1) and ronn(1).
+
+To create a man page manually.
+
+```fish
+mkdir -p man/man1
+cat > man/man1/wtc.1
+
+ .TH man 1 "Today" "1.0" "wtc man page"
+ .SH NAME
+ wtc \- Generate a random commit message
+ .SH SYNOPSIS
+ wtc [--help]
+ .SH OPTIONS
+ -h, --help: Display help information.
+ .SH SEE ALSO
+ https://github.com/ngerakines/commitment
+^C
+```
+
+#### DEPENDENCIES
+
+A plugin can list dependencies to other plugins using a *fishfile*.
+
+Create a new file in the root of your project and add the name or URL of your desired dependencies.
+
+```fish
+cat > fishfile
+my_plugin
+https://github.com/owner/another_plugin
+^D
+```
+
+### PROMPTS
+
+Prompts, also known as themes, are plugins that modify the appearance of the shell prompt and modify fish syntax colors.
+
+Create a `fish_prompt` function.
+
+```fish
+function fish_prompt
+ printf "%s (%s) >> " (prompt_pwd) Fisherman
+end
+~ (Fisherman) >> type here
+```
+
+To add a right prompt, create a `fish_right_prompt` function.
+
+```fish
+function fish_right_prompt
+ printf "%s" (date +%H:%M:%S)
+end
+```
+
+Save the functions to a directory and install the prompt as a plugin.
+
+```fish
+mkdir my_prompt
+cd my_prompt
+functions fish_prompt > fish_prompt.fish
+functions fish_right_prompt > fish_right_prompt.fish
+fisher install .
+```
+
+Customize the colors fish uses for syntax highlighting.
+
+```fish
+function set_color_custom
+ set -U fish_color_normal #...
+ set -U fish_color_command #...
+ set -U fish_color_param #...
+ set -U fish_color_redirection #...
+ set -U fish_color_comment #...
+ set -U fish_color_error #...
+ set -U fish_color_escape #...
+ set -U fish_color_operator #...
+ set -U fish_color_end #...
+ set -U fish_color_quote #...
+ set -U fish_color_autosuggestion #...
+ set -U fish_color_valid_path #...
+ set -U fish_color_cwd #...
+ set -U fish_color_cwd_root #...
+ set -U fish_color_match #...
+ set -U fish_color_search_match #...
+ set -U fish_color_selection #...
+ set -U fish_pager_color_prefix #...
+ set -U fish_pager_color_completion #...
+ set -U fish_pager_color_description #...
+ set -U fish_pager_color_progress #...
+ set -U fish_color_history_current #...
+end
+functions set_color_custom > set_color_custom.fish
+fisher update .
+```
+
+### COMMANDS
+
+Commands are plugins that extend the Fisherman CLI adding new `fisher `.
+
+Create a function `fisher_`
+
+```fish
+function fisher_time -d "Say hello"
+ printf "It's %s\n" (date +%H:%M)
+end
+```
+
+Test it works
+
+```fish
+fisher time
+It's 6:30
+```
+
+Make it a plugin
+
+
+```fish
+fisher install fisher_time
+```
+
+This creates a new directory fisher_time in the current working directory and installs the plugin.
+
+The following example implements a command to format plugin information into columns.
+
+```fish
+function fisher_info -d "Display information about plugins"
+ switch "$argv"
+ case -h --help
+ printf "Usage: fisher info [...]\n\n"
+ printf " -h --help Show usage help\n"
+ return
+ end
+
+ for item in $argv
+ fisher search $item --name --info
+ end | sed -E 's/;/: /' | column
+end
+
+fisher install fisher_info
+```
+
+### SNIPPETS
+
+Snippets are plugins that run code at the start of the shell. Snippets must be placed inside a sub directory named conf.d.
+
+The following example implements the fish_postexec hook to display the runtime of the last command in milliseconds.
+
+```fish
+mkdir -p runtime/conf.d
+cd runtime
+cat > conf.d/fish_postexec.fish
+function fish_postexec --on-event fish_postexec
+ printf "%sms\n" $CMD_DURATION > /dev/stderr
+end
+^D
+fisher install ./postexec
+```
+
## AUTHORS
Fisherman was created by Jorge Bucaran :: @bucaran :: *j@bucaran.me*.
diff --git a/man/man7/fisher-configuration.7 b/man/man7/fisher-configuration.7
deleted file mode 120000
index 4eec581..0000000
--- a/man/man7/fisher-configuration.7
+++ /dev/null
@@ -1 +0,0 @@
-fisher-config.7
\ No newline at end of file
diff --git a/man/man7/fisher-tutorial.7 b/man/man7/fisher-tutorial.7
deleted file mode 100644
index d2e74e4..0000000
--- a/man/man7/fisher-tutorial.7
+++ /dev/null
@@ -1,537 +0,0 @@
-.\" generated with Ronn/v0.7.3
-.\" http://github.com/rtomayko/ronn/tree/0.7.3
-.
-.TH "FISHER\-TUTORIAL" "7" "February 2016" "" "fisherman"
-.
-.SH "NAME"
-\fBfisher\-tutorial\fR \- A tutorial introduction to Fisherman
-.
-.SH "DESCRIPTION"
-This document tells you how to start using Fisherman key features\.
-.
-.SH "INSTALLING PLUGINS"
-Install a plugin\.
-.
-.IP "" 4
-.
-.nf
-
-fisher install
-.
-.fi
-.
-.IP "" 0
-.
-.P
-\fIplugin\fR can be name registered in the Fisherman index, a URL to a Git repository or a path in the local system\. Plugins are collected in a special location inside the Fisherman\'s configuration directory known as the cache\.
-.
-.SH "UPDATE AND UNINSTALL"
-Update a plugin\.
-.
-.IP "" 4
-.
-.nf
-
-fisher update
-.
-.fi
-.
-.IP "" 0
-.
-.P
-Uninstall a plugin\.
-.
-.IP "" 4
-.
-.nf
-
-fisher uninstall
-.
-.fi
-.
-.IP "" 0
-.
-.SH "LIST AND SEARCH"
-The list command displays all the plugins you have installed\. The search command queries the index to show what\'s available to install\.
-.
-.P
-List installed plugins\.
-.
-.IP "" 4
-.
-.nf
-
-fisher list
- debug
-* fishtape
-> shellder
-* spin
-@ wipe
-.
-.fi
-.
-.IP "" 0
-.
-.P
-The legend consists of:
-.
-.P
-\fB*\fR Indicate the plugin is currently installed
-.
-.br
-\fB>\fR Indicate the plugin is a prompt
-.
-.br
-\fB@\fR Indicate the plugin is a symbolic link
-.
-.br
-.
-.P
-Search the index\.
-.
-.IP "" 4
-.
-.nf
-
-fisher search
- \.\.\.
-* debug Conditional debug logger
- errno POSIX error code/string translator
-* fishtape TAP producing test runner
- flash Flash\-inspired, thunder prompt
- fzf Efficient keybindings for fzf
- get Press any key to continue
- \.\.\.
-> shellder Powerline prompt optimized for speed
- \.\.\.
-.
-.fi
-.
-.IP "" 0
-.
-.P
-Get detailed information about a plugin\.
-.
-.IP "" 4
-.
-.nf
-
-fisher search shellder
-> shellder by simnalamburt
-Powerline prompt optimized for speed
-github\.com/simnalamburt/shellder
-.
-.fi
-.
-.IP "" 0
-.
-.P
-Search plugins using tags\.
-.
-.IP "" 4
-.
-.nf
-
-fisher search \-\-tag={git,test}
- \.\.\.
-* fishtape TAP producing test runner
- git\-branch\-name Get the name of the current Git branch
- git\-is\-repo Test if the current directory is a Git repo
- git\-is\-dirty Test if there are changes not staged for commit
- git\-is\-stashed Test if there are changes in the stash
- \.\.\.
-.
-.fi
-.
-.IP "" 0
-.
-.SH "PLUMBING"
-Fisherman commands are pipe aware\. Plumb one with another to create complex functionality\.
-.
-.P
-Update all the plugins in the cache\.
-.
-.IP "" 4
-.
-.nf
-
-fisher list | fisher update \-
-.
-.fi
-.
-.IP "" 0
-.
-.P
-Install all the plugins that are currently disabled\.
-.
-.IP "" 4
-.
-.nf
-
-fisher list \-\-disabled | fisher install
-.
-.fi
-.
-.IP "" 0
-.
-.SH "DOTFILES"
-When you install a plugin, Fisherman updates a file known as \fIfishfile\fR to track what plugins are currently enabled\.
-.
-.P
-To customize its location:
-.
-.IP "" 4
-.
-.nf
-
-set \-g fisher_file ~/\.dotfiles/fishfile
-.
-.fi
-.
-.IP "" 0
-.
-.SH "PLUGINS"
-Plugins can be utilities, prompts, commands or snippets\.
-.
-.SS "UTILITIES"
-Utilities are plugins that define one or more functions which are mean to be used in the CLI directly by the user\.
-.
-.P
-This example walks you through creating \fIwtc\fR, a plugin based in \fIgithub/ngerakines/commitment\fR random commit message generator\.
-.
-.IP "\(bu" 4
-Create a directory and initialize a Git repository\.
-.
-.IP "" 0
-.
-.IP "" 4
-.
-.nf
-
-mkdir wtc
-cd wtc
-git init
-git remote add origin https://github\.com//wtc
-.
-.fi
-.
-.IP "" 0
-.
-.IP "\(bu" 4
-Add the wtc function\.
-.
-.IP "" 0
-.
-.IP "" 4
-.
-.nf
-
-function wtc \-d "Generate a random commit message"
- switch "$argv"
- case \-h \-\-help
- printf "Usage: wtc [\-\-help]\en\en"
- printf " \-h \-\-help Show usage help\en"
- return
- end
- curl \-s whatthecommit\.com/index\.txt
-end
-.
-.fi
-.
-.IP "" 0
-.
-.IP "\(bu" 4
-Install the plugin\.
-.
-.IP "" 0
-.
-.IP "" 4
-.
-.nf
-
-fisher install \.
-wtc
-(\e /)
-(O\.o)
-(> <) Bunny approves these changes\.
-.
-.fi
-.
-.IP "" 0
-.
-.IP "\(bu" 4
-Commit changes and push to your remote origin when you are done\.
-.
-.IP "" 0
-.
-.IP "" 4
-.
-.nf
-
-git add \-\-all
-git commit \-m "What the commit?"
-git push origin master
-.
-.fi
-.
-.IP "" 0
-.
-.P
-To submit wtc to the official index\.
-.
-.IP "" 4
-.
-.nf
-
-fisher install submit
-fisher submit
-.
-.fi
-.
-.IP "" 0
-.
-.P
-This will create a PR in the Fisherman index repository\. Once the PR is approved, Fisherman users will be able to install wtc if they have the latest index\.
-.
-.IP "" 4
-.
-.nf
-
-fisher install wtc
-.
-.fi
-.
-.IP "" 0
-.
-.P
-See \fBfisher help submit\fR for more submit options\.
-.
-.P
-Create a completions directory and add a completions file\.
-.
-.IP "" 4
-.
-.nf
-
-mkdir completions
-cat > completions/wtc\.fish
-complete \-\-command wtc \-\-short h \-\-long help \-\-description "Show usage help"
-^
-.
-.fi
-.
-.IP "" 0
-.
-.P
-Alternatively, use \fB__fisher_complete\fR to create completions from wtc usage output\.
-.
-.IP "" 4
-.
-.nf
-
-wtc \-\-help | __fisher_complete wtc
-.
-.fi
-.
-.IP "" 0
-.
-.P
-Create a man/man1 directory and add a man(1) page for wtc\.
-.
-.P
-There are utilities that can help you generate man pages from various text formats\. For example, pandoc(1) and ronn(1)\.
-.
-.P
-To create a man page manually\.
-.
-.IP "" 4
-.
-.nf
-
-mkdir \-p man/man1
-cat > man/man1/wtc\.1
-
- \.TH man 1 "Today" "1\.0" "wtc man page"
- \.SH NAME
- wtc \e\- Generate a random commit message
- \.SH SYNOPSIS
- wtc [\-\-help]
- \.SH OPTIONS
- \-h, \-\-help: Display help information\.
- \.SH SEE ALSO
- https://github\.com/ngerakines/commitment
-^C
-.
-.fi
-.
-.IP "" 0
-.
-.P
-A plugin can list dependencies to other plugins using a \fIfishfile\fR\.
-.
-.P
-Create a new file in the root of your project and add the name or URL of your desired dependencies\.
-.
-.IP "" 4
-.
-.nf
-
-cat > fishfile
-my_plugin
-https://github\.com/owner/another_plugin
-^D
-.
-.fi
-.
-.IP "" 0
-.
-.SS "PROMPTS"
-Prompts, also known as themes, are plugins that modify the appearance of the shell prompt\.
-.
-.P
-Create a \fBfish_prompt\fR function\.
-.
-.IP "" 4
-.
-.nf
-
-function fish_prompt
- printf "%s (%s) >> " (prompt_pwd) Fisherman
-end
-~ (Fisherman) >> type here
-.
-.fi
-.
-.IP "" 0
-.
-.P
-To add a right prompt, create a \fBfish_right_prompt\fR function\.
-.
-.IP "" 4
-.
-.nf
-
-function fish_right_prompt
- printf "%s" (date +%H:%M:%S)
-end
-.
-.fi
-.
-.IP "" 0
-.
-.P
-Save the functions to a directory and install the prompt as a plugin\.
-.
-.IP "" 4
-.
-.nf
-
-mkdir my_prompt
-cd my_prompt
-functions fish_prompt > fish_prompt\.fish
-functions fish_right_prompt > fish_right_prompt\.fish
-fisher install \.
-.
-.fi
-.
-.IP "" 0
-.
-.SS "COMMANDS"
-Commands are plugins that extend the Fisherman CLI adding new \fBfisher \fR\.
-.
-.P
-Create a function \fBfisher_\fR
-.
-.IP "" 4
-.
-.nf
-
-function fisher_time \-d "Say hello"
- printf "It\'s %s\en" (date +%H:%M)
-end
-.
-.fi
-.
-.IP "" 0
-.
-.P
-Test it works
-.
-.IP "" 4
-.
-.nf
-
-fisher time
-It\'s 6:30
-.
-.fi
-.
-.IP "" 0
-.
-.P
-Make it a plugin
-.
-.IP "" 4
-.
-.nf
-
-fisher install fisher_time
-.
-.fi
-.
-.IP "" 0
-.
-.P
-This creates a new directory fisher_time in the current working directory and installs the plugin\.
-.
-.P
-The following example implements a command to format plugin information into columns\.
-.
-.IP "" 4
-.
-.nf
-
-function fisher_info \-d "Display information about plugins"
- switch "$argv"
- case \-h \-\-help
- printf "Usage: fisher info [\.\.\.]\en\en"
- printf " \-h \-\-help Show usage help\en"
- return
- end
-
- for item in $argv
- fisher search $item \-\-name \-\-info
- end | sed \-E \'s/;/: /\' | column
-end
-
-fisher install fisher_info
-.
-.fi
-.
-.IP "" 0
-.
-.SS "SNIPPETS"
-Snippets are plugins that run code at the start of the shell\. Snippets must be placed inside a sub directory named conf\.d\.
-.
-.P
-The following example implements the fish_postexec hook to display the runtime of the last command in milliseconds\.
-.
-.IP "" 4
-.
-.nf
-
-mkdir \-p runtime/conf\.d
-cd runtime
-cat > conf\.d/fish_postexec\.fish
-function fish_postexec \-\-on\-event fish_postexec
- printf "%sms\en" $CMD_DURATION > /dev/stderr
-end
-^D
-fisher install \./postexec
-.
-.fi
-.
-.IP "" 0
-.
-.SH "SEE ALSO"
-fisher(1)
diff --git a/man/man7/fisher-tutorial.md b/man/man7/fisher-tutorial.md
deleted file mode 100644
index 598c807..0000000
--- a/man/man7/fisher-tutorial.md
+++ /dev/null
@@ -1,336 +0,0 @@
-fisher-tutorial(7) -- A tutorial introduction to Fisherman
-==========================================================
-
-## DESCRIPTION
-
-This document tells you how to start using Fisherman key features.
-
-## INSTALLING PLUGINS
-
-Install a plugin.
-
-```
-fisher install
-```
-
-*plugin* can be name registered in the Fisherman index, a URL to a Git repository or a path in the local system. Plugins are collected in a special location inside the Fisherman's configuration directory known as the cache.
-
-## UPDATE AND UNINSTALL
-
-Update a plugin.
-
-```
-fisher update
-```
-
-Uninstall a plugin.
-
-```
-fisher uninstall
-```
-
-## LIST AND SEARCH
-
-The list command displays all the plugins you have installed. The search command queries the index to show what's available to install.
-
-List installed plugins.
-
-```
-fisher list
- debug
-* fishtape
-> shellder
-* spin
-@ wipe
-```
-
-The legend consists of:
-
-`*` Indicate the plugin is currently installed
-`>` Indicate the plugin is a prompt
-`@` Indicate the plugin is a symbolic link
-
-Search the index.
-
-```
-fisher search
- ...
-* debug Conditional debug logger
- errno POSIX error code/string translator
-* fishtape TAP producing test runner
- flash Flash-inspired, thunder prompt
- fzf Efficient keybindings for fzf
- get Press any key to continue
- ...
-> shellder Powerline prompt optimized for speed
- ...
-```
-
-Get detailed information about a plugin.
-
-```
-fisher search shellder
-> shellder by simnalamburt
-Powerline prompt optimized for speed
-github.com/simnalamburt/shellder
-```
-
-Search plugins using tags.
-
-```
-fisher search --tag={git,test}
- ...
-* fishtape TAP producing test runner
- git-branch-name Get the name of the current Git branch
- git-is-repo Test if the current directory is a Git repo
- git-is-dirty Test if there are changes not staged for commit
- git-is-stashed Test if there are changes in the stash
- ...
-```
-
-## PLUMBING
-
-Fisherman commands are pipe aware. Plumb one with another to create complex functionality.
-
-Update all the plugins in the cache.
-
-```fish
-fisher list | fisher update -
-```
-
-Install all the plugins that are currently disabled.
-
-```fish
-fisher list --disabled | fisher install
-```
-
-## DOTFILES
-
-When you install a plugin, Fisherman updates a file known as *fishfile* to track what plugins are currently enabled.
-
-To customize its location:
-
-```fish
-set -g fisher_file ~/.dotfiles/fishfile
-```
-
-## PLUGINS
-
-Plugins can be utilities, prompts, commands or snippets.
-
-### UTILITIES
-
-Utilities are plugins that define one or more functions which are mean to be used in the CLI directly by the user.
-
-This example walks you through creating *wtc*, a plugin based in *github/ngerakines/commitment* random commit message generator.
-
-* Create a directory and initialize a Git repository.
-
-```fish
-mkdir wtc
-cd wtc
-git init
-git remote add origin https://github.com//wtc
-```
-
-* Add the wtc function.
-
-```fish
-function wtc -d "Generate a random commit message"
- switch "$argv"
- case -h --help
- printf "Usage: wtc [--help]\n\n"
- printf " -h --help Show usage help\n"
- return
- end
- curl -s whatthecommit.com/index.txt
-end
-```
-
-* Install the plugin.
-
-```fish
-fisher install .
-wtc
-(\ /)
-(O.o)
-(> <) Bunny approves these changes.
-```
-
-* Commit changes and push to your remote origin when you are done.
-
-```fish
-git add --all
-git commit -m "What the commit?"
-git push origin master
-```
-
-#### SUBMIT
-
-To submit wtc to the official index.
-
-```fish
-fisher install submit
-fisher submit
-```
-
-This will create a PR in the Fisherman index repository. Once the PR is approved, Fisherman users will be able to install wtc if they have the latest index.
-
-```fish
-fisher install wtc
-```
-
-See `fisher help submit` for more submit options.
-
-#### COMPLETIONS
-
-Create a completions directory and add a completions file.
-
-```fish
-mkdir completions
-cat > completions/wtc.fish
-complete --command wtc --short h --long help --description "Show usage help"
-^
-```
-
-Alternatively, use `__fisher_complete` to create completions from wtc usage output.
-
-```
-wtc --help | __fisher_complete wtc
-```
-
-#### MAN
-
-Create a man/man1 directory and add a man(1) page for wtc.
-
-There are utilities that can help you generate man pages from various text formats. For example, pandoc(1) and ronn(1).
-
-To create a man page manually.
-
-```fish
-mkdir -p man/man1
-cat > man/man1/wtc.1
-
- .TH man 1 "Today" "1.0" "wtc man page"
- .SH NAME
- wtc \- Generate a random commit message
- .SH SYNOPSIS
- wtc [--help]
- .SH OPTIONS
- -h, --help: Display help information.
- .SH SEE ALSO
- https://github.com/ngerakines/commitment
-^C
-```
-
-#### DEPENDENCIES
-
-A plugin can list dependencies to other plugins using a *fishfile*.
-
-Create a new file in the root of your project and add the name or URL of your desired dependencies.
-
-```fish
-cat > fishfile
-my_plugin
-https://github.com/owner/another_plugin
-^D
-```
-
-### PROMPTS
-
-Prompts, also known as themes, are plugins that modify the appearance of the shell prompt.
-
-Create a `fish_prompt` function.
-
-```fish
-function fish_prompt
- printf "%s (%s) >> " (prompt_pwd) Fisherman
-end
-~ (Fisherman) >> type here
-```
-
-To add a right prompt, create a `fish_right_prompt` function.
-
-```fish
-function fish_right_prompt
- printf "%s" (date +%H:%M:%S)
-end
-```
-
-Save the functions to a directory and install the prompt as a plugin.
-
-```fish
-mkdir my_prompt
-cd my_prompt
-functions fish_prompt > fish_prompt.fish
-functions fish_right_prompt > fish_right_prompt.fish
-fisher install .
-```
-
-### COMMANDS
-
-Commands are plugins that extend the Fisherman CLI adding new `fisher `.
-
-Create a function `fisher_`
-
-```fish
-function fisher_time -d "Say hello"
- printf "It's %s\n" (date +%H:%M)
-end
-```
-
-Test it works
-
-```fish
-fisher time
-It's 6:30
-```
-
-Make it a plugin
-
-
-```fish
-fisher install fisher_time
-```
-
-This creates a new directory fisher_time in the current working directory and installs the plugin.
-
-The following example implements a command to format plugin information into columns.
-
-```fish
-function fisher_info -d "Display information about plugins"
- switch "$argv"
- case -h --help
- printf "Usage: fisher info [...]\n\n"
- printf " -h --help Show usage help\n"
- return
- end
-
- for item in $argv
- fisher search $item --name --info
- end | sed -E 's/;/: /' | column
-end
-
-fisher install fisher_info
-```
-
-### SNIPPETS
-
-Snippets are plugins that run code at the start of the shell. Snippets must be placed inside a sub directory named conf.d.
-
-The following example implements the fish_postexec hook to display the runtime of the last command in milliseconds.
-
-```fish
-mkdir -p runtime/conf.d
-cd runtime
-cat > conf.d/fish_postexec.fish
-function fish_postexec --on-event fish_postexec
- printf "%sms\n" $CMD_DURATION > /dev/stderr
-end
-^D
-fisher install ./postexec
-```
-
-## SEE ALSO
-
-fisher(1)
diff --git a/man/man7/fisher.7 b/man/man7/fisher.7
deleted file mode 120000
index a6d0070..0000000
--- a/man/man7/fisher.7
+++ /dev/null
@@ -1 +0,0 @@
-/Users/bucaran/c/fisherman/fisherman/man/man7/fisher-tutorial.7
\ No newline at end of file
diff --git a/man/man7/fisherman.7 b/man/man7/fisherman.7
deleted file mode 120000
index a6d0070..0000000
--- a/man/man7/fisherman.7
+++ /dev/null
@@ -1 +0,0 @@
-/Users/bucaran/c/fisherman/fisherman/man/man7/fisher-tutorial.7
\ No newline at end of file
diff --git a/test/fisher.fish b/test/fisher.fish
index 18f1498..1e9210b 100644
--- a/test/fisher.fish
+++ b/test/fisher.fish
@@ -37,7 +37,7 @@ test "$TESTNAME - Display usage help"
end
test "$TESTNAME - Display basic information help info about 'help'"
- (fisher | tail -n2 | xargs) = "Use fisher help -g to list guides and other documentation. See fisher help to access a man page."
+ (fisher | tail -n2 | xargs) = "Use fisher help to access a man page."
end
test "$TESTNAME - Display basic information about available commands"
diff --git a/test/fixtures/help/usage.txt b/test/fixtures/help/usage.txt
index e19c87a..1fa97a9 100644
--- a/test/fixtures/help/usage.txt
+++ b/test/fixtures/help/usage.txt
@@ -28,8 +28,4 @@ Usage: fisher install [] [--force] [--quiet] [--help]
-f --force Reinstall given plugin/s
-q --quiet Enable quiet mode
-h --help Show usage help
-Usage: fisher help [] [--all] [--guides] [--help]
-
- -a --all List all the documentation
- -g --guides List available guides
- -h --help Show usage help
+Usage: fisher help [] [--help]
diff --git a/test/help.fish b/test/help.fish
index 2ab62a5..70e5365 100644
--- a/test/help.fish
+++ b/test/help.fish
@@ -17,14 +17,6 @@ function -S teardown
rm -rf $path
end
-test "$TESTNAME - Show both available guides and command with help --all"
- ! -z (fisher help --all | grep -E 'Available Commands:$|Other Documentation:$' | xargs)
-end
-
-test "$TESTNAME - Show available guides/tutorials with --guides"
- ! -z (fisher help --guides | grep -E 'Other Documentation:$' | xargs)
-end
-
test "$TESTNAME - Show usage help with --usage=command"
(fisher help --usage=help) = (fisher help -h)
end