Document vim-misc as external dependency

INSTALL.md

@@ -1,3 +1,13 @@
-If you're looking for the simplest way to get the plug-in up and running, download [the latest ZIP archive](http://peterodding.com/code/vim/downloads/shell.zip) from [Vim Online](http://www.vim.org/scripts/script.php?script_id=3123), unzip that in `~/.vim/` (on UNIX) or `%USERPROFILE%\vimfiles` (on Windows) and you're good to go.
+*Please note that the vim-shell plug-in requires my vim-misc plug-in which is separately distributed.*
 
-If you're using git and/or [Pathogen](http://www.vim.org/scripts/script.php?script_id=2332), [Vundle](https://github.com/gmarik/vundle) or a similar plug-in manager and want to keep the plug-in up to date using git, you can use the GitHub repository directly, it should just work.
+Unzip the most recent ZIP archives of the [vim-shell] [download-shell] and [vim-misc] [download-misc] plug-ins inside your Vim profile directory (usually this is `~/.vim` on UNIX and `%USERPROFILE%\vimfiles` on Windows), restart Vim and execute the command `:helptags ~/.vim/doc` (use `:helptags ~\vimfiles\doc` instead on Windows).
+
+If you prefer you can also use [Pathogen] [pathogen], [Vundle] [vundle] or a similar tool to install & update the [vim-shell] [github-shell] and [vim-misc] [github-misc] plug-ins using a local clone of the git repository.
+
+
+[download-misc]: http://peterodding.com/code/vim/downloads/misc.zip
+[download-shell]: http://peterodding.com/code/vim/downloads/shell.zip
+[github-misc]: http://github.com/xolox/vim-misc
+[github-shell]: http://github.com/xolox/vim-shell
+[pathogen]: http://www.vim.org/scripts/script.php?script_id=2332
+[vundle]: https://github.com/gmarik/vundle

README.md

@@ -1,16 +1,26 @@
 # Improved integration between <br> Vim and its environment
 
-This plug-in aims to improve the integration between [Vim][vim] and its environment (your operating system) by providing the following functionality:
+This plug-in aims to improve the integration between [Vim] [vim] and its environment (your operating system) by providing the following functionality:
 
