Rails guide: Added PluginGem section, reorganized the odds and ends.

13 files changed, 254 insertions, 156 deletions

diff --git a/railties/doc/guides/html/authors.html b/railties/doc/guides/html/authors.html
index a54135b14d..6fd556d2cd 100644
--- a/railties/doc/guides/html/authors.html
+++ b/railties/doc/guides/html/authors.html
@@ -231,6 +231,11 @@ Heiko has rarely looked back.</p></div>
 <div class="para"><p>Tore Darell is an independent developer based in Menton, France who specialises in cruft-free web applications using Ruby, Rails

 and unobtrusive JavaScript. His home on the internet is his blog <a href="http://tore.darell.no/">Sneaky Abstractions</a>.</p></div>

 </div></div>

+<div class="sidebarblock" id="zilkey">

+<div class="sidebar-content">

+<div class="sidebar-title">Jeff Dean</div>

+<div class="para"><p>Jeff Dean is a software engineer with <a href="http://pivotallabs.com/">Pivotal Labs</a>.</p></div>

+</div></div>

 </div>

 </div>

 
diff --git a/railties/doc/guides/html/creating_plugins.html b/railties/doc/guides/html/creating_plugins.html
index 45c81f2af1..1762bd95d2 100644
--- a/railties/doc/guides/html/creating_plugins.html
+++ b/railties/doc/guides/html/creating_plugins.html
@@ -269,28 +269,20 @@ ul#navMain {
 						
 							<li><a href="#_create_a_custom_rake_task">Create a custom rake task</a></li>
 						
-							<li><a href="#_call_plugin_migrations_from_regular_migrations">Call plugin migrations from regular migrations</a></li>
+							<li><a href="#_call_migrations_directly">Call migrations directly</a></li>
+						
+							<li><a href="#_generate_migrations">Generate migrations</a></li>
 						
 						</ul>
 					</li>
 					<li>
-					<a href="#_generating_migrations">Generating migrations</a>
+					<a href="#_rake_tasks">Rake tasks</a>
 					</li>
 					<li>
-					<a href="#_odds_and_ends">Odds and ends</a>
-						<ul>
-						
-							<li><a href="#_generate_rdoc_documentation">Generate RDoc Documentation</a></li>
-						
-							<li><a href="#_write_custom_rake_tasks_in_your_plugin">Write custom Rake tasks in your plugin</a></li>
-						
-							<li><a href="#_store_plugins_in_alternate_locations">Store plugins in alternate locations</a></li>
-						
-							<li><a href="#_create_your_own_plugin_loaders_and_plugin_locators">Create your own Plugin Loaders and Plugin Locators</a></li>
-						
-							<li><a href="#_use_custom_plugin_generators">Use Custom Plugin Generators</a></li>
-						
-						</ul>
+					<a href="#_plugingems">PluginGems</a>
+					</li>
+					<li>
+					<a href="#_rdoc_documentation">RDoc Documentation</a>
 					</li>
 					<li>
 					<a href="#_appendix">Appendix</a>
@@ -1030,7 +1022,7 @@ http://www.gnu.org/software/src-highlite -->
 <div class="sectionbody">

 <div class="para"><p>This section describes how to add a controller named <em>woodpeckers</em> to your plugin that will behave the same as a controller in your main app.  This is very similar to adding a model.</p></div>

 <div class="para"><p>You can test your plugin's controller as you would test any other controller:</p></div>

-<div class="para"><p><strong>vendor/plugins/yaffle/yaffle/woodpeckers_controller_test.rb:</strong></p></div>

+<div class="para"><p><strong>vendor/plugins/yaffle/test/woodpeckers_controller_test.rb:</strong></p></div>

 <div class="listingblock">

 <div class="content"><!-- Generator: GNU source-highlight 2.9

 by Lorenzo Bettini

@@ -1545,7 +1537,7 @@ http://www.gnu.org/software/src-highlite -->
   <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>

 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>

 </tt></pre></div></div>

-<h3 id="_call_plugin_migrations_from_regular_migrations">11.2. Call plugin migrations from regular migrations</h3>

