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

railties/Rakefile

@@ -283,26 +283,35 @@ task :guides do
 
   template = File.expand_path("doc/guides/source/templates/guides.html.erb")
 
-  ignore = ['icons', 'images', 'templates', 'stylesheets']
+  ignore = ['..', 'icons', 'images', 'templates', 'stylesheets']
   ignore << 'active_record_basics.txt'
 
   indexless = ['index.txt', 'authors.txt']
 
-  Dir.entries(source)[2..-1].each do |entry|
+  # Traverse all entries in doc/guides/source/
+  Dir.entries(source).each do |entry|
     next if ignore.include?(entry)
 
     if File.directory?(File.join(source, entry))
-      input  = File.join(source, entry, 'index.txt')
-      output = File.join(html, entry)
+      # If the current entry is a directory, then we will want to compile
+      # the 'index.txt' file inside this directory.
+      if entry == '.'
+        input  = File.join(source, 'index.txt')
+        output = File.join(html, "index.html")
+      else
+        input  = File.join(source, entry, 'index.txt')
+        output = File.join(html, "#{entry}.html")
+      end
     else
+      # If the current entry is a file, then we will want to compile this file.
       input  = File.join(source, entry)
-      output = File.join(html, entry).sub(/\.txt$/, '')
+      output = File.join(html, entry).sub(/\.txt$/, '.html')
     end
 
     begin
       puts "GENERATING => #{output}"
       ENV['MANUALSONRAILS_TOC'] = 'no' if indexless.include?(entry)
-      Mizuho::Generator.new(input, output, template).start
+      Mizuho::Generator.new(input, :output => output, :template => template).start
     rescue Mizuho::GenerationError
       STDERR.puts "*** ERROR"
       exit 2

railties/doc/guides/html/2_2_release_notes.html

@@ -407,7 +407,7 @@ <h2 id="_documentation">2. Documentation</h2>
 </li>
 </ul></div>
 <div class="para"><p>All told, the Guides provide tens of thousands of words of guidance for beginning and intermediate Rails developers.</p></div>
-<div class="para"><p>If you want to these generate guides locally, inside your application:</p></div>
+<div class="para"><p>If you want to generate these guides locally, inside your application:</p></div>
 <div class="listingblock">
 <div class="content"><!-- Generator: GNU source-highlight 2.9
 by Lorenzo Bettini

railties/doc/guides/html/debugging_rails_applications.html

@@ -340,10 +340,7 @@ <h3 id="_debug">1.1. debug</h3>
 </tt></pre></div></div>
 <div class="para"><p>You'll see something like this:</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 -->
+<div class="content">
 <pre><tt>--- !ruby/object:Post
 attributes:
   updated_at: 2008-09-05 22:55:47
@@ -355,8 +352,8 @@ <h3 id="_debug">1.1. debug</h3>
 attributes_cache: {}
 
 
-Title: Rails debugging guide
-</tt></pre></div></div>
+Title: Rails debugging guide</tt></pre>
+</div></div>
 <h3 id="_to_yaml">1.2. to_yaml</h3>
 <div class="para"><p>Displaying an instance variable, or any other object or method, in yaml format can be achieved this way:</p></div>
 <div class="listingblock">
@@ -373,10 +370,7 @@ <h3 id="_to_yaml">1.2. to_yaml</h3>
 <div class="para"><p>The <tt>to_yaml</tt> method converts the method to YAML format leaving it more readable, and then the <tt>simple_format</tt> helper is used to render each line as in the console. This is how <tt>debug</tt> method does its magic.</p></div>
 <div class="para"><p>As a result of this, you will have something like this in your view:</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 -->
+<div class="content">
 <pre><tt>--- !ruby/object:Post
 attributes:
 updated_at: 2008-09-05 22:55:47
@@ -387,8 +381,8 @@ <h3 id="_to_yaml">1.2. to_yaml</h3>
 created_at: 2008-09-05 22:55:47
 attributes_cache: {}
 
