Make compatibility with miscellaneous scripts explicit

.gitignore

@@ -0,0 +1 @@
+doc/tags

README.md

@@ -108,7 +108,7 @@ If you have questions, bug reports, suggestions, etc. the author can be contacte
 ## License
 
 This software is licensed under the [MIT license](http://en.wikipedia.org/wiki/MIT_License).  
-© 2011 Peter Odding &lt;<peter@peterodding.com>&gt;.
+© 2013 Peter Odding &lt;<peter@peterodding.com>&gt;.
 
 
 [ctags]: http://en.wikipedia.org/wiki/Ctags

autoload/xolox/misc/README.md

@@ -1,24 +1,49 @@
 # Miscellaneous auto-load Vim scripts
 
-The git repository at <http://github.com/xolox/vim-misc> contains Vim scripts that are used by most of the [Vim plug-ins I've written] [plugins] yet don't really belong with any single one. I include this repository as a subdirectory of my plug-in repositories using the following commands:
+The git repository at [github.com/xolox/vim-misc] [repository] contains Vim scripts that are used by most of the [Vim plug-ins I've written] [plugins] yet don't really belong with any single one. I include this repository as a subdirectory of my plug-in repositories using the following commands:
 
     $ git remote add -f vim-misc https://github.com/xolox/vim-misc.git
     $ git merge -s ours --no-commit vim-misc/master
     $ git read-tree --prefix=autoload/xolox/misc/ -u vim-misc/master
     $ git commit -m "Merge vim-misc repository as subdirectory"
 
-To update a plug-in repository to the latest versions of the miscellaneous auto-load scripts I execute the following command:
+The above trick is called the [subtree merge strategy] [merge-strategy]. To update a plug-in repository to the latest version of the miscellaneous auto-load scripts I execute the following command:
 
     $ git pull -s subtree vim-misc master
 
+## Why make things so complex?
+
+I came up with this solution after multiple years of back and forth between Vim Online users, the GitHub crowd and my own sanity:
+
+1. When I started publishing my first Vim plug-ins I would prepare ZIP archives for Vim Online using makefiles. The makefiles would make sure the miscellaneous scripts were included in the uploaded distributions. This had two disadvantages: It lost git history and the repositories on GitHub were not usable out of the box, so [I got complaints from GitHub (Pathogen) users] [github-complaints].
+
+2. My second attempt to solve the problem used git submodules which seemed like the ideal solution until I actually started doing it. Submodules are not initialized during a normal `git clone`, you need to use `git clone --recursive` instead but Vim plug-in managers like [Pathogen] [pathogen] and [Vundle] [vundle] don't do this (at least [they didn't when I tried] [vundle-discussion]) so people would end up with broken checkouts.
+
+3. After finding out that git submodules were not going to solve my problems I searched for other inclusion strategies supported by git. After a while I came upon the [subtree merge strategy] [merge-strategy] which I have been using for more than two years now.
+
+## Compatibility issues
+
+Regardless of the inclusion strategies discussed above, my current scheme has a flaw: If more than one of my plug-ins are installed in a Vim profile using [Pathogen] [pathogen] or [Vundle] [vundle], the miscellaneous autoload scripts will all be loaded from the subdirectory of one single plug-in.
+
+This means that when I break compatibility in the miscellaneous scripts, I have to make sure to merge the changes into all of my plug-ins. Even then, if a user has more than one of my plug-ins installed but updates only one of them, the other plug-ins (that are not yet up to date) can break (because of the backwards incompatible change).
+
+The `xolox#misc#compat#check()` function makes sure that incompatibilities are detected early so that the user knows which plug-in to update if incompatibilities arise.
+
 ## Contact
 
 If you have questions, bug reports, suggestions, etc. the author can be contacted at <peter@peterodding.com>. The latest version is available at <http://peterodding.com/code/vim/misc> and <http://github.com/xolox/vim-misc>.
 
 ## License
 
