Plugin Guide: cleaned up file paths, made formatting more consistent

7 files changed, 62 insertions, 54 deletions

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 12d40deb18..06878543e4 100644
--- a/railties/doc/guides/source/creating_plugins/acts_as_yaffle.txt
+++ b/railties/doc/guides/source/creating_plugins/acts_as_yaffle.txt
@@ -4,10 +4,10 @@ A common pattern in plugins is to add a method called `acts_as_something` to mod
 
 To keep things clean, create a new test file called 'acts_as_yaffle_test.rb' in your plugin's test directory and require your test helper.
 
+*vendor/plugins/yaffle/test/acts_as_yaffle_test.rb*
+
 [source, ruby]
 ------------------------------------------------------
-# File: vendor/plugins/yaffle/test/acts_as_yaffle_test.rb
-
 require File.dirname(__FILE__) + '/test_helper.rb'
 
 class Hickwall < ActiveRecord::Base
@@ -18,16 +18,18 @@ class ActsAsYaffleTest < Test::Unit::TestCase
 end
 ------------------------------------------------------
 
+*vendor/plugins/lib/acts_as_yaffle.rb*
+
 [source, ruby]
 ------------------------------------------------------
-# File: vendor/plugins/lib/acts_as_yaffle.rb
-
 module Yaffle
 end
 ------------------------------------------------------
 
 One of the most common plugin patterns for `acts_as_yaffle` plugins is to structure your file like so:
 
+*vendor/plugins/lib/acts_as_yaffle.rb*
+
 [source, ruby]
 ------------------------------------------------------
 module Yaffle
@@ -65,10 +67,10 @@ end
 
 Now that test should pass.  Since your plugin is going to work with field names, you need to allow people to define the field names, in case there is a naming conflict.  You can write a few simple tests for this:
 
+*vendor/plugins/yaffle/test/acts_as_yaffle_test.rb*
+
 [source, ruby]
 ------------------------------------------------------
-# File: vendor/plugins/yaffle/test/acts_as_yaffle_test.rb
-
 require File.dirname(__FILE__) + '/test_helper.rb'
 
 class ActsAsYaffleTest < Test::Unit::TestCase
@@ -92,10 +94,10 @@ end
 
 To make these tests pass, you could modify your `acts_as_yaffle` file like so:
 
+*vendor/plugins/yaffle/lib/acts_as_yaffle.rb*
+
 [source, ruby]
 ------------------------------------------------------
-# File: vendor/plugins/yaffle/lib/acts_as_yaffle.rb
-
 module Yaffle
   def self.included(base)
     base.send :extend, ClassMethods
@@ -117,10 +119,10 @@ end
 
 Now you can add tests for the instance methods, and the instance method itself:
 
+*vendor/plugins/yaffle/test/acts_as_yaffle_test.rb*
+
 [source, ruby]
 ------------------------------------------------------
-# File: vendor/plugins/yaffle/test/acts_as_yaffle_test.rb
-
 require File.dirname(__FILE__) + '/test_helper.rb'
 
 class ActsAsYaffleTest < Test::Unit::TestCase
@@ -163,10 +165,10 @@ class ActsAsYaffleTest < Test::Unit::TestCase
 end
 ------------------------------------------------------
 
+*vendor/plugins/yaffle/lib/acts_as_yaffle.rb*
+
 [source, ruby]
 ------------------------------------------------------
-# File: vendor/plugins/yaffle/lib/acts_as_yaffle.rb
-
 module Yaffle
   def self.included(base)
     base.send :extend, ClassMethods
@@ -190,4 +192,5 @@ module Yaffle
 end
 ------------------------------------------------------
 
-Note the use of `write_attribute` to write to the field in model.
+.Editor's note:
+NOTE: The use of `write_attribute` to write to the field in model is just one example of how a plugin can interact with the model, and will not always be the right method to use.  For example, you could also use `send("#{self.class.yaffle_text_field}=", string.to_squawk)`.
diff --git a/railties/doc/guides/source/creating_plugins/custom_generator.txt b/railties/doc/guides/source/creating_plugins/custom_generator.txt
index 6d9613ea01..a8cf1b48ce 100644
--- a/railties/doc/guides/source/creating_plugins/custom_generator.txt
+++ b/railties/doc/guides/source/creating_plugins/custom_generator.txt
@@ -8,19 +8,20 @@ You may have noticed above that you can used one of the built-in rails migration
 
 Working with the internals of generators is beyond the scope of this tutorial, but here is a basic example:
 
+*vendor/plugins/yaffle/init.rb*
+
 [source, ruby]
 -----------------------------------------------------------
-# File: vendor/plugins/yaffle/init.rb
 require "commands"
 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
 -----------------------------------------------------------
 
