1 files changed, 115 insertions, 0 deletions
diff --git a/projects/gem_plugin/README b/projects/gem_plugin/README
new file mode 100644
index 0000000..b4c87f7
--- /dev/null
+++ b/projects/gem_plugin/README
@@ -0,0 +1,115 @@
+= GemPlugin:  Gem Based Plugin System
+
+GemPlugin is a system that lets your users install gems and lets you load
+them as additional features to use in your software.  It originated from the
+Mongrel (http://mongrel.rubyforge.org) project but proved useful enough to
+break out into a separate project.
+
+GemPlugin works by listing the gems installed, and doing a require_gem on 
+any that have the right dependencies.  For example, if a gem depends on
+"gem_plugin" and "mongrel" then it'll load as a Mongrel plugin.  This
+makes it so that users of the plugins only need to gem install (and maybe
+config a bit), and plugin authors only need to make gems.
+
+
+== Implementers
+
+To use GemPlugin in your system you only have to require 'gem_plugin' and 
+then use the GemPlugin::Manager.create, GemPlugin::Manager.load, and 
+GemPlugin::Manager.available methods to work with them.
+
+* GemPlugin::Manager.load -- Takes a "depend include/exclude map" and loads plugins based on it.
+* GemPlugin::Manager.create -- Takes a URI style name and some options then creates one for you.
+* GemPlugin::Manager.available -- Lets you inspect and mess with the internal plugin registry.
+
+=== Loading Plugins
+
+As an example from Mongrel it's necessary to load plugins that depend on rails after 
+the Rails system is configured, but load other plugins right when Mongrel is ready.
+To do this we very first do:
+
+ GemPlugin::Manager.instance.load "mongrel" => GemPlugin::INCLUDE, "rails" => GemPlugin::EXCLUDE
+
+Later, when it's ready to load Rails plugins as well we do this:
+
+ GemPlugin::Manager.instance.load "mongrel" => GemPlugin::INCLUDE
+
+This simply loads any plugins that remain and are ready for use in Rails.
+
+=== Creating Plugins
+
+Creating a plugin is cake:
+
+ plug = GemPlugin::Manager.instance.create("/commands/snazzy", "something" => "yeah")
+
+In this case we're making the snazzy command and passing a couple fake options.
+
+=== Finding Available Plugins
+
+Finding plugins is also very easy, you just call GemPlugin::Manager.instance.available
+and you get a Hash that maps categories to name => class.  For example, if I had
+the "/commands/snazzy" plugin registered above, then I'd get the following:
+
+ puts GemPlugin::Manager.instance.available["/commands"].inspect
+ -> { "/snazzy" => Snazzy}
+
+
+=== Plugins Inside Modules
+
+Plugins that are placed in modules are also lowercased when registered but
+still retain their module.  So, if Snazzy was actually MyModule::Snazzy, then
+it'd be registered as "/commands/mymodule::snazzy".
+
+
+== Plugin Authors
+
+People who wish to write gem plugins have a faily easy time of it, but need
+to know the particular rules for the target system.  To keep this example
+concrete we'll assume you want to write a Mongrel command plugin.
+
+First thing is create your project like normal and setup Rake to make
+your gem.  Your plugin then needs to be created like so:
+
+ class Snazzy < GemPlugin::Plugin "/commands"
+    ...
+ end
+
+And place this code in a file you will have RubyGems autorequire (I use lib/init.rb).
+
+Next you need to add the following to whatever Rakefile code you use to create
+your gem:
+
+ spec.add_dependency('gem_plugin', '>= 0.1')
+ spec.add_dependency('mongrel', '>= 0.3.9')
+ spec.autorequire = 'init.rb'
+
+This does three things:
+
+* Tells GemPlugins::Manager.load that this is a GemPlugin.
+* Tells Mongrel that this is a Mongrel specific GemPlugin.
+* Tells RubyGems to run init.rb when the gem is required, just hooking up your plugin.
+
+Now, all the users of your plugin have to do is gem install it and then
+they get the plugin automagically.
+
+People writing GemPlugins for other systems would have to check the 
+documentation from that project to get an idea of what extra 
+requirements might be needed.  For example, you'd probably have to
+depend on another project other that *mongrel* and most likely have
+a few more things to configure in your init.rb.
+
+== Plugin Users
+
+Plugin users have it the easiest of all.  They simply do:
+
+ gem install mongrel_command_snazzy
+
+And that's it.  When they run mongrel_rails (given the above example)
+this snazzy command get loaded automatically without any intervention.
+
+The only thing missing in this release is a way for end users to configure
+such a plugin.  I really think this is the job of the implementers to define.
+
+== Contact
+
+E-mail zedshaw at zedshaw.com and I'll help.  Comments about the API are welcome.