maxbrunsfeld/vim-yankstack — Issue #4: Including a help file
Author: mMontu
Created: 2012-02-17 12:37:56+00:00
State: open

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$
<

==============================================================================
MAPPINGS *yankstack-mappings*

By default, yankstack adds only 2 key bindings, in normal and visual modes:

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

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

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