From 79efc9bceb224b7c50537911d97280a796590545 Mon Sep 17 00:00:00 2001 From: Jorge Bucaran Date: Thu, 10 Mar 2016 14:08:48 +0900 Subject: [PATCH] Remove dead links and tidy up README. --- README.md | 147 +++++++++++++++++-------------------- man/man1/fisher-tutorial.1 | 2 +- man/man1/fisher.1 | 71 ++++++++++-------- man/man1/fisher.md | 45 ++++++------ 4 files changed, 129 insertions(+), 136 deletions(-) diff --git a/README.md b/README.md index 28b1084..2c0e878 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ curl -sL get.fisherman.sh | fish If you don't have Fish, you need to install it too. Install instructions can be found here. -## Setup +## Install Download Fisherman using Git and setup your system automatically. See [other] install options. @@ -34,15 +34,13 @@ 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: *i* for install, *u* for update, *l* for list, *s* for search and *h* for help. +The Fisherman CLI consists of: *install*, *update*, *uninstall*, *list*, *search* and *help* and the following aliases: *i* for install, *u* for update, *l* for list, *s* for search and *h* for help. ### Examples * Install plugins. -```fish +``` fisher install fishtape shark get ``` @@ -66,19 +64,19 @@ fisher install gist.github.com/owner/1f40e1c6e0551b2666b2 * Update Fisherman. -```fish +``` fisher update ``` * Update plugins. -```fish +``` fisher update shark get ``` * Uninstall plugins. -```fish +``` fisher uninstall fishtape debug ``` @@ -98,7 +96,7 @@ fisher help 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. +List installed plugins. ``` fisher list @@ -109,14 +107,7 @@ fisher list @ wipe ``` -The legend consists of: - -* `*` The plugin is currently enabled -* `>` The plugin is a prompt -* `@` The plugin is a symbolic link - - -* Search the index. +Search the index. ``` fisher search @@ -132,7 +123,7 @@ fisher search ... ``` -* Get detailed information about a plugin. +Get detailed information about a plugin. ``` fisher search shellder @@ -141,7 +132,7 @@ Powerline prompt optimized for speed github.com/simnalamburt/shellder ``` -* Search plugins using tags. +Search plugins using tags. ``` fisher search --tag={git,test} @@ -154,6 +145,13 @@ fisher search --tag={git,test} ... ``` +The legend consists of: + +* `*` The plugin is currently enabled +* `>` The plugin is a prompt +* `@` The plugin is a symbolic link + + ## Plumbing Fisherman commands are pipe aware. Plumb one with another to create complex functionality. @@ -178,7 +176,7 @@ 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. +When you install a plugin, Fisherman updates a file known as the *fishfile* to track what plugins are currently enabled. * Customize the location of the fishfile. @@ -194,19 +192,19 @@ The following illustrates an example Fisherman configuration path with a single ``` $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 +├── cache +├── completions +│   └── my_plugin.fish +├── conf.d +│   └── my_plugin.fish +├── fishfile +├── functions +│   ├── fish_prompt.fish +│   ├── fish_right_prompt.fish +│   └── my_plugin.fish +└── man + └── man1 + └── my_plugin.1 ``` ## Index @@ -215,8 +213,6 @@ 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 @@ -232,7 +228,7 @@ 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*. +Otherwise, submit the plugin manually by creating a pull request in the [index](https://github.com/fisherman/fisher-index) repository. ``` git clone https://github.com/fisherman/fisher-index @@ -241,36 +237,21 @@ 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_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
+* *$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
+* *$fisher_file*
See FISHFILE above. -* $fisher_cache
+* *$fisher_cache*
The cache directory. Plugins are downloaded to this location. -* $fisher_alias *command*=*alias* ...
+* *$fisher_alias* *command*=*alias* ...
Use this variable to create aliases of Fisherman commands. ## Plugins @@ -279,7 +260,7 @@ 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. +Utilities are plugins that define one or more functions. This example walks you through creating *wtc*, a plugin based in [ngerakines/commitment](https://github/ngerakines/commitment) random commit message generator. @@ -304,6 +285,7 @@ function wtc -d "Generate a random commit message" end curl -s whatthecommit.com/index.txt end +functions wtc > wtc.fish ``` * Install the plugin. @@ -329,8 +311,7 @@ git push origin master To submit wtc to the official index. ```fish -fisher install submit -fisher submit +fisher submit wtc "Random commit message generator" "commit random fun" https://github.com/owner/wtc ``` 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. @@ -339,20 +320,20 @@ This will create a PR in the Fisherman index repository. Once the PR is approved 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" -^ +$EDITOR completions/wtc.fish ``` -Alternatively, use `__fisher_complete` to create completions from wtc usage output. +```fish +complete --command wtc --short h --long help --description "Show usage help" +``` + +Or use `__fisher_complete` to create completions from wtc usage output. ``` wtc --help | __fisher_complete wtc @@ -366,27 +347,28 @@ There are utilities that can help you generate man pages from various text forma To create a man page manually. -```fish +``` mkdir -p man/man1 -cat > man/man1/wtc.1 +$EDITOR 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 +``` +.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 ``` ### 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. +Create a new file in the root of your project and add the name or URL of your dependencies. ```fish cat > fishfile @@ -494,11 +476,14 @@ The following example implements the fish_postexec hook to display the runtime o ```fish mkdir -p runtime/conf.d cd runtime -cat > conf.d/fish_postexec.fish +$EDITOR conf.d/fish_postexec.fish +``` + +``` function fish_postexec --on-event fish_postexec printf "%sms\n" $CMD_DURATION > /dev/stderr end -^D + fisher install ./postexec ``` diff --git a/man/man1/fisher-tutorial.1 b/man/man1/fisher-tutorial.1 index ba5e5c8..feba221 120000 --- a/man/man1/fisher-tutorial.1 +++ b/man/man1/fisher-tutorial.1 @@ -1 +1 @@ -/Users/bucaran/c/fisherman/fisherman/man/man1/fisher.1 \ No newline at end of file +fisher.1 \ No newline at end of file diff --git a/man/man1/fisher.1 b/man/man1/fisher.1 index a087fd6..563797a 100644 --- a/man/man1/fisher.1 +++ b/man/man1/fisher.1 @@ -15,7 +15,7 @@ fisher \fIcommand\fR [\fIoptions\fR] [\-\-version] [\-\-help] Fisherman is a plugin manager for fish\. . .P -The CLI consists of the following commands: \fIinstall\fR, \fIupdate\fR, \fIuninstall\fR, \fIlist\fR, \fIsearch\fR and \fIhelp\fR\. +The Fisherman CLI consists of: \fIinstall\fR, \fIupdate\fR, \fIuninstall\fR, \fIlist\fR, \fIsearch\fR and \fIhelp\fR and the following aliases: \fIi\fR for install, \fIu\fR for update, \fIl\fR for list, \fIs\fR for search and \fIh\fR for help\. . .SH "USAGE" Run a command\. @@ -43,9 +43,6 @@ fisher help . .IP "" 0 . -.P -Fisherman knows the following aliases: \fIi\fR for install, \fIu\fR for update, \fIl\fR for list, \fIs\fR for search and \fIh\fR for help\. -. .SH "OPTIONS" . .TP @@ -195,20 +192,6 @@ fisher list .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 @@ -267,6 +250,20 @@ fisher search \-\-tag={git,test} . .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 +. .SH "PLUMBING" Fisherman commands are pipe aware\. Plumb one with another to create complex functionality\. . @@ -338,7 +335,7 @@ The following illustrates an example Fisherman configuration path with a single $fisher_config |\-\- cache/ |\-\- conf\.d/ -| `\-\- my_plugin\.config\.fish +| `\-\- my_plugin\.fish |\-\- fishfile |\-\- functions/ | |\-\- my_plugin\.fish @@ -454,7 +451,7 @@ Use this variable to create aliases of Fisherman commands\. 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\. +Utilities are plugins that define one or more functions\. . .P This example walks you through creating \fIwtc\fR, a plugin based in \fIgithub/ngerakines/commitment\fR random commit message generator\. @@ -491,6 +488,7 @@ function wtc \-d "Generate a random commit message" end curl \-s whatthecommit\.com/index\.txt end +functions wtc > wtc\.fish . .fi . @@ -535,8 +533,7 @@ To submit wtc to the official index\. . .nf -fisher install submit -fisher submit +fisher submit wtc "Random commit message generator" "commit random fun" https://github\.com/owner/wtc . .fi . @@ -556,9 +553,6 @@ fisher install wtc .IP "" 0 . .P -See \fBfisher help submit\fR for more submit options\. -. -.P Create a completions directory and add a completions file\. . .IP "" 4 @@ -566,16 +560,24 @@ Create a completions directory and add a completions file\. .nf mkdir completions -cat > completions/wtc\.fish +$EDITOR completions/wtc\.fish +. +.fi +. +.IP "" 0 +. +.IP "" 4 +. +.nf + 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\. +Or use \fB__fisher_complete\fR to create completions from wtc usage output\. . .IP "" 4 . @@ -601,7 +603,15 @@ To create a man page manually\. .nf mkdir \-p man/man1 -cat > man/man1/wtc\.1 +$EDITOR man/man1/wtc\.1 +. +.fi +. +.IP "" 0 +. +.IP "" 4 +. +.nf \.TH man 1 "Today" "1\.0" "wtc man page" \.SH NAME @@ -612,7 +622,6 @@ cat > man/man1/wtc\.1 \-h, \-\-help: Display help information\. \.SH SEE ALSO https://github\.com/ngerakines/commitment -^C . .fi . @@ -622,7 +631,7 @@ cat > man/man1/wtc\.1 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\. +Create a new file in the root of your project and add the name or URL of your dependencies\. . .IP "" 4 . diff --git a/man/man1/fisher.md b/man/man1/fisher.md index 94c3693..064da46 100644 --- a/man/man1/fisher.md +++ b/man/man1/fisher.md @@ -9,7 +9,7 @@ fisher *command* [*options*] [--version] [--help]
Fisherman is a plugin manager for fish. -The CLI consists of the following commands: *install*, *update*, *uninstall*, *list*, *search* and *help*. +The Fisherman CLI consists of: *install*, *update*, *uninstall*, *list*, *search* and *help* and the following aliases: *i* for install, *u* for update, *l* for list, *s* for search and *h* for help. ## USAGE @@ -25,8 +25,6 @@ Get help about a command. fisher help ``` -Fisherman knows the following aliases: *i* for install, *u* for update, *l* for list, *s* for search and *h* for help. - ## OPTIONS * -v, --version: @@ -106,12 +104,6 @@ fisher list @ wipe ``` -The legend consists of: - -`*` The plugin is currently enabled
-`>` The plugin is a prompt
-`@` The plugin is a symbolic link
- Search the index. ``` @@ -150,6 +142,12 @@ fisher search --tag={git,test} ... ``` +The legend consists of: + +`*` The plugin is currently enabled
+`>` The plugin is a prompt
+`@` The plugin is a symbolic link
+ ## PLUMBING Fisherman commands are pipe aware. Plumb one with another to create complex functionality. @@ -192,7 +190,7 @@ The following illustrates an example Fisherman configuration path with a single $fisher_config |-- cache/ |-- conf.d/ -| `-- my_plugin.config.fish +| `-- my_plugin.fish |-- fishfile |-- functions/ | |-- my_plugin.fish @@ -276,7 +274,7 @@ 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. +Utilities are plugins that define one or more functions. This example walks you through creating *wtc*, a plugin based in *github/ngerakines/commitment* random commit message generator. @@ -301,6 +299,7 @@ function wtc -d "Generate a random commit message" end curl -s whatthecommit.com/index.txt end +functions wtc > wtc.fish ``` Install the plugin. @@ -326,8 +325,7 @@ git push origin master To submit wtc to the official index. ```fish -fisher install submit -fisher submit +fisher submit wtc "Random commit message generator" "commit random fun" https://github.com/owner/wtc ``` 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. @@ -336,20 +334,20 @@ This will create a PR in the Fisherman index repository. Once the PR is approved 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" -^ +$EDITOR completions/wtc.fish ``` -Alternatively, use `__fisher_complete` to create completions from wtc usage output. +```fish +complete --command wtc --short h --long help --description "Show usage help" +``` + +Or use `__fisher_complete` to create completions from wtc usage output. ``` wtc --help | __fisher_complete wtc @@ -363,10 +361,12 @@ There are utilities that can help you generate man pages from various text forma To create a man page manually. -```fish +``` mkdir -p man/man1 -cat > man/man1/wtc.1 +$EDITOR man/man1/wtc.1 +``` +``` .TH man 1 "Today" "1.0" "wtc man page" .SH NAME wtc \- Generate a random commit message @@ -376,14 +376,13 @@ cat > man/man1/wtc.1 -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. +Create a new file in the root of your project and add the name or URL of your dependencies. ```fish cat > fishfile