+<h3 id="_call_migrations_directly">11.2. Call migrations directly</h3>

 <div class="para"><p><strong>vendor/plugins/yaffle/lib/yaffle.rb:</strong></p></div>

 <div class="listingblock">

 <div class="content"><!-- Generator: GNU source-highlight 2.9

@@ -1580,9 +1572,7 @@ http://www.gnu.org/software/src-highlite -->
 <td class="content">several plugin frameworks such as Desert and Engines provide more advanced plugin functionality.</td>

 </tr></table>

 </div>

-</div>

-<h2 id="_generating_migrations">12. Generating migrations</h2>

-<div class="sectionbody">

+<h3 id="_generate_migrations">11.3. Generate migrations</h3>

 <div class="para"><p>Generating migrations has several advantages over other methods.  Namely, you can allow other developers to more easily customize the migration.  The flow looks like this:</p></div>

 <div class="ilist"><ul>

 <li>

@@ -1709,41 +1699,8 @@ http://www.gnu.org/software/src-highlite -->
 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>

 </tt></pre></div></div>

 </div>

-<h2 id="_odds_and_ends">13. Odds and ends</h2>

+<h2 id="_rake_tasks">12. Rake tasks</h2>

 <div class="sectionbody">

-<h3 id="_generate_rdoc_documentation">13.1. Generate RDoc Documentation</h3>

-<div class="para"><p>Once your plugin is stable, the tests pass on all database and you are ready to deploy do everyone else a favor and document it!  Luckily, writing documentation for your plugin is easy.</p></div>

-<div class="para"><p>The first step is to update the README file with detailed information about how to use your plugin.  A few key things to include are:</p></div>

-<div class="ilist"><ul>

-<li>

-<p>

-Your name.

-</p>

-</li>

-<li>

-<p>

-How to install.

-</p>

-</li>

-<li>

-<p>

-How to add the functionality to the app (several examples of common use cases).

-</p>

-</li>

-<li>

-<p>

-Warning, gotchas or tips that might help save users time.

-</p>

-</li>

-</ul></div>

-<div class="para"><p>Once your README is solid, go through and add rdoc comments to all of the methods that developers will use.</p></div>

-<div class="para"><p>Before you generate your documentation, be sure to go through and add nodoc comments to those modules and methods that are not important to your users.</p></div>

-<div class="para"><p>Once your comments are good to go, navigate to your plugin directory and run:</p></div>

-<div class="literalblock">

-<div class="content">

-<pre><tt>rake rdoc</tt></pre>

-</div></div>

-<h3 id="_write_custom_rake_tasks_in_your_plugin">13.2. Write custom Rake tasks in your plugin</h3>

 <div class="para"><p>When you created the plugin with the built-in rails generator, it generated a rake file for you in <em>vendor/plugins/yaffle/tasks/yaffle.rake</em>.  Any rake task you add here will be available to the app.</p></div>

 <div class="para"><p>Many plugin authors put all of their rake tasks into a common namespace that is the same as the plugin, like so:</p></div>

 <div class="para"><p><strong>vendor/plugins/yaffle/tasks/yaffle.rake</strong></p></div>

@@ -1762,28 +1719,99 @@ http://www.gnu.org/software/src-highlite -->
 <div class="para"><p>When you run <tt>rake -T</tt> from your plugin you will see:</p></div>

 <div class="listingblock">

 <div class="content">

-<pre><tt>yaffle:squawk             # Prints out the word 'Yaffle'</tt></pre>

+<pre><tt>...

+yaffle:squawk             # Prints out the word 'Yaffle'

+...</tt></pre>

 </div></div>

 <div class="para"><p>You can add as many files as you want in the tasks directory, and if they end in .rake Rails will pick them up.</p></div>

-<h3 id="_store_plugins_in_alternate_locations">13.3. Store plugins in alternate locations</h3>

-<div class="para"><p>You can store plugins wherever you want - you just have to add those plugins to the plugins path in <em>environment.rb</em>.</p></div>

-<div class="para"><p>Since the plugin is only loaded after the plugin paths are defined, you can't redefine this in your plugins - but it may be good to now.</p></div>

-<div class="para"><p>You can even store plugins inside of other plugins for complete plugin madness!</p></div>

+<div class="para"><p>Note that tasks from <em>vendor/plugins/yaffle/Rakefile</em> are not available to the main app.</p></div>

