From 097b4678f6d52e86a9d46ba6c862e6eb6ef7bbdd Mon Sep 17 00:00:00 2001
From: Jeff Dean <jeff@zilkey.com>
Date: Sun, 16 Nov 2008 20:30:42 -0500
Subject: Plugin Guide: added section on migrations, updated generator section,
 tightened up spacing of P's inside LI's

---
 railties/doc/guides/html/configuring.html          | 119 ++-
 railties/doc/guides/html/creating_plugins.html     | 952 +++++++++++++--------
 railties/doc/guides/html/migrations.html           |   3 +-
 .../source/creating_plugins/acts_as_yaffle.txt     |   2 +-
 .../guides/source/creating_plugins/appendix.txt    |  73 +-
 .../guides/source/creating_plugins/controllers.txt |   2 +-
 .../source/creating_plugins/custom_route.txt       |  69 --
 .../doc/guides/source/creating_plugins/gem.txt     |   2 +
 .../source/creating_plugins/generator_commands.txt | 140 +++
 .../source/creating_plugins/generator_method.txt   |  89 --
 .../guides/source/creating_plugins/generators.txt  | 103 +++
 .../doc/guides/source/creating_plugins/helpers.txt |   2 +-
 .../doc/guides/source/creating_plugins/index.txt   |  16 +-
 .../creating_plugins/migration_generator.txt       | 156 ----
 .../guides/source/creating_plugins/migrations.txt  | 209 +++++
 .../doc/guides/source/creating_plugins/models.txt  |   2 +-
 .../doc/guides/source/creating_plugins/routes.txt  |  69 ++
 .../doc/guides/source/creating_plugins/setup.txt   |  64 ++
 .../guides/source/creating_plugins/test_setup.txt  | 230 -----
 .../doc/guides/source/creating_plugins/tests.txt   | 165 ++++
 railties/doc/guides/source/stylesheets/base.css    |   4 +
 21 files changed, 1505 insertions(+), 966 deletions(-)
 delete mode 100644 railties/doc/guides/source/creating_plugins/custom_route.txt
 create mode 100644 railties/doc/guides/source/creating_plugins/generator_commands.txt
 delete mode 100644 railties/doc/guides/source/creating_plugins/generator_method.txt
 create mode 100644 railties/doc/guides/source/creating_plugins/generators.txt
 delete mode 100644 railties/doc/guides/source/creating_plugins/migration_generator.txt
 create mode 100644 railties/doc/guides/source/creating_plugins/migrations.txt
 create mode 100644 railties/doc/guides/source/creating_plugins/routes.txt
 create mode 100644 railties/doc/guides/source/creating_plugins/setup.txt
 delete mode 100644 railties/doc/guides/source/creating_plugins/test_setup.txt
 create mode 100644 railties/doc/guides/source/creating_plugins/tests.txt

(limited to 'railties')

diff --git a/railties/doc/guides/html/configuring.html b/railties/doc/guides/html/configuring.html
index 4aa3a0f545..ea5f162cb7 100644
--- a/railties/doc/guides/html/configuring.html
+++ b/railties/doc/guides/html/configuring.html
@@ -205,6 +205,9 @@ ul#navMain {
 					<a href="#_using_a_preinitializer">Using a Preinitializer</a>
 					</li>
 					<li>
+					<a href="#_initialization_process_settings">Initialization Process Settings</a>
+					</li>
+					<li>
 					<a href="#_configuring_rails_components">Configuring Rails Components</a>
 						<ul>
 						
@@ -229,6 +232,9 @@ ul#navMain {
 					<a href="#_using_an_after_initializer">Using an After-Initializer</a>
 					</li>
 					<li>
+					<a href="#_rails_environment_settings">Rails Environment Settings</a>
+					</li>
+					<li>
 					<a href="#_changelog">Changelog</a>
 					</li>
 			</ol>
@@ -264,26 +270,81 @@ after-initializer</p></div>
 <h2 id="_using_a_preinitializer">2. Using a Preinitializer</h2>
 <div class="sectionbody">
 </div>
-<h2 id="_configuring_rails_components">3. Configuring Rails Components</h2>
+<h2 id="_initialization_process_settings">3. Initialization Process Settings</h2>
+<div class="sectionbody">
+</div>
+<h2 id="_configuring_rails_components">4. Configuring Rails Components</h2>
 <div class="sectionbody">
