--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/chapters/43.markdown Sun Nov 13 18:33:12 2011 -0500
@@ -0,0 +1,119 @@
+A New Hope: Plugin Layout with Pathogen
+=======================================
+
+Vim's vanilla layout for plugin files makes sense if you're just adding a file
+here and there to customize your own Vim experience, but turns into a mess when
+you want to use plugins other people have written.
+
+In the past, when you wanted to use a plugin someone else wrote you would
+download the files and place them, one-by-one, into the appropriate directories.
+You could also use zip or tar to do the placing for you.
+
+There are a few significant problems with this approach:
+
+* What happens when you want to update a plugin? You can overwrite the old
+ files, but how do you know if the author deleted a file that you now need to
+ delete by hand?
+* What if two plugins happen to have a file with the same name (like `utils.vim`
+ or something generic like that)? Sometimes you can simply rename it, but if
+ it's in `autoload/` or another directory where the names matter you've got to
+ edit the plugin yourself. Not fun.
+
+People came up with several hacks to try to make things easier, like Vimballs.
+Luckily we don't need to suffer through these ugly hacks any more. [Tim Pope][]
+created the wonderful [Pathogen][] plugin that makes managing multiple plugins
+a breeze, as long as plugin authors structure their plugins in a sane way.
+
+Let's take a quick look at how Pathogen works and what we need to do to make our
+plugin compatible.
+
+[Tim Pope]: http://tpo.pe/
+[Pathogen]: http://www.vim.org/scripts/script.php?script_id=2332
+
+Runtimepath
+-----------
+
+When Vim looks for files in a specific directory, like `syntax/`, it doesn't
+just look in a single place. Much like `PATH` on Linux/Unix/BSD systems, Vim
+has the `runtimepath` setting which tells it where to find files to load.
+
+Create a `colors` directory on your Desktop. Create a file in that directory
+called `mycolor.vim` (you can leave it empty for this demonstration). Open Vim
+and run this command:
+
+ :color mycolor
+
+Vim will display an error, because it doesn't know to look on your Desktop for
+files. Now run this command:
+
+ :set runtimepath=/Users/sjl/Desktop
+
+You'll need to change the path to match the path of your own Desktop, of course.
+Now try the color command again:
+
+ :color mycolor
+
+This time Vim doesn't throw an error, because it was able to find the
+`mycolor.vim` file. Because the file was blank it didn't actually *do*
+anything, but we know it was found because it didn't throw an error.
+
+Pathogen
+--------
+
+The Pathogen plugin automatically adds paths to your `runtimepath` when you load
+Vim. Any directories inside `~/.vim/bundle/` will each be added to the
+`runtimepath`.
+
+This means that each directory inside `bundle/` should contain some or all of
+the standard Vim plugin directories, like `colors/` and `syntax/`. Vim can now
+load files from each of those directories, which makes it simple to keep each
+plugin's files in its own directory.
+
+This makes it trivial to update plugins. You can simply blow away the old
+plugin's directory entirely and replace it with the new version. If you keep
+your `~/.vim` directory under version control (and you should) you can use
+Mercurial's subrepos or Git's submodules to directly check out each plugin's
+repository into `~/.vim/bundle/` and then update it with a simple `hg pull; hg
+update` or `git pull origin master`.
+
+Being Pathogen-Compatible
+-------------------------
+
+When we write our Potion plugin we want to let our users use it with Pathogen.
+Doing this is simple: we simply put our files in the appropriate directories
+inside the plugin's repository!
+
+Our plugin's repository will wind up looking like this:
+
+ potion/
+ README
+ LICENSE
+ docs/
+ potion.txt
+ ftdetect/
+ potion.vim
+ ftplugin/
+ potion.vim
+ syntax/
+ potion.vim
+ ... etc ...
+
+We can put this on GitHub or Bitbucket and users can simply clone it down into
+`bundle/` and everything will just work!
+
+Exercises
+---------
+
+Install Pathogen if you haven't already done so.
+
+Create a Mercurial or Git repository for your plugin, called `potion`. You can
+put it anywhere you like and symlink it into `~/.vim/bundle/potion/` or just put
+it directory in `~/.vim/bundle/potion/`.
+
+Create `README` and `LICENSE` files in the repository and commit them.
+
+Push the repository up to Bitbucket or GitHub.
+
+Read `:help runtimepath`.
+
+