+</div>

+<h2 id="_plugingems">13. PluginGems</h2>

+<div class="sectionbody">

+<div class="para"><p>Turning your rails plugin into a gem is a simple and straightforward task.  This section will cover how to turn your plugin into a gem.  It will not cover how to distribute that gem.</p></div>

+<div class="para"><p>Historically rails plugins loaded the plugin's <em>init.rb</em> file.  In fact some plugins contain all of their code in that one file.  To be compatible with plugins, <em>init.rb</em> was moved to <em>rails/init.rb</em>.</p></div>

+<div class="para"><p>It's common practice to put any developer-centric rake tasks (such as tests, rdoc and gem package tasks) in <em>Rakefile</em>.  A rake task that packages the gem might look like this:</p></div>

+<div class="para"><p><strong>vendor/plugins/yaffle/Rakefile:</strong></p></div>

 <div class="listingblock">

 <div class="content"><!-- Generator: GNU source-highlight 2.9

 by Lorenzo Bettini

 http://www.lorenzobettini.it

 http://www.gnu.org/software/src-highlite -->

-<pre><tt>config<span style="color: #990000">.</span>plugin_paths <span style="color: #990000">&lt;&lt;</span> File<span style="color: #990000">.</span>join<span style="color: #990000">(</span>RAILS_ROOT<span style="color: #990000">,</span><span style="color: #FF0000">"vendor"</span><span style="color: #990000">,</span><span style="color: #FF0000">"plugins"</span><span style="color: #990000">,</span><span style="color: #FF0000">"yaffle"</span><span style="color: #990000">,</span><span style="color: #FF0000">"lib"</span><span style="color: #990000">,</span><span style="color: #FF0000">"plugins"</span><span style="color: #990000">)</span>

+<pre><tt>PKG_FILES <span style="color: #990000">=</span> FileList<span style="color: #990000">[</span>

+  <span style="color: #FF0000">'[a-zA-Z]*'</span><span style="color: #990000">,</span>

+  <span style="color: #FF0000">'generators/**/*'</span><span style="color: #990000">,</span>

+  <span style="color: #FF0000">'lib/**/*'</span><span style="color: #990000">,</span>

+  <span style="color: #FF0000">'rails/**/*'</span><span style="color: #990000">,</span>

+  <span style="color: #FF0000">'tasks/**/*'</span><span style="color: #990000">,</span>

+  <span style="color: #FF0000">'test/**/*'</span>

+<span style="color: #990000">]</span>

+

+spec <span style="color: #990000">=</span> Gem<span style="color: #990000">::</span>Specification<span style="color: #990000">.</span>new <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>s<span style="color: #990000">|</span>

+  s<span style="color: #990000">.</span>name <span style="color: #990000">=</span> <span style="color: #FF0000">"yaffle"</span>

+  s<span style="color: #990000">.</span>version <span style="color: #990000">=</span> <span style="color: #FF0000">"0.0.1"</span>

+  s<span style="color: #990000">.</span>author <span style="color: #990000">=</span> <span style="color: #FF0000">"Gleeful Yaffler"</span>

+  s<span style="color: #990000">.</span>email <span style="color: #990000">=</span> <span style="color: #FF0000">"yaffle@example.com"</span>

+  s<span style="color: #990000">.</span>homepage <span style="color: #990000">=</span> <span style="color: #FF0000">"http://yafflers.example.com/"</span>

+  s<span style="color: #990000">.</span>platform <span style="color: #990000">=</span> Gem<span style="color: #990000">::</span>Platform<span style="color: #990000">::</span>RUBY

+  s<span style="color: #990000">.</span>summary <span style="color: #990000">=</span> <span style="color: #FF0000">"Sharing Yaffle Goodness"</span>

+  s<span style="color: #990000">.</span>files <span style="color: #990000">=</span> PKG_FILES<span style="color: #990000">.</span>to_a

+  s<span style="color: #990000">.</span>require_path <span style="color: #990000">=</span> <span style="color: #FF0000">"lib"</span>

+  s<span style="color: #990000">.</span>has_rdoc <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">false</span></span>

+  s<span style="color: #990000">.</span>extra_rdoc_files <span style="color: #990000">=</span> <span style="color: #990000">[</span><span style="color: #FF0000">"README"</span><span style="color: #990000">]</span>