-Title: Rails debugging guide
-</tt></pre></div></div>
+Title: Rails debugging guide</tt></pre>
+</div></div>
 <h3 id="_inspect">1.3. inspect</h3>
 <div class="para"><p>Another useful method for displaying object values is <tt>inspect</tt>, especially when working with arrays or hashes. This will print the object value as a string. For example:</p></div>
 <div class="listingblock">
@@ -404,14 +398,11 @@ <h3 id="_inspect">1.3. inspect</h3>
 </tt></pre></div></div>
 <div class="para"><p>Will be rendered as follows:</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 -->
+<div class="content">
 <pre><tt>[1, 2, 3, 4, 5]
 
-Title: Rails debugging guide
-</tt></pre></div></div>
+Title: Rails debugging guide</tt></pre>
+</div></div>
 <h3 id="_debugging_javascript">1.4. Debugging Javascript</h3>
 <div class="para"><p>Rails has built-in support to debug RJS, to active it, set <tt>ActionView::Base.debug_rjs</tt> to <em>true</em>, this will specify whether RJS responses should be wrapped in a try/catch block that alert()s the caught exception (and then re-raises it).</p></div>
 <div class="para"><p>To enable it, add the following in the <tt>Rails::Initializer do |config|</tt> block inside <tt>environment.rb</tt>:</p></div>
@@ -529,11 +520,8 @@ <h3 id="_sending_messages">2.3. Sending Messages</h3>
 </tt></pre></div></div>
 <div class="para"><p>Here's an example of the log generated by this method:</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>Processing PostsController#create (for <span style="color: #009900">127.0.0.1</span> at 2008-09-08 11:52:54) [POST]
