Clean up plugin READMEs and a few plugins

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

plugins/apache2-macports/README.md

-## APACHE2 MACPORTS PLUGIN
+# apache2-macports plugin
 
+Enables aliases to control a local Apache2 installed via [MacPorts](https://www.macports.org/).
 
----
+To use it, add `apache2-macports` to the plugins array in your zshrc file:
 
-### FEATURES
+```zsh
+plugins=(... apache2-macports)
+```
 
-| Alias          | Function                                                                       | Description           |
-|:--------------:|:-------------------------------------------------------------------------------|----------------------:|
-| apache2restart | sudo /opt/local/etc/LaunchDaemons/org.macports.apache2/apache2.wrapper restart | Restart apache daemon |
-| apache2start   | sudo /opt/local/etc/LaunchDaemons/org.macports.apache2/apache2.wrapper start   | Start apache daemon   |
-| apache2stop    | sudo /opt/local/etc/LaunchDaemons/org.macports.apache2/apache2.wrapper stop    | Stop apache daemon    |
+## Aliases
 
----
+| Alias          | Function                                | Description           |
+|----------------|-----------------------------------------|-----------------------|
+| apache2restart | `sudo /path/to/apache2.wrapper restart` | Restart apache daemon |
+| apache2start   | `sudo /path/to/apache2.wrapper start`   | Start apache daemon   |
+| apache2stop    | `sudo /path/to/apache2.wrapper stop`    | Stop apache daemon    |
 
-### CONTRIBUTORS
- - Alexander Rinass (alex@rinass.net)
+## Contributors
 
----
+- Alexander Rinass (alex@rinass.net)

plugins/archlinux/README.md

 # Archlinux plugin
 
+This plugin adds some aliases and functions to work with Arch Linux.
+
+To use it, add `archlinux` to the plugins array in your zshrc file:
+
+```zsh
+plugins=(... archlinux)
+```
+
 ## Features
 
 #### YAY

plugins/bower/README.md

@@ -4,7 +4,7 @@ This plugin adds completion for [Bower](https://bower.io/) and a few useful alia
 
 To use it, add `bower` to the plugins array in your zshrc file:
 
-```
+```zsh
 plugins=(... bower)
 ```
 
@@ -15,4 +15,3 @@ plugins=(... bower)
 | bi    | `bower install` | Installs the project dependencies listed in bower.json |
 | bl    | `bower list`    | List local packages and possible updates               |
 | bs    | `bower search`  | Finds all packages or a specific package.              |
-

plugins/cake/README.md

@@ -10,6 +10,6 @@ plugins=(... cake)
 
 ## Note
 
-This plugin generates a cache file of the cake tasks found, named `.cake_task_cache`, in the current working directory. 
+This plugin generates a cache file of the cake tasks found, named `.cake_task_cache`, in the current working directory.
 It is regenerated when the Cakefile is newer than the cache file. It is advised that you add the cake file to your
 `.gitignore` files.

plugins/catimg/README.md

@@ -2,27 +2,15 @@
 
 Plugin for displaying images on the terminal using the the `catimg.sh` script provided by [posva](https://github.com/posva/catimg)
 
-## Requirements
-
-- `convert` (ImageMagick)
-
-## Enabling the plugin
+To use it, add `catimg` to the plugins array in your zshrc file:
 
-1. Open your `.zshrc` file and add `catimg` in the plugins section:
+```zsh
+plugins=(... catimg)
+```
 
-   ```zsh
-   plugins=(
-       # all your enabled plugins
-       catimg
-   )
-   ```
-
-2. Restart the shell or restart your Terminal session:
+## Requirements
 
-   ```console
-   $ exec zsh
-   $
-   ```
+- `convert` (ImageMagick)
 
 ## Functions
 

plugins/chucknorris/README.md

 # chucknorris
 
-Chuck Norris fortunes plugin for oh-my-zsh
+Chuck Norris fortunes plugin for oh-my-zsh. Perfectly suitable as MOTD.
 
 **Maintainers**: [apjanke](https://github.com/apjanke) [maff](https://github.com/maff)
 
@@ -10,11 +10,31 @@ To use it add `chucknorris` to the plugins array in you zshrc file.
 plugins=(... chucknorris)
 ```
 
-
-Depends on fortune (and cowsay if using chuck_cow) being installed (available via homebrew, apt, ...). Perfectly suitable as MOTD.
-
+## Usage
 
 | Command     | Description                     |
 | ----------- | ------------------------------- |
 | `chuck`     | Print random Chuck Norris quote |
 | `chuck_cow` | Print quote in cowthink         |
+
+Example: output of `chuck_cow`:
+
+```
+Last login: Fri Jan 30 23:12:26 on ttys001
+ ______________________________________
+( When Chuck Norris plays Monopoly, it )
+( affects the actual world economy.    )
+ --------------------------------------
+        o   ^__^
+         o  (oo)\_______
+            (__)\       )\/\
+                ||----w |
+                ||     ||
+```
+
+## Requirements
+
+- `fortune`
+- `cowsay` if using `chuck_cow`
+
+Available via homebrew, apt, ...

plugins/cloudapp/README.md

@@ -4,7 +4,7 @@
 
 To use it, add `cloudapp` to the plugins array of your `~/.zshrc` file:
 
-```
+```zsh
 plugins=(... cloudapp)
 ```
 

plugins/coffee/README.md

-## Coffeescript Plugin
+# Coffeescript Plugin
 
 This plugin provides aliases for quickly compiling and previewing your
 coffeescript code.

plugins/compleat/README.md

@@ -3,6 +3,7 @@
 This plugin looks for [compleat](https://github.com/mbrubeck/compleat) and loads its completion.
 
 To use it, add compleat to the plugins array in your zshrc file:
-```
+
+```zsh
 plugins=(... compleat)
 ```

plugins/composer/README.md

@@ -12,18 +12,18 @@ plugins=(... composer)
 
 ## Aliases
 
-| Alias  | Command                                      | Description                                                                            |
-| ------ | -------------------------------------------- | -------------------------------------------------------------------------------------- |
-| `c`    | composer                                     | Starts composer                                                                        |
-| `csu`  | composer self-update                         | Updates composer to the latest version                                                 |
-| `cu`   | composer update                              | Updates composer dependencies and `composer.lock` file                                 |
-| `cr`   | composer require                             | Adds new packages to `composer.json`                                                   |
-| `crm`  | composer remove                              | Removes packages from `composer.json`                                                  |
-| `ci`   | composer install                             | Resolves and installs dependencies from `composer.json`                                |
-| `ccp`  | composer create-project                      | Create new project from an existing package                                            |
-| `cdu`  | composer dump-autoload                       | Updates the autoloader                                                                 |
-| `cdo`  | composer dump-autoload --optimize-autoloader | Converts PSR-0/4 autoloading to classmap for a faster autoloader (good for production) |
-| `cgu`  | composer global update                       | Allows update command to run on COMPOSER_HOME directory                                |
-| `cgr`  | composer global require                      | Allows require command to run on COMPOSER_HOME directory                               |
-| `cgrm` | composer global remove                       | Allows remove command to run on COMPOSER_HOME directory                                |
-| `cget` | `curl -s https://getcomposer.org/installer`  | Installs composer in the current directory                                             |
+| Alias  | Command                                        | Description                                                                            |
+| ------ | ---------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `c`    | `composer`                                     | Starts composer                                                                        |
+| `csu`  | `composer self-update`                         | Updates composer to the latest version                                                 |
+| `cu`   | `composer update`                              | Updates composer dependencies and `composer.lock` file                                 |
+| `cr`   | `composer require`                             | Adds new packages to `composer.json`                                                   |
+| `crm`  | `composer remove`                              | Removes packages from `composer.json`                                                  |
+| `ci`   | `composer install`                             | Resolves and installs dependencies from `composer.json`                                |
+| `ccp`  | `composer create-project`                      | Create new project from an existing package                                            |
+| `cdu`  | `composer dump-autoload`                       | Updates the autoloader                                                                 |
+| `cdo`  | `composer dump-autoload --optimize-autoloader` | Converts PSR-0/4 autoloading to classmap for a faster autoloader (good for production) |
+| `cgu`  | `composer global update`                       | Allows update command to run on COMPOSER_HOME directory                                |
+| `cgr`  | `composer global require`                      | Allows require command to run on COMPOSER_HOME directory                               |
+| `cgrm` | `composer global remove`                       | Allows remove command to run on COMPOSER_HOME directory                                |
+| `cget` | `curl -s https://getcomposer.org/installer`    | Installs composer in the current directory                                             |

plugins/copyfile/README.md

@@ -3,7 +3,8 @@
 Puts the contents of a file in your system clipboard so you can paste it anywhere.
 
 To use, add `copyfile` to your plugins array:
-```
+
+```zsh
 plugins=(... copyfile)
 ```
 

plugins/cpanm/README.md

 # Cpanm
 
 This plugin provides completion for [Cpanm](https://github.com/miyagawa/cpanminus) ([docs](https://metacpan.org/pod/App::cpanminus)).
- 
+
 To use it add cpanm to the plugins array in your zshrc file.
- 
- ```bash
+
+```zsh
 plugins=(... cpanm)
 ```

plugins/dirhistory/README.md

@@ -7,6 +7,7 @@ To use it, add `dirhistory` to the plugins array in your zshrc file:
 ```zsh
 plugins=(... dirhistory)
 ```
+
 ## Keyboard Shortcuts
 
 | Shortcut                          | Description                                               |
@@ -15,3 +16,24 @@ plugins=(... dirhistory)
 | <kbd>alt</kbd> + <kbd>right</kbd> | Undo <kbd>alt</kbd> + <kbd>left</kbd>                     |
 | <kbd>alt</kbd> + <kbd>up</kbd>    | Move into the parent directory                            |
 | <kbd>alt</kbd> + <kbd>down</kbd>  | Move into the first child directory by alphabetical order |
+
+## Usage
+
+This plugin allows you to navigate the history of previous current-working-directories using ALT-LEFT and ALT-RIGHT. ALT-LEFT moves back to directories that the user has changed to in the past, and ALT-RIGHT undoes ALT-LEFT. MAC users may alternately use OPT-LEFT and OPT-RIGHT.
+
+Also, navigate directory **hierarchy** using ALT-UP and ALT-DOWN. (mac keybindings not yet implemented). ALT-UP moves to higher hierarchy (shortcut for 'cd ..'). ALT-DOWN moves into the first directory found in alphabetical order (useful to navigate long empty directories e.g. java packages)
+
+For example, if the shell was started, and the following commands were entered:
+
+```shell
+cd ~
+cd /usr
+cd share
+cd doc
+```
+
+Then entering ALT-LEFT at the prompt would change directory from /usr/share/doc to /usr/share, then if pressed again to /usr/, then ~. If ALT-RIGHT were pressed the directory would be changed to /usr/ again.
+
+After that, ALT-DOWN will probably go to /usr/bin (depends on your /usr structure), ALT-UP will return to /usr, then ALT-UP will get you to /
+
+**Currently the max history size is 30**. The navigation should work for xterm, PuTTY xterm mode, GNU screen, and on MAC with alternate keys as mentioned above.

plugins/dirpersist/README.md

 # Dirpersist plugin
 
-This plugin keeps a running tally of the previous 20 unique directories in the $HOME/.zdirs file.  When you cd to a new directory, it is prepended to the beginning of the file.
+This plugin keeps a running tally of the previous 20 unique directories in the `$HOME/.zdirs` file.
+When you cd to a new directory, it is prepended to the beginning of the file.
 
 To use it, add `dirpersist` to the plugins array in your zshrc file:
 

plugins/django/README.md

@@ -34,23 +34,3 @@ runfcgi                    -- run this project as a fastcgi
 runserver                  -- start a lightweight web server for development
 ...
 ```
-
-If you want to see the options available for a specific command, try:
-
-```zsh
-$> python manage.py makemessages (press <TAB> here)
-```
-
-And that would result in:
-
-```zsh
---all         -a  -- re-examine all code and templates
---domain      -d  -- domain of the message files (default: "django")
---extensions  -e  -- file extension(s) to examine (default: ".html")
---help            -- display help information
---locale      -l  -- locale to process (default: all)
---pythonpath      -- directory to add to the Python path
---settings        -- python path to settings module
-...
-```
-

plugins/dnf/README.md

-## Description
+# dnf plugin
 
-This plugin makes `dnf` usage easier by adding aliases for the most
-common commands.
+This plugin makes `dnf` usage easier by adding aliases for the most common commands.
 
-`dnf` is the new package manager for RPM-based distributions, which
-replaces `yum`.
+`dnf` is the new package manager for RPM-based distributions, which replaces `yum`.
+
+To use it, add `dnf` to the plugins array in your zshrc file:
+
+```zsh
+plugins=(... dnf)
+```
 
 ## Aliases
 

plugins/docker-compose/README.md

@@ -4,7 +4,8 @@ This plugin provides completion for [docker-compose](https://docs.docker.com/com
 aliases for frequent docker-compose commands.
 
 To use it, add docker-compose to the plugins array of your zshrc file:
-```
+
+```zsh
 plugins=(... docker-compose)
 ```
 

plugins/docker/README.md

@@ -3,6 +3,7 @@
 This plugin adds auto-completion for [docker](https://www.docker.com/).
 
 To use it add `docker` to the plugins array in your zshrc file.
+
 ```zsh
 plugins=(... docker)
 ```

plugins/encode64/README.md

 # encode64
 
-Alias plugin for encoding or decoding using `base64` command
+Alias plugin for encoding or decoding using `base64` command.
+
+To use it, add `encode64` to the plugins array in your zshrc file:
+
+```zsh
+plugins=(... encode64)
+```
 
 ## Functions and Aliases
 
@@ -9,23 +15,6 @@ Alias plugin for encoding or decoding using `base64` command
 | `encode64` | `e64` | Encodes given data to base64   |
 | `decode64` | `d64` | Decodes given data from base64 |
 
-## Enabling plugin
-
-1. Edit your `.zshrc` file and add `encode64` to the list of plugins:
-
-   ```sh
-   plugins=(
-     # ...other enabled plugins
-     encode64
-   )
-   ```
-
-2. Restart your terminal session or restart the shell:
-
-   ```sh
-   exec zsh
-   ```
-
 ## Usage and examples
 
 ### Encoding

plugins/fabric/README.md

@@ -4,6 +4,6 @@ This plugin provides completion for [Fabric](https://www.fabfile.org/).
 
 To use it add fabric to the plugins array in your zshrc file.
 
-```bash
+```zsh
 plugins=(... fabric)
 ```