- * The `:Fullscreen` command and `<F11>` mapping toggle Vim between normal and full-screen mode (see the [screenshots](http://peterodding.com/code/vim/shell/screenshots/)). To invoke this functionality without using the `:Fullscreen` command see the `xolox#shell#fullscreen()` and `xolox#shell#is_fullscreen()` functions.
+ * The `:Fullscreen` command and `<F11>` mapping toggle Vim between normal and full-screen mode (see the [screenshots] [screenshots]). To invoke this functionality without using the `:Fullscreen` command see the `xolox#shell#fullscreen()` and `xolox#shell#is_fullscreen()` functions.
 
    * The `:Maximize` command and `<Control-F11>` mapping toggle Vim between normal and maximized state: They show/hide Vim's menu bar, tool bar and/or tab line without hiding the operating system task bar.
 
- * The `:Open` command and `<F6>` mapping know how to open file and directory names, URLs and e-mail addresses in your favorite programs (file manager, web browser, e-mail client, etc). To invoke this functionality without using the `:Open` command see my [open.vim](http://peterodding.com/code/vim/open-associated-programs/) plug-in, which was split off from `shell.vim` so that other Vim plug-ins can bundle it without bringing in all the other crap :-).
+ * The `:Open` command and `<F6>` mapping know how to open file and directory names, URLs and e-mail addresses in your favorite programs (file manager, web browser, e-mail client, etc).
 
  * The `xolox#misc#os#exec()` function enables other Vim plug-ins (like my [easytags.vim] [easytags] plug-in) to execute external commands in the background (i.e. asynchronously) *without opening a command prompt window on Windows*.
 
-Two [Windows DLL files][dll] are included to perform these functions on Windows, while on UNIX external commands are used.
+Two [Windows DLL files] [dll] are included to perform these functions on Windows, while on UNIX external commands are used.
+
+## Installation
+
+*Please note that the vim-shell plug-in requires my vim-misc plug-in which is separately distributed.*
+
+Unzip the most recent ZIP archives of the [vim-shell] [download-shell] and [vim-misc] [download-misc] plug-ins inside your Vim profile directory (usually this is `~/.vim` on UNIX and `%USERPROFILE%\vimfiles` on Windows), restart Vim and execute the command `:helptags ~/.vim/doc` (use `:helptags ~\vimfiles\doc` instead on Windows).
+
+If you prefer you can also use [Pathogen] [pathogen], [Vundle] [vundle] or a similar tool to install & update the [vim-shell] [github-shell] and [vim-misc] [github-misc] plug-ins using a local clone of the git repository.
+
+After you've installed the plug-in and restarted Vim, the following commands will be available to you:
 
 ## Usage (commands & functions)
 
@@ -20,7 +30,7 @@ This command toggles the visibility of Vim's main menu, tool bar and/or tab line
 
 ### The `:Fullscreen` command
 
-The `:Fullscreen` command toggles Vim between normal and [full-screen mode](http://peterodding.com/code/vim/shell/screenshots/). It's mapped to `<F11>` by default, see `g:shell_mappings_enabled` if you don't like this. This command first executes `:Maximize` and then (if possible) switches Vim's [GUI window] [gui] to real full-screen mode (hiding any [taskbars, panels or docks](http://en.wikipedia.org/wiki/Taskbar)). When you leave full-screen Vim's main menu, toolbar and tabline are restored and the [GUI window] [gui] is switched back to normal mode.
+The `:Fullscreen` command toggles Vim between normal and [full-screen mode] [screenshots]. It's mapped to `<F11>` by default, see `g:shell_mappings_enabled` if you don't like this. This command first executes `:Maximize` and then (if possible) switches Vim's [GUI window] [gui] to real full-screen mode (hiding any [taskbars, panels or docks] [taskbars]). When you leave full-screen Vim's main menu, toolbar and tabline are restored and the [GUI window] [gui] is switched back to normal mode.
 
 Note that on UNIX this command even works inside of graphical terminal emulators like `gnome-terminal` or `xterm` (try it out!).
 
@@ -38,46 +48,46 @@ Note that on UNIX if the environment variable `$DISPLAY` is empty the plug-in wi
 
 ### The `:MakeWithShell` command
 
-This command is a very simple replacement for the [:make][make] command that does not pop up a console window on Windows. It doesn't come with all of the bells and whistles that Vim's built-in make command does but it should work.
+This command is a very simple replacement for the [:make] [make] command that does not pop up a console window on Windows. It doesn't come with all of the bells and whistles that Vim's built-in make command does but it should work.
 
-Because Vim's [v:shell_error][shell_error] variable is read only (which means it cannot be set by a Vim plug-in) the vim-shell plug-in defines its own variable with the exit code of the `make` process executed by `:MakeWithShell`. This variable is called `g:xolox#shell#make_exit_code`. The semantics are exactly the same as for [v:shell_error][shell_error].
+Because Vim's [v:shell_error] [shell_error] variable is read only (which means it cannot be set by a Vim plug-in) the vim-shell plug-in defines its own variable with the exit code of the `make` process executed by `:MakeWithShell`. This variable is called `g:xolox#shell#make_exit_code`. The semantics are exactly the same as for [v:shell_error] [shell_error].
 
 ### The `xolox#misc#os#exec()` function
 
-This function enables other Vim plug-ins to execute external commands in the background (i.e. asynchronously) *without opening a command prompt window on Windows*. For example try to execute the following command on Windows ([vimrun.exe][vimrun] is only included with Vim for Windows because it isn't needed on other platforms):
+This function enables other Vim plug-ins to execute external commands in the background (i.e. asynchronously) *without opening a command prompt window on Windows*. For example try to execute the following command on Windows ([vimrun.exe] [vimrun] is only included with Vim for Windows because it isn't needed on other platforms):
 
     :call xolox#misc#os#exec({'command': 'vimrun', 'async': 1})
 
-Immediately after executing this command Vim will respond to input again because `xolox#misc#os#exec()` doesn't wait for the external command to finish when the 'async' argument is true (1). In addition no command prompt window will be shown which means [vimrun.exe][vimrun] is running completely invisible in the background.
+Immediately after executing this command Vim will respond to input again because `xolox#misc#os#exec()` doesn't wait for the external command to finish when the 'async' argument is true (1). In addition no command prompt window will be shown which means [vimrun.exe] [vimrun] is running completely invisible in the background.
 
 The function returns a dictionary of return values. In asynchronous mode the dictionary is empty. In synchronous mode it contains the following key/value pairs:
 
     :echo xolox#misc#os#exec({'command': 'echo "this is stdout" && echo "this is stderr" >&2 && exit 42'})
     {'exit_code': 42, 'stdout': ['this is stdout'], 'stderr': ['this is stderr']}
 
-If you want to verify that this function works as described, execute the command mentioning `vimrun` above, open the Windows task manager by pressing `Control-Shift-Escape` and check that the process `vimrun.exe` is listed in the processes tab. If you don't see the problem this is solving, try executing [vimrun.exe][vimrun] using Vim's built-in [system()][system] function instead:
+If you want to verify that this function works as described, execute the command mentioning `vimrun` above, open the Windows task manager by pressing `Control-Shift-Escape` and check that the process `vimrun.exe` is listed in the processes tab. If you don't see the problem this is solving, try executing [vimrun.exe] [vimrun] using Vim's built-in [system()] [system] function instead:
 
     :call system('vimrun')
 
-Vim will be completely unresponsive until you "press any key to continue" in the command prompt window that's running [vimrun.exe][vimrun]. Of course the [system()][system] function should only be used with non-interactive programs (the documentation says as much) but the point is to simulate an external command that takes a while to finish and blocks Vim while doing so.
+Vim will be completely unresponsive until you "press any key to continue" in the command prompt window that's running [vimrun.exe] [vimrun]. Of course the [system()] [system] function should only be used with non-interactive programs (the documentation says as much) but the point is to simulate an external command that takes a while to finish and blocks Vim while doing so.
 
-Note that on Windows this function uses Vim's ['shell'][sh_opt] and ['shellcmdflag'][shcf_opt] options to compose the command line passed to the DLL.
+Note that on Windows this function uses Vim's ['shell'] [sh_opt] and ['shellcmdflag'] [shcf_opt] options to compose the command line passed to the DLL.
 
 ### The `xolox#shell#fullscreen()` function
 
 Call this function to toggle Vim's full screen status. The `:Fullscreen` command is just a shorter way to call this function.
 
 ### The `xolox#shell#is_fullscreen()` function
 
-Call this function to determine whether Vim is in full screen mode. My [session.vim plug-in](http://peterodding.com/code/vim/session) uses this to persist full screen mode.
+Call this function to determine whether Vim is in full screen mode. My [session.vim plug-in] [vim-session] uses this to persist full screen mode.
 
 ### The `g:shell_fullscreen_items` option
 
 This variable is a string containing any combination of the following characters:
 
- * `m`: Hide the [main menu](http://vimdoc.sourceforge.net/htmldoc/options.html#%27go-m%27) when switching to full-screen;
- * `T`: Hide the [toolbar](http://vimdoc.sourceforge.net/htmldoc/options.html#%27go-T%27) when switching to full-screen;
- * `e`: Hide the [tabline](http://vimdoc.sourceforge.net/htmldoc/options.html#%27go-e%27) when switching to full-screen (this also toggles the [showtabline option](http://vimdoc.sourceforge.net/htmldoc/options.html#%27showtabline%27)).
+ * `m`: Hide the [main menu] [go-m] when switching to full-screen;
+ * `T`: Hide the [toolbar] [go-T] when switching to full-screen;
+ * `e`: Hide the [tabline] [go-e] when switching to full-screen (this also toggles the [showtabline option] [stal]).
 
 By default all the above items are hidden in full-screen mode. You can also set the buffer local variable `b:shell_fullscreen_items` to change these settings for specific buffers.
 
@@ -108,38 +118,51 @@ If you actually deal with URLs that include significant trailing punctuation and
 
 ## Background
 
-Vim has a limited ability to call external libraries using the Vim script function [libcall()][libcall]. A few years ago when I was still using Windows a lot I created a [Windows DLL][dll] that could be used with [libcall()][libcall] to toggle [Vim][vim]'s GUI window between regular and full-screen mode. I also added a few other useful functions, e.g. `openurl()` to launch the default web browser and `execute()` which works like Vim's [system()][system] function but doesn't wait for the process to finish and doesn't show a command prompt.
-
-Since then I switched to Linux and didn't look back, which meant the DLL sat in my `~/.vim/etc/` waiting to be revived. Now that I've published my [easytags.vim][easytags] plug-in and put a lot of effort into making it Windows compatible, the `execute()` function from the DLL would be very useful to run [Exuberant Ctags][ctags] in the background without stealing Vim's focus by opening a command prompt window. This is why I've decided to release the DLL. Because I switched to Linux I've also added an autoload script that wraps the DLL on Windows and calls out to external programs such as `wmctrl`, `gnome-open`, `kde-open`, and others on UNIX.
+Vim has a limited ability to call external libraries using the Vim script function [libcall()] [libcall]. A few years ago when I was still using Windows a lot I created a [Windows DLL] [dll] that could be used with [libcall()] [libcall] to toggle [Vim] [vim]'s GUI window between regular and full-screen mode. I also added a few other useful functions, e.g. `openurl()` to launch the default web browser and `execute()` which works like Vim's [system()] [system] function but doesn't wait for the process to finish and doesn't show a command prompt.
 
-Before I go ahead and bundle the DLL files with my [easytags.vim][easytags] plug-in I need to make sure they're compatible with as many Windows Vim installations out there as possible, e.g. XP/Vista/7, different service packs, 32/64 bits, etc. I've uploaded a [ZIP archive including two compiled DLL files][download] to the [Vim scripts page][vim_scripts_entry] for this plug-in (build using the latest Windows SDK but targeting Windows XP x86/x64 RELEASE, should also work on Vista/7) and the source code is available in the [GitHub repository](http://github.com/xolox/vim-shell) (there's also a [Batch script](http://github.com/xolox/vim-shell/blob/master/dll/Makefile) with compile instructions).
+Since then I switched to Linux and didn't look back, which meant the DLL sat in my `~/.vim/etc/` waiting to be revived. Now that I've published my [easytags.vim] [easytags] plug-in and put a lot of effort into making it Windows compatible, the `execute()` function from the DLL would be very useful to run [Exuberant Ctags] [ctags] in the background without stealing Vim's focus by opening a command prompt window. This is why I've decided to release the DLL. Because I switched to Linux I've also added an autoload script that wraps the DLL on Windows and calls out to external programs such as `wmctrl`, `gnome-open`, `kde-open`, and others on UNIX.
 
 ## Other full-screen implementations
 
-After publishing this plug-in I found that the Vim plug-ins [VimTweak](http://www.vim.org/scripts/script.php?script_id=687) and [gvimfullscreen_win32](http://www.vim.org/scripts/script.php?script_id=2596) also implement full-screen on Windows using a similar approach as my plug-in. I prefer the effect of my plug-in because it seems to hide window decorations more effectively. Also note that my plug-in was developed independently of the other two.
+After publishing this plug-in I found that the Vim plug-ins [VimTweak] [vimtweak] and [gvimfullscreen_win32] [gvimfullscreen_win32] also implement full-screen on Windows using a similar approach as my plug-in. I prefer the effect of my plug-in because it seems to hide window decorations more effectively. Also note that my plug-in was developed independently of the other two.
 
 ## 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/shell/> and <http://github.com/xolox/vim-shell>. If you like the plug-in please vote for it on [Vim Online] [vim_scripts_entry].
 
 ## License
 
-This software is licensed under the [MIT license](http://en.wikipedia.org/wiki/MIT_License).  
+This software is licensed under the [MIT license] [mit].  
 © 2013 Peter Odding &lt;<peter@peterodding.com>&gt;.
 
 
 [ctags]: http://en.wikipedia.org/wiki/Ctags
 [dll]: http://en.wikipedia.org/wiki/Dynamic-link_library
-[download]: http://peterodding.com/code/vim/downloads/shell.zip
+[download-misc]: http://peterodding.com/code/vim/downloads/misc.zip
+[download-shell]: http://peterodding.com/code/vim/downloads/shell.zip
 [easytags]: http://peterodding.com/code/vim/easytags/
+[github-misc]: http://github.com/xolox/vim-misc
+[github-shell]: http://github.com/xolox/vim-shell
+[go-e]: http://vimdoc.sourceforge.net/htmldoc/options.html#%27go-e%27
+[go-m]: http://vimdoc.sourceforge.net/htmldoc/options.html#%27go-m%27
+[go-T]: http://vimdoc.sourceforge.net/htmldoc/options.html#%27go-T%27
 [gui]: http://vimdoc.sourceforge.net/htmldoc/gui.html#GUI
+[gvimfullscreen_win32]: http://www.vim.org/scripts/script.php?script_id=2596
 [libcall]: http://vimdoc.sourceforge.net/htmldoc/eval.html#libcall()
 [make]: http://vimdoc.sourceforge.net/htmldoc/quickfix.html#:make
+[mit]: http://en.wikipedia.org/wiki/MIT_License
+[pathogen]: http://www.vim.org/scripts/script.php?script_id=2332
+[screenshots]: http://peterodding.com/code/vim/shell/screenshots/
 [sh_opt]: http://vimdoc.sourceforge.net/htmldoc/options.html#%27shell%27
 [shcf_opt]: http://vimdoc.sourceforge.net/htmldoc/options.html#%27shellcmdflag%27
 [shell_error]: http://vimdoc.sourceforge.net/htmldoc/eval.html#v:shell_error
+[stal]: http://vimdoc.sourceforge.net/htmldoc/options.html#%27showtabline%27
 [system]: http://vimdoc.sourceforge.net/htmldoc/eval.html#system()
+[taskbars]: http://en.wikipedia.org/wiki/Taskbar
+[vim-session]: http://peterodding.com/code/vim/session/
 [vim]: http://www.vim.org/
 [vim_scripts_entry]: http://www.vim.org/scripts/script.php?script_id=3123
 [vimrc]: http://vimdoc.sourceforge.net/htmldoc/starting.html#vimrc
 [vimrun]: http://vimdoc.sourceforge.net/htmldoc/gui_w32.html#win32-vimrun
+[vimtweak]: http://www.vim.org/scripts/script.php?script_id=687
+[vundle]: https://github.com/gmarik/vundle