+<div class="content">
+<pre><tt>Processing PostsController#create (for 127.0.0.1 at 2008-09-08 11:52:54) [POST]
   Session ID: BAh7BzoMY3NyZl9pZCIlMDY5MWU1M2I1ZDRjODBlMzkyMWI1OTg2NWQyNzViZjYiCmZsYXNoSUM6J0FjdGl
 vbkNvbnRyb2xsZXI6OkZsYXNoOjpGbGFzaEhhc2h7AAY6CkB1c2VkewA=--b18cd92fba90eacf8137e5f6b3b06c4d724596a4
   Parameters: {"commit"=&gt;"Create", "post"=&gt;{"title"=&gt;"Debugging Rails",
@@ -547,8 +535,8 @@ <h3 id="_sending_messages">2.3. Sending Messages</h3>
  'I''m learning how to print in logs!!!', 'f', '2008-09-08 14:52:54')
 The post was saved and now is the user is going to be redirected...
 Redirected to #&lt;Post:0x20af760&gt;
-Completed in 0.01224 (81 reqs/sec) | DB: 0.00044 (3%) | 302 Found [http://localhost/posts]
-</tt></pre></div></div>
+Completed in 0.01224 (81 reqs/sec) | DB: 0.00044 (3%) | 302 Found [http://localhost/posts]</tt></pre>
+</div></div>
 <div class="para"><p>Adding extra logging like this makes it easy to search for unexpected or unusual behavior in your logs. If you add extra logging, be sure to make sensible use of log levels, to avoid filling your production logs with useless trivia.</p></div>
 </div>
 <h2 id="_debugging_with_ruby_debug">3. Debugging with ruby-debug</h2>
@@ -581,12 +569,9 @@ <h3 id="_setup">3.1. Setup</h3>
 </tt></pre></div></div>
 <div class="para"><p>If you see the message in the console or logs:</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>***** Debugger requested, but was not available: Start server with --debugger to enable *****
-</tt></pre></div></div>
+<div class="content">
+<pre><tt>***** Debugger requested, but was not available: Start server with --debugger to enable *****</tt></pre>
+</div></div>
 <div class="para"><p>Make sure you have started your web server with the option <tt>&#8212;debugger</tt>:</p></div>
 <div class="listingblock">
 <div class="content"><!-- Generator: GNU source-highlight 2.9
@@ -1010,14 +995,11 @@ <h3 id="_settings">3.12. Settings</h3>
 </div>
 <div class="para"><p>Here's a good start for an <tt>.rdebugrc</tt>:</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 -->
+<div class="content">
 <pre><tt>set autolist
 set forcestep
-set listsize 25
-</tt></pre></div></div>
+set listsize 25</tt></pre>
+</div></div>
 </div>
 <h2 id="_debugging_memory_leaks">4. Debugging Memory Leaks</h2>
 <div class="sectionbody">
@@ -1046,20 +1028,14 @@ <h3 id="_bleakhouse">4.1. BleakHouse</h3>
 </div></div>
 <div class="para"><p>Make sure to run a couple hundred requests to get better data samples, then press <tt>CTRL-C</tt>. The server will stop and Bleak House will produce a dumpfile in <tt>/tmp</tt>:</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 -->
+<div class="content">
 <pre><tt>** BleakHouse: working...
 ** BleakHouse: complete
-** Bleakhouse: run 'bleak /tmp/bleak.5979.0.dump' to analyze.
-</tt></pre></div></div>
+** Bleakhouse: run 'bleak /tmp/bleak.5979.0.dump' to analyze.</tt></pre>
+</div></div>
 <div class="para"><p>To analyze it, just run the listed command. The top 20 leakiest lines will be listed:</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 -->
+<div class="content">
 <pre><tt>  191691 total objects
   Final heap size 191691 filled, 220961 free
   Displaying top 20 most common line/class pairs
@@ -1071,8 +1047,8 @@ <h3 id="_bleakhouse">4.1. BleakHouse</h3>
    951 /opt/local//lib/ruby/site_ruby/1.8/rubygems/version.rb:111:String
    935 /opt/local//lib/ruby/site_ruby/1.8/rubygems/specification.rb:557:String
    834 /opt/local//lib/ruby/site_ruby/1.8/rubygems/version.rb:146:Array
-  ...
-</tt></pre></div></div>
+  ...</tt></pre>
+</div></div>
 <div class="para"><p>This way you can find where your application is leaking memory and fix it.</p></div>
 <div class="para"><p>If <a href="http://github.com/fauna/bleak_house/tree/master">BleakHouse</a> doesn't report any heap growth but you still have memory growth, you might have a broken C extension, or real leak in the interpreter. In that case, try using Valgrind to investigate further.</p></div>
 <h3 id="_valgrind">4.2. Valgrind</h3>

railties/doc/guides/html/finders.html

@@ -373,27 +373,21 @@ <h2 id="_ids_first_last_and_all">4. IDs, First, Last and All</h2>
 <pre><tt><span style="font-weight: bold"><span style="color: #0000FF">SELECT</span></span> <span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #0000FF">FROM</span></span> <span style="color: #990000">+</span>clients<span style="color: #990000">+</span> <span style="font-weight: bold"><span style="color: #0000FF">WHERE</span></span> <span style="color: #990000">(+</span>clients<span style="color: #990000">+.+</span>id<span style="color: #990000">+</span> <span style="font-weight: bold"><span style="color: #0000FF">IN</span></span> <span style="color: #990000">(</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">))</span>
 </tt></pre></div></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 -->
+<div class="content">
 <pre><tt>&gt;&gt; Client.find(1,2)
 =&gt; [#&lt;Client id: 1, name: =&gt; "Ryan", locked: false, orders_count: 2,
   created_at: "2008-09-28 15:38:50", updated_at: "2008-09-28 15:38:50"&gt;,
   #&lt;Client id: 2, name: =&gt; "Michael", locked: false, orders_count: 3,
-  created_at: "2008-09-28 13:12:40", updated_at: "2008-09-28 13:12:40"&gt;]
-</tt></pre></div></div>
+  created_at: "2008-09-28 13:12:40", updated_at: "2008-09-28 13:12:40"&gt;]</tt></pre>
+</div></div>
 <div class="para"><p>Note that if you pass in a list of numbers that the result will be returned as an array, not as a single <tt>Client</tt> object.</p></div>
 <div class="para"><p>If you wanted to find the first client you would simply type <tt>Client.first</tt> and that would find the first client created in your clients table:</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 -->
+<div class="content">
 <pre><tt>&gt;&gt; Client.first
 =&gt; #&lt;Client id: 1, name: =&gt; "Ryan", locked: false, orders_count: 2,
-  created_at: "2008-09-28 15:38:50", updated_at: "2008-09-28 15:38:50"&gt;
-</tt></pre></div></div>
+  created_at: "2008-09-28 15:38:50", updated_at: "2008-09-28 15:38:50"&gt;</tt></pre>
+</div></div>
 <div class="para"><p>If you were running script/server you might see the following output:</p></div>
 <div class="listingblock">
 <div class="content"><!-- Generator: GNU source-highlight 2.9
@@ -405,14 +399,11 @@ <h2 id="_ids_first_last_and_all">4. IDs, First, Last and All</h2>
 <div class="para"><p>Indicating the query that Rails has performed on your database.</p></div>
 <div class="para"><p>To find the last client you would simply type <tt>Client.find(:last)</tt> and that would find the last client created in your clients table:</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 -->
+<div class="content">
 <pre><tt>&gt;&gt; Client.find(:last)
 =&gt; #&lt;Client id: 2, name: =&gt; "Michael", locked: false, orders_count: 3,
-  created_at: "2008-09-28 13:12:40", updated_at: "2008-09-28 13:12:40"&gt;
-</tt></pre></div></div>
+  created_at: "2008-09-28 13:12:40", updated_at: "2008-09-28 13:12:40"&gt;</tt></pre>
+</div></div>
 <div class="listingblock">
 <div class="content"><!-- Generator: GNU source-highlight 2.9
 by Lorenzo Bettini
@@ -422,16 +413,13 @@ <h2 id="_ids_first_last_and_all">4. IDs, First, Last and All</h2>
 </tt></pre></div></div>
 <div class="para"><p>To find all the clients you would simply type <tt>Client.all</tt> and that would find all the clients in your clients table:</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 -->
+<div class="content">
 <pre><tt>&gt;&gt; Client.all
 =&gt; [#&lt;Client id: 1, name: =&gt; "Ryan", locked: false, orders_count: 2,
   created_at: "2008-09-28 15:38:50", updated_at: "2008-09-28 15:38:50"&gt;,
   #&lt;Client id: 2, name: =&gt; "Michael", locked: false, orders_count: 3,
-  created_at: "2008-09-28 13:12:40", updated_at: "2008-09-28 13:12:40"&gt;]
-</tt></pre></div></div>
+  created_at: "2008-09-28 13:12:40", updated_at: "2008-09-28 13:12:40"&gt;]</tt></pre>
+</div></div>
 <div class="para"><p>As alternatives to calling <tt>Client.first</tt>, <tt>Client.last</tt>, and <tt>Client.all</tt>, you can use the class methods <tt>Client.first</tt>, <tt>Client.last</tt>, and <tt>Client.all</tt> instead. <tt>Client.first</tt>, <tt>Client.last</tt> and <tt>Client.all</tt> just call their longer counterparts: <tt>Client.find(:first)</tt>, <tt>Client.find(:last)</tt> and <tt>Client.find(:all)</tt> respectively.</p></div>
 <div class="para"><p>Be aware that <tt>Client.first</tt>/<tt>Client.find(:first)</tt> and <tt>Client.last</tt>/<tt>Client.find(:last)</tt> will both return a single object, where as <tt>Client.all</tt>/<tt>Client.find(:all)</tt> will return an array of Client objects, just as passing in an array of ids to find will do also.</p></div>
 </div>
@@ -510,12 +498,9 @@ <h3 id="_array_conditions">5.2. Array Conditions</h3>
 </tt></pre></div></div>
 <div class="para"><p>This could possibly cause your database server to raise an unexpected error, for example MySQL will throw back this error:</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>Got a packet bigger than 'max_allowed_packet' bytes: _query_
-</tt></pre></div></div>
+<div class="content">
+<pre><tt>Got a packet bigger than 'max_allowed_packet' bytes: _query_</tt></pre>
+</div></div>
 <div class="para"><p>Where <em>query</em> is the actual query used to get that error.</p></div>
 <div class="para"><p>In this example it would be better to use greater-than and less-than operators in SQL, like so:</p></div>
 <div class="listingblock">