improve invalid bookmarks handling

invalid bookmarks now placed after a blank line at the bottom of the
bookmarks file

if invalid bookmarks are detected, an error is outputted which directs
the user to :help NERDTreeInvalidBookmarks, which had been added to the
help file in this commit

doc/NERD_tree.txt

@@ -25,6 +25,7 @@ CONTENTS                                                   *NERDTree-contents*
         2.2 Bookmarks.........................|NERDTreeBookmarks|
             2.2.1 The bookmark table..........|NERDTreeBookmarkTable|
             2.2.2 Bookmark commands...........|NERDTreeBookmarkCommands|
+            2.2.3 Invalid bookmarks...........|NERDTreeInvalidBookmarks|
         2.3 NERD tree mappings................|NERDTreeMappings|
         2.4 The filesystem menu...............|NERDTreeFilesysMenu|
     3.Options.................................|NERDTreeOptions|
@@ -158,8 +159,27 @@ Note that the following commands are only available in the NERD tree buffer.
 :ClearAllBookmarks
     Remove all bookmarks.
 
+:ReadBookmarks
+    Re-read the bookmarks in the |NERDTreeBookmarksFile|.
+
 See also |:NERDTree| and |:NERDTreeFromBookmark|.
 
+------------------------------------------------------------------------------
+2.2.3. Invalid Bookmarks                            *NERDTreeInvalidBookmarks*
+
+If invalid bookmarks are detected, the script will issue an error message and
+the invalid bookmarks will become unavailable for use.
+
+These bookmarks will still be stored in the bookmarks file (see
+|NERDTreeBookmarksFile|), down the bottom. There will always be a blank line
+after the valid bookmarks but before the invalid ones.
+
+Each line in the bookmarks file represents one bookmark. The proper format is:
+<bookmark name><space><full path to the bookmark location>
+
+After you have corrected any invalid bookmarks, either restart vim, or go
+:ReadBookmarks from the NERD tree window.
+
 ------------------------------------------------------------------------------
 2.3. NERD tree Mappings                                     *NERDTreeMappings*
 

plugin/NERD_tree.vim

@@ -221,25 +221,29 @@ function! s:oBookmark.CacheBookmarks(silent) dict
         let bookmarkStrings = readfile(g:NERDTreeBookmarksFile)
         let invalidBookmarksFound = 0
         for i in bookmarkStrings
-            let name = substitute(i, '^\(.\{-}\) .*$', '\1', '')
-            let path = substitute(i, '^.\{-} \(.*\)$', '\1', '')
 
-            try
-                let bookmark = s:oBookmark.New(name, s:oPath.New(path))
-                call add(g:NERDTreeBookmarks, bookmark)
-            catch /NERDTree.Path.InvalidArguments/
-                call add(g:NERDTreeInvalidBookmarks, i)
-                let invalidBookmarksFound += 1
-            endtry
+            "ignore blank lines
+            if i != ''
+
+                let name = substitute(i, '^\(.\{-}\) .*$', '\1', '')
+                let path = substitute(i, '^.\{-} \(.*\)$', '\1', '')
+
+                try
+                    let bookmark = s:oBookmark.New(name, s:oPath.New(path))
+                    call add(g:NERDTreeBookmarks, bookmark)
+                catch /NERDTree.Path.InvalidArguments/
+                    call add(g:NERDTreeInvalidBookmarks, i)
+                    let invalidBookmarksFound += 1
+                endtry
+            endif
         endfor
         if invalidBookmarksFound
             call s:oBookmark.Write()
             if !a:silent
-                call s:Echo(invalidBookmarksFound .
-                    \ " invalid bookmarks were read. They have been moved to the bottom of ".
-                    \ g:NERDTreeBookmarksFile. " please edit or remove them.")
+                call s:Echo(invalidBookmarksFound . " invalid bookmarks were read. See :help NERDTreeInvalidBookmarks for info.")
             endif
         endif
+        call s:oBookmark.Sort()
     endif
 endfunction
 " FUNCTION: oBookmark.CompareTo(otherbookmark) {{{3
@@ -352,6 +356,10 @@ function! s:oBookmark.Write() dict
     for i in s:oBookmark.Bookmarks()
         call add(bookmarkStrings, i.name . ' ' . i.path.StrForOS(0))
     endfor
+
+    "add a blank line before the invalid ones
+    call add(bookmarkStrings, "")
+
     for j in s:oBookmark.InvalidBookmarks()
         call add(bookmarkStrings, j)
     endfor
@@ -2809,8 +2817,7 @@ function! s:ValidateBookmark(bookmark)
         return 1
     catch /NERDTree.BookmarkPointsToInvalidLocation/
         call s:RenderView()
-        echo a:bookmark.name . " now points to an invalid location. It has been moved to the bottom of ".
-            \ g:NERDTreeBookmarksFile . " please edit or remove it"
+        call s:Echo(a:bookmark.name . "now points to an invalid location. See :help NERDTreeInvalidBookmarks for info.")
     endtry
 endfunction