Permalink
Browse files

Document vim-misc as external dependency

  • Loading branch information...
1 parent 60482dc commit 54d2c81285e8d6b9c5ad0509fe1ee6913f42a8b3 @xolox committed May 25, 2013
Showing with 89 additions and 36 deletions.
  1. +12 −2 INSTALL.md
  2. +47 −18 README.md
  3. +30 −16 doc/reload.txt
View
@@ -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/reload.zip) from [Vim Online](http://www.vim.org/scripts/script.php?script_id=3148), unzip that in `~/.vim/` (on UNIX) or `%USERPROFILE%\vimfiles` (on Windows) and you're good to go.
+*Please note that the vim-reload 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-reload] [download-reload] 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-reload] [github-reload] 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-reload]: http://peterodding.com/code/vim/downloads/reload.zip
+[github-misc]: http://github.com/xolox/vim-misc
+[github-reload]: http://github.com/xolox/vim-reload
+[pathogen]: http://www.vim.org/scripts/script.php?script_id=2332
+[vundle]: https://github.com/gmarik/vundle
View
@@ -1,28 +1,34 @@
# Automatic reloading of Vim scripts
-The reload.vim plug-in automatically reloads various types of [Vim][vim] scripts as you're editing them in Vim to give you instant feedback on the changes you make. For example while writing a Vim syntax script you can open a split window of the relevant file type and every time you [:update][update] your syntax script, reload.vim will refresh the syntax highlighting in the split window. Automatic reloading of Vim scripts is currently supported for the following types of scripts:
+The reload.vim plug-in automatically reloads various types of [Vim] [vim] scripts as you're editing them in Vim to give you instant feedback on the changes you make. For example while writing a Vim syntax script you can open a split window of the relevant file type and every time you [:update] [update] your syntax script, reload.vim will refresh the syntax highlighting in the split window. Automatic reloading of Vim scripts is currently supported for the following types of scripts:
- * [Standard plug-ins](http://vimdoc.sourceforge.net/htmldoc/usr_05.html#standard-plugin) located in `~/.vim/plugin` on UNIX, `~\vimfiles\plugin` on Windows;
+ * [Standard plug-ins] [standard-plugins] located in `~/.vim/plugin` on UNIX, `~\vimfiles\plugin` on Windows;
- * [Auto-load scripts](http://vimdoc.sourceforge.net/htmldoc/eval.html#autoload) located in or below `~/.vim/autoload` on UNIX, `~\vimfiles\autoload` on Windows;
+ * [Auto-load scripts] [autoload-scripts] located in or below `~/.vim/autoload` on UNIX, `~\vimfiles\autoload` on Windows;
- * [File-type plug-ins](http://vimdoc.sourceforge.net/htmldoc/filetype.html#filetype-plugins) located in or below `~/.vim/ftplugin` on UNIX, `~\vimfiles\ftplugin` on Windows;
+ * [File-type plug-ins] [filetype-plugins] located in or below `~/.vim/ftplugin` on UNIX, `~\vimfiles\ftplugin` on Windows;
- * [Syntax highlighting scripts](http://vimdoc.sourceforge.net/htmldoc/syntax.html#syntax-highlighting) located in `~/.vim/syntax` on UNIX, `~\vimfiles\syntax` on Windows;
+ * [Syntax highlighting scripts] [syntax-scripts] located in `~/.vim/syntax` on UNIX, `~\vimfiles\syntax` on Windows;
- * [File-type indentation plug-ins](http://vimdoc.sourceforge.net/htmldoc/usr_30.html#30.3) located in `~/.vim/indent` on UNIX, `~\vimfiles\indent` on Windows;
+ * [File-type indentation plug-ins] [indent-scripts] located in `~/.vim/indent` on UNIX, `~\vimfiles\indent` on Windows;
- * [Color scheme scripts](http://vimdoc.sourceforge.net/htmldoc/syntax.html#:colorscheme) located in `~/.vim/colors` on UNIX, `~\vimfiles\colors` on Windows.
+ * [Color scheme scripts] [color-schemes] located in `~/.vim/colors` on UNIX, `~\vimfiles\colors` on Windows.
-The directories listed above are Vim's defaults but you're free to change the ['runtimepath'](http://vimdoc.sourceforge.net/htmldoc/options.html#%27runtimepath%27) and reloading will still work.
+The directories listed above are Vim's defaults but you're free to change the ['runtimepath'] [rtp] and reloading will still work.
-Note that [vimrc scripts][vimrc] are not reloaded because that seems to cause more trouble than it's worth...
+Note that [vimrc scripts] [vimrc] are not reloaded because that seems to cause more trouble than it's worth...
## Install & first use
-Unzip the most recent [ZIP archive](http://peterodding.com/code/vim/downloads/reload) file 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). Now try it out: Edit any Vim script that's already loaded (you can check using the [:scriptnames command][scriptnames]) and confirm that the script is reloaded when you save it (the reload.vim plug-in will print a message to confirm when a script is reloaded).
+*Please note that the vim-reload plug-in requires my vim-misc plug-in which is separately distributed.*
-Out of the box the reload.vim plug-in is configured to automatically reload all Vim scripts that it knows how to. If you like it this way then you don't need to configure anything! However if you don't like the automatic reloading then you'll need the following:
+Unzip the most recent ZIP archives of the [vim-reload] [download-reload] 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-reload] [github-reload] and [vim-misc] [github-misc] plug-ins using a local clone of the git repository.
+
+Now try it out: Edit any Vim script that's already loaded (you can check using the [:scriptnames command] [scriptnames]) and confirm that the script is reloaded when you save it (the reload.vim plug-in will print a message to confirm when a script is reloaded).
+
+Out of the box the reload.vim plug-in is configured to automatically reload all Vim scripts that it knows how to. If you like it this way then you don't need to configure anything! However if you don't like the automatic reloading then you can use the option below.
### The `g:reload_on_write` option
@@ -38,15 +44,15 @@ You can execute the `:ReloadScript` command to reload the Vim script you're edit
:ReloadScript ~/.vim/plugin/reload.vim
-If after executing this command you see Vim errors such as "Function already exists" ([E122](http://vimdoc.sourceforge.net/htmldoc/eval.html#E122)) or "Command already exists" ([E174](http://vimdoc.sourceforge.net/htmldoc/map.html#E174)) then you'll need to change your Vim script(s) slightly to enable reloading, see below.
+If after executing this command you see Vim errors such as "Function already exists" ([E122] [E122]) or "Command already exists" ([E174] [E174]) then you'll need to change your Vim script(s) slightly to enable reloading, see below.
## Things that prevent reloading
If you want your Vim plug-ins and/or other scripts to be automatically reloaded they'll have to be written a certain way, though you can consider the following points good practice for Vim script writing anyway:
### Use a bang in command and function definitions!
-Function and command definitions using Vim's [:command](http://vimdoc.sourceforge.net/htmldoc/map.html#:command) and [:function](http://vimdoc.sourceforge.net/htmldoc/eval.html#:function) built-ins should include a [bang (!)](http://vimdoc.sourceforge.net/htmldoc/map.html#:command-bang) symbol, otherwise Vim will complain that the command or function already exists:
+Function and command definitions using Vim's [:command] [command] and [:function] [function] built-ins should include a [bang (!)] [bang] symbol, otherwise Vim will complain that the command or function already exists:
" Bad:
:command MyCmd call MyFun()
@@ -60,7 +66,7 @@ Function and command definitions using Vim's [:command](http://vimdoc.sourceforg
### Use automatic command groups
-Automatic commands using Vim's [:autocmd][autocmd] built-in should be defined inside of an [automatic command group](http://vimdoc.sourceforge.net/htmldoc/autocmd.html#:augroup) that's cleared so the automatic commands don't stack indefinitely when your [:autocmd][autocmd] commands are executed several times:
+Automatic commands using Vim's [:autocmd][autocmd] built-in should be defined inside of an [automatic command group] [augroup] that's cleared so the automatic commands don't stack indefinitely when your [:autocmd][autocmd] commands are executed several times:
" Bad example: If the following line were re-evaluated, the message would
" appear multiple times the next time the automatic command fires:
@@ -74,26 +80,49 @@ Automatic commands using Vim's [:autocmd][autocmd] built-in should be defined in
## Alternatives
-The [ReloadScript](http://www.vim.org/scripts/script.php?script_id=1904) plug-in on [Vim Online][vim] also supports reloading of Vim scripts, but there are a few notable differences:
+The [ReloadScript] [reload-script] plug-in on [Vim Online][vim] also supports reloading of Vim scripts, but there are a few notable differences:
* This plug-in focuses on automatic reloading (I'm lazy) while the other one requires manual reloading;
- * This plug-in will *never* [:source](http://vimdoc.sourceforge.net/htmldoc/repeat.html#:source) a file that hasn't already been loaded by Vim -- it checks using Vim's [:scriptnames][scriptnames] command;
+ * This plug-in will *never* [:source] [source] a file that hasn't already been loaded by Vim -- it checks using Vim's [:scriptnames][scriptnames] command;
* This plug-in can more or less reload itself ;-)
## 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/reload/> and <http://github.com/xolox/vim-reload>. If you like the plug-in please vote for it on [Vim Online](http://www.vim.org/scripts/script.php?script_id=3148).
+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/reload/> and <http://github.com/xolox/vim-reload>. If you like the plug-in please vote for it on [Vim Online] [vim-online].
## 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;.
+[augroup]: http://vimdoc.sourceforge.net/htmldoc/autocmd.html#:augroup
[autocmd]: http://vimdoc.sourceforge.net/htmldoc/autocmd.html#:autocmd
+[autoload-scripts]: http://vimdoc.sourceforge.net/htmldoc/eval.html#autoload
+[bang]: http://vimdoc.sourceforge.net/htmldoc/map.html#:command-bang
+[color-schemes]: http://vimdoc.sourceforge.net/htmldoc/syntax.html#:colorscheme
+[command]: http://vimdoc.sourceforge.net/htmldoc/map.html#:command
+[download-misc]: http://peterodding.com/code/vim/downloads/misc.zip
+[download-reload]: http://peterodding.com/code/vim/downloads/reload.zip
+[E122]: http://vimdoc.sourceforge.net/htmldoc/eval.html#E122
+[E174]: http://vimdoc.sourceforge.net/htmldoc/map.html#E174
+[filetype-plugins]: http://vimdoc.sourceforge.net/htmldoc/filetype.html#filetype-plugins
+[function]: http://vimdoc.sourceforge.net/htmldoc/eval.html#:function
+[github-misc]: http://github.com/xolox/vim-misc
+[github-reload]: http://github.com/xolox/vim-reload
+[indent-scripts]: http://vimdoc.sourceforge.net/htmldoc/usr_30.html#30.3
+[mit]: http://en.wikipedia.org/wiki/MIT_License
+[pathogen]: http://www.vim.org/scripts/script.php?script_id=2332
+[reload-script]: http://www.vim.org/scripts/script.php?script_id=1904
+[rtp]: http://vimdoc.sourceforge.net/htmldoc/options.html#%27runtimepath%27
[scriptnames]: http://vimdoc.sourceforge.net/htmldoc/repeat.html#:scriptnames
+[source]: http://vimdoc.sourceforge.net/htmldoc/repeat.html#:source
+[standard-plugins]: http://vimdoc.sourceforge.net/htmldoc/usr_05.html#standard-plugin
+[syntax-scripts]: http://vimdoc.sourceforge.net/htmldoc/syntax.html#syntax-highlighting
[update]: http://vimdoc.sourceforge.net/htmldoc/editing.html#:update
+[vim-online]: http://www.vim.org/scripts/script.php?script_id=3148
[vim]: http://www.vim.org/
[vimrc]: http://vimdoc.sourceforge.net/htmldoc/starting.html#vimrc
+[vundle]: https://github.com/gmarik/vundle
View
@@ -55,18 +55,27 @@ trouble than it's worth...
*reload-install-first-use*
Install & first use ~
-Unzip the most recent ZIP archive [1] file 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). Now try it out: Edit any Vim script
-that's already loaded (you can check using the |:scriptnames| command) and
-confirm that the script is reloaded when you save it (the reload.vim plug-in
-will print a message to confirm when a script is reloaded).
+Please note that the vim-reload plug-in requires my vim-misc plug-in which is
+separately distributed.
+
+Unzip the most recent ZIP archives of the vim-reload [1] and vim-misc [2]
+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 [3], Vundle [4] or a similar tool to
+install & update the vim-reload [5] and vim-misc [6] plug-ins using a local
+clone of the git repository.
+
+Now try it out: Edit any Vim script that's already loaded (you can check using
+the |:scriptnames| command) and confirm that the script is reloaded when you
+save it (the reload.vim plug-in will print a message to confirm when a script
+is reloaded).
Out of the box the reload.vim plug-in is configured to automatically reload
all Vim scripts that it knows how to. If you like it this way then you don't
need to configure anything! However if you don't like the automatic reloading
-then you'll need the following:
+then you can use the option below.
-------------------------------------------------------------------------------
The *g:reload_on_write* option
@@ -140,7 +149,7 @@ several times:
*reload-alternatives*
Alternatives ~
-The ReloadScript [2] plug-in on Vim Online also supports reloading of Vim
+The ReloadScript [7] plug-in on Vim Online also supports reloading of Vim
scripts, but there are a few notable differences:
- This plug-in focuses on automatic reloading (I'm lazy) while the other one
@@ -158,22 +167,27 @@ 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/reload/ and http://github.com/xolox/vim-reload.
-If you like the plug-in please vote for it on Vim Online [3].
+If you like the plug-in please vote for it on Vim Online [8].
===============================================================================
*reload-license*
License ~
-This software is licensed under the MIT license [4]. Š 2013 Peter Odding
-<peter@peterodding.com>.
+This software is licensed under the MIT license [9]. Copyright 2013 Peter
+Odding <peter@peterodding.com>.
===============================================================================
*reload-references*
References ~
-[1] http://peterodding.com/code/vim/downloads/reload
-[2] http://www.vim.org/scripts/script.php?script_id=1904
-[3] http://www.vim.org/scripts/script.php?script_id=3148
-[4] http://en.wikipedia.org/wiki/MIT_License
+[1] http://peterodding.com/code/vim/downloads/reload.zip
+[2] http://peterodding.com/code/vim/downloads/misc.zip
+[3] http://www.vim.org/scripts/script.php?script_id=2332
+[4] https://github.com/gmarik/vundle
+[5] http://github.com/xolox/vim-reload
+[6] http://github.com/xolox/vim-misc
+[7] http://www.vim.org/scripts/script.php?script_id=1904
+[8] http://www.vim.org/scripts/script.php?script_id=3148
+[9] http://en.wikipedia.org/wiki/MIT_License
vim: ft=help

0 comments on commit 54d2c81

Please sign in to comment.