Clean up plugin READMEs and a few plugins

- fasd
- history
- mercurial
- pylint
- repo
- yii2

plugins/lighthouse/README.md

@@ -16,7 +16,8 @@ plugins=(... lighthouse)
   file in your directory with the URL to the individual project.
 
   Example:
-  ```zsh
+
+  ```console
   $ cat .lighthouse-url
   https://rails.lighthouseapp.com/projects/8994
 
@@ -24,3 +25,5 @@ plugins=(... lighthouse)
   Opening ticket #23
   # The browser goes to https://rails.lighthouseapp.com/projects/8994/tickets/23
   ```
+
+See a demo: http://screencast.com/t/ZDgwNDUwNT

plugins/lol/README.md

 # lol
 
-Plugin for adding catspeak aliases, because why not
+Plugin for adding catspeak aliases, because why not.
 
-## Enabling the plugin
+To use it, add `lol` to the plugins array in your zshrc file:
 
-1. Open your `.zshrc` file and add `lol` in the plugins section:
-
-   ```zsh
-   plugins=(
-       # all your enabled plugins
-       lol
-   )
-   ```
-
-2. Restart your terminal session or restart the shell:
-
-   ```console
-   $ exec zsh
-   $
-   ```
+```zsh
+plugins=(... lol)
+```
 
 ## Aliases
 
 | Alias        | Command                                                         |
-| ------------ | ---------------------------------------------------------------- |
+| ------------ | --------------------------------------------------------------- |
 | `:3`         | `echo`                                                          |
 | `alwayz`     | `tail -f`                                                       |
 | `bringz`     | `git pull`                                                      |

plugins/mercurial/README.md

 # Mercurial plugin
-### Usage
-Update .zshrc:
 
-1. Add name to the list of plugins, e.g. `plugins=(... mercurial ...)`
-   (that is pretty obvious).
-2. Switch to a theme which uses `hg_prompt_info`.
+This plugin adds some handy aliases for using Mercurial as well as a few
+utility and prompt functions that can be used in a theme.
 
-   Or, customize the `$PROMPT` variable of your current theme to contain current folder mercurial repo info. This can be done by putting a custom version of the theme in `$ZSH_CUSTOM` or by changing `$PROMPT` in `.zshrc` after loading the theme.
+To use it, add `mercurial` to the plugins array in your zshrc file:
 
-   The `robbyrussell` theme is used by default, so you need to modify `$PROMPT` var by adding `$(hg_prompt_info)` after `$(git_prompt_info)`, so it looks like this:
+```zsh
+plugins=(... mercurial)
+```
+
+## Aliases
+
+| Alias  | Command                                                                                                     |
+|--------|-------------------------------------------------------------------------------------------------------------|
+| `hga`  | `hg add`                                                                                                    |
+| `hgc`  | `hg commit`                                                                                                 |
+| `hgca` | `hg commit --amend`                                                                                         |
+| `hgb`  | `hg branch`                                                                                                 |
+| `hgba` | `hg branches`                                                                                               |
+| `hgbk` | `hg bookmarks`                                                                                              |
+| `hgco` | `hg checkout`                                                                                               |
+| `hgd`  | `hg diff`                                                                                                   |
+| `hged` | `hg diffmerge`                                                                                              |
+| `hgp`  | `hg push`                                                                                                   |
+| `hgs`  | `hg status`                                                                                                 |
+| `hgsl` | `hg log --limit 20 --template "{node|short} | {date|isodatesec} | {author|user}: {desc|strip|firstline}\n"` |
+| `hgun` | `hg resolve --list`                                                                                         |
+| `hgi`  | `hg incoming`                                                                                               |
+| `hgl`  | `hg pull -u`                                                                                                |
+| `hglr` | `hg pull --rebase`                                                                                          |
+| `hgo`  | `hg outgoing`                                                                                               |
+
+## Prompt usage
+
+- Switch to a theme which uses `hg_prompt_info`
+
+- Or customize the `$PROMPT` variable of your current theme to contain current folder mercurial repo info.
+  This can be done by putting a custom version of the theme in `$ZSH_CUSTOM` or by changing `$PROMPT` in
+  `.zshrc` after loading the theme.
+
+  For example, for the `robbyrussell` theme you need to modify `$PROMPT` var by adding `$(hg_prompt_info)`
+  after `$(git_prompt_info)`, so it looks like this:
 
   ```zsh
   PROMPT='${ret_status}%{$fg_bold[green]%}%p %{$fg[cyan]%}%c %{$fg_bold[blue]%}$(git_prompt_info)$(hg_prompt_info)%{$fg_bold[blue]%} % %{$reset_color%}'
   ```
 
-3. Initialize additional vars used in plugin. So in short put next in **.zshrc**:
+You can also redefine additional vars used in the plugin (after Oh My Zsh is sourced):
 
-   ```
-   ZSH_THEME_HG_PROMPT_PREFIX="%{$fg_bold[magenta]%}hg:(%{$fg[red]%}"
-   ZSH_THEME_HG_PROMPT_SUFFIX="%{$reset_color%}"
-   ZSH_THEME_HG_PROMPT_DIRTY="%{$fg[magenta]%}) %{$fg[yellow]%}✗%{$reset_color%}"
-   ZSH_THEME_HG_PROMPT_CLEAN="%{$fg[magenta]%})"
-   ```
+```zsh
+ZSH_THEME_HG_PROMPT_PREFIX="%{$fg_bold[magenta]%}hg:(%{$fg[red]%}"
+ZSH_THEME_HG_PROMPT_SUFFIX="%{$reset_color%}"
+ZSH_THEME_HG_PROMPT_DIRTY="%{$fg[magenta]%}) %{$fg[yellow]%}✗%{$reset_color%}"
+ZSH_THEME_HG_PROMPT_CLEAN="%{$fg[magenta]%})"
+```
+
+### Display repo branch and directory status in prompt
+
+This is the same as git plugin does. **Note**: additional changes to `.zshrc`, or using a theme designed
+to use `hg_prompt_info`, are required in order for this to work.
+
+## Mantainers
 
-### What's inside?
-#### Adds handy aliases:
-###### general
-* `hga` - 'hg add`
-* `hgc` - `hg commit`
-* `hgb` - `hg branch`
-* `hgba` - `hg branches`
-* `hgbk` - `hg bookmarks`
-* `hgco` - `hg checkout`
-* `hgd`  - `hg diff`
-* `hged` - `hg diffmerge`
-
-###### pull and update
-* `hgi` - `hg incoming`
-* `hgl` - `hg pull -u`
-* `hglr` - `hg pull --rebase`
-* `hgo` - `hg outgoing`
-* `hgp` - `hg push`
-* `hgs` - `hg status`
-* `hgsl` - `hg log --limit 20 --template "{node|short} | {date|isodatesec} | {author|user}: {desc|strip|firstline}\n"`
-
-###### this is the 'git commit --amend' equivalent
-* `hgca` - `hg qimport -r tip ; hg qrefresh -e ; hg qfinish tip`
-
-###### list unresolved files (since hg does not list unmerged files in the status command)
-* `hgun` - `hg resolve --list`
-
-#### Displays repo branch and directory status in prompt
-This is the same as git plugin does.
-
-**Note**: Additional changes to **.zshrc**, or using a theme designed to use `hg_prompt_info`, are required in order for this to work.
-
-### Mantainers
-[ptrv](https://github.com/ptrv) - original creator
-
-[oshybystyi](https://github.com/oshybystyi) - created this README and know how most of code works
+- [ptrv](https://github.com/ptrv): original creator
+- [oshybystyi](https://github.com/oshybystyi)

plugins/mercurial/mercurial.plugin.zsh

-# Mercurial
+# aliases
 alias hga='hg add'
 alias hgc='hg commit'
+alias hgca='hg commit --amend'
 alias hgb='hg branch'
 alias hgba='hg branches'
 alias hgbk='hg bookmarks'
 alias hgco='hg checkout'
 alias hgd='hg diff'
 alias hged='hg diffmerge'
+alias hgp='hg push'
+alias hgs='hg status'
+alias hgsl='hg log --limit 20 --template "{node|short} | {date|isodatesec} | {author|user}: {desc|strip|firstline}\n"'
+alias hgun='hg resolve --list'
 # pull and update
 alias hgi='hg incoming'
 alias hgl='hg pull -u'
 alias hglr='hg pull --rebase'
 alias hgo='hg outgoing'
-alias hgp='hg push'
-alias hgs='hg status'
-alias hgsl='hg log --limit 20 --template "{node|short} | {date|isodatesec} | {author|user}: {desc|strip|firstline}\n" '
-alias hgca='hg commit --amend'
-# list unresolved files (since hg does not list unmerged files in the status command)
-alias hgun='hg resolve --list'
 
 function in_hg() {
   if [[ -d .hg ]] || $(hg summary > /dev/null 2>&1); then

plugins/meteor/README.md

-## Introduction
+# meteor plugin
 
 The [meteor plugin](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/meteor) provides many
 [useful aliases](#aliases) as well as completion for the `meteor` command.
 
 Enable it by adding `meteor` to the plugins array in your zshrc file:
+
 ```zsh
 plugins=(... meteor)
 ```

plugins/mvn/README.md

@@ -4,6 +4,7 @@ The mvn plugin provides many [useful aliases](#aliases) as well as completion fo
 the [Apache Maven](https://maven.apache.org/) command (`mvn`).
 
 Enable it by adding `mvn` to the plugins array in your zshrc file:
+
 ```zsh
 plugins=(... mvn)
 ```

plugins/mysql-macports/README.md

@@ -13,8 +13,8 @@ For instructions on how to install MySQL using MacPorts, read the [MacPorts wiki
 ## Aliases
 
 | Alias        | Command                              | Description                                |
-| ------------ | --------------------------------------------------------- | ------------------------------------------ |
-| mysqlstart   | `sudo /opt/local/share/mysql5/mysql/mysql.server start`   | Start the MySQL server.                    |
-| mysqlstop    | `sudo /opt/local/share/mysql5/mysql/mysql.server stop`    | Stop the MySQL server.                     |
-| mysqlrestart | `sudo /opt/local/share/mysql5/mysql/mysql.server restart` | Restart the MySQL server.                  |
+| ------------ | ------------------------------------ | ------------------------------------------ |
+| mysqlstart   | `sudo /path/to/mysql.server start`   | Start the MySQL server.                    |
+| mysqlstop    | `sudo /path/to/mysql.server stop`    | Stop the MySQL server.                     |
+| mysqlrestart | `sudo /path/to/mysql.server restart` | Restart the MySQL server.                  |
 | mysqlstatus  | `mysqladmin5 -u root -p ping`        | Check whether the MySQL server is running. |

plugins/node/README.md

 # node plugin
 
+This plugin adds `node-docs` function that opens specific section in [Node.js](https://nodejs.org)
+documentation (depending on the installed version).
+
 To use it, add `node` to the plugins array of your zshrc file:
+
 ```zsh
 plugins=(... node)
 ```
 
-This plugin adds `node-docs` function that open specific section in [Node.js](https://nodejs.org) documentation (depending on the installed version).
-For example:
+## Usage
 
 ```zsh
 # Opens https://nodejs.org/docs/latest-v10.x/api/fs.html

plugins/npm/README.md

-## npm plugin
+# npm plugin
 
 The npm plugin provides completion as well as adding many useful aliases.
 
 To use it, add npm to the plugins array of your zshrc file:
-```
+
+```zsh
 plugins=(... npm)
 ```
 

plugins/osx/README.md

 # OSX plugin
 
-## Description
-
-This plugin provides a few utilities to make it more enjoyable on OSX.
+This plugin provides a few utilities to make it more enjoyable on macOS (previously named OSX).
 
 To start using it, add the `osx` plugin to your plugins array in `~/.zshrc`:
 
@@ -12,6 +10,27 @@ plugins=(... osx)
 
 Original author: [Sorin Ionescu](https://github.com/sorin-ionescu)
 
+## Commands
+
+| Command         | Description                                           |
+| :-------------- | :---------------------------------------------------- |
+| `tab`           | Open the current directory in a new tab               |
+| `split_tab`     | Split the current terminal tab horizontally           |
+| `vsplit_tab`    | Split the current terminal tab vertically             |
+| `ofd`           | Open the current directory in a Finder window         |
+| `pfd`           | Return the path of the frontmost Finder window        |
+| `pfs`           | Return the current Finder selection                   |
+| `cdf`           | `cd` to the current Finder directory                  |
+| `pushdf`        | `pushd` to the current Finder directory               |
+| `quick-look`    | Quick-Look a specified file                           |
+| `man-preview`   | Open a specified man page in Preview app              |
+| `showfiles`     | Show hidden files                                     |
+| `hidefiles`     | Hide the hidden files                                 |
+| `itunes`        | DEPRECATED. Use `music` from macOS Catalina on        |
+| `music`         | Control Apple Music. Use `music -h` for usage details |
+| `spotify`       | Control Spotify and search by artist, album, track…   |
+| `rmdsstore`     | Remove .DS\_Store files recursively in a directory    |
+
 ## Acknowledgements
 
 This application makes use of the following third party scripts:
@@ -38,25 +57,3 @@ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-
-## Commands
-
-| Command         | Description                                           |
-| :-------------- | :---------------------------------------------------- |
-| `tab`           | Open the current directory in a new tab               |
-| `split_tab`     | Split the current terminal tab horizontally           |
-| `vsplit_tab`    | Split the current terminal tab vertically             |
-| `ofd`           | Open the current directory in a Finder window         |
-| `pfd`           | Return the path of the frontmost Finder window        |
-| `pfs`           | Return the current Finder selection                   |
-| `cdf`           | `cd` to the current Finder directory                  |
-| `pushdf`        | `pushd` to the current Finder directory               |
-| `quick-look`    | Quick-Look a specified file                           |
-| `man-preview`   | Open a specified man page in Preview app              |
-| `showfiles`     | Show hidden files                                     |
-| `hidefiles`     | Hide the hidden files                                 |
-| `itunes`        | DEPRECATED. Use `music` from macOS Catalina on        |
-| `music`         | Control Apple Music. Use `music -h` for usage details |
-| `spotify`       | Control Spotify and search by artist, album, track…   |
-| `rmdsstore`     | Remove .DS\_Store files recursively in a directory    |

plugins/perms/README.md

-## Perms
+# Perms plugin
 
-Plugin to handle some unix filesystem permissions quickly
+Plugin to handle some unix filesystem permissions quickly.
 
-### Usage
+To use it, add `perms` to the plugins array in your zshrc file:
+
+```zsh
+plugins=(... perms)
+```
+
+## Usage
 
 * `set755` recursively sets all given directories (default to .) to octal 755.
 * `set644` recursively sets all given files (default to .) to octal 644.

plugins/pylint/README.md

 # pylint
 
-This plugin adds code analysis for python through [Pylint](https://www.pylint.org/).
+This plugin adds aliases and autocompletion for [Pylint](https://www.pylint.org/),
+the Python code style checking tool.
 
 To use it, add `pylint` to the plugins array in your zshrc file:
 
@@ -12,4 +13,4 @@ plugins=(... pylint)
 
 | Alias        | Command              | Description                                                                                                              |
 | -------------| -------------------- | -------------------------------------------------------------------------------------------------------------------------|
-| pylint-quick | `pylint --reports=n` | Displays a set of reports each one focusing on a particular aspect of the project, default set `no` for multiple reports |                                         |
+| pylint-quick | `pylint --reports=n` | Displays a set of reports each one focusing on a particular aspect of the project, default set `no` for multiple reports |

plugins/pylint/pylint.plugin.zsh

-# Aliases
 alias pylint-quick='pylint --reports=n'
-compdef _pylint-quick pylint-quick='pylint --reports=n'

plugins/rails/README.md

@@ -80,4 +80,3 @@ separately. For example: `REP rake db:migrate` will migrate the production db.
 | `ssp`   | `ruby script/spec`                 |
 | `sc`    | `ruby script/console`              |
 | `sd`    | `ruby script/server --debugger`    |
-

plugins/repo/README.md

-## repo
-**Maintainer:** [Stibbons](https://github.com/Stibbons)
+# repo plugin
 
-This plugin mainly add support automatic completion for the repo command line tool:
-https://code.google.com/p/git-repo/
+This plugin mainly adds some aliases and support for automatic completion for
+the [repo command line tool](https://code.google.com/p/git-repo/).
 
-* `r` aliases `repo`
+To use it, add `repo` to the plugins array in your zshrc file:
+
+```zsh
+plugins=(... repo)
+```
+
+## Aliases
+
+| Alias   | Command                                |
+|---------|----------------------------------------|
+| `r`     | `repo`                                 |
+| `rra`   | `repo rebase --auto-stash`             |
+| `rs`    | `repo sync`                            |
+| `rsrra` | `repo sync ; repo rebase --auto-stash` |
+| `ru`    | `repo upload`                          |
+| `rst`   | `repo status`                          |
+| `rsto`  | `repo status -o`                       |
+| `rfa`   | `repo forall -c`                       |
+| `rfap`  | `repo forall -p -c`                    |
+| `rinf`  | `repo info`                            |

plugins/repo/_repo

 #compdef repo
 
-
 __git_apply_whitespace_strategies ()
 {
   declare -a strategies
@@ -269,4 +268,3 @@ __repo_projects_or_all()
 
 _repo "$@"
 return $?
-

plugins/repo/repo.plugin.zsh

-# Aliases
 alias r='repo'
-compdef _repo r=repo
-
 alias rra='repo rebase --auto-stash'
-compdef _repo rra='repo rebase --auto-stash'
-
 alias rs='repo sync'
-compdef _repo rs='repo sync'
-
 alias rsrra='repo sync ; repo rebase --auto-stash'
-compdef _repo rsrra='repo sync ; repo rebase --auto-stash'
-
 alias ru='repo upload'
-compdef _repo ru='repo upload'
-
 alias rst='repo status'
-compdef _repo rst='repo status'
-
 alias rsto='repo status -o'
-compdef _repo rsto='repo status -o'
-
 alias rfa='repo forall -c'
-compdef _repo rfa='repo forall -c'
-
 alias rfap='repo forall -p -c'
-compdef _repo rfap='repo forall -p -c'
-
 alias rinf='repo info'
-compdef _repo rinf='repo info'

plugins/rvm/README.md

@@ -8,7 +8,8 @@ To use it, add `rvm` to the plugins array in your zshrc file:
 plugins=(... rvm)
 ```
 
-## Functions
+## Aliases
+
 | Alias          | Command              |
 |----------------|----------------------|
 | `rb18`         | `rvm use ruby-1.8.7` |

plugins/scala/README.md

-## Scala plugin
+# Scala plugin
 
 Completion script for [scala and scalac](https://www.scala-lang.org/) commands.
 
 To use it, add `scala` to the plugins array of your zshrc file:
-```
+
+```zsh
 plugins=(... scala)
 ```
 
 ## Aliases
 
 | Command  | Description                     |
-|------------------|---------------------------------------------------------------------------------|
+|----------|---------------------------------|
 | `scala`  | Run code in the Scala language  |
 | `scalac` | Compiler for the Scala language |

plugins/sdk/README.md

@@ -3,6 +3,12 @@
 Plugin for SDKMAN, a tool for managing parallel versions of multiple Software Development Kits on most Unix based systems.
 Provides autocompletion for all known commands.
 
+To use it, add `sdk` to your plugins array in your zshrc file:
+
+```zsh
+plugins=(... sdk)
+```
+
 ## Requirements
 
- * [SDKMAN](http://sdkman.io/)
+* [SDKMAN](http://sdkman.io/)