-This software is licensed under the [MIT license](http://en.wikipedia.org/wiki/MIT_License).  
-© 2011 Peter Odding &lt;<peter@peterodding.com>&gt;.
+This software is licensed under the [MIT license] [mit].  
+© 2013 Peter Odding &lt;<peter@peterodding.com>&gt;.
 
 
+[github-complaints]: https://github.com/xolox/vim-easytags/issues/1
+[merge-strategy]: http://www.kernel.org/pub/software/scm/git/docs/howto/using-merge-subtree.html
+[mit]: http://en.wikipedia.org/wiki/MIT_License
+[pathogen]: http://www.vim.org/scripts/script.php?script_id=2332
 [plugins]: http://peterodding.com/code/vim/
+[repository]: https://github.com/xolox/vim-misc
+[vundle-discussion]: https://github.com/gmarik/vundle/pull/41
+[vundle]: https://github.com/gmarik/vundle

autoload/xolox/misc/buffer.vim

@@ -1,37 +1,51 @@
 " Vim auto-load script
 " Author: Peter Odding <peter@peterodding.com>
-" Last Change: September 4, 2011
+" Last Change: April 18, 2013
 " URL: http://peterodding.com/code/vim/misc/
 
-function! xolox#misc#buffer#is_empty()
+function! xolox#misc#buffer#is_empty() " {{{1
   " Check if the current buffer is an empty, unchanged buffer which can be reused.
   return !&modified && expand('%') == '' && line('$') <= 1 && getline(1) == ''
 endfunction
 
-function! xolox#misc#buffer#prepare(bufname)
-  let bufname = '[' . a:bufname . ']'
-  let buffers = tabpagebuflist()
-  call map(buffers, 'fnamemodify(bufname(v:val), ":t:r")')
-  let idx = index(buffers, bufname)
-  if idx >= 0
-    execute (idx + 1) . 'wincmd w'
-  elseif !(xolox#misc#buffer#is_empty() || expand('%:t') == bufname)
+function! xolox#misc#buffer#prepare(...) " {{{1
+  " Open a special buffer (with generated contents, not directly edited by the user).
+  if a:0 == 1 && type(a:1) == type('')
+    " Backwards compatibility with old interface.
+    let options = {'name': a:1, 'path': a:1}
+  elseif type(a:1) == type({})
+    let options = a:1
+  else
+    throw "Invalid arguments"
+  endif
+  let winnr = 1
+  let found = 0
+  for bufnr in tabpagebuflist()
+    if xolox#misc#path#equals(options['path'], bufname(bufnr))
+      execute winnr . 'wincmd w'
+      let found = 1
+      break
+    else
+      let winnr += 1
+    endif
+  endfor
+  if !(found || xolox#misc#buffer#is_empty())
     vsplit
   endif
-  silent execute 'edit' fnameescape(bufname)
+  silent execute 'edit' fnameescape(options['path'])
   lcd " clear working directory
   setlocal buftype=nofile bufhidden=hide noswapfile
-  let &l:statusline = bufname
+  let &l:statusline = '[' . options['name'] . ']'
   call xolox#misc#buffer#unlock()
   silent %delete
 endfunction
 
-function! xolox#misc#buffer#lock()
+function! xolox#misc#buffer#lock() " {{{1
   " Lock a special buffer so it can no longer be edited.
   setlocal readonly nomodifiable nomodified
 endfunction
 
-function! xolox#misc#buffer#unlock()
+function! xolox#misc#buffer#unlock() " {{{1
   " Unlock a special buffer so that its content can be updated.
   setlocal noreadonly modifiable
 endfunction

autoload/xolox/misc/compat.vim

@@ -0,0 +1,23 @@
+" Vim auto-load script
+" Author: Peter Odding <peter@peterodding.com>
+" Last Change: April 20, 2013
+" URL: http://peterodding.com/code/vim/misc/
+
+" The following integer will be bumped whenever a change in the miscellaneous
+" scripts breaks backwards compatibility. This enables my Vim plug-ins to fail
+" early when they detect an incompatible version, instead of breaking at the
+" worst possible moments :-).
+let g:xolox#misc#compat#version = 1
+
+" Remember the directory where the miscellaneous scripts are loaded from
+" so the user knows which plug-in to update if incompatibilities arise.
+let s:misc_directory = fnamemodify(expand('<sfile>'), ':p:h')
+
+function! xolox#misc#compat#check(plugin_name, required_version)
+  if a:required_version != g:xolox#misc#compat#version
+    let msg = "The %s plug-in requires version %i of the miscellaneous scripts, however version %i was loaded from %s!"
+    throw printf(msg, a:plugin_name, a:required_version, g:xolox#misc#compat#version, s:misc_directory)
+  endif
+endfunction
+
+" vim: ts=2 sw=2 et

autoload/xolox/misc/path.vim

@@ -1,9 +1,10 @@
 " Vim auto-load script
 " Author: Peter Odding <peter@peterodding.com>
-" Last Change: September 26, 2011
+" Last Change: April 18, 2013
 " URL: http://peterodding.com/code/vim/misc/
 
 let s:windows_compatible = has('win32') || has('win64')
+let s:mac_os_x_compatible = has('macunix')
 
 function! xolox#misc#path#which(...)
   let extensions = s:windows_compatible ? split($PATHEXT, ';') : ['']
@@ -129,7 +130,13 @@ endfunction
 " Encode a pathname so it can be used as a filename.
 
 function! xolox#misc#path#encode(path)
-  let mask = s:windows_compatible ? '[*|\\/:"<>?%]' : '[\\/%]'
+  if s:windows_compatible
+    let mask = '[*|\\/:"<>?%]'
+  elseif s:mac_os_x_compatible
+    let mask = '[\\/%:]'
+  else
+    let mask = '[\\/%]'
+  endif
   return substitute(a:path, mask, '\=printf("%%%x", char2nr(submatch(0)))', 'g')
 endfunction
 

autoload/xolox/shell.vim

@@ -1,9 +1,11 @@
 " Vim auto-load script
 " Author: Peter Odding <peter@peterodding.com>
-" Last Change: November 26, 2011
+" Last Change: April 21, 2013
 " URL: http://peterodding.com/code/vim/shell/
 
-let g:xolox#shell#version = '0.9.23'
+let g:xolox#shell#version = '0.9.24'
+
+call xolox#misc#compat#check('shell', 1)
 
 if !exists('s:fullscreen_enabled')
   let s:enoimpl = "%s() hasn't been implemented on your platform! %s"
@@ -104,7 +106,7 @@ function! xolox#shell#highlight_urls() " -- highlight URLs and e-mail addresses
       let urlgroup = 'HelpURL'
       let mailgroup = 'HelpEmail'
     else
-      let command = 'syntax match %s /%s/ contained containedin=.*Comment.*'
+      let command = 'syntax match %s /%s/ contained containedin=.*Comment.*,.*String.*'
       let urlgroup = 'CommentURL'
       let mailgroup = 'CommentEmail'
     endif
@@ -306,11 +308,11 @@ EOF
 endfunction
 
 function! xolox#shell#url_pattern() " -- get the preferred/default pattern to match URLs {{{1
-  return xolox#misc#option#get('shell_patt_url', '\<\w\{3,}://\(\S*\w\)\+[/?#]\?')
+  return xolox#misc#option#get('shell_patt_url', '\<\w\{3,}://\(\(\S\&[^"]\)*\w\)\+[/?#]\?')
 endfunction
 
 function! xolox#shell#mail_pattern() " -- get the preferred/default pattern to match e-mail addresses {{{1
-  return xolox#misc#option#get('shell_patt_mail', '\<\w[^@ \t\r]*\w@\w[^@ \t\r]\+\w\>')
+  return xolox#misc#option#get('shell_patt_mail', '\<\w[^@ \t\r<>]*\w@\w[^@ \t\r<>]\+\w\>')
 endfunction
 
 " Miscellaneous script-local functions. {{{1

doc/shell.txt

@@ -1,5 +1,29 @@
 *shell.txt*  Improved integration between Vim and its environment
 
+===============================================================================
+                                                                *shell-contents*
+Contents ~
+
+ 1. Introduction                                            |shell-introduction|
+ 2. Usage (commands & functions)              |shell-usage-(commands-functions)|
+  1. The |:Maximize| command
+  2. The |:Fullscreen| command
+  3. The |:Open| command
+  4. The |xolox#shell#execute()| function
+  5. The |xolox#shell#fullscreen()| function
+  6. The |xolox#shell#is_fullscreen()| function
+  7. The |g:shell_fullscreen_items| option
+  8. The |g:shell_mappings_enabled| option
+  9. The |g:shell_verify_urls| option
+ 3. Background                                                |shell-background|
+ 4. Other full-screen implementations  |shell-other-full-screen-implementations|
+ 5. Contact                                                      |shell-contact|
+ 6. License                                                      |shell-license|
+
+===============================================================================
+                                                            *shell-introduction*
+Introduction ~
+
 This plug-in aims to improve the integration between Vim and its environment
 (your operating system) by providing the following functionality:
 
@@ -228,7 +252,7 @@ If you like the plug-in please vote for it on Vim Online [9].
                                                                  *shell-license*
 License ~
 
-This software is licensed under the MIT license [14]. Copyright 2011 Peter
+This software is licensed under the MIT license [14]. Copyright 2013 Peter
 Odding <peter@peterodding.com>.
 
 ===============================================================================