+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>

+

+desc <span style="color: #FF0000">'Turn this plugin into a gem.'</span>

+Rake<span style="color: #990000">::</span>GemPackageTask<span style="color: #990000">.</span>new<span style="color: #990000">(</span>spec<span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>pkg<span style="color: #990000">|</span>

+  pkg<span style="color: #990000">.</span>gem_spec <span style="color: #990000">=</span> spec

+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>

 </tt></pre></div></div>

-<h3 id="_create_your_own_plugin_loaders_and_plugin_locators">13.4. Create your own Plugin Loaders and Plugin Locators</h3>

-<div class="para"><p>If the built-in plugin behavior is inadequate, you can change almost every aspect of the location and loading process.  You can write your own plugin locators and plugin loaders, but that's beyond the scope of this tutorial.</p></div>

-<h3 id="_use_custom_plugin_generators">13.5. Use Custom Plugin Generators</h3>

-<div class="para"><p>If you are an RSpec fan, you can install the <tt>rspec_plugin_generator</tt> gem, which will generate the spec folder and database for you. See <a href="http://github.com/pat-maddox/rspec-plugin-generator/tree/master">http://github.com/pat-maddox/rspec-plugin-generator/tree/master</a>.</p></div>

+<div class="para"><p>To build and install the gem locally, run the following commands:</p></div>

+<div class="listingblock">

+<div class="content">

+<pre><tt>cd vendor/plugins/yaffle

+rake gem

+sudo gem install pkg/yaffle-0.0.1.gem</tt></pre>

+</div></div>

+<div class="para"><p>To test this, create a new rails app, add <em>config.gem "yaffle"</em> to environment.rb and all of your plugin's functionality will be available to you.</p></div>

 </div>

-<h2 id="_appendix">14. Appendix</h2>

+<h2 id="_rdoc_documentation">14. RDoc Documentation</h2>

 <div class="sectionbody">

-<h3 id="_references">14.1. References</h3>

+<div class="para"><p>Once your plugin is stable, the tests pass on all database and you are ready to deploy do everyone else a favor and document it!  Luckily, writing documentation for your plugin is easy.</p></div>

+<div class="para"><p>The first step is to update the README file with detailed information about how to use your plugin.  A few key things to include are:</p></div>

+<div class="ilist"><ul>

+<li>

+<p>

+Your name

+</p>

+</li>

+<li>

+<p>

+How to install

+</p>

+</li>

+<li>

+<p>

+How to add the functionality to the app (several examples of common use cases)

+</p>

+</li>

+<li>

+<p>

+Warning, gotchas or tips that might help save users time

+</p>

+</li>

+</ul></div>

+<div class="para"><p>Once your README is solid, go through and add rdoc comments to all of the methods that developers will use.</p></div>

+<div class="para"><p>Before you generate your documentation, be sure to go through and add nodoc comments to those modules and methods that are not important to your users.</p></div>

+<div class="para"><p>Once your comments are good to go, navigate to your plugin directory and run:</p></div>

+<div class="listingblock">

+<div class="content">

+<pre><tt>rake rdoc</tt></pre>

+</div></div>

+</div>

+<h2 id="_appendix">15. Appendix</h2>

+<div class="sectionbody">

+<div class="para"><p>If you prefer to use RSpec instead of tets, you may be interested in the <a href="http://github.com/pat-maddox/rspec-plugin-generator/tree/master">RSpec Plugin Generator</a>.</p></div>

+<h3 id="_references">15.1. References</h3>

 <div class="ilist"><ul>

 <li>

 <p>

@@ -1811,20 +1839,27 @@ http://www.gnu.org/software/src-highlite -->
 </p>

 </li>

 </ul></div>

-<h3 id="_final_plugin_directory_structure">14.2. Final plugin directory structure</h3>

+<h3 id="_final_plugin_directory_structure">15.2. Final plugin directory structure</h3>

 <div class="para"><p>The final plugin should have a directory structure that looks something like this:</p></div>

 <div class="listingblock">

 <div class="content">

-<pre><tt>vendor/plugins/yaffle/

-|-- MIT-LICENSE

+<pre><tt>|-- MIT-LICENSE

 |-- README

 |-- Rakefile

 |-- generators

-|   `-- yaffle

+|   |-- yaffle_definition

+|   |   |-- USAGE

+|   |   |-- templates

+|   |   |   `-- definition.txt

+|   |   `-- yaffle_definition_generator.rb

+|   |-- yaffle_migration

+|   |   |-- USAGE

+|   |   |-- templates

+|   |   `-- yaffle_migration_generator.rb

+|   `-- yaffle_route

 |       |-- USAGE

 |       |-- templates

-|       |   `-- definition.txt

-|       `-- yaffle_generator.rb

+|       `-- yaffle_route_generator.rb

 |-- install.rb

 |-- lib

 |   |-- app

@@ -1834,11 +1869,16 @@ http://www.gnu.org/software/src-highlite -->
 |   |   |   `-- woodpeckers_helper.rb

 |   |   `-- models

 |   |       `-- woodpecker.rb

+|   |-- db

+|   |   `-- migrate

+|   |       `-- 20081116181115_create_birdhouses.rb

 |   |-- yaffle

 |   |   |-- acts_as_yaffle.rb

 |   |   |-- commands.rb

 |   |   `-- core_ext.rb

 |   `-- yaffle.rb

+|-- pkg

+|   `-- yaffle-0.0.1.gem

 |-- rails

 |   `-- init.rb

 |-- tasks

@@ -1848,7 +1888,9 @@ http://www.gnu.org/software/src-highlite -->
 |   |-- core_ext_test.rb

 |   |-- database.yml

 |   |-- debug.log

-|   |-- generator_test.rb

+|   |-- definition_generator_test.rb

+|   |-- migration_generator_test.rb

+|   |-- route_generator_test.rb

 |   |-- schema.rb

 |   |-- test_helper.rb

 |   |-- woodpecker_test.rb

diff --git a/railties/doc/guides/html/routing_outside_in.html b/railties/doc/guides/html/routing_outside_in.html
index 947d0836ce..1d313b619f 100644
--- a/railties/doc/guides/html/routing_outside_in.html
+++ b/railties/doc/guides/html/routing_outside_in.html
@@ -1454,7 +1454,7 @@ http://www.gnu.org/software/src-highlite -->
 <td class="icon">

 <img src="./images/icons/tip.png" alt="Tip" />

 </td>

-<td class="content">If your application has many RESTful routes, using <tt>:only</tt> and <tt>:accept</tt> to generate only the routes that you actually need can cut down on memory use and speed up the routing process.</td>

+<td class="content">If your application has many RESTful routes, using <tt>:only</tt> and <tt>:except</tt> to generate only the routes that you actually need can cut down on memory use and speed up the routing process.</td>

 </tr></table>

 </div>

 <h3 id="_nested_resources">3.8. Nested Resources</h3>

diff --git a/railties/doc/guides/source/authors.txt b/railties/doc/guides/source/authors.txt
index 94dfc4db08..987238eb4c 100644
--- a/railties/doc/guides/source/authors.txt
+++ b/railties/doc/guides/source/authors.txt
@@ -37,3 +37,9 @@ Heiko has rarely looked back.
 Tore Darell is an independent developer based in Menton, France who specialises in cruft-free web applications using Ruby, Rails
 and unobtrusive JavaScript. His home on the internet is his blog http://tore.darell.no/[Sneaky Abstractions].
 ***********************************************************
+
+.Jeff Dean
+[[zilkey]]
+***********************************************************
+Jeff Dean is a software engineer with http://pivotallabs.com/[Pivotal Labs].
+***********************************************************
diff --git a/railties/doc/guides/source/creating_plugins/appendix.txt b/railties/doc/guides/source/creating_plugins/appendix.txt
index d890f861b5..19f677c5fd 100644
--- a/railties/doc/guides/source/creating_plugins/appendix.txt
+++ b/railties/doc/guides/source/creating_plugins/appendix.txt
@@ -1,5 +1,7 @@
 == Appendix ==
 
+If you prefer to use RSpec instead of tets, you may be interested in the http://github.com/pat-maddox/rspec-plugin-generator/tree/master[RSpec Plugin Generator].
+
 === References ===
 
  * http://nubyonrails.com/articles/the-complete-guide-to-rails-plugins-part-i
@@ -13,16 +15,23 @@
 The final plugin should have a directory structure that looks something like this:
 
 ------------------------------------------------
-vendor/plugins/yaffle/
 |-- MIT-LICENSE
 |-- README
 |-- Rakefile
 |-- generators
-|   `-- yaffle
+|   |-- yaffle_definition
+|   |   |-- USAGE
+|   |   |-- templates
+|   |   |   `-- definition.txt
+|   |   `-- yaffle_definition_generator.rb
+|   |-- yaffle_migration
+|   |   |-- USAGE
+|   |   |-- templates
+|   |   `-- yaffle_migration_generator.rb
+|   `-- yaffle_route
 |       |-- USAGE
 |       |-- templates
-|       |   `-- definition.txt
-|       `-- yaffle_generator.rb
+|       `-- yaffle_route_generator.rb
 |-- install.rb
 |-- lib
 |   |-- app
@@ -32,11 +41,16 @@ vendor/plugins/yaffle/
 |   |   |   `-- woodpeckers_helper.rb
 |   |   `-- models
 |   |       `-- woodpecker.rb
+|   |-- db
+|   |   `-- migrate
+|   |       `-- 20081116181115_create_birdhouses.rb
 |   |-- yaffle
 |   |   |-- acts_as_yaffle.rb
 |   |   |-- commands.rb
 |   |   `-- core_ext.rb
 |   `-- yaffle.rb
+|-- pkg
+|   `-- yaffle-0.0.1.gem
 |-- rails
 |   `-- init.rb
 |-- tasks
@@ -46,7 +60,9 @@ vendor/plugins/yaffle/
 |   |-- core_ext_test.rb
 |   |-- database.yml
 |   |-- debug.log
-|   |-- generator_test.rb
+|   |-- definition_generator_test.rb
+|   |-- migration_generator_test.rb
+|   |-- route_generator_test.rb
 |   |-- schema.rb
 |   |-- test_helper.rb
 |   |-- woodpecker_test.rb
diff --git a/railties/doc/guides/source/creating_plugins/controllers.txt b/railties/doc/guides/source/creating_plugins/controllers.txt
index 4f4417b416..e38cf8251e 100644
--- a/railties/doc/guides/source/creating_plugins/controllers.txt
+++ b/railties/doc/guides/source/creating_plugins/controllers.txt
@@ -4,7 +4,7 @@ This section describes how to add a controller named 'woodpeckers' to your plugi
 
 You can test your plugin's controller as you would test any other controller:
 
-*vendor/plugins/yaffle/yaffle/woodpeckers_controller_test.rb:*
+*vendor/plugins/yaffle/test/woodpeckers_controller_test.rb:*
 
 [source, ruby]
 ----------------------------------------------
diff --git a/railties/doc/guides/source/creating_plugins/gem.txt b/railties/doc/guides/source/creating_plugins/gem.txt
deleted file mode 100644
index 8a0bbb3bc0..0000000000
--- a/railties/doc/guides/source/creating_plugins/gem.txt
+++ /dev/null
@@ -1,3 +0,0 @@
-== Gems ==
-
-http://www.mbleigh.com/2008/6/11/gemplugins-a-brief-introduction-to-the-future-of-rails-plugins
\ No newline at end of file
diff --git a/railties/doc/guides/source/creating_plugins/gems.txt b/railties/doc/guides/source/creating_plugins/gems.txt
new file mode 100644
index 0000000000..67d55adb3a
--- /dev/null
+++ b/railties/doc/guides/source/creating_plugins/gems.txt
@@ -0,0 +1,50 @@
+== PluginGems ==
+
+Turning your rails plugin into a gem is a simple and straightforward task.  This section will cover how to turn your plugin into a gem.  It will not cover how to distribute that gem.
+
+Historically rails plugins loaded the plugin's 'init.rb' file.  In fact some plugins contain all of their code in that one file.  To be compatible with plugins, 'init.rb' was moved to 'rails/init.rb'.
+
+It's common practice to put any developer-centric rake tasks (such as tests, rdoc and gem package tasks) in 'Rakefile'.  A rake task that packages the gem might look like this:
+
+*vendor/plugins/yaffle/Rakefile:*
+
+[source, ruby]
+----------------------------------------------
+PKG_FILES = FileList[
+  '[a-zA-Z]*',
+  'generators/**/*', 
+  'lib/**/*', 
+  'rails/**/*',
+  'tasks/**/*', 
+  'test/**/*'
+]
+
+spec = Gem::Specification.new do |s| 
+  s.name = "yaffle"
+  s.version = "0.0.1"
+  s.author = "Gleeful Yaffler"
+  s.email = "yaffle@example.com"
+  s.homepage = "http://yafflers.example.com/"
+  s.platform = Gem::Platform::RUBY
+  s.summary = "Sharing Yaffle Goodness"
+  s.files = PKG_FILES.to_a
+  s.require_path = "lib"
+  s.has_rdoc = false
+  s.extra_rdoc_files = ["README"]
+end
+
+desc 'Turn this plugin into a gem.'
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end 
+----------------------------------------------
+
+To build and install the gem locally, run the following commands:
+
+----------------------------------------------
+cd vendor/plugins/yaffle
+rake gem
+sudo gem install pkg/yaffle-0.0.1.gem
+----------------------------------------------
+
+To test this, create a new rails app, add 'config.gem "yaffle"' to environment.rb and all of your plugin's functionality will be available to you.
\ No newline at end of file
diff --git a/railties/doc/guides/source/creating_plugins/index.txt b/railties/doc/guides/source/creating_plugins/index.txt
index 5d10fa4f31..0607bc7487 100644
--- a/railties/doc/guides/source/creating_plugins/index.txt
+++ b/railties/doc/guides/source/creating_plugins/index.txt
@@ -51,6 +51,10 @@ include::generator_commands.txt[]
 
 include::migrations.txt[]
 
-include::odds_and_ends.txt[]
+include::tasks.txt[]
+
+include::gems.txt[]
+
+include::rdoc.txt[]
 
 include::appendix.txt[]
diff --git a/railties/doc/guides/source/creating_plugins/migrations.txt b/railties/doc/guides/source/creating_plugins/migrations.txt
index 7154f0bc06..4dd932734d 100644
--- a/railties/doc/guides/source/creating_plugins/migrations.txt
+++ b/railties/doc/guides/source/creating_plugins/migrations.txt
@@ -63,7 +63,7 @@ namespace :db do
 end
 ----------------------------------------------
 
-=== Call plugin migrations from regular migrations ===
+=== Call migrations directly ===
 
 *vendor/plugins/yaffle/lib/yaffle.rb:*
 
@@ -91,7 +91,7 @@ end
 
 NOTE: several plugin frameworks such as Desert and Engines provide more advanced plugin functionality.
 
-== Generating migrations ==
+=== Generate migrations ===
 
 Generating migrations has several advantages over other methods.  Namely, you can allow other developers to more easily customize the migration.  The flow looks like this:
 
diff --git a/railties/doc/guides/source/creating_plugins/odds_and_ends.txt b/railties/doc/guides/source/creating_plugins/odds_and_ends.txt
deleted file mode 100644
index e328c04a79..0000000000
--- a/railties/doc/guides/source/creating_plugins/odds_and_ends.txt
+++ /dev/null
@@ -1,69 +0,0 @@
-== Odds and ends ==
-
-=== Generate RDoc Documentation ===
-
-Once your plugin is stable, the tests pass on all database and you are ready to deploy do everyone else a favor and document it!  Luckily, writing documentation for your plugin is easy.
-
-The first step is to update the README file with detailed information about how to use your plugin.  A few key things to include are:
-
- * Your name.
- * How to install.
- * How to add the functionality to the app (several examples of common use cases).
- * Warning, gotchas or tips that might help save users time.
-
-Once your README is solid, go through and add rdoc comments to all of the methods that developers will use.
-
-Before you generate your documentation, be sure to go through and add nodoc comments to those modules and methods that are not important to your users.
-
-Once your comments are good to go, navigate to your plugin directory and run:
-
-    rake rdoc
-
-=== Write custom Rake tasks in your plugin ===
-
-When you created the plugin with the built-in rails generator, it generated a rake file for you in 'vendor/plugins/yaffle/tasks/yaffle.rake'.  Any rake task you add here will be available to the app.
-
-Many plugin authors put all of their rake tasks into a common namespace that is the same as the plugin, like so:
-
-*vendor/plugins/yaffle/tasks/yaffle.rake*
-
-[source, ruby]
----------------------------------------------------------
-namespace :yaffle do
-  desc "Prints out the word 'Yaffle'"
-  task :squawk => :environment do
-    puts "squawk!"
-  end
-end
----------------------------------------------------------
-
-When you run `rake -T` from your plugin you will see:
-
----------------------------------------------------------
-yaffle:squawk             # Prints out the word 'Yaffle'
----------------------------------------------------------
-
-You can add as many files as you want in the tasks directory, and if they end in .rake Rails will pick them up.
-
-=== Store plugins in alternate locations ===
-
-You can store plugins wherever you want - you just have to add those plugins to the plugins path in 'environment.rb'.
-
-Since the plugin is only loaded after the plugin paths are defined, you can't redefine this in your plugins - but it may be good to now.
-
-You can even store plugins inside of other plugins for complete plugin madness!
-
-[source, ruby]
----------------------------------------------------------
-config.plugin_paths << File.join(RAILS_ROOT,"vendor","plugins","yaffle","lib","plugins")
----------------------------------------------------------
-
-=== Create your own Plugin Loaders and Plugin Locators ===
-
-If the built-in plugin behavior is inadequate, you can change almost every aspect of the location and loading process.  You can write your own plugin locators and plugin loaders, but that's beyond the scope of this tutorial.
-
-
-=== Use Custom Plugin Generators ===
-
-If you are an RSpec fan, you can install the `rspec_plugin_generator` gem, which will generate the spec folder and database for you. See http://github.com/pat-maddox/rspec-plugin-generator/tree/master.
-
diff --git a/railties/doc/guides/source/creating_plugins/rdoc.txt b/railties/doc/guides/source/creating_plugins/rdoc.txt
new file mode 100644
index 0000000000..0f6f843c42
--- /dev/null
+++ b/railties/doc/guides/source/creating_plugins/rdoc.txt
@@ -0,0 +1,18 @@
+== RDoc Documentation ==
+
+Once your plugin is stable and you are ready to deploy do everyone else a favor and document it!  Luckily, writing documentation for your plugin is easy.
+
+The first step is to update the README file with detailed information about how to use your plugin.  A few key things to include are:
+
+ * Your name
+ * How to install
+ * How to add the functionality to the app (several examples of common use cases)
+ * Warning, gotchas or tips that might help save users time
+
+Once your README is solid, go through and add rdoc comments to all of the methods that developers will use.  It's also customary to add '#:nodoc:' comments to those parts of the code that are not part of the public api.
+
+Once your comments are good to go, navigate to your plugin directory and run:
+
+---------------------------------------------------------
+rake rdoc
+---------------------------------------------------------
diff --git a/railties/doc/guides/source/creating_plugins/tasks.txt b/railties/doc/guides/source/creating_plugins/tasks.txt
new file mode 100644
index 0000000000..c71ba42bb0
--- /dev/null
+++ b/railties/doc/guides/source/creating_plugins/tasks.txt
@@ -0,0 +1,29 @@
+== Rake tasks ==
+
+When you created the plugin with the built-in rails generator, it generated a rake file for you in 'vendor/plugins/yaffle/tasks/yaffle.rake'.  Any rake task you add here will be available to the app.
+
+Many plugin authors put all of their rake tasks into a common namespace that is the same as the plugin, like so:
+
+*vendor/plugins/yaffle/tasks/yaffle.rake*
+
+[source, ruby]
+---------------------------------------------------------
+namespace :yaffle do
+  desc "Prints out the word 'Yaffle'"
+  task :squawk => :environment do
+    puts "squawk!"
+  end
+end
+---------------------------------------------------------
+
+When you run `rake -T` from your plugin you will see:
+
+---------------------------------------------------------
+...
+yaffle:squawk             # Prints out the word 'Yaffle'
+...
+---------------------------------------------------------
+
+You can add as many files as you want in the tasks directory, and if they end in .rake Rails will pick them up.
+
+Note that tasks from 'vendor/plugins/yaffle/Rakefile' are not available to the main app.
\ No newline at end of file