-<h3 id="_configuring_active_record">3.1. Configuring Active Record</h3>
-<h3 id="_configuring_action_controller">3.2. Configuring Action Controller</h3>
-<h3 id="_configuring_action_view">3.3. Configuring Action View</h3>
-<h3 id="_configuring_action_mailer">3.4. Configuring Action Mailer</h3>
-<h3 id="_configuring_active_resource">3.5. Configuring Active Resource</h3>
-<h3 id="_configuring_active_support">3.6. Configuring Active Support</h3>
+<h3 id="_configuring_active_record">4.1. Configuring Active Record</h3>
+<div class="para"><p><tt>ActiveRecord::Base</tt> includej a variety of configuration options:</p></div>
+<div class="para"><p><tt>logger</tt> accepts a logger conforming to the interface of Log4r or the default Ruby 1.8+ Logger class, which is then passed on to any new database connections made. You can retrieve this logger by calling <tt>logger</tt> on either an ActiveRecord model class or an ActiveRecord model instance. Set to nil to disable logging.</p></div>
+<div class="para"><p><tt>primary_key_prefix_type</tt> lets you adjust the naming for primary key columns. By default, Rails assumes that primary key columns are named <tt>id</tt> (and this configuration option doesn't need to be set.) There are two other choices:</p></div>
+<div class="ilist"><ul>
+<li>
+<p>
+<tt>:table_name</tt> would make the primary key for the Customer class <tt>customerid</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>:table_name_with_underscore</tt> would make the primary key for the Customer class <tt>customer_id</tt>
+</p>
+</li>
+</ul></div>
+<div class="para"><p><tt>table_name_prefix</tt> lets you set a global string to be prepended to table names. If you set this to <tt>northwest_</tt>, then the Customer class will look for <tt>northwest_customers</tt> as its table. The default is an empty string.</p></div>
+<div class="para"><p><tt>table_name_suffix</tt> lets you set a global string to be appended to table names. If you set this to <tt>_northwest</tt>, then the Customer class will look for <tt>customers_northwest</tt> as its table. The default is an empty string.</p></div>
+<div class="para"><p><tt>pluralize_table_names</tt> specifies whether Rails will look for singular or plural table names in the database. If set to <tt>true</tt> (the default), then the Customer class will use the <tt>customers</tt> table. If set to <tt>false</tt>, then the Customers class will use the <tt>customer</tt> table.</p></div>
+<div class="para"><p><tt>colorize_logging</tt> (true by default) specifies whether or not to use ANSI color codes when logging information from ActiveRecord.</p></div>
+<div class="para"><p><tt>default_timezone</tt> determines whether to use <tt>Time.local</tt> (if set to <tt>:local</tt>) or <tt>Time.utc</tt> (if set to <tt>:utc</tt>) when pulling dates and times from the database. The default is <tt>:local</tt>.</p></div>
+<div class="para"><p><tt>schema_format</tt> controls the format for dumping the database schema to a file. The options are <tt>:ruby</tt> (the default) for a database-independent version that depends on migrations, or <tt>:sql</tt> for a set of (potentially database-dependent) SQL statements.</p></div>
+<div class="para"><p><tt>timestamped_migrations</tt> controls whether migrations are numbered with serial integers or with timestamps. The default is <tt>true</tt>, to use timestamps, which are preferred if there are multiple developers working on the same application.</p></div>
+<div class="para"><p><tt>lock_optimistically</tt> controls whether ActiveRecord will use optimistic locking. By default this is <tt>true</tt>.</p></div>
+<div class="para"><p>The MySQL adapter adds one additional configuration option:</p></div>
+<div class="para"><p><tt>ActiveRecord::ConnectionAdapters::MysqlAdapter.emulate_booleans</tt> controls whether ActiveRecord will consider all <tt>tinyint(1)</tt> columns in a MySQL database to be booleans. By default this is <tt>true</tt>.</p></div>
+<div class="para"><p>The schema dumper adds one additional configuration option:</p></div>
+<div class="para"><p><tt>ActiveRecord::SchemaDumper.ignore_tables</tt> accepts an array of tables that should <em>not</em> be included in any generated schema file. This setting is ignored unless <tt>ActiveRecord::Base.schema_format == :ruby</tt>.</p></div>
+<h3 id="_configuring_action_controller">4.2. Configuring Action Controller</h3>
+<div class="para"><p>ActionController::Base includes a number of configuration settings:</p></div>
+<div class="para"><p><tt>asset_host</tt> provides a string that is prepended to all of the URL-generating helpers in <tt>AssetHelper</tt>. This is designed to allow moving all javascript, CSS, and image files to a separate asset host.</p></div>
+<div class="para"><p><tt>consider_all_requests_local</tt> is generally set to <tt>true</tt> during development and <tt>false</tt> during production; if it is set to <tt>true</tt>, then any error will cause detailed debugging information to be dumped in the HTTP response. For finer-grained control, set this to <tt>false</tt> and implement <tt>local_request?</tt> to specify which requests should provide debugging information on errors.</p></div>
+<div class="para"><p><tt>allow_concurrency</tt> should be set to <tt>true</tt> to allow concurrent (threadsafe) action processing. Set to <tt>false</tt> by default.</p></div>
+<div class="para"><p><tt>param_parsers</tt> provides an array of handlers that can extract information from incoming HTTP requests and add it to the <tt>params</tt> hash. By default, parsers for multipart forms, URL-encoded forms, XML, and JSON are active.</p></div>
+<div class="para"><p><tt>default_charset</tt> specifies the default character set for all renders. The default is "utf-8".</p></div>
+<div class="para"><p><tt>logger</tt> accepts a logger conforming to the interface of Log4r or the default Ruby 1.8+ Logger class, which is then used to log information from Action Controller. Set to nil to disable logging.</p></div>
+<div class="para"><p><tt>resource_action_separator</tt> gives the token to be used between resources and actions when building or interpreting RESTful URLs. By default, this is "/".</p></div>
+<div class="para"><p><tt>resource_path_names</tt> is a hash of default names for several RESTful actions. By default, the new action is named <tt>new</tt> and the edit action is named <tt>edit</tt>.</p></div>
+<div class="para"><p><tt>request_forgery_protection_token</tt> sets the token parameter name for RequestForgery. Calling <tt>protect_from_forgery</tt> sets it to <tt>:authenticity_token</tt> by default.</p></div>
+<div class="para"><p><tt>optimise_named_routes</tt> turns on some optimizations in generating the routing table. It is set to <tt>true</tt> by default.</p></div>
+<div class="para"><p><tt>use_accept_header</tt> sets the rules for determining the response format. If this is set to <tt>true</tt> (the default) then <tt>respond_to</tt> and <tt>Request#format</tt> will take the Accept header into account. If it is set to false then the request format will be determined solely by examining <tt>params[:format]</tt>. If there is no <tt>format</tt> parameter, then the response format will be either HTML or Javascript depending on whether the request is an AJAX request.</p></div>
+<div class="para"><p><tt>allow_forgery_protection</tt> enables or disables CSRF protection. By default this is <tt>false</tt> in test mode and <tt>true</tt> in all other modes.</p></div>
+<div class="para"><p><tt>relative_url_root</tt> can be used to tell Rails that you are deploying to a subdirectory. The default is <tt>ENV[<em>RAILS_RELATIVE_URL_ROOT</em>]</tt>.</p></div>
+<div class="para"><p>The caching code adds two additional settings:</p></div>
+<div class="para"><p><tt>ActionController::Caching::Pages.page_cache_directory</tt> sets the directory where Rails will create cached pages for your web server. The default is <tt>Rails.public_path</tt> (which is usually set to <tt>RAILS_ROOT </tt> "/public"+).</p></div>
+<div class="para"><p><tt>ActionController::Caching::Pages.page_cache_extension</tt> sets the extension to be used when generating pages for the cache (this is ignored if the incoming request already has an extension). The default is <tt>.html</tt>.</p></div>
+<div class="para"><p>The dispatcher includes one setting:</p></div>
+<div class="para"><p><tt>ActionController::Dispatcher.error_file_path</tt> gives the path where Rails will look for error files such as <tt>404.html</tt>. The default is <tt>Rails.public_path</tt>.</p></div>
+<div class="para"><p>The Active Record session store can also be configured:</p></div>
+<div class="para"><p><tt>CGI::Session::ActiveRecordStore::Session.data_column_name</tt> sets the name of the column to use to store session data. By default it is <em>data</em></p></div>
+<h3 id="_configuring_action_view">4.3. Configuring Action View</h3>
+<h3 id="_configuring_action_mailer">4.4. Configuring Action Mailer</h3>
+<h3 id="_configuring_active_resource">4.5. Configuring Active Resource</h3>
+<h3 id="_configuring_active_support">4.6. Configuring Active Support</h3>
 </div>
-<h2 id="_using_initializers">4. Using Initializers</h2>
+<h2 id="_using_initializers">5. Using Initializers</h2>
 <div class="sectionbody">
 <div class="literalblock">
 <div class="content">
 <pre><tt>organization, controlling load order</tt></pre>
 </div></div>
 </div>
-<h2 id="_using_an_after_initializer">5. Using an After-Initializer</h2>
+<h2 id="_using_an_after_initializer">6. Using an After-Initializer</h2>
+<div class="sectionbody">
+</div>
+<h2 id="_rails_environment_settings">7. Rails Environment Settings</h2>
 <div class="sectionbody">
+<div class="para"><p>ENV</p></div>
 </div>
-<h2 id="_changelog">6. Changelog</h2>
+<h2 id="_changelog">8. Changelog</h2>
 <div class="sectionbody">
 <div class="para"><p><a href="http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/28">Lighthouse ticket</a></p></div>
 <div class="ilist"><ul>
@@ -366,37 +427,6 @@ November 5, 2008: Rough outline by <a href="../authors.html#mgunderloy">Mike Gun
 <div class="para"><p>activerecord/lib/active_record/attribute_methods.rb
 9:      base.cattr_accessor :attribute_types_cached_by_default, :instance_writer &#8658; false
 11:      base.cattr_accessor :time_zone_aware_attributes, :instance_writer &#8658; false</p></div>
-<div class="para"><p>activerecord/lib/active_record/base.rb
-394:    cattr_accessor :logger, :instance_writer &#8658; false
-443:    cattr_accessor :configurations, :instance_writer &#8658; false
-450:    cattr_accessor :primary_key_prefix_type, :instance_writer &#8658; false
-456:    cattr_accessor :table_name_prefix, :instance_writer &#8658; false
-461:    cattr_accessor :table_name_suffix, :instance_writer &#8658; false
-467:    cattr_accessor :pluralize_table_names, :instance_writer &#8658; false
-473:    cattr_accessor :colorize_logging, :instance_writer &#8658; false
-478:    cattr_accessor :default_timezone, :instance_writer &#8658; false
-487:    cattr_accessor :schema_format , :instance_writer &#8658; false
-491:    cattr_accessor :timestamped_migrations , :instance_writer &#8658; false</p></div>
-<div class="para"><p>activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb
-11:    cattr_accessor :connection_handler, :instance_writer &#8658; false</p></div>
-<div class="para"><p>activerecord/lib/active_record/connection_adapters/mysql_adapter.rb
-166:      cattr_accessor :emulate_booleans</p></div>
-<div class="para"><p>activerecord/lib/active_record/fixtures.rb
-498:  cattr_accessor :all_loaded_fixtures</p></div>
-<div class="para"><p>activerecord/lib/active_record/locking/optimistic.rb
-38:        base.cattr_accessor :lock_optimistically, :instance_writer &#8658; false</p></div>
-<div class="para"><p>activerecord/lib/active_record/migration.rb
-259:    cattr_accessor :verbose</p></div>
-<div class="para"><p>activerecord/lib/active_record/schema_dumper.rb
-13:    cattr_accessor :ignore_tables</p></div>
-<div class="para"><p>activerecord/lib/active_record/serializers/json_serializer.rb
-4:      base.cattr_accessor :include_root_in_json, :instance_writer &#8658; false</p></div>
-<div class="para"><p>activerecord/Rakefile
-142:  rdoc.options &lt;&lt; <em>&#8212;line-numbers</em> &lt;&lt; <em>&#8212;inline-source</em> &lt;&lt; <em>-A cattr_accessor=object</em></p></div>
-<div class="para"><p>activerecord/test/cases/lifecycle_test.rb
-61:  cattr_reader :last_inherited</p></div>
-<div class="para"><p>activerecord/test/cases/mixin_test.rb
-9:  cattr_accessor :forced_now_time</p></div>
 <div class="para"><p>activeresource/lib/active_resource/base.rb
 206:    cattr_accessor :logger</p></div>
 <div class="para"><p>activeresource/Rakefile
@@ -430,6 +460,13 @@ November 5, 2008: Rough outline by <a href="../authors.html#mgunderloy">Mike Gun
 12:    cattr_accessor :local_request</p></div>
 <div class="para"><p>Rakefile
 32:  rdoc.options &lt;&lt; <em>-A cattr_accessor=object</em></p></div>
+<div class="qlist"><ol>
+<li>
+<p><em>
+need to look for def self. ?
+</em></p>
+</li>
+</ol></div>
 </div>
 
 		</div>
diff --git a/railties/doc/guides/html/creating_plugins.html b/railties/doc/guides/html/creating_plugins.html
index 375d216b4a..45c81f2af1 100644
--- a/railties/doc/guides/html/creating_plugins.html
+++ b/railties/doc/guides/html/creating_plugins.html
@@ -199,14 +199,18 @@ ul#navMain {
 			<h2>Chapters</h2>
 			<ol>
 					<li>
-					<a href="#_preparation">Preparation</a>
+					<a href="#_setup">Setup</a>
 						<ul>
 						
 							<li><a href="#_create_the_basic_app">Create the basic app</a></li>
 						
 							<li><a href="#_generate_the_plugin_skeleton">Generate the plugin skeleton</a></li>
 						
-							<li><a href="#_setup_the_plugin_for_testing">Setup the plugin for testing</a></li>
+						</ul>
+					</li>
+					<li>
+					<a href="#_tests">Tests</a>
+						<ul>
 						
 							<li><a href="#_run_the_plugin_tests">Run the plugin tests</a></li>
 						
@@ -225,7 +229,7 @@ ul#navMain {
 						</ul>
 					</li>
 					<li>
-					<a href="#_add_an_tt_acts_as_yaffle_tt_method_to_active_record">Add an <tt>acts_as_yaffle</tt> method to Active Record</a>
+					<a href="#_add_an_em_acts_as_em_method_to_active_record">Add an <em>acts_as</em> method to Active Record</a>
 						<ul>
 						
 							<li><a href="#_add_a_class_method">Add a class method</a></li>
@@ -235,33 +239,42 @@ ul#navMain {
 						</ul>
 					</li>
 					<li>
-					<a href="#_create_a_generator">Create a generator</a>
+					<a href="#_models">Models</a>
+					</li>
+					<li>
+					<a href="#_controllers">Controllers</a>
+					</li>
+					<li>
+					<a href="#_helpers">Helpers</a>
+					</li>
+					<li>
+					<a href="#_routes">Routes</a>
+					</li>
+					<li>
+					<a href="#_generators">Generators</a>
 						<ul>
 						
 							<li><a href="#_testing_generators">Testing generators</a></li>
 						
-							<li><a href="#_adding_to_the_manifest">Adding to the manifest</a></li>
-						
-							<li><a href="#_manually_test_the_generator">Manually test the generator</a></li>
-						
 							<li><a href="#_the_usage_file">The USAGE file</a></li>
 						
 						</ul>
 					</li>
 					<li>
-					<a href="#_add_a_custom_generator_command">Add a custom generator command</a>
-					</li>
-					<li>
-					<a href="#_add_a_model">Add a model</a>
+					<a href="#_generator_commands">Generator Commands</a>
 					</li>
 					<li>
-					<a href="#_add_a_controller">Add a controller</a>
-					</li>
-					<li>
-					<a href="#_add_a_helper">Add a helper</a>
+					<a href="#_migrations">Migrations</a>
+						<ul>
+						
+							<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>
+						
+						</ul>
 					</li>
 					<li>
-					<a href="#_add_a_custom_route">Add a Custom Route</a>
+					<a href="#_generating_migrations">Generating migrations</a>
 					</li>
 					<li>
 					<a href="#_odds_and_ends">Odds and ends</a>
@@ -388,7 +401,7 @@ A custom route method that can be used in routes.rb
 <div class="para"><p>For the purpose of this guide pretend for a moment that you are an avid bird watcher.  Your favorite bird is the Yaffle, and you want to create a plugin that allows other developers to share in the Yaffle goodness.  First, you need to get setup for development.</p></div>
 </div>
 </div>
-<h2 id="_preparation">1. Preparation</h2>
+<h2 id="_setup">1. Setup</h2>
 <div class="sectionbody">
 <h3 id="_create_the_basic_app">1.1. Create the basic app</h3>
 <div class="para"><p>The examples in this guide require that you have a working rails application.  To create a simple rails app execute:</p></div>
@@ -448,7 +461,9 @@ create  vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb
 create  vendor/plugins/yaffle/generators/yaffle/USAGE</tt></pre>
 </div></div>
 <div class="para"><p>To begin just change one thing - move <em>init.rb</em> to <em>rails/init.rb</em>.</p></div>
-<h3 id="_setup_the_plugin_for_testing">1.3. Setup the plugin for testing</h3>
+</div>
+<h2 id="_tests">2. Tests</h2>
+<div class="sectionbody">
 <div class="para"><p>If your plugin interacts with a database, you'll need to setup a database connection.  In this guide you will learn how to test your plugin against multiple different database adapters using Active Record.  This guide will not cover how to use fixtures in plugin tests.</p></div>
 <div class="para"><p>To setup your plugin to allow for easy testing you'll need to add 3 files:</p></div>
 <div class="ilist"><ul>
@@ -558,7 +573,7 @@ ENV<span style="color: #990000">[</span><span style="color: #FF0000">'RAILS_ROOT
 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
 </tt></pre></div></div>
 <div class="para"><p>Now whenever you write a test that requires the database, you can call <em>load_schema</em>.</p></div>
-<h3 id="_run_the_plugin_tests">1.4. Run the plugin tests</h3>
+<h3 id="_run_the_plugin_tests">2.1. Run the plugin tests</h3>
 <div class="para"><p>Once you have these files in place, you can write your first test to ensure that your plugin-testing setup is correct.  By default rails generates a file in <em>vendor/plugins/yaffle/test/yaffle_test.rb</em> with a sample test.  Replace the contents of that file with:</p></div>
 <div class="para"><p><strong>vendor/plugins/yaffle/test/yaffle_test.rb:</strong></p></div>
 <div class="listingblock">
@@ -619,7 +634,7 @@ rake DB=postgresql</tt></pre>
 </div></div>
 <div class="para"><p>Now you are ready to test-drive your plugin!</p></div>
 </div>
-<h2 id="_extending_core_classes">2. Extending core classes</h2>
+<h2 id="_extending_core_classes">3. Extending core classes</h2>
 <div class="sectionbody">
 <div class="para"><p>This section will explain how to add a method to String that will be available anywhere in your rails app by:</p></div>
 <div class="ilist"><ul>
@@ -634,7 +649,7 @@ Creating and requiring the correct files
 </p>
 </li>
 </ul></div>
-<h3 id="_creating_the_test">2.1. Creating the test</h3>
+<h3 id="_creating_the_test">3.1. Creating the test</h3>
 <div class="para"><p>In this example you will add a method to String named <tt>to_squawk</tt>.  To begin, create a new test file with a few assertions:</p></div>
 <div class="para"><p><strong>vendor/plugins/yaffle/test/core_ext_test.rb</strong></p></div>
 <div class="listingblock">
@@ -665,7 +680,7 @@ NoMethodError: undefined method `to_squawk' for "Hello World":String
     ./test/core_ext_test.rb:5:in `test_to_squawk_prepends_the_word_squawk'</tt></pre>
 </div></div>
 <div class="para"><p>Great - now you are ready to start development.</p></div>
-<h3 id="_organize_your_files">2.2. Organize your files</h3>
+<h3 id="_organize_your_files">3.2. Organize your files</h3>
 <div class="para"><p>A common pattern in rails plugins is to set up the file structure like this:</p></div>
 <div class="listingblock">
 <div class="content">
@@ -712,7 +727,7 @@ http://www.gnu.org/software/src-highlite -->
 &gt;&gt; "Hello World".to_squawk
 =&gt; "squawk! Hello World"</tt></pre>
 </div></div>
-<h3 id="_working_with_init_rb">2.3. Working with init.rb</h3>
+<h3 id="_working_with_init_rb">3.3. Working with init.rb</h3>
 <div class="para"><p>When rails loads plugins it looks for the file named init.rb.  However, when the plugin is initialized, <em>init.rb</em> is invoked via <tt>eval</tt> (not <tt>require</tt>) so it has slightly different behavior.</p></div>
 <div class="para"><p>Under certain circumstances if you reopen classes or modules in <em>init.rb</em> you may inadvertently create a new class, rather than reopening an existing class.  A better alternative is to reopen the class in a different file, and require that file from <tt>init.rb</tt>, as shown above.</p></div>
 <div class="para"><p>If you must reopen a class in <tt>init.rb</tt> you can use <tt>module_eval</tt> or <tt>class_eval</tt> to avoid any issues:</p></div>
@@ -742,7 +757,7 @@ 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="_add_an_tt_acts_as_yaffle_tt_method_to_active_record">3. Add an <tt>acts_as_yaffle</tt> method to Active Record</h2>
+<h2 id="_add_an_em_acts_as_em_method_to_active_record">4. Add an <em>acts_as</em> method to Active Record</h2>
 <div class="sectionbody">
 <div class="para"><p>A common pattern in plugins is to add a method called <em>acts_as_something</em> to models.  In this case, you want to write a method called <em>acts_as_yaffle</em> that adds a <em>squawk</em> method to your models.</p></div>
 <div class="para"><p>To begin, set up your files so that you have:</p></div>
@@ -801,7 +816,7 @@ http://www.gnu.org/software/src-highlite -->
 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
 </tt></pre></div></div>
 <div class="para"><p>With structure you can easily separate the methods that will be used for the class (like <tt>Hickwall.some_method</tt>) and the instance (like <tt>@hickwell.some_method</tt>).</p></div>
-<h3 id="_add_a_class_method">3.1. Add a class method</h3>
+<h3 id="_add_a_class_method">4.1. Add a class method</h3>
 <div class="para"><p>This plugin will expect that you've added a method to your model named <em>last_squawk</em>.  However, the plugin users might have already defined a method on their model named <em>last_squawk</em> that they use for something else.  This plugin will allow the name to be changed by adding a class method called <em>yaffle_text_field</em>.</p></div>
 <div class="para"><p>To start out, write a failing test that shows the behavior you'd like:</p></div>
 <div class="para"><p><strong>vendor/plugins/yaffle/test/acts_as_yaffle_test.rb</strong></p></div>
@@ -854,7 +869,7 @@ http://www.gnu.org/software/src-highlite -->
 
 ActiveRecord<span style="color: #990000">::</span>Base<span style="color: #990000">.</span>send <span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">include</span></span><span style="color: #990000">,</span> Yaffle
 </tt></pre></div></div>
-<h3 id="_add_an_instance_method">3.2. Add an instance method</h3>
+<h3 id="_add_an_instance_method">4.2. Add an instance method</h3>
 <div class="para"><p>This plugin will add a method named <em>squawk</em> to any Active Record objects that call <em>acts_as_yaffle</em>.  The <em>squawk</em> method will simply set the value of one of the fields in the database.</p></div>
 <div class="para"><p>To start out, write a failing test that shows the behavior you'd like:</p></div>
 <div class="para"><p><strong>vendor/plugins/yaffle/test/acts_as_yaffle_test.rb</strong></p></div>
@@ -936,267 +951,7 @@ ActiveRecord<span style="color: #990000">::</span>Base<span style="color: #99000
 </tr></table>
 </div>
 </div>
-<h2 id="_create_a_generator">4. Create a generator</h2>
-<div class="sectionbody">
-<div class="para"><p>Many plugins ship with generators.  When you created the plugin above, you specified the &#8212;with-generator option, so you already have the generator stubs in <em>vendor/plugins/yaffle/generators/yaffle</em>.</p></div>
-<div class="para"><p>Building generators is a complex topic unto itself and this section will cover one small aspect of generators:  creating a generator that adds a time-stamped migration.</p></div>
-<div class="para"><p>To create a generator you must:</p></div>
-<div class="ilist"><ul>
-<li>
-<p>
-Add your instructions to the <em>manifest</em> method of the generator
-</p>
-</li>
-<li>
-<p>
-Add any necessary template files to the templates directory
-</p>
-</li>
-<li>
-<p>
-Test the generator manually by running various combinations of <tt>script/generate</tt> and <tt>script/destroy</tt>
-</p>
-</li>
-<li>
-<p>
-Update the USAGE file to add helpful documentation for your generator
-</p>
-</li>
-</ul></div>
-<h3 id="_testing_generators">4.1. Testing generators</h3>
-<div class="para"><p>Many rails plugin authors do not test their generators, however testing generators is quite simple.  A typical generator test does the following:</p></div>
-<div class="ilist"><ul>
-<li>
-<p>
-Creates a new fake rails root directory that will serve as destination
-</p>
-</li>
-<li>
-<p>
-Runs the generator forward and backward, making whatever assertions are necessary
-</p>
-</li>
-<li>
-<p>
-Removes the fake rails root
-</p>
-</li>
-</ul></div>
-<div class="para"><p>For the generator in this section, the test could look something like this:</p></div>
-<div class="para"><p><strong>vendor/plugins/yaffle/test/yaffle_generator_test.rb</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><span style="font-weight: bold"><span style="color: #000080">require</span></span> File<span style="color: #990000">.</span>dirname<span style="color: #990000">(</span><span style="font-weight: bold"><span style="color: #0000FF">__FILE__</span></span><span style="color: #990000">)</span> <span style="color: #990000">+</span> <span style="color: #FF0000">'/test_helper.rb'</span>
-<span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">'rails_generator'</span>
-<span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">'rails_generator/scripts/generate'</span>
-<span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">'rails_generator/scripts/destroy'</span>
-
-<span style="font-weight: bold"><span style="color: #0000FF">class</span></span> GeneratorTest <span style="color: #990000">&lt;</span> Test<span style="color: #990000">::</span>Unit<span style="color: #990000">::</span>TestCase
-
-  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> fake_rails_root
-    File<span style="color: #990000">.</span>join<span style="color: #990000">(</span>File<span style="color: #990000">.</span>dirname<span style="color: #990000">(</span><span style="font-weight: bold"><span style="color: #0000FF">__FILE__</span></span><span style="color: #990000">),</span> <span style="color: #FF0000">'rails_root'</span><span style="color: #990000">)</span>
-  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-
-  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> file_list
-    Dir<span style="color: #990000">.</span>glob<span style="color: #990000">(</span>File<span style="color: #990000">.</span>join<span style="color: #990000">(</span>fake_rails_root<span style="color: #990000">,</span> <span style="color: #FF0000">"db"</span><span style="color: #990000">,</span> <span style="color: #FF0000">"migrate"</span><span style="color: #990000">,</span> <span style="color: #FF0000">"*"</span><span style="color: #990000">))</span>
-  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-
-  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> setup
-    FileUtils<span style="color: #990000">.</span>mkdir_p<span style="color: #990000">(</span>fake_rails_root<span style="color: #990000">)</span>
-    <span style="color: #009900">@original_files</span> <span style="color: #990000">=</span> file_list
-  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-
-  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> teardown
-    FileUtils<span style="color: #990000">.</span>rm_r<span style="color: #990000">(</span>fake_rails_root<span style="color: #990000">)</span>
-  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-
-  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> test_generates_correct_file_name
-    Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Scripts<span style="color: #990000">::</span>Generate<span style="color: #990000">.</span>new<span style="color: #990000">.</span>run<span style="color: #990000">([</span><span style="color: #FF0000">"yaffle"</span><span style="color: #990000">,</span> <span style="color: #FF0000">"bird"</span><span style="color: #990000">],</span> <span style="color: #990000">:</span>destination <span style="color: #990000">=&gt;</span> fake_rails_root<span style="color: #990000">)</span>
-    new_file <span style="color: #990000">=</span> <span style="color: #990000">(</span>file_list <span style="color: #990000">-</span> <span style="color: #009900">@original_files</span><span style="color: #990000">).</span>first
-    assert_match <span style="color: #FF6600">/add_yaffle_fields_to_bird/</span><span style="color: #990000">,</span> new_file
-  <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>
-<div class="para"><p>You can run <em>rake</em> from the plugin directory to see this fail.  Unless you are doing more advanced generator commands it typically suffices to just test the Generate script, and trust that rails will handle the Destroy and Update commands for you.</p></div>
-<h3 id="_adding_to_the_manifest">4.2. Adding to the manifest</h3>
-<div class="para"><p>This example will demonstrate how to use one of the built-in generator methods named <em>migration_template</em> to create a migration file.  To start, update your generator file to look like this:</p></div>
-<div class="para"><p><strong>vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb</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><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> YaffleGenerator <span style="color: #990000">&lt;</span> Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>NamedBase
-  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> manifest
-    record <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>m<span style="color: #990000">|</span>
-      m<span style="color: #990000">.</span>migration_template <span style="color: #FF0000">'migration:migration.rb'</span><span style="color: #990000">,</span> <span style="color: #FF0000">"db/migrate"</span><span style="color: #990000">,</span> <span style="color: #FF0000">{</span><span style="color: #990000">:</span>assigns <span style="color: #990000">=&gt;</span> yaffle_local_assigns<span style="color: #990000">,</span>
-        <span style="color: #990000">:</span>migration_file_name <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"add_yaffle_fields_to_#{custom_file_name}"</span>
-      <span style="color: #FF0000">}</span>
-    <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-
-  private
-    <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> custom_file_name
-      custom_name <span style="color: #990000">=</span> class_name<span style="color: #990000">.</span>underscore<span style="color: #990000">.</span>downcase
-      custom_name <span style="color: #990000">=</span> custom_name<span style="color: #990000">.</span>pluralize <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> ActiveRecord<span style="color: #990000">::</span>Base<span style="color: #990000">.</span>pluralize_table_names
-    <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-
-    <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> yaffle_local_assigns
-      returning<span style="color: #990000">(</span>assigns <span style="color: #990000">=</span> <span style="color: #FF0000">{}</span><span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">do</span></span>
-        assigns<span style="color: #990000">[:</span>migration_action<span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"add"</span>
-        assigns<span style="color: #990000">[:</span>class_name<span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"add_yaffle_fields_to_#{custom_file_name}"</span>
-        assigns<span style="color: #990000">[:</span>table_name<span style="color: #990000">]</span> <span style="color: #990000">=</span> custom_file_name
-        assigns<span style="color: #990000">[:</span>attributes<span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="color: #990000">[</span>Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>GeneratedAttribute<span style="color: #990000">.</span>new<span style="color: #990000">(</span><span style="color: #FF0000">"last_squawk"</span><span style="color: #990000">,</span> <span style="color: #FF0000">"string"</span><span style="color: #990000">)]</span>
-      <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-    <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>
-<div class="para"><p>The generator creates a new file in <em>db/migrate</em> with a timestamp and an <em>add_column</em> statement.  It reuses the built in rails <tt>migration_template</tt> method, and reuses the built-in rails migration template.</p></div>
-<div class="para"><p>It's courteous to check to see if table names are being pluralized whenever you create a generator that needs to be aware of table names.  This way people using your generator won't have to manually change the generated files if they've turned pluralization off.</p></div>
-<h3 id="_manually_test_the_generator">4.3. Manually test the generator</h3>
-<div class="para"><p>To run the generator, type the following at the command line:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><tt>./script/generate yaffle bird</tt></pre>
-</div></div>
-<div class="para"><p>and you will see a new file:</p></div>
-<div class="para"><p><strong>db/migrate/20080529225649_add_yaffle_fields_to_birds.rb</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><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> AddYaffleFieldsToBirds <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Migration
-  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>up
-    add_column <span style="color: #990000">:</span>birds<span style="color: #990000">,</span> <span style="color: #990000">:</span>last_squawk<span style="color: #990000">,</span> <span style="color: #990000">:</span>string
-  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-
-  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>down
-    remove_column <span style="color: #990000">:</span>birds<span style="color: #990000">,</span> <span style="color: #990000">:</span>last_squawk
-  <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="_the_usage_file">4.4. The USAGE file</h3>
-<div class="para"><p>Rails ships with several built-in generators.  You can see all of the generators available to you by typing the following at the command line:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><tt>script/generate</tt></pre>
-</div></div>
-<div class="para"><p>You should see something like this:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><tt>Installed Generators
-  Plugins (vendor/plugins): yaffle
-  Builtin: controller, integration_test, mailer, migration, model, observer, plugin, resource, scaffold, session_migration</tt></pre>
-</div></div>
-<div class="para"><p>When you run <tt>script/generate yaffle</tt> you should see the contents of your <em>vendor/plugins/yaffle/generators/yaffle/USAGE</em> file.</p></div>
-<div class="para"><p>For this plugin, update the USAGE file looks like this:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><tt>Description:
-    Creates a migration that adds yaffle squawk fields to the given model
-
-Example:
-    ./script/generate yaffle hickwall
-
-    This will create:
-        db/migrate/TIMESTAMP_add_yaffle_fields_to_hickwall</tt></pre>
-</div></div>
-</div>
-<h2 id="_add_a_custom_generator_command">5. Add a custom generator command</h2>
-<div class="sectionbody">
-<div class="para"><p>You may have noticed above that you can used one of the built-in rails migration commands <tt>migration_template</tt>.  If your plugin needs to add and remove lines of text from existing files you will need to write your own generator methods.</p></div>
-<div class="para"><p>This section describes how you you can create your own commands to add and remove a line of text from <em>routes.rb</em>.  This example creates a very simple method that adds or removes a text file.</p></div>
-<div class="para"><p>To start, add the following test method:</p></div>
-<div class="para"><p><strong>vendor/plugins/yaffle/test/generator_test.rb</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><span style="font-weight: bold"><span style="color: #0000FF">def</span></span> test_generates_definition
-  Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Scripts<span style="color: #990000">::</span>Generate<span style="color: #990000">.</span>new<span style="color: #990000">.</span>run<span style="color: #990000">([</span><span style="color: #FF0000">"yaffle"</span><span style="color: #990000">,</span> <span style="color: #FF0000">"bird"</span><span style="color: #990000">],</span> <span style="color: #990000">:</span>destination <span style="color: #990000">=&gt;</span> fake_rails_root<span style="color: #990000">)</span>
-  definition <span style="color: #990000">=</span> File<span style="color: #990000">.</span>read<span style="color: #990000">(</span>File<span style="color: #990000">.</span>join<span style="color: #990000">(</span>fake_rails_root<span style="color: #990000">,</span> <span style="color: #FF0000">"definition.txt"</span><span style="color: #990000">))</span>
-  assert_match <span style="color: #FF6600">/Yaffle\:/</span><span style="color: #990000">,</span> definition
-<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-</tt></pre></div></div>
-<div class="para"><p>Run <tt>rake</tt> to watch the test fail, then make the test pass add the following:</p></div>
-<div class="para"><p><strong>vendor/plugins/yaffle/generators/yaffle/templates/definition.txt</strong></p></div>
-<div class="listingblock">
-<div class="content">
-<pre><tt>Yaffle: A bird</tt></pre>
-</div></div>
-<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
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">"yaffle/commands"</span>
-</tt></pre></div></div>
-<div class="para"><p><strong>vendor/plugins/yaffle/lib/commands.rb</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><span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">'rails_generator'</span>
-<span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">'rails_generator/commands'</span>
-
-<span style="font-weight: bold"><span style="color: #0000FF">module</span></span> Yaffle <span style="font-style: italic"><span style="color: #9A1900">#:nodoc:</span></span>
-  <span style="font-weight: bold"><span style="color: #0000FF">module</span></span> Generator <span style="font-style: italic"><span style="color: #9A1900">#:nodoc:</span></span>
-    <span style="font-weight: bold"><span style="color: #0000FF">module</span></span> Commands <span style="font-style: italic"><span style="color: #9A1900">#:nodoc:</span></span>
-      <span style="font-weight: bold"><span style="color: #0000FF">module</span></span> Create
-        <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> yaffle_definition
-          file<span style="color: #990000">(</span><span style="color: #FF0000">"definition.txt"</span><span style="color: #990000">,</span> <span style="color: #FF0000">"definition.txt"</span><span style="color: #990000">)</span>
-        <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-      <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-
-      <span style="font-weight: bold"><span style="color: #0000FF">module</span></span> Destroy
-        <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> yaffle_definition
-          file<span style="color: #990000">(</span><span style="color: #FF0000">"definition.txt"</span><span style="color: #990000">,</span> <span style="color: #FF0000">"definition.txt"</span><span style="color: #990000">)</span>
-        <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-      <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-
-      <span style="font-weight: bold"><span style="color: #0000FF">module</span></span> List
-        <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> yaffle_definition
-          file<span style="color: #990000">(</span><span style="color: #FF0000">"definition.txt"</span><span style="color: #990000">,</span> <span style="color: #FF0000">"definition.txt"</span><span style="color: #990000">)</span>
-        <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-      <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-
-      <span style="font-weight: bold"><span style="color: #0000FF">module</span></span> Update
-        <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> yaffle_definition
-          file<span style="color: #990000">(</span><span style="color: #FF0000">"definition.txt"</span><span style="color: #990000">,</span> <span style="color: #FF0000">"definition.txt"</span><span style="color: #990000">)</span>
-        <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-      <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-    <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-
-Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Commands<span style="color: #990000">::</span>Create<span style="color: #990000">.</span>send   <span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">include</span></span><span style="color: #990000">,</span>  Yaffle<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Commands<span style="color: #990000">::</span>Create
-Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Commands<span style="color: #990000">::</span>Destroy<span style="color: #990000">.</span>send  <span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">include</span></span><span style="color: #990000">,</span>  Yaffle<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Commands<span style="color: #990000">::</span>Destroy
-Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Commands<span style="color: #990000">::</span>List<span style="color: #990000">.</span>send     <span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">include</span></span><span style="color: #990000">,</span>  Yaffle<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Commands<span style="color: #990000">::</span>List
-Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Commands<span style="color: #990000">::</span>Update<span style="color: #990000">.</span>send   <span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">include</span></span><span style="color: #990000">,</span>  Yaffle<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Commands<span style="color: #990000">::</span>Update
-</tt></pre></div></div>
-<div class="para"><p>Finally, call your new method in the manifest:</p></div>
-<div class="para"><p><strong>vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb</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><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> YaffleGenerator <span style="color: #990000">&lt;</span> Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>NamedBase
-  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> manifest
-    m<span style="color: #990000">.</span>yaffle_definition
-  <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>
-</div>
-<h2 id="_add_a_model">6. Add a model</h2>
+<h2 id="_models">5. Models</h2>
 <div class="sectionbody">
 <div class="para"><p>This section describes how to add a model named <em>Woodpecker</em> to your plugin that will behave the same as a model in your main app.  When storing models, controllers, views and helpers in your plugin, it's customary to keep them in directories that match the rails directories.  For this example, create a file structure like this:</p></div>
 <div class="listingblock">
@@ -1271,7 +1026,7 @@ http://www.gnu.org/software/src-highlite -->
 </tt></pre></div></div>
 <div class="para"><p>Now your test should be passing, and you should be able to use the Woodpecker model from within your rails app, and any changes made to it are reflected immediately when running in development mode.</p></div>
 </div>
-<h2 id="_add_a_controller">7. Add a controller</h2>
+<h2 id="_controllers">6. Controllers</h2>
 <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>
@@ -1330,7 +1085,7 @@ http://www.gnu.org/software/src-highlite -->
 </tt></pre></div></div>
 <div class="para"><p>Now your test should be passing, and you should be able to use the Woodpeckers controller in your app.  If you add a route for the woodpeckers controller you can start up your server and go to <a href="http://localhost:3000/woodpeckers">http://localhost:3000/woodpeckers</a> to see your controller in action.</p></div>
 </div>
-<h2 id="_add_a_helper">8. Add a helper</h2>
+<h2 id="_helpers">7. Helpers</h2>
 <div class="sectionbody">
 <div class="para"><p>This section describes how to add a helper named <em>WoodpeckersHelper</em> to your plugin that will behave the same as a helper in your main app.  This is very similar to adding a model and a controller.</p></div>
 <div class="para"><p>You can test your plugin's helper as you would test any other helper:</p></div>
@@ -1381,7 +1136,7 @@ http://www.gnu.org/software/src-highlite -->
 </tt></pre></div></div>
 <div class="para"><p>Now your test should be passing, and you should be able to use the Woodpeckers helper in your app.</p></div>
 </div>
-<h2 id="_add_a_custom_route">9. Add a Custom Route</h2>
+<h2 id="_routes">8. Routes</h2>
 <div class="sectionbody">
 <div class="para"><p>Testing routes in plugins can be complex, especially if the controllers are also in the plugin itself.  Jamis Buck showed a great example of this in <a href="http://weblog.jamisbuck.org/2006/10/26/monkey-patching-rails-extending-routes-2">http://weblog.jamisbuck.org/2006/10/26/monkey-patching-rails-extending-routes-2</a>.</p></div>
 <div class="para"><p><strong>vendor/plugins/yaffle/test/routing_test.rb</strong></p></div>
@@ -1454,41 +1209,541 @@ http://www.gnu.org/software/src-highlite -->
 </tt></pre></div></div>
 <div class="para"><p>You can also see if your routes work by running <tt>rake routes</tt> from your app directory.</p></div>
 </div>
-<h2 id="_odds_and_ends">10. Odds and ends</h2>
+<h2 id="_generators">9. Generators</h2>
 <div class="sectionbody">
-<h3 id="_generate_rdoc_documentation">10.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="para"><p>Many plugins ship with generators.  When you created the plugin above, you specified the &#8212;with-generator option, so you already have the generator stubs in <em>vendor/plugins/yaffle/generators/yaffle</em>.</p></div>
+<div class="para"><p>Building generators is a complex topic unto itself and this section will cover one small aspect of generators:  creating a generator that adds a time-stamped migration.</p></div>
+<div class="para"><p>To add a generator to a plugin:</p></div>
 <div class="ilist"><ul>
 <li>
 <p>
-Your name.
+Write a test
 </p>
 </li>
 <li>
 <p>
-How to install.
+Add your instructions to the <em>manifest</em> method of the generator
 </p>
 </li>
 <li>
 <p>
-How to add the functionality to the app (several examples of common use cases).
+Add any necessary template files to the templates directory
 </p>
 </li>
 <li>
 <p>
-Warning, gotchas or tips that might help save users time.
+Update the USAGE file to add helpful documentation for your generator
 </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">
+<h3 id="_testing_generators">9.1. Testing generators</h3>
+<div class="para"><p>Many rails plugin authors do not test their generators, however testing generators is quite simple.  A typical generator test does the following:</p></div>
+<div class="ilist"><ul>
+<li>
+<p>
+Creates a new fake rails root directory that will serve as destination
+</p>
+</li>
+<li>
+<p>
+Runs the generator
+</p>
+</li>
+<li>
+<p>
+Asserts that the correct files were generated
+</p>
+</li>
+<li>
+<p>
+Removes the fake rails root
+</p>
+</li>
+</ul></div>
+<div class="para"><p>This section will describe how to create a simple generator that adds a file.  For the generator in this section, the test could look something like this:</p></div>
+<div class="para"><p><strong>vendor/plugins/yaffle/test/definition_generator_test.rb</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><span style="font-weight: bold"><span style="color: #000080">require</span></span> File<span style="color: #990000">.</span>dirname<span style="color: #990000">(</span><span style="font-weight: bold"><span style="color: #0000FF">__FILE__</span></span><span style="color: #990000">)</span> <span style="color: #990000">+</span> <span style="color: #FF0000">'/test_helper.rb'</span>
+<span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">'rails_generator'</span>
+<span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">'rails_generator/scripts/generate'</span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">class</span></span> DefinitionGeneratorTest <span style="color: #990000">&lt;</span> Test<span style="color: #990000">::</span>Unit<span style="color: #990000">::</span>TestCase
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> fake_rails_root
+    File<span style="color: #990000">.</span>join<span style="color: #990000">(</span>File<span style="color: #990000">.</span>dirname<span style="color: #990000">(</span><span style="font-weight: bold"><span style="color: #0000FF">__FILE__</span></span><span style="color: #990000">),</span> <span style="color: #FF0000">'rails_root'</span><span style="color: #990000">)</span>
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> file_list
+    Dir<span style="color: #990000">.</span>glob<span style="color: #990000">(</span>File<span style="color: #990000">.</span>join<span style="color: #990000">(</span>fake_rails_root<span style="color: #990000">,</span> <span style="color: #FF0000">"*"</span><span style="color: #990000">))</span>
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> setup
+    FileUtils<span style="color: #990000">.</span>mkdir_p<span style="color: #990000">(</span>fake_rails_root<span style="color: #990000">)</span>
+    <span style="color: #009900">@original_files</span> <span style="color: #990000">=</span> file_list
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> teardown
+    FileUtils<span style="color: #990000">.</span>rm_r<span style="color: #990000">(</span>fake_rails_root<span style="color: #990000">)</span>
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> test_generates_correct_file_name
+    Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Scripts<span style="color: #990000">::</span>Generate<span style="color: #990000">.</span>new<span style="color: #990000">.</span>run<span style="color: #990000">([</span><span style="color: #FF0000">"yaffle_definition"</span><span style="color: #990000">],</span> <span style="color: #990000">:</span>destination <span style="color: #990000">=&gt;</span> fake_rails_root<span style="color: #990000">)</span>
+    new_file <span style="color: #990000">=</span> <span style="color: #990000">(</span>file_list <span style="color: #990000">-</span> <span style="color: #009900">@original_files</span><span style="color: #990000">).</span>first
+    assert_equal <span style="color: #FF0000">"definition.txt"</span><span style="color: #990000">,</span> File<span style="color: #990000">.</span>basename<span style="color: #990000">(</span>new_file<span style="color: #990000">)</span>
+  <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>
+<div class="para"><p>You can run <em>rake</em> from the plugin directory to see this fail.  Unless you are doing more advanced generator commands it typically suffices to just test the Generate script, and trust that rails will handle the Destroy and Update commands for you.</p></div>
+<div class="para"><p>To make it pass, create the generator:</p></div>
+<div class="para"><p><strong>vendor/plugins/yaffle/generators/yaffle_definition/yaffle_definition_generator.rb</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><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> YaffleDefinitionGenerator <span style="color: #990000">&lt;</span> Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Base
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> manifest
+    record <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>m<span style="color: #990000">|</span>
+      m<span style="color: #990000">.</span>file <span style="color: #FF0000">"definition.txt"</span><span style="color: #990000">,</span> <span style="color: #FF0000">"definition.txt"</span>
+    <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+  <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="_the_usage_file">9.2. The USAGE file</h3>
+<div class="para"><p>If you plan to distribute your plugin, developers will expect at least a minimum of documentation.  You can add simple documentation to the generator by updating the USAGE file.</p></div>
+<div class="para"><p>Rails ships with several built-in generators.  You can see all of the generators available to you by typing the following at the command line:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>./script/generate</tt></pre>
+</div></div>
+<div class="para"><p>You should see something like this:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>Installed Generators
+  Plugins (vendor/plugins): yaffle_definition
+  Builtin: controller, integration_test, mailer, migration, model, observer, plugin, resource, scaffold, session_migration</tt></pre>
+</div></div>
+<div class="para"><p>When you run <tt>script/generate yaffle_definition -h</tt> you should see the contents of your <em>vendor/plugins/yaffle/generators/yaffle_definition/USAGE</em>.</p></div>
+<div class="para"><p>For this plugin, update the USAGE file could look like this:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>Description:
+    Adds a file with the definition of a Yaffle to the app's main directory</tt></pre>
+</div></div>
+</div>
+<h2 id="_generator_commands">10. Generator Commands</h2>
+<div class="sectionbody">
+<div class="para"><p>You may have noticed above that you can used one of the built-in rails migration commands <tt>migration_template</tt>.  If your plugin needs to add and remove lines of text from existing files you will need to write your own generator methods.</p></div>
+<div class="para"><p>This section describes how you you can create your own commands to add and remove a line of text from <em>config/routes.rb</em>.</p></div>
+<div class="para"><p>To start, add the following test method:</p></div>
+<div class="para"><p><strong>vendor/plugins/yaffle/test/route_generator_test.rb</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><span style="font-weight: bold"><span style="color: #000080">require</span></span> File<span style="color: #990000">.</span>dirname<span style="color: #990000">(</span><span style="font-weight: bold"><span style="color: #0000FF">__FILE__</span></span><span style="color: #990000">)</span> <span style="color: #990000">+</span> <span style="color: #FF0000">'/test_helper.rb'</span>
+<span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">'rails_generator'</span>
+<span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">'rails_generator/scripts/generate'</span>
+<span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">'rails_generator/scripts/destroy'</span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">class</span></span> RouteGeneratorTest <span style="color: #990000">&lt;</span> Test<span style="color: #990000">::</span>Unit<span style="color: #990000">::</span>TestCase
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> fake_rails_root
+    File<span style="color: #990000">.</span>join<span style="color: #990000">(</span>File<span style="color: #990000">.</span>dirname<span style="color: #990000">(</span><span style="font-weight: bold"><span style="color: #0000FF">__FILE__</span></span><span style="color: #990000">),</span> <span style="color: #FF0000">"rails_root"</span><span style="color: #990000">)</span>
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> routes_path
+    File<span style="color: #990000">.</span>join<span style="color: #990000">(</span>fake_rails_root<span style="color: #990000">,</span> <span style="color: #FF0000">"config"</span><span style="color: #990000">,</span> <span style="color: #FF0000">"routes.rb"</span><span style="color: #990000">)</span>
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> setup
+    FileUtils<span style="color: #990000">.</span>mkdir_p<span style="color: #990000">(</span>File<span style="color: #990000">.</span>join<span style="color: #990000">(</span>fake_rails_root<span style="color: #990000">,</span> <span style="color: #FF0000">"config"</span><span style="color: #990000">))</span>
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> teardown
+    FileUtils<span style="color: #990000">.</span>rm_r<span style="color: #990000">(</span>fake_rails_root<span style="color: #990000">)</span>
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> test_generates_route
+    content <span style="color: #990000">=</span> <span style="color: #990000">&lt;&lt;-</span><span style="font-weight: bold"><span style="color: #0000FF">END</span></span>
+      ActionController<span style="color: #990000">::</span>Routing<span style="color: #990000">::</span>Routes<span style="color: #990000">.</span>draw <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>map<span style="color: #990000">|</span>
+        map<span style="color: #990000">.</span>connect <span style="color: #FF0000">':controller/:action/:id'</span>
+        map<span style="color: #990000">.</span>connect <span style="color: #FF0000">':controller/:action/:id.:format'</span>
+      <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+    <span style="font-weight: bold"><span style="color: #0000FF">END</span></span>
+    File<span style="color: #990000">.</span>open<span style="color: #990000">(</span>routes_path<span style="color: #990000">,</span> <span style="color: #FF0000">'wb'</span><span style="color: #990000">)</span> <span style="color: #FF0000">{</span><span style="color: #990000">|</span>f<span style="color: #990000">|</span> f<span style="color: #990000">.</span>write<span style="color: #990000">(</span>content<span style="color: #990000">)</span> <span style="color: #FF0000">}</span>
+
+    Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Scripts<span style="color: #990000">::</span>Generate<span style="color: #990000">.</span>new<span style="color: #990000">.</span>run<span style="color: #990000">([</span><span style="color: #FF0000">"yaffle_route"</span><span style="color: #990000">],</span> <span style="color: #990000">:</span>destination <span style="color: #990000">=&gt;</span> fake_rails_root<span style="color: #990000">)</span>
+    assert_match <span style="color: #FF6600">/map\.yaffle/</span><span style="color: #990000">,</span> File<span style="color: #990000">.</span>read<span style="color: #990000">(</span>routes_path<span style="color: #990000">)</span>
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> test_destroys_route
+    content <span style="color: #990000">=</span> <span style="color: #990000">&lt;&lt;-</span><span style="font-weight: bold"><span style="color: #0000FF">END</span></span>
+      ActionController<span style="color: #990000">::</span>Routing<span style="color: #990000">::</span>Routes<span style="color: #990000">.</span>draw <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>map<span style="color: #990000">|</span>
+        map<span style="color: #990000">.</span>yaffle
+        map<span style="color: #990000">.</span>connect <span style="color: #FF0000">':controller/:action/:id'</span>
+        map<span style="color: #990000">.</span>connect <span style="color: #FF0000">':controller/:action/:id.:format'</span>
+      <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+    <span style="font-weight: bold"><span style="color: #0000FF">END</span></span>
+    File<span style="color: #990000">.</span>open<span style="color: #990000">(</span>routes_path<span style="color: #990000">,</span> <span style="color: #FF0000">'wb'</span><span style="color: #990000">)</span> <span style="color: #FF0000">{</span><span style="color: #990000">|</span>f<span style="color: #990000">|</span> f<span style="color: #990000">.</span>write<span style="color: #990000">(</span>content<span style="color: #990000">)</span> <span style="color: #FF0000">}</span>
+
+    Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Scripts<span style="color: #990000">::</span>Destroy<span style="color: #990000">.</span>new<span style="color: #990000">.</span>run<span style="color: #990000">([</span><span style="color: #FF0000">"yaffle_route"</span><span style="color: #990000">],</span> <span style="color: #990000">:</span>destination <span style="color: #990000">=&gt;</span> fake_rails_root<span style="color: #990000">)</span>
+    assert_no_match <span style="color: #FF6600">/map\.yaffle/</span><span style="color: #990000">,</span> File<span style="color: #990000">.</span>read<span style="color: #990000">(</span>routes_path<span style="color: #990000">)</span>
+  <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>
+<div class="para"><p>Run <tt>rake</tt> to watch the test fail, then make the test pass add the following:</p></div>
+<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
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">"yaffle/commands"</span>
+</tt></pre></div></div>
+<div class="para"><p><strong>vendor/plugins/yaffle/lib/yaffle/commands.rb</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><span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">'rails_generator'</span>
+<span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">'rails_generator/commands'</span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">module</span></span> Yaffle <span style="font-style: italic"><span style="color: #9A1900">#:nodoc:</span></span>
+  <span style="font-weight: bold"><span style="color: #0000FF">module</span></span> Generator <span style="font-style: italic"><span style="color: #9A1900">#:nodoc:</span></span>
+    <span style="font-weight: bold"><span style="color: #0000FF">module</span></span> Commands <span style="font-style: italic"><span style="color: #9A1900">#:nodoc:</span></span>
+      <span style="font-weight: bold"><span style="color: #0000FF">module</span></span> Create
+        <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> yaffle_route
+          logger<span style="color: #990000">.</span>route <span style="color: #FF0000">"map.yaffle"</span>
+          look_for <span style="color: #990000">=</span> <span style="color: #FF0000">'ActionController::Routing::Routes.draw do |map|'</span>
+          <span style="font-weight: bold"><span style="color: #0000FF">unless</span></span> options<span style="color: #990000">[:</span>pretend<span style="color: #990000">]</span>
+            gsub_file<span style="color: #990000">(</span><span style="color: #FF0000">'config/routes.rb'</span><span style="color: #990000">,</span> <span style="color: #FF6600">/(#{Regexp.escape(look_for)})/</span>mi<span style="color: #990000">)</span><span style="color: #FF0000">{</span><span style="color: #990000">|</span>match<span style="color: #990000">|</span> <span style="color: #FF0000">"#{match}\n  map.yaffle\n"</span><span style="color: #FF0000">}</span>
+          <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+        <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+      <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+      <span style="font-weight: bold"><span style="color: #0000FF">module</span></span> Destroy
+        <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> yaffle_route
+          logger<span style="color: #990000">.</span>route <span style="color: #FF0000">"map.yaffle"</span>
+          gsub_file <span style="color: #FF0000">'config/routes.rb'</span><span style="color: #990000">,</span> <span style="color: #FF6600">/\n.+?map\.yaffle/</span>mi<span style="color: #990000">,</span> <span style="color: #FF0000">''</span>
+        <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+      <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+      <span style="font-weight: bold"><span style="color: #0000FF">module</span></span> List
+        <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> yaffle_route
+        <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+      <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+      <span style="font-weight: bold"><span style="color: #0000FF">module</span></span> Update
+        <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> yaffle_route
+        <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+      <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+    <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Commands<span style="color: #990000">::</span>Create<span style="color: #990000">.</span>send   <span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">include</span></span><span style="color: #990000">,</span>  Yaffle<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Commands<span style="color: #990000">::</span>Create
+Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Commands<span style="color: #990000">::</span>Destroy<span style="color: #990000">.</span>send  <span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">include</span></span><span style="color: #990000">,</span>  Yaffle<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Commands<span style="color: #990000">::</span>Destroy
+Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Commands<span style="color: #990000">::</span>List<span style="color: #990000">.</span>send     <span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">include</span></span><span style="color: #990000">,</span>  Yaffle<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Commands<span style="color: #990000">::</span>List
+Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Commands<span style="color: #990000">::</span>Update<span style="color: #990000">.</span>send   <span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">include</span></span><span style="color: #990000">,</span>  Yaffle<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Commands<span style="color: #990000">::</span>Update
+</tt></pre></div></div>
+<div class="para"><p><strong>vendor/plugins/yaffle/generators/yaffle/yaffle_route_generator.rb</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><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> YaffleRouteGenerator <span style="color: #990000">&lt;</span> Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Base
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> manifest
+    record <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>m<span style="color: #990000">|</span>
+      m<span style="color: #990000">.</span>yaffle_route
+    <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+  <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>
+<div class="para"><p>To see this work, type:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>./script/generate yaffle_route
+./script/destroy yaffle_route</tt></pre>
+</div></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/note.png" alt="Note" />
+</td>
+<td class="content">If you haven't set up the custom route from above, <em>script/destroy</em> will fail and you'll have to remove it manually.</td>
+</tr></table>
+</div>
+</div>
+<h2 id="_migrations">11. Migrations</h2>
+<div class="sectionbody">
+<div class="para"><p>If your plugin requires changes to the app's database you will likely want to somehow add migrations.  Rails does not include any built-in support for calling migrations from plugins, but you can still make it easy for developers to call migrations from plugins.</p></div>
+<div class="para"><p>If you have a very simple needs, like creating a table that will always have the same name and columns, then you can use a more simple solution, like creating a custom rake task or method.  If your migration needs user input to supply table names or other options, you probably want to opt for generating a migration.</p></div>
+<div class="para"><p>Let's say you have the following migration in your plugin:</p></div>
+<div class="para"><p><strong>vendor/plugins/yaffle/lib/db/migrate/20081116181115_create_birdhouses.rb:</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><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> CreateBirdhouses <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Migration
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>up
+    create_table <span style="color: #990000">:</span>birdhouses<span style="color: #990000">,</span> <span style="color: #990000">:</span>force <span style="color: #990000">=&gt;</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span> <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>t<span style="color: #990000">|</span>
+      t<span style="color: #990000">.</span>string <span style="color: #990000">:</span>name
+      t<span style="color: #990000">.</span>timestamps
+    <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>down
+    drop_table <span style="color: #990000">:</span>birdhouses
+  <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>
+<div class="para"><p>Here are a few possibilities for how to allow developers to use your plugin migrations:</p></div>
+<h3 id="_create_a_custom_rake_task">11.1. Create a custom rake task</h3>
+<div class="para"><p><strong>vendor/plugins/yaffle/lib/db/migrate/20081116181115_create_birdhouses.rb:</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><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> CreateBirdhouses <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Migration
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>up
+    create_table <span style="color: #990000">:</span>birdhouses<span style="color: #990000">,</span> <span style="color: #990000">:</span>force <span style="color: #990000">=&gt;</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span> <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>t<span style="color: #990000">|</span>
+      t<span style="color: #990000">.</span>string <span style="color: #990000">:</span>name
+      t<span style="color: #990000">.</span>timestamps
+    <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>down
+    drop_table <span style="color: #990000">:</span>birdhouses
+  <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>
+<div class="para"><p><strong>vendor/plugins/yaffle/tasks/yaffle.rake:</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>namespace <span style="color: #990000">:</span>db <span style="font-weight: bold"><span style="color: #0000FF">do</span></span>
+  namespace <span style="color: #990000">:</span>migrate <span style="font-weight: bold"><span style="color: #0000FF">do</span></span>
+    desc <span style="color: #FF0000">"Migrate the database through scripts in vendor/plugins/yaffle/lib/db/migrate and update db/schema.rb by invoking db:schema:dump. Target specific version with VERSION=x. Turn off output with VERBOSE=false."</span>
+    task <span style="color: #990000">:</span>yaffle <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>environment <span style="font-weight: bold"><span style="color: #0000FF">do</span></span>
+      ActiveRecord<span style="color: #990000">::</span>Migration<span style="color: #990000">.</span>verbose <span style="color: #990000">=</span> ENV<span style="color: #990000">[</span><span style="color: #FF0000">"VERBOSE"</span><span style="color: #990000">]</span> <span style="color: #990000">?</span> ENV<span style="color: #990000">[</span><span style="color: #FF0000">"VERBOSE"</span><span style="color: #990000">]</span> <span style="color: #990000">==</span> <span style="color: #FF0000">"true"</span> <span style="color: #990000">:</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span>
+      ActiveRecord<span style="color: #990000">::</span>Migrator<span style="color: #990000">.</span>migrate<span style="color: #990000">(</span><span style="color: #FF0000">"vendor/plugins/yaffle/lib/db/migrate/"</span><span style="color: #990000">,</span> ENV<span style="color: #990000">[</span><span style="color: #FF0000">"VERSION"</span><span style="color: #990000">]</span> <span style="color: #990000">?</span> ENV<span style="color: #990000">[</span><span style="color: #FF0000">"VERSION"</span><span style="color: #990000">].</span>to_i <span style="color: #990000">:</span> <span style="font-weight: bold"><span style="color: #0000FF">nil</span></span><span style="color: #990000">)</span>
+      Rake<span style="color: #990000">::</span>Task<span style="color: #990000">[</span><span style="color: #FF0000">"db:schema:dump"</span><span style="color: #990000">].</span>invoke <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> ActiveRecord<span style="color: #990000">::</span>Base<span style="color: #990000">.</span>schema_format <span style="color: #990000">==</span> <span style="color: #990000">:</span>ruby
+    <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+  <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>
+<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
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>Dir<span style="color: #990000">.</span>glob<span style="color: #990000">(</span>File<span style="color: #990000">.</span>join<span style="color: #990000">(</span>File<span style="color: #990000">.</span>dirname<span style="color: #990000">(</span><span style="font-weight: bold"><span style="color: #0000FF">__FILE__</span></span><span style="color: #990000">),</span> <span style="color: #FF0000">"db"</span><span style="color: #990000">,</span> <span style="color: #FF0000">"migrate"</span><span style="color: #990000">,</span> <span style="color: #FF0000">"*"</span><span style="color: #990000">)).</span>each <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>file<span style="color: #990000">|</span>
+  <span style="font-weight: bold"><span style="color: #000080">require</span></span> file
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+</tt></pre></div></div>
+<div class="para"><p><strong>db/migrate/20081116181115_create_birdhouses.rb:</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><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> CreateBirdhouses <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Migration
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>up
+    Yaffle<span style="color: #990000">::</span>CreateBirdhouses<span style="color: #990000">.</span>up
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>down
+    Yaffle<span style="color: #990000">::</span>CreateBirdhouses<span style="color: #990000">.</span>down
+  <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>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/note.png" alt="Note" />
+</td>
+<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">
+<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>
+<p>
+call your script/generate script and pass in whatever options they need
+</p>
+</li>
+<li>
+<p>
+examine the generated migration, adding/removing columns or other options as necessary
+</p>
+</li>
+</ul></div>
+<div class="para"><p>This example will demonstrate how to use one of the built-in generator methods named <em>migration_template</em> to create a migration file.  Extending the rails migration generator requires a somewhat intimate knowledge of the migration generator internals, so it's best to write a test first:</p></div>
+<div class="para"><p><strong>vendor/plugins/yaffle/test/yaffle_migration_generator_test.rb</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><span style="font-weight: bold"><span style="color: #000080">require</span></span> File<span style="color: #990000">.</span>dirname<span style="color: #990000">(</span><span style="font-weight: bold"><span style="color: #0000FF">__FILE__</span></span><span style="color: #990000">)</span> <span style="color: #990000">+</span> <span style="color: #FF0000">'/test_helper.rb'</span>
+<span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">'rails_generator'</span>
+<span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">'rails_generator/scripts/generate'</span>
+<span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">'rails_generator/scripts/destroy'</span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">class</span></span> MigrationGeneratorTest <span style="color: #990000">&lt;</span> Test<span style="color: #990000">::</span>Unit<span style="color: #990000">::</span>TestCase
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> fake_rails_root
+    File<span style="color: #990000">.</span>join<span style="color: #990000">(</span>File<span style="color: #990000">.</span>dirname<span style="color: #990000">(</span><span style="font-weight: bold"><span style="color: #0000FF">__FILE__</span></span><span style="color: #990000">),</span> <span style="color: #FF0000">'rails_root'</span><span style="color: #990000">)</span>
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> file_list
+    Dir<span style="color: #990000">.</span>glob<span style="color: #990000">(</span>File<span style="color: #990000">.</span>join<span style="color: #990000">(</span>fake_rails_root<span style="color: #990000">,</span> <span style="color: #FF0000">"db"</span><span style="color: #990000">,</span> <span style="color: #FF0000">"migrate"</span><span style="color: #990000">,</span> <span style="color: #FF0000">"*"</span><span style="color: #990000">))</span>
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> setup
+    FileUtils<span style="color: #990000">.</span>mkdir_p<span style="color: #990000">(</span>fake_rails_root<span style="color: #990000">)</span>
+    <span style="color: #009900">@original_files</span> <span style="color: #990000">=</span> file_list
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> teardown
+    FileUtils<span style="color: #990000">.</span>rm_r<span style="color: #990000">(</span>fake_rails_root<span style="color: #990000">)</span>
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> test_generates_correct_file_name
+    Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Scripts<span style="color: #990000">::</span>Generate<span style="color: #990000">.</span>new<span style="color: #990000">.</span>run<span style="color: #990000">([</span><span style="color: #FF0000">"yaffle"</span><span style="color: #990000">,</span> <span style="color: #FF0000">"some_name_nobody_is_likely_to_ever_use_in_a_real_migration"</span><span style="color: #990000">],</span> <span style="color: #990000">:</span>destination <span style="color: #990000">=&gt;</span> fake_rails_root<span style="color: #990000">)</span>
+    new_file <span style="color: #990000">=</span> <span style="color: #990000">(</span>file_list <span style="color: #990000">-</span> <span style="color: #009900">@original_files</span><span style="color: #990000">).</span>first
+    assert_match <span style="color: #FF6600">/add_yaffle_fields_to_some_name_nobody_is_likely_to_ever_use_in_a_real_migrations/</span><span style="color: #990000">,</span> new_file
+    assert_match <span style="color: #FF6600">/add_column :some_name_nobody_is_likely_to_ever_use_in_a_real_migrations do |t|/</span><span style="color: #990000">,</span> File<span style="color: #990000">.</span>read<span style="color: #990000">(</span>new_file<span style="color: #990000">)</span>
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> test_pluralizes_properly
+    ActiveRecord<span style="color: #990000">::</span>Base<span style="color: #990000">.</span>pluralize_table_names <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">false</span></span>
+    Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Scripts<span style="color: #990000">::</span>Generate<span style="color: #990000">.</span>new<span style="color: #990000">.</span>run<span style="color: #990000">([</span><span style="color: #FF0000">"yaffle"</span><span style="color: #990000">,</span> <span style="color: #FF0000">"some_name_nobody_is_likely_to_ever_use_in_a_real_migration"</span><span style="color: #990000">],</span> <span style="color: #990000">:</span>destination <span style="color: #990000">=&gt;</span> fake_rails_root<span style="color: #990000">)</span>
+    new_file <span style="color: #990000">=</span> <span style="color: #990000">(</span>file_list <span style="color: #990000">-</span> <span style="color: #009900">@original_files</span><span style="color: #990000">).</span>first
+    assert_match <span style="color: #FF6600">/add_yaffle_fields_to_some_name_nobody_is_likely_to_ever_use_in_a_real_migration/</span><span style="color: #990000">,</span> new_file
+    assert_match <span style="color: #FF6600">/add_column :some_name_nobody_is_likely_to_ever_use_in_a_real_migration do |t|/</span><span style="color: #990000">,</span> File<span style="color: #990000">.</span>read<span style="color: #990000">(</span>new_file<span style="color: #990000">)</span>
+  <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>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/note.png" alt="Note" />
+</td>
+<td class="content">the migration generator checks to see if a migation already exists, and it's hard-coded to check the <em>db/migrate</em> directory.  As a result, if your test tries to generate a migration that already exists in the app, it will fail.  The easy workaround is to make sure that the name you generate in your test is very unlikely to actually appear in the app.</td>
+</tr></table>
+</div>
+<div class="para"><p>After running the test with <em>rake</em> you can make it pass with:</p></div>
+<div class="para"><p><strong>vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb</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><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> YaffleGenerator <span style="color: #990000">&lt;</span> Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>NamedBase
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> manifest
+    record <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>m<span style="color: #990000">|</span>
+      m<span style="color: #990000">.</span>migration_template <span style="color: #FF0000">'migration:migration.rb'</span><span style="color: #990000">,</span> <span style="color: #FF0000">"db/migrate"</span><span style="color: #990000">,</span> <span style="color: #FF0000">{</span><span style="color: #990000">:</span>assigns <span style="color: #990000">=&gt;</span> yaffle_local_assigns<span style="color: #990000">,</span>
+        <span style="color: #990000">:</span>migration_file_name <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"add_yaffle_fields_to_#{custom_file_name}"</span>
+      <span style="color: #FF0000">}</span>
+    <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+  private
+    <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> custom_file_name
+      custom_name <span style="color: #990000">=</span> class_name<span style="color: #990000">.</span>underscore<span style="color: #990000">.</span>downcase
+      custom_name <span style="color: #990000">=</span> custom_name<span style="color: #990000">.</span>pluralize <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> ActiveRecord<span style="color: #990000">::</span>Base<span style="color: #990000">.</span>pluralize_table_names
+    <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+    <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> yaffle_local_assigns
+      returning<span style="color: #990000">(</span>assigns <span style="color: #990000">=</span> <span style="color: #FF0000">{}</span><span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">do</span></span>
+        assigns<span style="color: #990000">[:</span>migration_action<span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"add"</span>
+        assigns<span style="color: #990000">[:</span>class_name<span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"add_yaffle_fields_to_#{custom_file_name}"</span>
+        assigns<span style="color: #990000">[:</span>table_name<span style="color: #990000">]</span> <span style="color: #990000">=</span> custom_file_name
+        assigns<span style="color: #990000">[:</span>attributes<span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="color: #990000">[</span>Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>GeneratedAttribute<span style="color: #990000">.</span>new<span style="color: #990000">(</span><span style="color: #FF0000">"last_squawk"</span><span style="color: #990000">,</span> <span style="color: #FF0000">"string"</span><span style="color: #990000">)]</span>
+      <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+    <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>
+<div class="para"><p>The generator creates a new file in <em>db/migrate</em> with a timestamp and an <em>add_column</em> statement.  It reuses the built in rails <tt>migration_template</tt> method, and reuses the built-in rails migration template.</p></div>
+<div class="para"><p>It's courteous to check to see if table names are being pluralized whenever you create a generator that needs to be aware of table names.  This way people using your generator won't have to manually change the generated files if they've turned pluralization off.</p></div>
+<div class="para"><p>To run the generator, type the following at the command line:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>./script/generate yaffle_migration bird</tt></pre>
+</div></div>
+<div class="para"><p>and you will see a new file:</p></div>
+<div class="para"><p><strong>db/migrate/20080529225649_add_yaffle_fields_to_birds.rb</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><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> AddYaffleFieldsToBirds <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Migration
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>up
+    add_column <span style="color: #990000">:</span>birds<span style="color: #990000">,</span> <span style="color: #990000">:</span>last_squawk<span style="color: #990000">,</span> <span style="color: #990000">:</span>string
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>down
+    remove_column <span style="color: #990000">:</span>birds<span style="color: #990000">,</span> <span style="color: #990000">:</span>last_squawk
+  <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>
+</div>
+<h2 id="_odds_and_ends">13. Odds and ends</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">10.2. Write custom Rake tasks in your plugin</h3>
+<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>
@@ -1510,7 +1765,7 @@ http://www.gnu.org/software/src-highlite -->
 <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">10.3. Store plugins in alternate locations</h3>
+<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>
@@ -1521,14 +1776,14 @@ 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>
 </tt></pre></div></div>
-<h3 id="_create_your_own_plugin_loaders_and_plugin_locators">10.4. Create your own Plugin Loaders and Plugin Locators</h3>
+<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">10.5. Use Custom Plugin Generators</h3>
+<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>
-<h2 id="_appendix">11. Appendix</h2>
+<h2 id="_appendix">14. Appendix</h2>
 <div class="sectionbody">
-<h3 id="_references">11.1. References</h3>
+<h3 id="_references">14.1. References</h3>
 <div class="ilist"><ul>
 <li>
 <p>
@@ -1550,41 +1805,58 @@ http://www.gnu.org/software/src-highlite -->
 <a href="http://daddy.platte.name/2007/05/rails-plugins-keep-initrb-thin.html">http://daddy.platte.name/2007/05/rails-plugins-keep-initrb-thin.html</a>
 </p>
 </li>
+<li>
+<p>
+<a href="http://www.mbleigh.com/2008/6/11/gemplugins-a-brief-introduction-to-the-future-of-rails-plugins">http://www.mbleigh.com/2008/6/11/gemplugins-a-brief-introduction-to-the-future-of-rails-plugins</a>
+</p>
+</li>
 </ul></div>
-<h3 id="_final_plugin_directory_structure">11.2. Final plugin directory structure</h3>
+<h3 id="_final_plugin_directory_structure">14.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>  |-- MIT-LICENSE
-  |-- README
-  |-- Rakefile
-  |-- generators
-  |   `-- yaffle
-  |       |-- USAGE
-  |       |-- templates
-  |       |   `-- definition.txt
-  |       `-- yaffle_generator.rb
-  |-- init.rb
-  |-- install.rb
-  |-- lib
-  |   |-- acts_as_yaffle.rb
-  |   |-- commands.rb
-  |   |-- core_ext.rb
-  |   |-- routing.rb
-  |   `-- view_helpers.rb
-  |-- tasks
-  |   `-- yaffle_tasks.rake
-  |-- test
-  |   |-- acts_as_yaffle_test.rb
-  |   |-- core_ext_test.rb
-  |   |-- database.yml
-  |   |-- debug.log
-  |   |-- routing_test.rb
-  |   |-- schema.rb
-  |   |-- test_helper.rb
-  |   `-- view_helpers_test.rb
-  |-- uninstall.rb
-  `-- yaffle_plugin.sqlite3.db</tt></pre>
+<pre><tt>vendor/plugins/yaffle/
+|-- MIT-LICENSE
+|-- README
+|-- Rakefile
+|-- generators
+|   `-- yaffle
+|       |-- USAGE
+|       |-- templates
+|       |   `-- definition.txt
+|       `-- yaffle_generator.rb
+|-- install.rb
+|-- lib
+|   |-- app
+|   |   |-- controllers
+|   |   |   `-- woodpeckers_controller.rb
+|   |   |-- helpers
+|   |   |   `-- woodpeckers_helper.rb
+|   |   `-- models
+|   |       `-- woodpecker.rb
+|   |-- yaffle
+|   |   |-- acts_as_yaffle.rb
+|   |   |-- commands.rb
+|   |   `-- core_ext.rb
+|   `-- yaffle.rb
+|-- rails
+|   `-- init.rb
+|-- tasks
+|   `-- yaffle_tasks.rake
+|-- test
+|   |-- acts_as_yaffle_test.rb
+|   |-- core_ext_test.rb
+|   |-- database.yml
+|   |-- debug.log
+|   |-- generator_test.rb
+|   |-- schema.rb
+|   |-- test_helper.rb
+|   |-- woodpecker_test.rb
+|   |-- woodpeckers_controller_test.rb
+|   |-- wookpeckers_helper_test.rb
+|   |-- yaffle_plugin.sqlite3.db
+|   `-- yaffle_test.rb
+`-- uninstall.rb</tt></pre>
 </div></div>
 </div>
 
diff --git a/railties/doc/guides/html/migrations.html b/railties/doc/guides/html/migrations.html
index 8b580d8086..9f7fa28daf 100644
--- a/railties/doc/guides/html/migrations.html
+++ b/railties/doc/guides/html/migrations.html
@@ -279,7 +279,7 @@ ul#navMain {
 				<h1>Migrations</h1>
 			<div id="preamble">
 <div class="sectionbody">
-<div class="para"><p>Migrations are a convenient way for you to alter your database in a structured and organised manner. You could edit fragments of SQL by hand but you would then be responsible for telling other developers that they need to go and run it. You'd also have to keep track of which changes need to be run against the production machines next time you deploy. Active Record tracks which migrations have already been run so all you have to do is update your source and run <tt>rake db:migrate</tt>. Active Record will work out which migrations should be run.</p></div>
+<div class="para"><p>Migrations are a convenient way for you to alter your database in a structured and organised manner. You could edit fragments of SQL by hand but you would then be responsible for telling other developers that they need to go and run it. You'd also have to keep track of which changes need to be run against the production machines next time you deploy. Active Record tracks which migrations have already been run so all you have to do is update your source and run <tt>rake db:migrate</tt>. Active Record will work out which migrations should be run. It will also update your db/schema.rb file to match the structure of your database.</p></div>
 <div class="para"><p>Migrations also allow you to describe these transformations using Ruby. The great thing about this is that (like most of Active Record's functionality) it is database independent: you don't need to worry about the precise syntax of CREATE TABLE any more that you worry about variations on SELECT * (you can drop down to raw SQL for database specific features). For example you could use SQLite3 in development, but MySQL in production.</p></div>
 <div class="para"><p>You'll learn all about migrations including:</p></div>
 <div class="ilist"><ul>
@@ -699,6 +699,7 @@ displayed saying that it can't be done.</p></div>
 <h2 id="_running_migrations">4. Running Migrations</h2>
 <div class="sectionbody">
 <div class="para"><p>Rails provides a set of rake tasks to work with migrations which boils down to running certain sets of migrations. The very first migration related rake task you use will probably be <tt>db:migrate</tt>. In its most basic form it just runs the <tt>up</tt> method for all the migrations that have not yet been run. If there are no such migrations it exits.</p></div>
+<div class="para"><p>Note that running the <tt>db:migrate</tt> also invokes the <tt>db:schema:dump</tt> task, which will update your db/schema.rb file to match the structure of your database.</p></div>
 <div class="para"><p>If you specify a target version, Active Record will run the required migrations (up or down) until it has reached the specified version. The
 version is the numerical prefix on the migration's filename. For example to migrate to version 20080906120000 run</p></div>
 <div class="listingblock">
diff --git a/railties/doc/guides/source/creating_plugins/acts_as_yaffle.txt b/railties/doc/guides/source/creating_plugins/acts_as_yaffle.txt
index de116af7db..674f086e17 100644
--- a/railties/doc/guides/source/creating_plugins/acts_as_yaffle.txt
+++ b/railties/doc/guides/source/creating_plugins/acts_as_yaffle.txt
@@ -1,4 +1,4 @@
-== Add an `acts_as_yaffle` method to Active Record ==
+== Add an 'acts_as' method to Active Record ==
 
 A common pattern in plugins is to add a method called 'acts_as_something' to models.  In this case, you want to write a method called 'acts_as_yaffle' that adds a 'squawk' method to your models.
 
diff --git a/railties/doc/guides/source/creating_plugins/appendix.txt b/railties/doc/guides/source/creating_plugins/appendix.txt
index a78890ccd5..d890f861b5 100644
--- a/railties/doc/guides/source/creating_plugins/appendix.txt
+++ b/railties/doc/guides/source/creating_plugins/appendix.txt
@@ -6,41 +6,54 @@
  * http://nubyonrails.com/articles/2006/05/09/the-complete-guide-to-rails-plugins-part-ii
  * http://github.com/technoweenie/attachment_fu/tree/master
  * http://daddy.platte.name/2007/05/rails-plugins-keep-initrb-thin.html
+ * http://www.mbleigh.com/2008/6/11/gemplugins-a-brief-introduction-to-the-future-of-rails-plugins
 
 === Final plugin directory structure ===
 
 The final plugin should have a directory structure that looks something like this:
 
 ------------------------------------------------
-  |-- MIT-LICENSE
-  |-- README
-  |-- Rakefile
-  |-- generators
-  |   `-- yaffle
-  |       |-- USAGE
-  |       |-- templates
-  |       |   `-- definition.txt
-  |       `-- yaffle_generator.rb
-  |-- init.rb
-  |-- install.rb
-  |-- lib
-  |   |-- acts_as_yaffle.rb
-  |   |-- commands.rb
-  |   |-- core_ext.rb
-  |   |-- routing.rb
-  |   `-- view_helpers.rb
-  |-- tasks
-  |   `-- yaffle_tasks.rake
-  |-- test
-  |   |-- acts_as_yaffle_test.rb
-  |   |-- core_ext_test.rb
-  |   |-- database.yml
-  |   |-- debug.log
-  |   |-- routing_test.rb
-  |   |-- schema.rb
-  |   |-- test_helper.rb
-  |   `-- view_helpers_test.rb
-  |-- uninstall.rb
-  `-- yaffle_plugin.sqlite3.db
+vendor/plugins/yaffle/
+|-- MIT-LICENSE
+|-- README
+|-- Rakefile
+|-- generators
+|   `-- yaffle
+|       |-- USAGE
+|       |-- templates
+|       |   `-- definition.txt
+|       `-- yaffle_generator.rb
+|-- install.rb
+|-- lib
+|   |-- app
+|   |   |-- controllers
+|   |   |   `-- woodpeckers_controller.rb
+|   |   |-- helpers
+|   |   |   `-- woodpeckers_helper.rb
+|   |   `-- models
+|   |       `-- woodpecker.rb
+|   |-- yaffle
+|   |   |-- acts_as_yaffle.rb
+|   |   |-- commands.rb
+|   |   `-- core_ext.rb
+|   `-- yaffle.rb
+|-- rails
+|   `-- init.rb
+|-- tasks
+|   `-- yaffle_tasks.rake
+|-- test
+|   |-- acts_as_yaffle_test.rb
+|   |-- core_ext_test.rb
+|   |-- database.yml
+|   |-- debug.log
+|   |-- generator_test.rb
+|   |-- schema.rb
+|   |-- test_helper.rb
+|   |-- woodpecker_test.rb
+|   |-- woodpeckers_controller_test.rb
+|   |-- wookpeckers_helper_test.rb
+|   |-- yaffle_plugin.sqlite3.db
+|   `-- yaffle_test.rb
+`-- uninstall.rb
 ------------------------------------------------
 
diff --git a/railties/doc/guides/source/creating_plugins/controllers.txt b/railties/doc/guides/source/creating_plugins/controllers.txt
index ee408adb1d..4f4417b416 100644
--- a/railties/doc/guides/source/creating_plugins/controllers.txt
+++ b/railties/doc/guides/source/creating_plugins/controllers.txt
@@ -1,4 +1,4 @@
-== Add a controller ==
+== Controllers ==
 
 This section describes how to add a controller named 'woodpeckers' to your plugin that will behave the same as a controller in your main app.  This is very similar to adding a model.
 
diff --git a/railties/doc/guides/source/creating_plugins/custom_route.txt b/railties/doc/guides/source/creating_plugins/custom_route.txt
deleted file mode 100644
index 1fce902a4e..0000000000
--- a/railties/doc/guides/source/creating_plugins/custom_route.txt
+++ /dev/null
@@ -1,69 +0,0 @@
-== Add a Custom Route ==
-
-Testing routes in plugins can be complex, especially if the controllers are also in the plugin itself.  Jamis Buck showed a great example of this in http://weblog.jamisbuck.org/2006/10/26/monkey-patching-rails-extending-routes-2.
-
-*vendor/plugins/yaffle/test/routing_test.rb*
-
-[source, ruby]
---------------------------------------------------------
-require "#{File.dirname(__FILE__)}/test_helper"
-
-class RoutingTest < Test::Unit::TestCase
-
-  def setup
-    ActionController::Routing::Routes.draw do |map|
-      map.yaffles
-    end
-  end
-
-  def test_yaffles_route
-    assert_recognition :get, "/yaffles", :controller => "yaffles_controller", :action => "index"
-  end
-
-  private
-
-    # yes, I know about assert_recognizes, but it has proven problematic to
-    # use in these tests, since it uses RouteSet#recognize (which actually
-    # tries to instantiate the controller) and because it uses an awkward
-    # parameter order.
-    def assert_recognition(method, path, options)
-      result = ActionController::Routing::Routes.recognize_path(path, :method => method)
-      assert_equal options, result
-    end
-end
---------------------------------------------------------
-
-*vendor/plugins/yaffle/init.rb*
-
-[source, ruby]
---------------------------------------------------------
-require "routing"
-ActionController::Routing::RouteSet::Mapper.send :include, Yaffle::Routing::MapperExtensions
---------------------------------------------------------
-
-*vendor/plugins/yaffle/lib/routing.rb*
-
-[source, ruby]
---------------------------------------------------------
-module Yaffle #:nodoc:
-  module Routing #:nodoc:
-    module MapperExtensions
-      def yaffles
-        @set.add_route("/yaffles", {:controller => "yaffles_controller", :action => "index"})
-      end
-    end
-  end
-end
---------------------------------------------------------
-
-*config/routes.rb*
-
-[source, ruby]
---------------------------------------------------------
-ActionController::Routing::Routes.draw do |map|
-  ...
-  map.yaffles
-end
---------------------------------------------------------
-
-You can also see if your routes work by running `rake routes` from your app directory.
diff --git a/railties/doc/guides/source/creating_plugins/gem.txt b/railties/doc/guides/source/creating_plugins/gem.txt
index 93f5e0ee89..8a0bbb3bc0 100644
--- a/railties/doc/guides/source/creating_plugins/gem.txt
+++ b/railties/doc/guides/source/creating_plugins/gem.txt
@@ -1 +1,3 @@
+== 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/generator_commands.txt b/railties/doc/guides/source/creating_plugins/generator_commands.txt
new file mode 100644
index 0000000000..5cce81c8bd
--- /dev/null
+++ b/railties/doc/guides/source/creating_plugins/generator_commands.txt
@@ -0,0 +1,140 @@
+== Generator Commands ==
+
+You may have noticed above that you can used one of the built-in rails migration commands `migration_template`.  If your plugin needs to add and remove lines of text from existing files you will need to write your own generator methods.
+
+This section describes how you you can create your own commands to add and remove a line of text from 'config/routes.rb'.
+
+To start, add the following test method:
+
+*vendor/plugins/yaffle/test/route_generator_test.rb*
+
+[source, ruby]
+-----------------------------------------------------------
+require File.dirname(__FILE__) + '/test_helper.rb'
+require 'rails_generator'
+require 'rails_generator/scripts/generate'
+require 'rails_generator/scripts/destroy'
+
+class RouteGeneratorTest < Test::Unit::TestCase
+
+  def fake_rails_root
+    File.join(File.dirname(__FILE__), "rails_root")
+  end
+  
+  def routes_path
+    File.join(fake_rails_root, "config", "routes.rb")
+  end
+
+  def setup
+    FileUtils.mkdir_p(File.join(fake_rails_root, "config"))
+  end
+  
+  def teardown
+    FileUtils.rm_r(fake_rails_root)
+  end
+  
+  def test_generates_route
+    content = <<-END
+      ActionController::Routing::Routes.draw do |map|
+        map.connect ':controller/:action/:id'
+        map.connect ':controller/:action/:id.:format'
+      end
+    END
+    File.open(routes_path, 'wb') {|f| f.write(content) }
+    
+    Rails::Generator::Scripts::Generate.new.run(["yaffle_route"], :destination => fake_rails_root)
+    assert_match /map\.yaffle/, File.read(routes_path)
+  end
+
+  def test_destroys_route
+    content = <<-END
+      ActionController::Routing::Routes.draw do |map|
+        map.yaffle
+        map.connect ':controller/:action/:id'
+        map.connect ':controller/:action/:id.:format'
+      end
+    END
+    File.open(routes_path, 'wb') {|f| f.write(content) }
+    
+    Rails::Generator::Scripts::Destroy.new.run(["yaffle_route"], :destination => fake_rails_root)
+    assert_no_match /map\.yaffle/, File.read(routes_path)
+  end
+end
+-----------------------------------------------------------
+
+Run `rake` to watch the test fail, then make the test pass add the following:
+
+*vendor/plugins/yaffle/lib/yaffle.rb*
+
+[source, ruby]
+-----------------------------------------------------------
+require "yaffle/commands"
+-----------------------------------------------------------
+
+*vendor/plugins/yaffle/lib/yaffle/commands.rb*
+
+[source, ruby]
+-----------------------------------------------------------
+require 'rails_generator'
+require 'rails_generator/commands'
+
+module Yaffle #:nodoc:
+  module Generator #:nodoc:
+    module Commands #:nodoc:
+      module Create
+        def yaffle_route
+          logger.route "map.yaffle"
+          look_for = 'ActionController::Routing::Routes.draw do |map|'
+          unless options[:pretend]
+            gsub_file('config/routes.rb', /(#{Regexp.escape(look_for)})/mi){|match| "#{match}\n  map.yaffle\n"}
+          end
+        end
+      end
+
+      module Destroy
+        def yaffle_route
+          logger.route "map.yaffle"
+          gsub_file 'config/routes.rb', /\n.+?map\.yaffle/mi, ''
+        end
+      end
+
+      module List
+        def yaffle_route
+        end
+      end
+
+      module Update
+        def yaffle_route
+        end
+      end
+    end
+  end
+end
+
+Rails::Generator::Commands::Create.send   :include,  Yaffle::Generator::Commands::Create
+Rails::Generator::Commands::Destroy.send  :include,  Yaffle::Generator::Commands::Destroy
+Rails::Generator::Commands::List.send     :include,  Yaffle::Generator::Commands::List
+Rails::Generator::Commands::Update.send   :include,  Yaffle::Generator::Commands::Update
+-----------------------------------------------------------
+
+*vendor/plugins/yaffle/generators/yaffle/yaffle_route_generator.rb*
+
+[source, ruby]
+-----------------------------------------------------------
+class YaffleRouteGenerator < Rails::Generator::Base
+  def manifest
+    record do |m|
+      m.yaffle_route
+    end
+  end
+end
+-----------------------------------------------------------
+
+To see this work, type:
+
+-----------------------------------------------------------
+./script/generate yaffle_route
+./script/destroy yaffle_route
+-----------------------------------------------------------
+
+NOTE: If you haven't set up the custom route from above, 'script/destroy' will fail and you'll have to remove it manually.
\ No newline at end of file
diff --git a/railties/doc/guides/source/creating_plugins/generator_method.txt b/railties/doc/guides/source/creating_plugins/generator_method.txt
deleted file mode 100644
index 126692f2c4..0000000000
--- a/railties/doc/guides/source/creating_plugins/generator_method.txt
+++ /dev/null
@@ -1,89 +0,0 @@
-== Add a custom generator command ==
-
-You may have noticed above that you can used one of the built-in rails migration commands `migration_template`.  If your plugin needs to add and remove lines of text from existing files you will need to write your own generator methods.
-
-This section describes how you you can create your own commands to add and remove a line of text from 'routes.rb'.  This example creates a very simple method that adds or removes a text file.
-
-To start, add the following test method:
-
-*vendor/plugins/yaffle/test/generator_test.rb*
-
-[source, ruby]
------------------------------------------------------------
-def test_generates_definition
-  Rails::Generator::Scripts::Generate.new.run(["yaffle", "bird"], :destination => fake_rails_root)
-  definition = File.read(File.join(fake_rails_root, "definition.txt"))
-  assert_match /Yaffle\:/, definition
-end
------------------------------------------------------------
-
-Run `rake` to watch the test fail, then make the test pass add the following:
-
-*vendor/plugins/yaffle/generators/yaffle/templates/definition.txt*
-
------------------------------------------------------------
-Yaffle: A bird
------------------------------------------------------------
-
-*vendor/plugins/yaffle/lib/yaffle.rb*
-
-[source, ruby]
------------------------------------------------------------
-require "yaffle/commands"
------------------------------------------------------------
-
-*vendor/plugins/yaffle/lib/commands.rb*
-
-[source, ruby]
------------------------------------------------------------
-require 'rails_generator'
-require 'rails_generator/commands'
-
-module Yaffle #:nodoc:
-  module Generator #:nodoc:
-    module Commands #:nodoc:
-      module Create
-        def yaffle_definition
-          file("definition.txt", "definition.txt")
-        end
-      end
-
-      module Destroy
-        def yaffle_definition
-          file("definition.txt", "definition.txt")
-        end
-      end
-
-      module List
-        def yaffle_definition
-          file("definition.txt", "definition.txt")
-        end
-      end
-
-      module Update
-        def yaffle_definition
-          file("definition.txt", "definition.txt")
-        end
-      end
-    end
-  end
-end
-
-Rails::Generator::Commands::Create.send   :include,  Yaffle::Generator::Commands::Create
-Rails::Generator::Commands::Destroy.send  :include,  Yaffle::Generator::Commands::Destroy
-Rails::Generator::Commands::List.send     :include,  Yaffle::Generator::Commands::List
-Rails::Generator::Commands::Update.send   :include,  Yaffle::Generator::Commands::Update
------------------------------------------------------------
-
-Finally, call your new method in the manifest:
-
-*vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb*
-
-[source, ruby]
------------------------------------------------------------
-class YaffleGenerator < Rails::Generator::NamedBase
-  def manifest
-    m.yaffle_definition
-  end
-end
------------------------------------------------------------
diff --git a/railties/doc/guides/source/creating_plugins/generators.txt b/railties/doc/guides/source/creating_plugins/generators.txt
new file mode 100644
index 0000000000..eb0fbb5ee9
--- /dev/null
+++ b/railties/doc/guides/source/creating_plugins/generators.txt
@@ -0,0 +1,103 @@
+== Generators ==
+
+Many plugins ship with generators.  When you created the plugin above, you specified the --with-generator option, so you already have the generator stubs in 'vendor/plugins/yaffle/generators/yaffle'.
+
+Building generators is a complex topic unto itself and this section will cover one small aspect of generators:  creating a generator that adds a time-stamped migration.
+
+To add a generator to a plugin:
+
+ * Write a test
+ * Add your instructions to the 'manifest' method of the generator
+ * Add any necessary template files to the templates directory
+ * Update the USAGE file to add helpful documentation for your generator
+
+=== Testing generators ===
+
+Many rails plugin authors do not test their generators, however testing generators is quite simple.  A typical generator test does the following:
+
+ * Creates a new fake rails root directory that will serve as destination
+ * Runs the generator
+ * Asserts that the correct files were generated
+ * Removes the fake rails root
+
+This section will describe how to create a simple generator that adds a file.  For the generator in this section, the test could look something like this:
+
+*vendor/plugins/yaffle/test/definition_generator_test.rb*
+
+[source, ruby]
+------------------------------------------------------------------
+require File.dirname(__FILE__) + '/test_helper.rb'
+require 'rails_generator'
+require 'rails_generator/scripts/generate'
+
+class DefinitionGeneratorTest < Test::Unit::TestCase
+
+  def fake_rails_root
+    File.join(File.dirname(__FILE__), 'rails_root')
+  end
+  
+  def file_list
+    Dir.glob(File.join(fake_rails_root, "*"))
+  end
+
+  def setup
+    FileUtils.mkdir_p(fake_rails_root)
+    @original_files = file_list
+  end
+
+  def teardown
+    FileUtils.rm_r(fake_rails_root)
+  end
+  
+  def test_generates_correct_file_name
+    Rails::Generator::Scripts::Generate.new.run(["yaffle_definition"], :destination => fake_rails_root)
+    new_file = (file_list - @original_files).first
+    assert_equal "definition.txt", File.basename(new_file)
+  end
+  
+end
+------------------------------------------------------------------
+
+You can run 'rake' from the plugin directory to see this fail.  Unless you are doing more advanced generator commands it typically suffices to just test the Generate script, and trust that rails will handle the Destroy and Update commands for you.
+
+To make it pass, create the generator:
+
+*vendor/plugins/yaffle/generators/yaffle_definition/yaffle_definition_generator.rb*
+
+[source, ruby]
+------------------------------------------------------------------
+class YaffleDefinitionGenerator < Rails::Generator::Base
+  def manifest
+    record do |m|
+      m.file "definition.txt", "definition.txt"
+    end
+  end
+end
+------------------------------------------------------------------
+
+=== The USAGE file ===
+
+If you plan to distribute your plugin, developers will expect at least a minimum of documentation.  You can add simple documentation to the generator by updating the USAGE file.
+
+Rails ships with several built-in generators.  You can see all of the generators available to you by typing the following at the command line:
+
+------------------------------------------------------------------
+./script/generate
+------------------------------------------------------------------
+
+You should see something like this:
+
+------------------------------------------------------------------
+Installed Generators
+  Plugins (vendor/plugins): yaffle_definition
+  Builtin: controller, integration_test, mailer, migration, model, observer, plugin, resource, scaffold, session_migration
+------------------------------------------------------------------
+
+When you run `script/generate yaffle_definition -h` you should see the contents of your 'vendor/plugins/yaffle/generators/yaffle_definition/USAGE'.  
+
+For this plugin, update the USAGE file could look like this:
+
+------------------------------------------------------------------
+Description:
+    Adds a file with the definition of a Yaffle to the app's main directory
+------------------------------------------------------------------
diff --git a/railties/doc/guides/source/creating_plugins/helpers.txt b/railties/doc/guides/source/creating_plugins/helpers.txt
index 51b4cebb01..c2273813dd 100644
--- a/railties/doc/guides/source/creating_plugins/helpers.txt
+++ b/railties/doc/guides/source/creating_plugins/helpers.txt
@@ -1,4 +1,4 @@
-== Add a helper ==
+== Helpers ==
 
 This section describes how to add a helper named 'WoodpeckersHelper' to your plugin that will behave the same as a helper in your main app.  This is very similar to adding a model and a controller.
 
diff --git a/railties/doc/guides/source/creating_plugins/index.txt b/railties/doc/guides/source/creating_plugins/index.txt
index 19484e2830..5d10fa4f31 100644
--- a/railties/doc/guides/source/creating_plugins/index.txt
+++ b/railties/doc/guides/source/creating_plugins/index.txt
@@ -29,23 +29,27 @@ This guide describes how to build a test-driven plugin that will:
 For the purpose of this guide pretend for a moment that you are an avid bird watcher.  Your favorite bird is the Yaffle, and you want to create a plugin that allows other developers to share in the Yaffle goodness.  First, you need to get setup for development.
 
 
-include::test_setup.txt[]
+include::setup.txt[]
+
+include::tests.txt[]
 
 include::core_ext.txt[]
 
 include::acts_as_yaffle.txt[]
 
-include::migration_generator.txt[]
-
-include::generator_method.txt[]
-
 include::models.txt[]
 
 include::controllers.txt[]
 
 include::helpers.txt[]
 
-include::custom_route.txt[]
+include::routes.txt[]
+
+include::generators.txt[]
+
+include::generator_commands.txt[]
+
+include::migrations.txt[]
 
 include::odds_and_ends.txt[]
 
diff --git a/railties/doc/guides/source/creating_plugins/migration_generator.txt b/railties/doc/guides/source/creating_plugins/migration_generator.txt
deleted file mode 100644
index f4fc32481c..0000000000
--- a/railties/doc/guides/source/creating_plugins/migration_generator.txt
+++ /dev/null
@@ -1,156 +0,0 @@
-== Create a generator ==
-
-Many plugins ship with generators.  When you created the plugin above, you specified the --with-generator option, so you already have the generator stubs in 'vendor/plugins/yaffle/generators/yaffle'.
-
-Building generators is a complex topic unto itself and this section will cover one small aspect of generators:  creating a generator that adds a time-stamped migration.
-
-To create a generator you must:
-
- * Add your instructions to the 'manifest' method of the generator
- * Add any necessary template files to the templates directory
- * Test the generator manually by running various combinations of `script/generate` and `script/destroy`
- * Update the USAGE file to add helpful documentation for your generator
-
-=== Testing generators ===
-
-Many rails plugin authors do not test their generators, however testing generators is quite simple.  A typical generator test does the following:
-
- * Creates a new fake rails root directory that will serve as destination
- * Runs the generator forward and backward, making whatever assertions are necessary
- * Removes the fake rails root
-
-For the generator in this section, the test could look something like this:
-
-*vendor/plugins/yaffle/test/yaffle_generator_test.rb*
-
-[source, ruby]
-------------------------------------------------------------------
-require File.dirname(__FILE__) + '/test_helper.rb'
-require 'rails_generator'
-require 'rails_generator/scripts/generate'
-require 'rails_generator/scripts/destroy'
-
-class GeneratorTest < Test::Unit::TestCase
-
-  def fake_rails_root
-    File.join(File.dirname(__FILE__), 'rails_root')
-  end
-  
-  def file_list
-    Dir.glob(File.join(fake_rails_root, "db", "migrate", "*"))
-  end
-
-  def setup
-    FileUtils.mkdir_p(fake_rails_root)
-    @original_files = file_list
-  end
-
-  def teardown
-    FileUtils.rm_r(fake_rails_root)
-  end
-  
-  def test_generates_correct_file_name
-    Rails::Generator::Scripts::Generate.new.run(["yaffle", "bird"], :destination => fake_rails_root)
-    new_file = (file_list - @original_files).first
-    assert_match /add_yaffle_fields_to_bird/, new_file
-  end
-  
-end
-------------------------------------------------------------------
-
-You can run 'rake' from the plugin directory to see this fail.  Unless you are doing more advanced generator commands it typically suffices to just test the Generate script, and trust that rails will handle the Destroy and Update commands for you.
-
-=== Adding to the manifest ===
-
-This example will demonstrate how to use one of the built-in generator methods named 'migration_template' to create a migration file.  To start, update your generator file to look like this:
-
-*vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb*
-
-[source, ruby]
-------------------------------------------------------------------
-class YaffleGenerator < Rails::Generator::NamedBase
-  def manifest
-    record do |m|
-      m.migration_template 'migration:migration.rb', "db/migrate", {:assigns => yaffle_local_assigns,
-        :migration_file_name => "add_yaffle_fields_to_#{custom_file_name}"
-      }
-    end
-  end
-
-  private
-    def custom_file_name
-      custom_name = class_name.underscore.downcase
-      custom_name = custom_name.pluralize if ActiveRecord::Base.pluralize_table_names
-    end
-
-    def yaffle_local_assigns
-      returning(assigns = {}) do
-        assigns[:migration_action] = "add"
-        assigns[:class_name] = "add_yaffle_fields_to_#{custom_file_name}"
-        assigns[:table_name] = custom_file_name
-        assigns[:attributes] = [Rails::Generator::GeneratedAttribute.new("last_squawk", "string")]
-      end
-    end
-end
-------------------------------------------------------------------
-
-The generator creates a new file in 'db/migrate' with a timestamp and an 'add_column' statement.  It reuses the built in rails `migration_template` method, and reuses the built-in rails migration template.
-
-It's courteous to check to see if table names are being pluralized whenever you create a generator that needs to be aware of table names.  This way people using your generator won't have to manually change the generated files if they've turned pluralization off.
-
-=== Manually test the generator ===
-
-To run the generator, type the following at the command line:
-
-------------------------------------------------------------------
-./script/generate yaffle bird
-------------------------------------------------------------------
-
-and you will see a new file:
-
-*db/migrate/20080529225649_add_yaffle_fields_to_birds.rb*
-
-[source, ruby]
-------------------------------------------------------------------
-class AddYaffleFieldsToBirds < ActiveRecord::Migration
-  def self.up
-    add_column :birds, :last_squawk, :string
-  end
-
-  def self.down
-    remove_column :birds, :last_squawk
-  end
-end
-------------------------------------------------------------------
-
-
-=== The USAGE file ===
-
-Rails ships with several built-in generators.  You can see all of the generators available to you by typing the following at the command line:
-
-------------------------------------------------------------------
-script/generate
-------------------------------------------------------------------
-
-You should see something like this:
-
-------------------------------------------------------------------
-Installed Generators
-  Plugins (vendor/plugins): yaffle
-  Builtin: controller, integration_test, mailer, migration, model, observer, plugin, resource, scaffold, session_migration
-------------------------------------------------------------------
-
-When you run `script/generate yaffle` you should see the contents of your 'vendor/plugins/yaffle/generators/yaffle/USAGE' file.  
-
-For this plugin, update the USAGE file looks like this:
-
-------------------------------------------------------------------
-Description:
-    Creates a migration that adds yaffle squawk fields to the given model
-
-Example:
-    ./script/generate yaffle hickwall
-
-    This will create:
-        db/migrate/TIMESTAMP_add_yaffle_fields_to_hickwall
-------------------------------------------------------------------
diff --git a/railties/doc/guides/source/creating_plugins/migrations.txt b/railties/doc/guides/source/creating_plugins/migrations.txt
new file mode 100644
index 0000000000..7154f0bc06
--- /dev/null
+++ b/railties/doc/guides/source/creating_plugins/migrations.txt
@@ -0,0 +1,209 @@
+== Migrations ==
+
+If your plugin requires changes to the app's database you will likely want to somehow add migrations.  Rails does not include any built-in support for calling migrations from plugins, but you can still make it easy for developers to call migrations from plugins.
+
+If you have a very simple needs, like creating a table that will always have the same name and columns, then you can use a more simple solution, like creating a custom rake task or method.  If your migration needs user input to supply table names or other options, you probably want to opt for generating a migration.
+
+Let's say you have the following migration in your plugin:
+
+*vendor/plugins/yaffle/lib/db/migrate/20081116181115_create_birdhouses.rb:*
+
+[source, ruby]
+----------------------------------------------
+class CreateBirdhouses < ActiveRecord::Migration
+  def self.up
+    create_table :birdhouses, :force => true do |t|
+      t.string :name
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :birdhouses
+  end
+end
+----------------------------------------------
+
+Here are a few possibilities for how to allow developers to use your plugin migrations:
+
+=== Create a custom rake task ===
+
+*vendor/plugins/yaffle/lib/db/migrate/20081116181115_create_birdhouses.rb:*
+
+[source, ruby]
+----------------------------------------------
+class CreateBirdhouses < ActiveRecord::Migration
+  def self.up
+    create_table :birdhouses, :force => true do |t|
+      t.string :name
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :birdhouses
+  end
+end
+----------------------------------------------
+
+
+*vendor/plugins/yaffle/tasks/yaffle.rake:*
+
+[source, ruby]
+----------------------------------------------
+namespace :db do
+  namespace :migrate do
+    desc "Migrate the database through scripts in vendor/plugins/yaffle/lib/db/migrate and update db/schema.rb by invoking db:schema:dump. Target specific version with VERSION=x. Turn off output with VERBOSE=false."
+    task :yaffle => :environment do
+      ActiveRecord::Migration.verbose = ENV["VERBOSE"] ? ENV["VERBOSE"] == "true" : true
+      ActiveRecord::Migrator.migrate("vendor/plugins/yaffle/lib/db/migrate/", ENV["VERSION"] ? ENV["VERSION"].to_i : nil)
+      Rake::Task["db:schema:dump"].invoke if ActiveRecord::Base.schema_format == :ruby
+    end
+  end
+end
+----------------------------------------------
+
+=== Call plugin migrations from regular migrations ===
+
+*vendor/plugins/yaffle/lib/yaffle.rb:*
+
+[source, ruby]
+----------------------------------------------
+Dir.glob(File.join(File.dirname(__FILE__), "db", "migrate", "*")).each do |file|
+  require file
+end
+----------------------------------------------
+
+*db/migrate/20081116181115_create_birdhouses.rb:*
+
+[source, ruby]
+----------------------------------------------
+class CreateBirdhouses < ActiveRecord::Migration
+  def self.up
+    Yaffle::CreateBirdhouses.up
+  end
+
+  def self.down
+    Yaffle::CreateBirdhouses.down
+  end
+end
+----------------------------------------------
+
+NOTE: several plugin frameworks such as Desert and Engines provide more advanced plugin functionality.
+
+== Generating 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:
+
+ * call your script/generate script and pass in whatever options they need
+ * examine the generated migration, adding/removing columns or other options as necessary
+
+This example will demonstrate how to use one of the built-in generator methods named 'migration_template' to create a migration file.  Extending the rails migration generator requires a somewhat intimate knowledge of the migration generator internals, so it's best to write a test first:
+
+*vendor/plugins/yaffle/test/yaffle_migration_generator_test.rb*
+
+[source, ruby]
+------------------------------------------------------------------
+require File.dirname(__FILE__) + '/test_helper.rb'
+require 'rails_generator'
+require 'rails_generator/scripts/generate'
+require 'rails_generator/scripts/destroy'
+
+class MigrationGeneratorTest < Test::Unit::TestCase
+
+  def fake_rails_root
+    File.join(File.dirname(__FILE__), 'rails_root')
+  end
+  
+  def file_list
+    Dir.glob(File.join(fake_rails_root, "db", "migrate", "*"))
+  end
+
+  def setup
+    FileUtils.mkdir_p(fake_rails_root)
+    @original_files = file_list
+  end
+
+  def teardown
+    FileUtils.rm_r(fake_rails_root)
+  end
+  
+  def test_generates_correct_file_name
+    Rails::Generator::Scripts::Generate.new.run(["yaffle", "some_name_nobody_is_likely_to_ever_use_in_a_real_migration"], :destination => fake_rails_root)
+    new_file = (file_list - @original_files).first
+    assert_match /add_yaffle_fields_to_some_name_nobody_is_likely_to_ever_use_in_a_real_migrations/, new_file
+    assert_match /add_column :some_name_nobody_is_likely_to_ever_use_in_a_real_migrations do |t|/, File.read(new_file)
+  end
+
+  def test_pluralizes_properly
+    ActiveRecord::Base.pluralize_table_names = false
+    Rails::Generator::Scripts::Generate.new.run(["yaffle", "some_name_nobody_is_likely_to_ever_use_in_a_real_migration"], :destination => fake_rails_root)
+    new_file = (file_list - @original_files).first
+    assert_match /add_yaffle_fields_to_some_name_nobody_is_likely_to_ever_use_in_a_real_migration/, new_file
+    assert_match /add_column :some_name_nobody_is_likely_to_ever_use_in_a_real_migration do |t|/, File.read(new_file)
+  end
+  
+end
+------------------------------------------------------------------
+
+NOTE: the migration generator checks to see if a migation already exists, and it's hard-coded to check the 'db/migrate' directory.  As a result, if your test tries to generate a migration that already exists in the app, it will fail.  The easy workaround is to make sure that the name you generate in your test is very unlikely to actually appear in the app.
+
+After running the test with 'rake' you can make it pass with:
+
+*vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb*
+
+[source, ruby]
+------------------------------------------------------------------
+class YaffleGenerator < Rails::Generator::NamedBase
+  def manifest
+    record do |m|
+      m.migration_template 'migration:migration.rb', "db/migrate", {:assigns => yaffle_local_assigns,
+        :migration_file_name => "add_yaffle_fields_to_#{custom_file_name}"
+      }
+    end
+  end
+
+  private
+    def custom_file_name
+      custom_name = class_name.underscore.downcase
+      custom_name = custom_name.pluralize if ActiveRecord::Base.pluralize_table_names
+    end
+
+    def yaffle_local_assigns
+      returning(assigns = {}) do
+        assigns[:migration_action] = "add"
+        assigns[:class_name] = "add_yaffle_fields_to_#{custom_file_name}"
+        assigns[:table_name] = custom_file_name
+        assigns[:attributes] = [Rails::Generator::GeneratedAttribute.new("last_squawk", "string")]
+      end
+    end
+end
+------------------------------------------------------------------
+
+The generator creates a new file in 'db/migrate' with a timestamp and an 'add_column' statement.  It reuses the built in rails `migration_template` method, and reuses the built-in rails migration template.
+
+It's courteous to check to see if table names are being pluralized whenever you create a generator that needs to be aware of table names.  This way people using your generator won't have to manually change the generated files if they've turned pluralization off.
+
+To run the generator, type the following at the command line:
+
+------------------------------------------------------------------
+./script/generate yaffle_migration bird
+------------------------------------------------------------------
+
+and you will see a new file:
+
+*db/migrate/20080529225649_add_yaffle_fields_to_birds.rb*
+
+[source, ruby]
+------------------------------------------------------------------
+class AddYaffleFieldsToBirds < ActiveRecord::Migration
+  def self.up
+    add_column :birds, :last_squawk, :string
+  end
+
+  def self.down
+    remove_column :birds, :last_squawk
+  end
+end
+------------------------------------------------------------------
+
diff --git a/railties/doc/guides/source/creating_plugins/models.txt b/railties/doc/guides/source/creating_plugins/models.txt
index 458edec80a..dfe11f9c4e 100644
--- a/railties/doc/guides/source/creating_plugins/models.txt
+++ b/railties/doc/guides/source/creating_plugins/models.txt
@@ -1,4 +1,4 @@
-== Add a model ==
+== Models ==
 
 This section describes how to add a model named 'Woodpecker' to your plugin that will behave the same as a model in your main app.  When storing models, controllers, views and helpers in your plugin, it's customary to keep them in directories that match the rails directories.  For this example, create a file structure like this:
 
diff --git a/railties/doc/guides/source/creating_plugins/routes.txt b/railties/doc/guides/source/creating_plugins/routes.txt
new file mode 100644
index 0000000000..cdc20e998e
--- /dev/null
+++ b/railties/doc/guides/source/creating_plugins/routes.txt
@@ -0,0 +1,69 @@
+== Routes ==
+
+Testing routes in plugins can be complex, especially if the controllers are also in the plugin itself.  Jamis Buck showed a great example of this in http://weblog.jamisbuck.org/2006/10/26/monkey-patching-rails-extending-routes-2.
+
+*vendor/plugins/yaffle/test/routing_test.rb*
+
+[source, ruby]
+--------------------------------------------------------
+require "#{File.dirname(__FILE__)}/test_helper"
+
+class RoutingTest < Test::Unit::TestCase
+
+  def setup
+    ActionController::Routing::Routes.draw do |map|
+      map.yaffles
+    end
+  end
+
+  def test_yaffles_route
+    assert_recognition :get, "/yaffles", :controller => "yaffles_controller", :action => "index"
+  end
+
+  private
+
+    # yes, I know about assert_recognizes, but it has proven problematic to
+    # use in these tests, since it uses RouteSet#recognize (which actually
+    # tries to instantiate the controller) and because it uses an awkward
+    # parameter order.
+    def assert_recognition(method, path, options)
+      result = ActionController::Routing::Routes.recognize_path(path, :method => method)
+      assert_equal options, result
+    end
+end
+--------------------------------------------------------
+
+*vendor/plugins/yaffle/init.rb*
+
+[source, ruby]
+--------------------------------------------------------
+require "routing"
+ActionController::Routing::RouteSet::Mapper.send :include, Yaffle::Routing::MapperExtensions
+--------------------------------------------------------
+
+*vendor/plugins/yaffle/lib/routing.rb*
+
+[source, ruby]
+--------------------------------------------------------
+module Yaffle #:nodoc:
+  module Routing #:nodoc:
+    module MapperExtensions
+      def yaffles
+        @set.add_route("/yaffles", {:controller => "yaffles_controller", :action => "index"})
+      end
+    end
+  end
+end
+--------------------------------------------------------
+
+*config/routes.rb*
+
+[source, ruby]
+--------------------------------------------------------
+ActionController::Routing::Routes.draw do |map|
+  ...
+  map.yaffles
+end
+--------------------------------------------------------
+
+You can also see if your routes work by running `rake routes` from your app directory.
diff --git a/railties/doc/guides/source/creating_plugins/setup.txt b/railties/doc/guides/source/creating_plugins/setup.txt
new file mode 100644
index 0000000000..fcf5b459e6
--- /dev/null
+++ b/railties/doc/guides/source/creating_plugins/setup.txt
@@ -0,0 +1,64 @@
+== Setup ==
+
+=== Create the basic app ===
+
+The examples in this guide require that you have a working rails application.  To create a simple rails app execute:
+
+------------------------------------------------
+gem install rails
+rails yaffle_guide
+cd yaffle_guide
+script/generate scaffold bird name:string
+rake db:migrate
+script/server
+------------------------------------------------
+
+Then navigate to http://localhost:3000/birds.  Make sure you have a functioning rails app before continuing.
+
+.Editor's note:
+NOTE: The aforementioned instructions will work for sqlite3.  For more detailed instructions on how to create a rails app for other databases see the API docs.
+
+
+=== Generate the plugin skeleton ===
+
+Rails ships with a plugin generator which creates a basic plugin skeleton. Pass the plugin name, either 'CamelCased' or 'under_scored', as an argument. Pass `\--with-generator` to add an example generator also.
+
+This creates a plugin in 'vendor/plugins' including an 'init.rb' and 'README' as well as standard 'lib', 'task', and 'test' directories.
+
+Examples:
+----------------------------------------------
+./script/generate plugin yaffle
+./script/generate plugin yaffle --with-generator
+----------------------------------------------
+
+To get more detailed help on the plugin generator, type `./script/generate plugin`.
+
+Later on this guide will describe how to work with generators, so go ahead and generate your plugin with the `\--with-generator` option now:
+
+----------------------------------------------
+./script/generate plugin yaffle --with-generator
+----------------------------------------------
+
+You should see the following output:
+
+----------------------------------------------
+create  vendor/plugins/yaffle/lib
+create  vendor/plugins/yaffle/tasks
+create  vendor/plugins/yaffle/test
+create  vendor/plugins/yaffle/README
+create  vendor/plugins/yaffle/MIT-LICENSE
+create  vendor/plugins/yaffle/Rakefile
+create  vendor/plugins/yaffle/init.rb
+create  vendor/plugins/yaffle/install.rb
+create  vendor/plugins/yaffle/uninstall.rb
+create  vendor/plugins/yaffle/lib/yaffle.rb
+create  vendor/plugins/yaffle/tasks/yaffle_tasks.rake
+create  vendor/plugins/yaffle/test/core_ext_test.rb
+create  vendor/plugins/yaffle/generators
+create  vendor/plugins/yaffle/generators/yaffle
+create  vendor/plugins/yaffle/generators/yaffle/templates
+create  vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb
+create  vendor/plugins/yaffle/generators/yaffle/USAGE
+----------------------------------------------
+
+To begin just change one thing - move 'init.rb' to 'rails/init.rb'.
diff --git a/railties/doc/guides/source/creating_plugins/test_setup.txt b/railties/doc/guides/source/creating_plugins/test_setup.txt
deleted file mode 100644
index 64236ff110..0000000000
--- a/railties/doc/guides/source/creating_plugins/test_setup.txt
+++ /dev/null
@@ -1,230 +0,0 @@
-== Preparation ==
-
-=== Create the basic app ===
-
-The examples in this guide require that you have a working rails application.  To create a simple rails app execute:
-
-------------------------------------------------
-gem install rails
-rails yaffle_guide
-cd yaffle_guide
-script/generate scaffold bird name:string
-rake db:migrate
-script/server
-------------------------------------------------
-
-Then navigate to http://localhost:3000/birds.  Make sure you have a functioning rails app before continuing.
-
-.Editor's note:
-NOTE: The aforementioned instructions will work for sqlite3.  For more detailed instructions on how to create a rails app for other databases see the API docs.
-
-
-=== Generate the plugin skeleton ===
-
-Rails ships with a plugin generator which creates a basic plugin skeleton. Pass the plugin name, either 'CamelCased' or 'under_scored', as an argument. Pass `\--with-generator` to add an example generator also.
-
-This creates a plugin in 'vendor/plugins' including an 'init.rb' and 'README' as well as standard 'lib', 'task', and 'test' directories.
-
-Examples:
-----------------------------------------------
-./script/generate plugin yaffle
-./script/generate plugin yaffle --with-generator
-----------------------------------------------
-
-To get more detailed help on the plugin generator, type `./script/generate plugin`.
-
-Later on this guide will describe how to work with generators, so go ahead and generate your plugin with the `\--with-generator` option now:
-
-----------------------------------------------
-./script/generate plugin yaffle --with-generator
-----------------------------------------------
-
-You should see the following output:
-
-----------------------------------------------
-create  vendor/plugins/yaffle/lib
-create  vendor/plugins/yaffle/tasks
-create  vendor/plugins/yaffle/test
-create  vendor/plugins/yaffle/README
-create  vendor/plugins/yaffle/MIT-LICENSE
-create  vendor/plugins/yaffle/Rakefile
-create  vendor/plugins/yaffle/init.rb
-create  vendor/plugins/yaffle/install.rb
-create  vendor/plugins/yaffle/uninstall.rb
-create  vendor/plugins/yaffle/lib/yaffle.rb
-create  vendor/plugins/yaffle/tasks/yaffle_tasks.rake
-create  vendor/plugins/yaffle/test/core_ext_test.rb
-create  vendor/plugins/yaffle/generators
-create  vendor/plugins/yaffle/generators/yaffle
-create  vendor/plugins/yaffle/generators/yaffle/templates
-create  vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb
-create  vendor/plugins/yaffle/generators/yaffle/USAGE
-----------------------------------------------
-
-To begin just change one thing - move 'init.rb' to 'rails/init.rb'.
-
-=== Setup the plugin for testing ===
-
-If your plugin interacts with a database, you'll need to setup a database connection.  In this guide you will learn how to test your plugin against multiple different database adapters using Active Record.  This guide will not cover how to use fixtures in plugin tests.
-
-To setup your plugin to allow for easy testing you'll need to add 3 files:
-
- * A 'database.yml' file with all of your connection strings
- * A 'schema.rb' file with your table definitions
- * A test helper method that sets up the database
-
-*vendor/plugins/yaffle/test/database.yml:*
-
-----------------------------------------------
-sqlite:
-  :adapter: sqlite
-  :dbfile: vendor/plugins/yaffle/test/yaffle_plugin.sqlite.db
-
-sqlite3:
-  :adapter: sqlite3
-  :dbfile: vendor/plugins/yaffle/test/yaffle_plugin.sqlite3.db
-
-postgresql:
-  :adapter: postgresql
-  :username: postgres
-  :password: postgres
-  :database: yaffle_plugin_test
-  :min_messages: ERROR
-
-mysql:
-  :adapter: mysql
-  :host: localhost
-  :username: root
-  :password: password
-  :database: yaffle_plugin_test
-----------------------------------------------
-
-For this guide you'll need 2 tables/models, Hickwalls and Wickwalls, so add the following:
-
-*vendor/plugins/yaffle/test/schema.rb:*
-
-[source, ruby]
-----------------------------------------------
-ActiveRecord::Schema.define(:version => 0) do
-  create_table :hickwalls, :force => true do |t|
-    t.string :name
-    t.string :last_squawk
-    t.datetime :last_squawked_at
-  end
-  create_table :wickwalls, :force => true do |t|
-    t.string :name
-    t.string :last_tweet
-    t.datetime :last_tweeted_at
-  end
-  create_table :woodpeckers, :force => true do |t|
-    t.string :name
-  end
-end
-----------------------------------------------
-
-*vendor/plugins/yaffle/test/test_helper.rb:*
-
-[source, ruby]
-----------------------------------------------
-ENV['RAILS_ENV'] = 'test'
-ENV['RAILS_ROOT'] ||= File.dirname(__FILE__) + '/../../../..'
-
-require 'test/unit'
-require File.expand_path(File.join(ENV['RAILS_ROOT'], 'config/environment.rb'))
-
-def load_schema
-  config = YAML::load(IO.read(File.dirname(__FILE__) + '/database.yml'))
-  ActiveRecord::Base.logger = Logger.new(File.dirname(__FILE__) + "/debug.log")
-
-  db_adapter = ENV['DB']
-
-  # no db passed, try one of these fine config-free DBs before bombing.
-  db_adapter ||=
-    begin
-      require 'rubygems'
-      require 'sqlite'
-      'sqlite'
-    rescue MissingSourceFile
-      begin
-        require 'sqlite3'
-        'sqlite3'
-      rescue MissingSourceFile
-      end
-    end
-
-  if db_adapter.nil?
-    raise "No DB Adapter selected. Pass the DB= option to pick one, or install Sqlite or Sqlite3."
-  end
-
-  ActiveRecord::Base.establish_connection(config[db_adapter])
-  load(File.dirname(__FILE__) + "/schema.rb")
-  require File.dirname(__FILE__) + '/../rails/init.rb'
-end
-----------------------------------------------
-
-Now whenever you write a test that requires the database, you can call 'load_schema'.
-
-=== Run the plugin tests ===
-
-Once you have these files in place, you can write your first test to ensure that your plugin-testing setup is correct.  By default rails generates a file in 'vendor/plugins/yaffle/test/yaffle_test.rb' with a sample test.  Replace the contents of that file with:
-
-*vendor/plugins/yaffle/test/yaffle_test.rb:*
-
-[source, ruby]
-----------------------------------------------
-require File.dirname(__FILE__) + '/test_helper.rb'
-
-class YaffleTest < Test::Unit::TestCase
-  load_schema
-  
-  class Hickwall < ActiveRecord::Base
-  end
-
-  class Wickwall < ActiveRecord::Base
-  end
-  
-  def test_schema_has_loaded_correctly
-    assert_equal [], Hickwall.all
-    assert_equal [], Wickwall.all
-  end
-  
-end
-----------------------------------------------
-
-To run this, go to the plugin directory and run `rake`:
-
-----------------------------------------------
-cd vendor/plugins/yaffle
-rake
-----------------------------------------------
-
-You should see output like:
-
-----------------------------------------------
-/opt/local/bin/ruby -Ilib:lib "/opt/local/lib/ruby/gems/1.8/gems/rake-0.8.3/lib/rake/rake_test_loader.rb" "test/yaffle_test.rb" 
--- create_table(:hickwalls, {:force=>true})
-   -> 0.0220s
--- create_table(:wickwalls, {:force=>true})
-   -> 0.0077s
--- initialize_schema_migrations_table()
-   -> 0.0007s
--- assume_migrated_upto_version(0)
-   -> 0.0007s
-Loaded suite /opt/local/lib/ruby/gems/1.8/gems/rake-0.8.3/lib/rake/rake_test_loader
-Started
-.
-Finished in 0.002236 seconds.
-
-1 test, 1 assertion, 0 failures, 0 errors
-----------------------------------------------
-
-By default the setup above runs your tests with sqlite or sqlite3.  To run tests with one of the other connection strings specified in database.yml, pass the DB environment variable to rake:
-
-----------------------------------------------
-rake DB=sqlite
-rake DB=sqlite3
-rake DB=mysql
-rake DB=postgresql
-----------------------------------------------
-
-Now you are ready to test-drive your plugin!
diff --git a/railties/doc/guides/source/creating_plugins/tests.txt b/railties/doc/guides/source/creating_plugins/tests.txt
new file mode 100644
index 0000000000..ef6dab2f9f
--- /dev/null
+++ b/railties/doc/guides/source/creating_plugins/tests.txt
@@ -0,0 +1,165 @@
+== Tests ==
+
+If your plugin interacts with a database, you'll need to setup a database connection.  In this guide you will learn how to test your plugin against multiple different database adapters using Active Record.  This guide will not cover how to use fixtures in plugin tests.
+
+To setup your plugin to allow for easy testing you'll need to add 3 files:
+
+ * A 'database.yml' file with all of your connection strings
+ * A 'schema.rb' file with your table definitions
+ * A test helper method that sets up the database
+
+*vendor/plugins/yaffle/test/database.yml:*
+
+----------------------------------------------
+sqlite:
+  :adapter: sqlite
+  :dbfile: vendor/plugins/yaffle/test/yaffle_plugin.sqlite.db
+
+sqlite3:
+  :adapter: sqlite3
+  :dbfile: vendor/plugins/yaffle/test/yaffle_plugin.sqlite3.db
+
+postgresql:
+  :adapter: postgresql
+  :username: postgres
+  :password: postgres
+  :database: yaffle_plugin_test
+  :min_messages: ERROR
+
+mysql:
+  :adapter: mysql
+  :host: localhost
+  :username: root
+  :password: password
+  :database: yaffle_plugin_test
+----------------------------------------------
+
+For this guide you'll need 2 tables/models, Hickwalls and Wickwalls, so add the following:
+
+*vendor/plugins/yaffle/test/schema.rb:*
+
+[source, ruby]
+----------------------------------------------
+ActiveRecord::Schema.define(:version => 0) do
+  create_table :hickwalls, :force => true do |t|
+    t.string :name
+    t.string :last_squawk
+    t.datetime :last_squawked_at
+  end
+  create_table :wickwalls, :force => true do |t|
+    t.string :name
+    t.string :last_tweet
+    t.datetime :last_tweeted_at
+  end
+  create_table :woodpeckers, :force => true do |t|
+    t.string :name
+  end
+end
+----------------------------------------------
+
+*vendor/plugins/yaffle/test/test_helper.rb:*
+
+[source, ruby]
+----------------------------------------------
+ENV['RAILS_ENV'] = 'test'
+ENV['RAILS_ROOT'] ||= File.dirname(__FILE__) + '/../../../..'
+
+require 'test/unit'
+require File.expand_path(File.join(ENV['RAILS_ROOT'], 'config/environment.rb'))
+
+def load_schema
+  config = YAML::load(IO.read(File.dirname(__FILE__) + '/database.yml'))
+  ActiveRecord::Base.logger = Logger.new(File.dirname(__FILE__) + "/debug.log")
+
+  db_adapter = ENV['DB']
+
+  # no db passed, try one of these fine config-free DBs before bombing.
+  db_adapter ||=
+    begin
+      require 'rubygems'
+      require 'sqlite'
+      'sqlite'
+    rescue MissingSourceFile
+      begin
+        require 'sqlite3'
+        'sqlite3'
+      rescue MissingSourceFile
+      end
+    end
+
+  if db_adapter.nil?
+    raise "No DB Adapter selected. Pass the DB= option to pick one, or install Sqlite or Sqlite3."
+  end
+
+  ActiveRecord::Base.establish_connection(config[db_adapter])
+  load(File.dirname(__FILE__) + "/schema.rb")
+  require File.dirname(__FILE__) + '/../rails/init.rb'
+end
+----------------------------------------------
+
+Now whenever you write a test that requires the database, you can call 'load_schema'.
+
+=== Run the plugin tests ===
+
+Once you have these files in place, you can write your first test to ensure that your plugin-testing setup is correct.  By default rails generates a file in 'vendor/plugins/yaffle/test/yaffle_test.rb' with a sample test.  Replace the contents of that file with:
+
+*vendor/plugins/yaffle/test/yaffle_test.rb:*
+
+[source, ruby]
+----------------------------------------------
+require File.dirname(__FILE__) + '/test_helper.rb'
+
+class YaffleTest < Test::Unit::TestCase
+  load_schema
+  
+  class Hickwall < ActiveRecord::Base
+  end
+
+  class Wickwall < ActiveRecord::Base
+  end
+  
+  def test_schema_has_loaded_correctly
+    assert_equal [], Hickwall.all
+    assert_equal [], Wickwall.all
+  end
+  
+end
+----------------------------------------------
+
+To run this, go to the plugin directory and run `rake`:
+
+----------------------------------------------
+cd vendor/plugins/yaffle
+rake
+----------------------------------------------
+
+You should see output like:
+
+----------------------------------------------
+/opt/local/bin/ruby -Ilib:lib "/opt/local/lib/ruby/gems/1.8/gems/rake-0.8.3/lib/rake/rake_test_loader.rb" "test/yaffle_test.rb" 
+-- create_table(:hickwalls, {:force=>true})
+   -> 0.0220s
+-- create_table(:wickwalls, {:force=>true})
+   -> 0.0077s
+-- initialize_schema_migrations_table()
+   -> 0.0007s
+-- assume_migrated_upto_version(0)
+   -> 0.0007s
+Loaded suite /opt/local/lib/ruby/gems/1.8/gems/rake-0.8.3/lib/rake/rake_test_loader
+Started
+.
+Finished in 0.002236 seconds.
+
+1 test, 1 assertion, 0 failures, 0 errors
+----------------------------------------------
+
+By default the setup above runs your tests with sqlite or sqlite3.  To run tests with one of the other connection strings specified in database.yml, pass the DB environment variable to rake:
+
+----------------------------------------------
+rake DB=sqlite
+rake DB=sqlite3
+rake DB=mysql
+rake DB=postgresql
+----------------------------------------------
+
+Now you are ready to test-drive your plugin!
diff --git a/railties/doc/guides/source/stylesheets/base.css b/railties/doc/guides/source/stylesheets/base.css
index 76ee6e2ca9..1cf0a3de98 100644
--- a/railties/doc/guides/source/stylesheets/base.css
+++ b/railties/doc/guides/source/stylesheets/base.css
@@ -97,6 +97,10 @@ ul li {
 	background-position:		0 0.55em;
 }
 
+ul li p {
+  margin-bottom: 0.5em;
+}
+
 /* ----------------------------------------------------------------------------
 	Structure
 ---------------------------------------------------------------------------- */
-- 
cgit v1.2.3