Merge branch 'master' of git@github.com:lifo/docrails

* 'master' of git@github.com:lifo/docrails:
  Updates to nested/shallow routes discussion in "Routing from the Outside In" guide.
  Add an index file for the guides.
  Get rid of the work-in-progress 'book' that's supposed to be based on Django's book.
  Add migrations guide to guide HTML generation task.
  Change over examples to use {{count}} and {{value}} instead of %d and %s.

activerecord/lib/active_record/validations.rb

@@ -509,13 +509,13 @@ def validates_presence_of(*attr_names)
       #
       #   class Person < ActiveRecord::Base
       #     validates_length_of :first_name, :maximum=>30
-      #     validates_length_of :last_name, :maximum=>30, :message=>"less than %d if you don't mind"
+      #     validates_length_of :last_name, :maximum=>30, :message=>"less than {{count}} if you don't mind"
       #     validates_length_of :fax, :in => 7..32, :allow_nil => true
       #     validates_length_of :phone, :in => 7..32, :allow_blank => true
       #     validates_length_of :user_name, :within => 6..20, :too_long => "pick a shorter name", :too_short => "pick a longer name"
-      #     validates_length_of :fav_bra_size, :minimum => 1, :too_short => "please enter at least %d character"
-      #     validates_length_of :smurf_leader, :is => 4, :message => "papa is spelled with %d characters... don't play me."
-      #     validates_length_of :essay, :minimum => 100, :too_short => "Your essay must be at least %d words."), :tokenizer => lambda {|str| str.scan(/\w+/) }
+      #     validates_length_of :fav_bra_size, :minimum => 1, :too_short => "please enter at least {{count}} character"
+      #     validates_length_of :smurf_leader, :is => 4, :message => "papa is spelled with {{count}} characters... don't play me."
+      #     validates_length_of :essay, :minimum => 100, :too_short => "Your essay must be at least {{count}} words."), :tokenizer => lambda {|str| str.scan(/\w+/) }
       #   end
       #
       # Configuration options:
@@ -526,9 +526,9 @@ def validates_presence_of(*attr_names)
       # * <tt>:in</tt> - A synonym(or alias) for <tt>:within</tt>.
       # * <tt>:allow_nil</tt> - Attribute may be +nil+; skip validation.
       # * <tt>:allow_blank</tt> - Attribute may be blank; skip validation.
-      # * <tt>:too_long</tt> - The error message if the attribute goes over the maximum (default is: "is too long (maximum is %d characters)").
-      # * <tt>:too_short</tt> - The error message if the attribute goes under the minimum (default is: "is too short (min is %d characters)").
-      # * <tt>:wrong_length</tt> - The error message if using the <tt>:is</tt> method and the attribute is the wrong size (default is: "is the wrong length (should be %d characters)").
+      # * <tt>:too_long</tt> - The error message if the attribute goes over the maximum (default is: "is too long (maximum is {{count}} characters)").
+      # * <tt>:too_short</tt> - The error message if the attribute goes under the minimum (default is: "is too short (min is {{count}} characters)").
+      # * <tt>:wrong_length</tt> - The error message if using the <tt>:is</tt> method and the attribute is the wrong size (default is: "is the wrong length (should be {{count}} characters)").
       # * <tt>:message</tt> - The error message to use for a <tt>:minimum</tt>, <tt>:maximum</tt>, or <tt>:is</tt> violation.  An alias of the appropriate <tt>too_long</tt>/<tt>too_short</tt>/<tt>wrong_length</tt> message.
       # * <tt>:on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>).
       # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
@@ -731,7 +731,7 @@ def validates_format_of(*attr_names)
       #   class Person < ActiveRecord::Base
       #     validates_inclusion_of :gender, :in => %w( m f ), :message => "woah! what are you then!??!!"
       #     validates_inclusion_of :age, :in => 0..99
-      #     validates_inclusion_of :format, :in => %w( jpg gif png ), :message => "extension %s is not included in the list"
+      #     validates_inclusion_of :format, :in => %w( jpg gif png ), :message => "extension {{value}} is not included in the list"
       #   end
       #
       # Configuration options:
@@ -765,7 +765,7 @@ def validates_inclusion_of(*attr_names)
       #   class Person < ActiveRecord::Base
       #     validates_exclusion_of :username, :in => %w( admin superuser ), :message => "You don't belong here"
       #     validates_exclusion_of :age, :in => 30..60, :message => "This site is only for under 30 and over 60"
-      #     validates_exclusion_of :format, :in => %w( mov avi ), :message => "extension %s is not allowed"
+      #     validates_exclusion_of :format, :in => %w( mov avi ), :message => "extension {{value}} is not allowed"
       #   end
       #
       # Configuration options:

railties/Rakefile

@@ -272,14 +272,19 @@ Rake::RDocTask.new { |rdoc|
   rdoc.rdoc_files.include('lib/commands/**/*.rb')
 }
 