+*vendor/plugins/yaffle/lib/commands.rb*
+
 [source, ruby]
 -----------------------------------------------------------
-# File: vendor/plugins/yaffle/lib/commands.rb
-
 require 'rails_generator'
 require 'rails_generator/commands'
 
@@ -49,16 +50,15 @@ module Yaffle #:nodoc:
 end
 -----------------------------------------------------------
 
+*vendor/plugins/yaffle/generators/yaffle/templates/definition.txt*
 -----------------------------------------------------------
-# File: vendor/plugins/yaffle/generators/yaffle/templates/definition.txt
-
 Yaffle is a bird
 -----------------------------------------------------------
 
+*vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb*
+
 [source, ruby]
 -----------------------------------------------------------
-# File: vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb
-
 class YaffleGenerator < Rails::Generator::NamedBase
   def manifest
     m.yaffle_definition
diff --git a/railties/doc/guides/source/creating_plugins/custom_route.txt b/railties/doc/guides/source/creating_plugins/custom_route.txt
index 7e399247ee..1fce902a4e 100644
--- a/railties/doc/guides/source/creating_plugins/custom_route.txt
+++ b/railties/doc/guides/source/creating_plugins/custom_route.txt
@@ -2,10 +2,10 @@
 
 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]
 --------------------------------------------------------
-# File: vendor/plugins/yaffle/test/routing_test.rb
-
 require "#{File.dirname(__FILE__)}/test_helper"
 
 class RoutingTest < Test::Unit::TestCase
@@ -33,18 +33,18 @@ class RoutingTest < Test::Unit::TestCase
 end
 --------------------------------------------------------
 
+*vendor/plugins/yaffle/init.rb*
+
 [source, ruby]
 --------------------------------------------------------
-# File: vendor/plugins/yaffle/init.rb
-
 require "routing"
 ActionController::Routing::RouteSet::Mapper.send :include, Yaffle::Routing::MapperExtensions
 --------------------------------------------------------
 
+*vendor/plugins/yaffle/lib/routing.rb*
+
 [source, ruby]
 --------------------------------------------------------
-# File: vendor/plugins/yaffle/lib/routing.rb
-
 module Yaffle #:nodoc:
   module Routing #:nodoc:
     module MapperExtensions
@@ -56,10 +56,10 @@ module Yaffle #:nodoc:
 end
 --------------------------------------------------------
 
+*config/routes.rb*
+
 [source, ruby]
 --------------------------------------------------------
-# File: config/routes.rb
-
 ActionController::Routing::Routes.draw do |map|
   ...
   map.yaffles
diff --git a/railties/doc/guides/source/creating_plugins/migration_generator.txt b/railties/doc/guides/source/creating_plugins/migration_generator.txt
index 598a0c8437..1a477a69ab 100644
--- a/railties/doc/guides/source/creating_plugins/migration_generator.txt
+++ b/railties/doc/guides/source/creating_plugins/migration_generator.txt
@@ -6,11 +6,15 @@ We'll be relying on the built-in rails generate template for this tutorial.  Goi
 
 Type:
 
-    script/generate
+------------------------------------------------------------------
+script/generate
+------------------------------------------------------------------
 
 You should see the line:
 
-    Plugins (vendor/plugins): yaffle
+------------------------------------------------------------------
+Plugins (vendor/plugins): yaffle
+------------------------------------------------------------------
 
 When you run `script/generate yaffle` you should see the contents of your USAGE file.  For this plugin, the USAGE file looks like this:
 
@@ -27,10 +31,10 @@ Example:
 
 Now you can add code to your generator:
 
+*vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb*
+
 [source, ruby]
 ------------------------------------------------------------------
-# File: vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb
-
 class YaffleGenerator < Rails::Generator::NamedBase
   def manifest
     record do |m|
@@ -67,14 +71,16 @@ This does a few things:
 
 When you run the generator like
 
-    script/generate yaffle bird
+------------------------------------------------------------------
+script/generate yaffle bird
+------------------------------------------------------------------
 
 You will see a new file:
 
+*db/migrate/20080529225649_add_yaffle_fields_to_birds.rb*
+
 [source, ruby]
 ------------------------------------------------------------------
-# File: db/migrate/20080529225649_add_yaffle_fields_to_birds.rb
-
 class AddYaffleFieldsToBirds < ActiveRecord::Migration
   def self.up
     add_column :birds, :last_squawk, :string
diff --git a/railties/doc/guides/source/creating_plugins/odds_and_ends.txt b/railties/doc/guides/source/creating_plugins/odds_and_ends.txt
index 32da7ed7f3..88cd4fe9ed 100644
--- a/railties/doc/guides/source/creating_plugins/odds_and_ends.txt
+++ b/railties/doc/guides/source/creating_plugins/odds_and_ends.txt
@@ -81,10 +81,10 @@ When you created the plugin with the built-in rails generator, it generated a ra
 
 Many plugin authors put all of their rake tasks into a common namespace that is the same as the plugin, like so:
 
