From 73e2d8ca7ed0d3eb4fce2c3220b9ce0e64ce57fc Mon Sep 17 00:00:00 2001
From: Martin Grenfell <martin.grenfell@gmail.com>
Date: Tue, 3 Jan 2012 16:05:19 +0000
Subject: [PATCH] update the doc for the new key api functionality

---
 doc/NERD_tree.txt | 31 ++++++++++++++++++++++---------
 1 file changed, 22 insertions(+), 9 deletions(-)

diff --git a/doc/NERD_tree.txt b/doc/NERD_tree.txt
index 174229d..395aafa 100644
--- a/doc/NERD_tree.txt
+++ b/doc/NERD_tree.txt
@@ -991,22 +991,32 @@ NERDTreeAddKeyMap({options})                             *NERDTreeAddKeyMap()*
     "quickhelpText" - the text that will appear in the quickhelp (see
     |NERDTree-?|)
 
+    Additionally, a "scope" argument may be supplied. This constrains the
+    mapping so that it is only activated if the cursor is on a certain object.
+    That object is then passed into the handling method. Possible values are:
+        "FileNode" - a file node
+        "DirNode" - a directory node
+        "Node" - a file or directory node
+        "Bookmark" - A bookmark
+        "all" - the keymap is not constrained to any scope (default). When
+        thei is used, the handling function is not passed any arguments.
+
+
     Example: >
         call NERDTreeAddKeyMap({
-               \ 'key': 'b',
-               \ 'callback': 'NERDTreeEchoCurrentNode',
+               \ 'key': 'foo',
+               \ 'callback': 'NERDTreeCDHandler',
                \ 'quickhelpText': 'echo full path of current node' })
+               \ 'scope': 'DirNode'
 
-        function! NERDTreeEchoCurrentNode()
-            let n = g:NERDTreeFileNode.GetSelected()
-            if n != {}
-                echomsg 'Current node: ' . n.path.str()
-            endif
+        function! NERDTreeCDHandler(dirnode)
+            call a:dirnode.changeToDir()
         endfunction
 <
     This code should sit in a file like ~/.vim/nerdtree_plugin/mymapping.vim.
-    It adds a (rather useless) mapping on 'b' which echos the full path to the
-    current node.
+    It adds a (redundant) mapping on 'foo' which changes vim's CWD to that of
+    the current dir node. Note this mapping will only fire when the cursor is
+    on a directory node.
 
 ------------------------------------------------------------------------------
 4.2. Menu API                                                *NERDTreeMenuAPI*
@@ -1116,6 +1126,9 @@ The latest dev versions are on github
 ==============================================================================
 6. Changelog                                               *NERDTreeChangelog*
 
+Next
+    - add 'scope' argument to the key map API
+
 4.2.0
     - Add NERDTreeDirArrows option to make the UI use pretty arrow chars
       instead of the old +~| chars to define the tree structure (sickill)