Including a help file

[Marcelo D Montu]

First of all, thanks for sharing this awesome plugin!

I think a help file (doc/yankstack.txt) would be nice for quick references,
therefore I've made attempted to format the README.md to vim help format:

*yankstack.txt*  lightweight implementation of the Emacs 'kill ring' 

Last updated on: 2012 fev 17

          YANKSTACK by: Max Brunsfeld 

==============================================================================
INTRODUCTION                                    *yankstack*

This plugin allows you to yank and delete things without worrying about losing
the text that you yanked previously. It effectively turns your default
register into a stack, and lets you cycle through the items in the stack after
doing a paste.

This plugin is intended to be a simpler alternative to the {Yankring} plugin
(https://github.com/chrismetcalf/vim-yankring).

==============================================================================
INSTALLATION                                    *yankstack-installation*

I recommend loading your plugins with {Pathogen}
(https://github.com/tpope/vim-pathogen), so you can just clone this repo into
your "bundle" directory.

==============================================================================
INITIALIZATION                                  *yankstack-initialization*

Yankstack works by mapping the yank and paste keys to functions that do some
book-keeping before calling through to the normal yank/paste keys. You may
want to define your own mappings of the yank and paste keys. For example, I
like to map the |Y| key to "y$", so that it behaves the same as |D| and |C|.
The yankstack mappings need to happen ***BEFORE*** you define any such
mappings of your own. To achieve this, just call 'yankstack#setup()'in your
|vimrc|, before defining your mappings: >

   call yankstack#setup()
   nmap Y y$
                 cycle backward through your history of yanks
    

                 cycle forwards through your history of yanks

After pasting some text using |p| or |P|, you can cycle through your yank
history using these commands.
It is possible to disable the creation of these mapping and/or adding your own
mappings to these functions - see |yankstack-configuration|.

==============================================================================
VIEWING THE LIST OF YANKS                    *yankstack-list* *yankstack-Yanks*

:Yanks                  list the contents of the yank-stack

==============================================================================
CONFIGURATION                                   *yankstack-configuration*

If you want to load yankstack without defining any of the default key
mappings, just add >

   let g:yankstack_map_keys = 0

to your |.vimrc| file.


Yankstack defines three plugin mappings that you can map to keys of your
choosing. The same mappings work in normal and insert modes.

yankstack_substitute_older_paste  cycle backwards through your history
                                        of yanks

yankstack_substitute_newer_paste  cycle forwards through your history of
                                         yanks

yankstack_insert_mode_paste       paste in insert mode, and create an
                                        undo entry, so that yankstack will
                                        register the paste

For example, if you wanted to define some mappings based on your 'leader' key, you could do this:

nmap p yankstack_substitute_older_paste
nmap P yankstack_substitute_older_paste

Or, if you wanted to define emacs style bindings in insert mode, you could do
this:

imap yankstack_insert_mode_paste
imap yankstack_substitute_older_paste
imap yankstack_substitute_older_paste

==============================================================================
CHANGELOG                                       *yankstack-changelog*

1.0.1:
  - Change default key bindings, update readme, add link to github page.
    2012-02-11

1.0.1   
  - Fix bug when displaying empty yanks. 2011-12-08

1.0     
  - Remove unnecessary dependency on the undotree() function. Plugin should
    now work on any recent version of vim.  2011-12-04


==============================================================================


 vim:tw=78:ts=8:ft=help:norl:

[Max Brunsfeld]

@mMontu, thanks; the text you included was a great start. I've included a help file.