+*vendor/plugins/yaffle/tasks/yaffle.rake*
+
 [source, ruby]
 ---------------------------------------------------------
-# File: vendor/plugins/yaffle/tasks/yaffle.rake
-
 namespace :yaffle do
   desc "Prints out the word 'Yaffle'"
   task :squawk => :environment do
diff --git a/railties/doc/guides/source/creating_plugins/string_to_squawk.txt b/railties/doc/guides/source/creating_plugins/string_to_squawk.txt
index 50516cef69..63f1131442 100644
--- a/railties/doc/guides/source/creating_plugins/string_to_squawk.txt
+++ b/railties/doc/guides/source/creating_plugins/string_to_squawk.txt
@@ -10,10 +10,10 @@ Most plugins store their code classes in the plugin's lib directory.  When you a
 
 First, you need to write the tests.  Testing plugins is very similar to testing rails apps.  The generated test file should look something like this:
 
+*vendor/plugins/yaffle/test/core_ext_test.rb*
+
 [source, ruby]
 --------------------------------------------------------
-# File: vendor/plugins/yaffle/test/core_ext_test.rb
-
 require 'test/unit'
 
 class CoreExtTest < Test::Unit::TestCase
@@ -26,11 +26,10 @@ end
 
 Start off by removing the default test, and adding a require statement for your test helper.
 
+*vendor/plugins/yaffle/test/core_ext_test.rb*
+
 [source, ruby]
 --------------------------------------------------------
-# File: vendor/plugins/yaffle/test/core_ext_test.rb
-
-require 'test/unit'
 require File.dirname(__FILE__) + '/test_helper.rb'
 
 class CoreExtTest < Test::Unit::TestCase
@@ -53,10 +52,10 @@ No tests were specified
 
 Great - now you are ready to start development.  The first thing we'll do is to add a method to String called `to_squawk` which will prefix the string with the word ``squawk!''.  The test will look something like this:
 
+*vendor/plugins/yaffle/init.rb*
+
 [source, ruby]
 --------------------------------------------------------
-# File: vendor/plugins/yaffle/init.rb
-
 class CoreExtTest < Test::Unit::TestCase
   def test_string_should_respond_to_squawk
     assert_equal true, "".respond_to?(:to_squawk)
@@ -72,17 +71,17 @@ class CoreExtTest < Test::Unit::TestCase
 end
 --------------------------------------------------------
 
+*vendor/plugins/yaffle/init.rb*
+
 [source, ruby]
 --------------------------------------------------------
-# File: vendor/plugins/yaffle/init.rb
-
 require "core_ext"
 --------------------------------------------------------
 
+*vendor/plugins/yaffle/lib/core_ext.rb*
+
 [source, ruby]
 --------------------------------------------------------
-# File: vendor/plugins/yaffle/lib/core_ext.rb
-
 String.class_eval do
   def to_squawk
     "squawk! #{self}".strip
diff --git a/railties/doc/guides/source/creating_plugins/view_helper.txt b/railties/doc/guides/source/creating_plugins/view_helper.txt
index b03a190e1a..4eaec93824 100644
--- a/railties/doc/guides/source/creating_plugins/view_helper.txt
+++ b/railties/doc/guides/source/creating_plugins/view_helper.txt
@@ -8,10 +8,10 @@ Creating a view helper is a 3-step process:
 
 First, create the test to define the functionality you want:
 
+*vendor/plugins/yaffle/test/view_helpers_test.rb*
+
 [source, ruby]
 ---------------------------------------------------------------
-# File: vendor/plugins/yaffle/test/view_helpers_test.rb
-
 require File.dirname(__FILE__) + '/test_helper.rb'
 include YaffleViewHelper
 
@@ -28,20 +28,20 @@ end
 
 Then add the following statements to init.rb:
 
+*vendor/plugins/yaffle/init.rb*
+
 [source, ruby]
 ---------------------------------------------------------------
-# File: vendor/plugins/yaffle/init.rb
-
 require "view_helpers"
 ActionView::Base.send :include, YaffleViewHelper
 ---------------------------------------------------------------
 
 Then add the view helpers file and
 
+*vendor/plugins/yaffle/lib/view_helpers.rb*
+
 [source, ruby]
 ---------------------------------------------------------------
-# File: vendor/plugins/yaffle/lib/view_helpers.rb
-
 module YaffleViewHelper
   def squawk_info_for(yaffle)
     returning "" do |result|