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.

4 files changed, 40 insertions, 139 deletions

diff --git a/railties/Rakefile b/railties/Rakefile
index 1a6c51991d..08a5d1797f 100644
--- a/railties/Rakefile
+++ b/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 ----------------------------------------------------------------------------
 
diff --git a/railties/doc/guides/index.txt b/railties/doc/guides/index.txt
index 5f44103570..6f5741a12b 100644
--- a/railties/doc/guides/index.txt
+++ b/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]
diff --git a/railties/doc/guides/introduction.txt b/railties/doc/guides/introduction.txt
deleted file mode 100644
index 403c10380f..0000000000
--- a/railties/doc/guides/introduction.txt
+++ /dev/null
@@ -1,116 +0,0 @@
-In this chapter, we provide a high-level overview of Ruby on Rails.
-
-=== What Is a Web Framework? ===
-
-Ruby on Rails is a prominent member of a new generation of web frameworks. So what exactly does that term mean?
-
-To answer that question, let's consider the design of a web application written in PHP, a popular way to write web applications at this time (circa 2008). PHP is a scripting language, mostly meant for producing dynamic web pages. When you write a PHP application, you do everything yourself -- the equivalent of baking a cake from scratch. For example, here's a simple PHP script, that displays the ten most recently published books from a database:
-
-[source, php]
------------------------------------------
-<?php
-echo "<html><head><title>Books</title></head>\n"
-echo "<body>\n"
-echo "<h1>Books</h1>\n"
-echo "<ul>\n";
-
-mysql_connect("localhost", "me", "letmein");
-mysql_select_db("my_db");
-$result = mysql_query("SELECT name FROM books ORDER BY pub_data DESC LIMIT 10");
-while ($row = mysql_fetch($result)) {
-	echo "<li>$row[0]</li>\n";
-}
-
-echo "</ul>\n";
-echo "</body></html>\n";
-?>
------------------------------------------
-
-This code is straightforward. First, it prints some introductory HTML. Then, it connects to a database and executes a query that retrieves the latest ten books. Looping over those books, it generates an HTML unordered list. Finally, it prints the closing HTML and closes the database connection.
-
-With a one-off dynamic page such as this one, the write-it-from-scratch approach isn't necessarily bad. For one thing, this code is simple to comprehend -- even a novice developer can read these 14 lines of PHP and understand all it does, from start to finish. There's nothing else to learn; no other code to read. It's also simple to deploy: just save this code in a file called 'latestbooks.php', upload that file to a web server, and visit that page with a browser.
-
-But as a web application grows beyond the trivial, this approach breaks down, and you face a number of problems:
-
- * What happens when multiple pages need to connect to the database? Surely that database-connecting code shouldn't be duplicated in each individual PHP script, so the pragmatic thing to do would be to refactor it into a shared function.
- * Should a developer really have to worry about printing the ``Content-Type'' line and remembering to close the database connection? This sort of boilerplate reduces programmer productivity and introduces opportunities for mistakes. These setup- and teardown-related tasks would best be handled by some common infrastructure.
- * What happens when this code is reused in multiple environments, each with a separate database and password? At this point, some environment-specific configuration becomes essential.
- * What happens when a web designer who has no experience coding Ruby wishes to redesign the page? Ideally, the logic of the page -- the retrieval of books from the database -- would be separate from the HTML display of the page, so that a designer could edit the latter without affecting the former.
-
-These problems are precisely what a web framework intends to solve. A web framework provides a programming infrastructure for your applications, so that you can focus on writing clean, maintainable code without having to reinvent the wheel. In a nutshell, that's what Ruby on Rails does. Ruby on Rails also leverages the power of the Ruby programming language, to make web development as pleasant as possible.
-
-
-=== The MVC Design Pattern ===
-
-Let's dive in with a quick example that demonstrates the difference between the previous approach and that undertaken using a web framework. Here's how you might write the previous PHP code using Ruby on Rails:
-
-[source, ruby]
-----------------------------------------
-# File: app/models/book.rb (the database model with business logic)
-
-class Book < ActiveRecord::Base
-   def self.latest_books
-      return Book.find(:all, :order => 'pub_date DESC', :limit => 10)
-   end
-end
-----------------------------------------
-
-[source, ruby]
-----------------------------------------
-# File: app/controllers/books_controller.rb (the controller, which handles HTTP requests)
-
-class BooksController < ApplicationController
-   def index
-      @books = Book.latest_books
-   end
-end
-----------------------------------------
-
-[source, html]
-----------------------------------------
-<!-- File: app/views/books/index.html.erb (the view template) -->
-
-<html>
-<head>
-   <title>Books</title>
-</head>
-<body>
-   <h1>Books</h1>
-   <ul>
-      <% for book in @books %>
-         <li><%=h book.name %></li>
-      <% end %>
-   </ul>
-</body>
-</html>
-----------------------------------------
-
-Don't worry about the particulars of how this works just yet -- we just want you to get a feel for the overall design. The main thing to note here is the separation of concerns:
-
-  * The 'book.rb' file contains a *model* for the 'books' database table. Using this class, you can create, retrieve, update, and delete records in your database using simple Ruby code rather than writing repetitive SQL statements.
-
-  * The 'books_controller.rb' file is called the *controller*. It receives HTTP requests and processes them. It prepares information that the view will use to render the final HTML output for the HTTP client.
-
-  * The 'index.html.erb' file an HTML-ERB *template* that describes the design of the page.
-
-Taken together, these pieces loosely follow the Model-View-Controller (MVC) design pattern. Simply put, MVC defines a way of developing software so that the code for defining and accessing data (the model) is separate from request logic (the controller), which in turn is separate from the user interface (the view).
-
-A key advantage of such an approach is that components are loosely coupled. That is, each distinct piece of a Ruby on Rails-powered web application has a single key purpose and can be changed independently without affecting the other pieces. For example, a designer can change the user interface without having to understand the business logic. A database administrator can rename a database table and specify the change in a single place, rather than having to search and replace through a dozen files.
-
-
-=== Ruby on Rails's Philosophies: Convention-Over-Configuration and Don't-Repeat-Yourself ===
-
-Ruby on Rails is intended to emphasize *Convention over Configuration* (CoC), and the agile programming principle of *Don't repeat yourself* (DRY). But what do these terms mean?
-
-``Don't repeat yourself'' means that information is located in a single, unambiguous place. The careful reader will notice that that the model file lacks sort of database column definitions. Traditionally, web developers have to define database table information in their databases (in the form of a schema) and again in their applications. However, there are very few good reasons why such information should be duplicated, and -- indeed -- such duplication could lead to code maintenance problems. Ruby on Rails's database abstraction layer -- called 'ActiveRecord' -- automatically infers how your 'books' database table looks like, by performing database introspection.
-
-Ruby on Rails also places emphasis on ``Convention over Configuration''. For example, ActiveRecord automatically infers from the model class's name, `Book`, that the database table should be called 'books'. By following this naming convention, the developer need not to write a lot of configuration files.
-
-These philosophies are intended to speed up development and to reduce redundant information in the code base. DRY and CoC are key properties of the Ruby on Rails framework, and they are reflected throughout all of the framework.
-
-That said, it is still possible to tell ActiveRecord that the database table has a different name. So Ruby on Rails does not force you follow conventions, but you should carefully consider whether you will want to deviate from the convention because of the development speed advantages that following conventions will give you.
-
-
-=== What's Next ===
-
-In the next chapter, we'll get started with Ruby on Rails, covering installation and initial setup.
diff --git a/railties/doc/guides/routing/routing_outside_in.txt b/railties/doc/guides/routing/routing_outside_in.txt
index aecfb949e9..13d8a8b732 100644
--- a/railties/doc/guides/routing/routing_outside_in.txt
+++ b/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