+# In this array, one defines the guides for which HTML output should be
+# generated. Specify the folder names of the guides. If the .txt filename
+# doesn't equal its folder name, then specify a hash: { 'folder_name' => 'filename.txt' }
 guides = [
   'securing_rails_applications',
   'testing_rails_applications',
   'creating_plugins',
+  'migrations',
   { 'routing' => 'routing_outside_in' },
   { 'debugging' => 'debugging_rails_applications' }
 ]
-guides_html_files = []
+
+guides_html_files = []  # autogenerated from the 'guides' variable.
 guides.each do |entry|
   if entry.is_a?(Hash)
     guide_folder = entry.keys.first
@@ -296,8 +301,13 @@ guides.each do |entry|
   end
 end
 
+file 'doc/guides/index.html' => 'doc/guides/index.txt' do
+  sh "mizuho", 'doc/guides/index.txt', "--template", "manualsonrails", "--icons-dir", "icons"
+end
+
 desc "Generate HTML output for the guides"
 task :generate_guides => guides_html_files
+task :generate_guides => 'doc/guides/index.html'
 
 # Generate GEM ----------------------------------------------------------------------------
 

railties/doc/guides/index.txt

@@ -1,21 +1,9 @@
-The Book on Rails
-=================
-
-This book is about Ruby on Rails, a web development framework that saves you time and makes web development a joy. Using Ruby on Rails, you can build and maintain high-quality web applications with minimal fuss.
-
-At its best, web development is an exciting, creative act; at its worst, it can be a repetitive, frustrating nuisance. Ruby on Rails lets you focus on the fun stuff -- the crux of your web application -- while easing the pain of the repetitive bits. In doing so, it provides high-level abstractions of common web development patterns, shortcuts for frequent programming tasks, and clear conventions for how to solve problems.
-
-The goal of this book is to make you familiar with Ruby on Rails. This book assumes that you are already familiar with Ruby -- the programming language that Ruby on Rails is written in -- and that you have basic knowledge about HTML and web development.
-
-The focus of this book is twofold. First, we explain, in depth, what Ruby on Rails does and how to build web applications with it. Second, we discuss higher-level concepts where appropriate, answering the question ``How can I apply these tools effectively in my own projects?'' By reading this book, you'll learn the skills needed to develop powerful web sites quickly, with code that is clean and easy to maintain.
-
-== Introduction to Ruby on Rails ==
-include::introduction.txt[]
-
-== Installing Ruby on Rails ==
-include::installing_rails.txt[]
-
-== Creating a New Rails Project ==
-
-== Deploying Ruby on Rails ==
-
+Ruby on Rails guides
+====================
+
+* link:migrations/migrations.html[Guide to Rails Database Migrations]
+* link:testing_rails_applications/testing_rails_applications.html[Testing Rails Applications]
+* link:securing_rails_applications/securing_rails_applications.html[Securing Rails Applications]
+* link:routing/routing_outside_in.html[Routing Outside-In]
+* link:debugging/debugging_rails_applications.html[Debugging Rails Applications]
+* link:creating_plugins/creating_plugins.html[The Basics of Creating Rails Plugins]

railties/doc/guides/routing/routing_outside_in.txt

@@ -455,7 +455,9 @@ However, without the use of +name_prefix => nil+, deeply-nested resources quickl
 /publishers/1/magazines/2/photos/3
 -------------------------------------------------------
 
-The corresponding route helper would be +publisher_magazine_photo_url+, requiring you to specify objects at all three levels.
+The corresponding route helper would be +publisher_magazine_photo_url+, requiring you to specify objects at all three levels. Indeed, this situation is confusing enough that a popular link:http://weblog.jamisbuck.org/2007/2/5/nesting-resources[article] by Jamis Buck proposes a rule of thumb for good Rails design:
+
+_Resources should never be nested more than 1 level deep._
 
 ==== Shallow Nesting
 
@@ -479,6 +481,23 @@ This will enable recognition of (among others) these routes:
 /magazines/2/photos     ==> magazines_photos_path(2)
 /photos/3               ==> photo_path(3)
 -------------------------------------------------------
+
+With shallow nesting, you need only supply enough information to uniquely identify the resource that you want to work with - but you _can_ supply more information. All of the nested routes continue to work, just as they would without shallow nesting, but less-deeply nested routes (even direct routes) work as well. So, with the declaration above, all of these routes refer to the same resource:
+
+-------------------------------------------------------
+/publishers/1/magazines/2/photos/3   ==> publisher_magazine_photo_path(1,2,3)
+/magazines/2/photos/3                ==> magazine_photo_path(2,3)
+/photos/3                            ==> photo_path(3)
+-------------------------------------------------------
+
+Shallow nesting gives you the flexibility to use the shorter direct routes when you like, while still preserving the longer nested routes for times when they add code clarity.
+
+If you like, you can combine shallow nesting with the +:has_one+ and +:has_many+ options:
+
+[source, ruby]
+-------------------------------------------------------
+map.resources :publishers, :has_many => { :magazines => :photos }, :shallow => true
+-------------------------------------------------------
 
 === Adding More RESTful Actions