Add examples & installation instructions

Address issue #2.

README.md

@@ -1,22 +1,33 @@
 # `zsh-hist`
 Edit your history in Zsh, without ever leaving the command line.
 
-## Features
-* Edit your history with the [`hist` command](#hist-command-syntax).
-* Fix your previous command by [pressing <kbd>undo</kbd>](#added-undo-functionality).
-* Push/get lines to/from history with [<kbd>push-line</kbd> and
-  <kbd>get-line</kbd>](#push-line-to-history--get-line-from-history).
+* [Installation](#installation)
+* Features:
+  * Fix your previous command by [pressing <kbd>undo</kbd>](#added-undo-functionality).
+  * Push & get lines to/from history with [<kbd>push-line</kbd> and
+    <kbd>get-line</kbd>](#push--get-lines-tofrom-history).
+  * Edit your history with the [`hist` command](#hist-command-syntax).
+* Don't know how to change your key bindings? Please [read these notes](#note-about-key-bindings).
+* [Author](#author)
+* [License](#license)
 
-(Don't know how to change your key bindings? Please [read these notes](#note-about-key-bindings))
+## Installation
+ 1. `git clone` this repo.
+ 1. Add the following to your `~/.zshrc` file:
+    ```zsh
+    source path/to/zsh-hist.plugin.zsh
+    ```
 
-## Added <kbd>undo</kbd> functionality
+To update, `cd` into your clone and `git pull`.
+
+## Added Undo functionality
 On any new command line, you can now press <kbd>undo</kbd> to pop the last command from your
-history into the line editor, letting you correct any mistakes you made before running it back.
-Afterwards, the old command will no longer be found in your history.
+history into the line editor, letting you correct any mistakes you made, before running it back.
+Afterwards, the old, faulty command will be gone from your history.
 
-## <kbd>push-line</kbd> to history & <kbd>get-line</kbd> from history
+## Push & Get lines to/from history
 When you press <kbd>push-line</kbd>, <kbd>push-input</kbd> or <kbd>push-line-or-edit</kbd>, your
-line is now written to history (without being executed).
+line is now written to history (without being executed) instead of to the buffer stack.
 
 This has the following benefits:
 * A pushed line does not automatically get popped back into your line editor. You can instead get
@@ -57,13 +68,26 @@ Selection (required for some actions; mutually exclusive):
   positive integer  index from beginning of history
   negative integer  offset from end of history
   string            pattern to match; can select multiple entries
+
+
+--Examples--
+
+Delete all history items starting with `fc `:
+  hist d 'fc *'
+
+List all history items starting with `git ` and ending with `lease`:
+  hist l 'git *lease'
+
+Fix the last history item: Cut from history, paste into command line.
+  hist f -1
 ```
 
-## Note About Key Bindings
+## Note about key bindings
 `zsh-hist` does not change your key bindings. To use the keyboard commands (a.k.a "widgets") that
-`zsh-hist` enhances, you will need to know to which key strokes they are bound. Not all widgets discussed here are bound by default.
+`zsh-hist` enhances, you will need to know to which key strokes they are bound. Not all widgets
+discussed here are bound by default.
 * Type `bindkey` to see your current key bindings.
-* To add a new new keybinding or override an existing one, add lines like in this example to your
+* To add a new new keybinding or override an existing one, add lines like the following to your
   `~/.zshrc` file, where `^` means <kbd>Ctrl</kbd> and `^[` means <kbd>Alt</kbd> (depending on your
   terminal):
   ```sh

functions/.hist.help

@@ -1,27 +1,44 @@
 #!/bin/zsh
-emulate -L zsh -o noshortloops -o warncreateglobal -o extendedglob -o rcquotes
+emulate -L zsh -o warncreateglobal -o extendedglob
 
 local key value
 
-print 'Usage:'
-print '  hist [options] <action> [selection]  ->  $reply'
-print -l
-print 'Return value:'
-print '  reply  an associative array of history (index, entry) tuples'
-print -l
-print 'Options (can be combined):'
+print -l \
+  'Usage:' \
+  '  hist [options] <action> [selection]  ->  $reply' \
+  '' \
+  'Return value:' \
+  '  reply  an associative array of history (index, entry) tuples' \
+  '' \
+  'Options (can be combined):'
 for key in ${(ko@)_HIST__OPTS}; do
   print "  $key  ${_HIST__OPTS[$key]}"
 done
-print 'By default, hist asks for confirmation only when operating on multiple history entries.'
-print -l
-print 'Actions (required; mutually exclusive):'
+print -l \
+  'By default, hist asks for confirmation only when operating on multiple history entries.' \
+  '' \
+  'Actions (required; mutually exclusive):'
 for key in ${(ko@)_HIST__ARGS}; do
   print "  $key  ${_HIST__ARGS[$key]}"
 done
-print -l
-print 'Selection (required for some actions; mutually exclusive):'
-print '  empty or 0        pushed lines'
-print '  positive integer  index from beginning of history'
-print '  negative integer  offset from end of history'
-print '  string            pattern to match; can select multiple entries'
+print -l \
+  '' \
+  'Selection (required for some actions; mutually exclusive):' \
+  '  empty or 0        pushed lines' \
+  '  positive integer  index from beginning of history' \
+  '  negative integer  offset from end of history' \
+  '  string            pattern to match; can select multiple entries' \
+  '' \
+  '' \
+  '--Examples--' \
+  '' \
+  'Delete all history items starting with `fc `:' \
+ $'  hist d \'fc *\'' \
+  '' \
+  'List all history items starting with `git ` and ending with `lease`:' \
+ $'  hist l \'git *lease\'' \
+  '' \
+  'Fix the last history item: Cut from history, paste into command line.' \
+  '  hist f -1' \
+  ''
+