Finalized debugging guide.

4 files changed, 37 insertions, 47 deletions

diff --git a/railties/doc/guides/html/debugging_rails_applications.html b/railties/doc/guides/html/debugging_rails_applications.html
index 0fdc1b0a1f..d3a3180842 100644
--- a/railties/doc/guides/html/debugging_rails_applications.html
+++ b/railties/doc/guides/html/debugging_rails_applications.html
@@ -258,7 +258,7 @@ ul#navMain {
 					<a href="#_debugging_memory_leaks">Debugging Memory Leaks</a>
 						<ul>
 						
-							<li><a href="#_bleak_house">Bleak House</a></li>
+							<li><a href="#_bleakhouse">BleakHouse</a></li>
 						
 							<li><a href="#_valgrind">Valgrind</a></li>
 						
@@ -617,7 +617,7 @@ http://www.gnu.org/software/src-highlite -->
 <pre><tt>@posts = Post.find(:all)

 (rdb:7)</tt></pre>

 </div></div>

-<div class="para"><p>Now it's time to play and dig into your application. A good place to start is by asking the debugger for help&#8230; so type: <tt>help</tt> (You didn't see that coming, right?)</p></div>

+<div class="para"><p>Now it's time to explore and dig into your application. A good place to start is by asking the debugger for help&#8230; so type: <tt>help</tt> (You didn't see that coming, right?)</p></div>

 <div class="listingblock">

 <div class="content">

 <pre><tt>(rdb:7) help

@@ -1021,17 +1021,17 @@ set listsize 25
 </div>

 <h2 id="_debugging_memory_leaks">4. Debugging Memory Leaks</h2>

 <div class="sectionbody">

-<div class="para"><p>A Ruby application (on Rails or not), can leak memory whether in the Ruby code but also in the C code.</p></div>

-<div class="para"><p>In this section, you will learn how to find and fix this leaks by using Bleak House and Valgrind debugging tools.</p></div>

-<h3 id="_bleak_house">4.1. Bleak House</h3>

-<div class="para"><p><a href="http://github.com/fauna/bleak_house/tree/master">Bleak House</a> is a library for finding memory leaks.</p></div>

-<div class="para"><p>If a Ruby object does not go out of scope, the Ruby Garbage Collector won't sweep it since it is referenced somewhere, this leaks can grow slowly and your application will consume more and more memory gradually affecting the overall system performance. This tool will help you find leaks on the Ruby heap.</p></div>

+<div class="para"><p>A Ruby application (on Rails or not), can leak memory - either in the Ruby code or at the C code level.</p></div>

+<div class="para"><p>In this section, you will learn how to find and fix such leaks by using Bleak House and Valgrind debugging tools.</p></div>

+<h3 id="_bleakhouse">4.1. BleakHouse</h3>

+<div class="para"><p><a href="http://github.com/fauna/bleak_house/tree/master">BleakHouse</a> is a library for finding memory leaks.</p></div>

+<div class="para"><p>If a Ruby object does not go out of scope, the Ruby Garbage Collector won't sweep it since it is referenced somewhere. Leaks like this can grow slowly and your application will consume more and more memory, gradually affecting the overall system performance. This tool will help you find leaks on the Ruby heap.</p></div>

 <div class="para"><p>To install it run:</p></div>

 <div class="listingblock">

 <div class="content">

 <pre><tt>sudo gem install bleak_house</tt></pre>

 </div></div>

-<div class="para"><p>Then setup you application for profiling, add the following at the bottom of config/environment.rb:</p></div>

+<div class="para"><p>Then setup you application for profiling. Then add the following at the bottom of config/environment.rb:</p></div>

 <div class="listingblock">

 <div class="content"><!-- Generator: GNU source-highlight 2.9

 by Lorenzo Bettini

@@ -1039,12 +1039,12 @@ 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">'bleak_house'</span> <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> ENV<span style="color: #990000">[</span><span style="color: #FF0000">'BLEAK_HOUSE'</span><span style="color: #990000">]</span>

 </tt></pre></div></div>

-<div class="para"><p>Start a server instance with Bleak House integration:</p></div>

+<div class="para"><p>Start a server instance with BleakHouse integration:</p></div>

 <div class="listingblock">

 <div class="content">

 <pre><tt>RAILS_ENV=production BLEAK_HOUSE=1 ruby-bleak-house ./script/server</tt></pre>

 </div></div>

-<div class="para"><p>Make sure to run a couple hundred requests to get better data samples, hit <tt>CTRL-C</tt>. The server will stop and Bleak House will produce a dumpfile in <tt>/tmp</tt>:</p></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

@@ -1073,16 +1073,16 @@ http://www.gnu.org/software/src-highlite -->
    834 /opt/local//lib/ruby/site_ruby/1.8/rubygems/version.rb:146:Array

   ...

 </tt></pre></div></div>

-<div class="para"><p>This way you can find where you 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, try using Valgrind.</p></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>

-<div class="para"><p><a href="http://valgrind.org/">Valgrind</a> is a Linux (only works on Linux) application for detecting C-based memory leaks and race conditions.</p></div>

+<div class="para"><p><a href="http://valgrind.org/">Valgrind</a> is a Linux-only application for detecting C-based memory leaks and race conditions.</p></div>

 <div class="para"><p>There are Valgrind tools that can automatically detect many memory management and threading bugs, and profile your programs in detail. For example, a C extension in the interpreter calls <tt>malloc()</tt> but is doesn't properly call <tt>free()</tt>, this memory won't be available until the app terminates.</p></div>

-<div class="para"><p>For further information on how to install and using with Ruby, refer to the <a href="http://blog.evanweaver.com/articles/2008/02/05/valgrind-and-ruby/">Valgrind and Ruby Evan Weaver's article</a>.</p></div>

+<div class="para"><p>For further information on how to install Valgrind and use with Ruby, refer to <a href="http://blog.evanweaver.com/articles/2008/02/05/valgrind-and-ruby/">Valgrind and Ruby</a> by Evan Weaver.</p></div>

 </div>

 <h2 id="_plugins_for_debugging">5. Plugins for Debugging</h2>

 <div class="sectionbody">

-<div class="para"><p>To make life easier Rails offer plugins, some of them will help you to find errors and debug your application. Here is a list of useful plugins for debugging:</p></div>

+<div class="para"><p>There are some Rails plugins to help you to find errors and debug your application. Here is a list of useful plugins for debugging:</p></div>

 <div class="ilist"><ul>

 <li>

 <p>

@@ -1101,7 +1101,7 @@ http://www.gnu.org/software/src-highlite -->
 </li>

 <li>

 <p>

-<a href="http://code.google.com/p/query-reviewer/">Query Reviewer</a>: This rails plugin not only runs "EXPLAIN" before each of your select queries in development, but provides a small DIV in the rendered output of each page with the summary of query warnings that it analyzed.

+<a href="http://code.google.com/p/query-reviewer/">Query Reviewer</a>: This rails plugin not only runs "EXPLAIN" before each of your select queries in development, but provides a small DIV in the rendered output of each page with the summary of warnings for each query that it analyzed.

 </p>

 </li>

 <li>

@@ -1177,7 +1177,7 @@ http://www.gnu.org/software/src-highlite -->
 <div class="ilist"><ul>

 <li>

 <p>

-November 3, 2008: Added RJS, memory leaks and plugins chapters by <a href="../authors.html#miloops">Emilio Tagua</a>

+November 3, 2008: Accepted for publication. Added RJS, memory leaks and plugins chapters by <a href="../authors.html#miloops">Emilio Tagua</a>

 </p>

 </li>

 <li>

diff --git a/railties/doc/guides/html/index.html b/railties/doc/guides/html/index.html
index 306257678b..84618d95e2 100644
--- a/railties/doc/guides/html/index.html
+++ b/railties/doc/guides/html/index.html
@@ -250,7 +250,7 @@ ul#navMain {
 <div class="sidebar-content">

 <div class="sidebar-title"><a href="layouts_and_rendering.html">Layouts and Rendering in Rails</a></div>

 <div class="para"><p>This guide covers the basic layout features of Action Controller and Action View,

-including rendering and redirecting, using +content_for_ blocks, and working

+including rendering and redirecting, using <tt>content_for</tt> blocks, and working

 with partials.</p></div>

 </div></div>

 <div class="sidebarblock">

@@ -318,20 +318,12 @@ Enjoy.</p></div>
 <div class="sidebarblock">

 <div class="sidebar-content">

 <div class="sidebar-title"><a href="security.html">Securing Rails Applications</a></div>

-<div class="para"><p>This manual describes common security problems in web applications and how to

+<div class="para"><p>This guide describes common security problems in web applications and how to

 avoid them with Rails.</p></div>

 </div></div>

 <div class="sidebarblock">

 <div class="sidebar-content">

 <div class="sidebar-title"><a href="debugging_rails_applications.html">Debugging Rails Applications</a></div>

-<div class="admonitionblock">

-<table><tr>

-<td class="icon">

-<img src="./images/icons/caution.png" alt="Caution" />

-</td>

-<td class="content"><a href="http://rails.lighthouseapp.com/projects/16213/tickets/5">Lighthouse Ticket</a></td>

-</tr></table>

-</div>

 <div class="para"><p>This guide describes how to debug Rails applications. It covers the different

 ways of achieving this and how to understand what is happening "behind the scenes"

 of your code.</p></div>

diff --git a/railties/doc/guides/source/debugging_rails_applications.txt b/railties/doc/guides/source/debugging_rails_applications.txt
index 7271a05666..b67f4be126 100644
--- a/railties/doc/guides/source/debugging_rails_applications.txt
+++ b/railties/doc/guides/source/debugging_rails_applications.txt
@@ -292,7 +292,7 @@ For example:
 (rdb:7)
 ----------------------------------------------------------------------------
 
-Now it's time to play and dig into your application. A good place to start is by asking the debugger for help... so type: `help` (You didn't see that coming, right?)
+Now it's time to explore and dig into your application. A good place to start is by asking the debugger for help... so type: `help` (You didn't see that coming, right?)
 
 ----------------------------------------------------------------------------
 (rdb:7) help
@@ -640,15 +640,15 @@ set listsize 25
 
 == Debugging Memory Leaks
 
-A Ruby application (on Rails or not), can leak memory whether in the Ruby code but also in the C code.
+A Ruby application (on Rails or not), can leak memory - either in the Ruby code or at the C code level.
 
-In this section, you will learn how to find and fix this leaks by using Bleak House and Valgrind debugging tools.
+In this section, you will learn how to find and fix such leaks by using Bleak House and Valgrind debugging tools.
 
-=== Bleak House
+=== BleakHouse
 
-link:http://github.com/fauna/bleak_house/tree/master[Bleak House] is a library for finding memory leaks.
+link:http://github.com/fauna/bleak_house/tree/master[BleakHouse] is a library for finding memory leaks.
 
-If a Ruby object does not go out of scope, the Ruby Garbage Collector won't sweep it since it is referenced somewhere, this leaks can grow slowly and your application will consume more and more memory gradually affecting the overall system performance. This tool will help you find leaks on the Ruby heap.
+If a Ruby object does not go out of scope, the Ruby Garbage Collector won't sweep it since it is referenced somewhere. Leaks like this can grow slowly and your application will consume more and more memory, gradually affecting the overall system performance. This tool will help you find leaks on the Ruby heap.
 
 To install it run:
 
@@ -656,20 +656,20 @@ To install it run:
 sudo gem install bleak_house
 ----------------------------------------------------------------------------
 
-Then setup you application for profiling, add the following at the bottom of config/environment.rb:
+Then setup you application for profiling. Then add the following at the bottom of config/environment.rb:
 
 [source, ruby]
 ----------------------------------------------------------------------------
 require 'bleak_house' if ENV['BLEAK_HOUSE']
 ----------------------------------------------------------------------------
 
-Start a server instance with Bleak House integration:
+Start a server instance with BleakHouse integration:
 
 ----------------------------------------------------------------------------
 RAILS_ENV=production BLEAK_HOUSE=1 ruby-bleak-house ./script/server
 ----------------------------------------------------------------------------
 
-Make sure to run a couple hundred requests to get better data samples, hit `CTRL-C`. The server will stop and Bleak House will produce a dumpfile in `/tmp`:
+Make sure to run a couple hundred requests to get better data samples, then press `CTRL-C`. The server will stop and Bleak House will produce a dumpfile in `/tmp`:
 
 [source, log]
 ----------------------------------------------------------------------------
@@ -696,26 +696,26 @@ To analyze it, just run the listed command. The top 20 leakiest lines will be li
   ...
 ----------------------------------------------------------------------------
 
-This way you can find where you application is leaking memory and fix it.
+This way you can find where your application is leaking memory and fix it.
 
-If link:http://github.com/fauna/bleak_house/tree/master[BleakHouse] 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, try using Valgrind.
+If link:http://github.com/fauna/bleak_house/tree/master[BleakHouse] 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.
 
 === Valgrind
 
-link:http://valgrind.org/[Valgrind] is a Linux (only works on Linux) application for detecting C-based memory leaks and race conditions.
+link:http://valgrind.org/[Valgrind] is a Linux-only application for detecting C-based memory leaks and race conditions.
 
 There are Valgrind tools that can automatically detect many memory management and threading bugs, and profile your programs in detail. For example, a C extension in the interpreter calls `malloc()` but is doesn't properly call `free()`, this memory won't be available until the app terminates.
 
-For further information on how to install and using with Ruby, refer to the link:http://blog.evanweaver.com/articles/2008/02/05/valgrind-and-ruby/[Valgrind and Ruby Evan Weaver's article].
+For further information on how to install Valgrind and use with Ruby, refer to link:http://blog.evanweaver.com/articles/2008/02/05/valgrind-and-ruby/[Valgrind and Ruby] by Evan Weaver.
 
 == Plugins for Debugging
 
-To make life easier Rails offer plugins, some of them will help you to find errors and debug your application. Here is a list of useful plugins for debugging:
+There are some Rails plugins to help you to find errors and debug your application. Here is a list of useful plugins for debugging:
 
 * link:http://github.com/drnic/rails-footnotes/tree/master[Footnotes]: Every Rails page has footnotes that link give request information and link back to your source via TextMate.
 * link:http://github.com/ntalbott/query_trace/tree/master[Query Trace]: Adds query origin tracing to your logs.
 * link:http://github.com/dan-manges/query_stats/tree/master[Query Stats]: A Rails plugin to track database queries. 
-* link:http://code.google.com/p/query-reviewer/[Query Reviewer]: This rails plugin not only runs "EXPLAIN" before each of your select queries in development, but provides a small DIV in the rendered output of each page with the summary of query warnings that it analyzed.
+* link:http://code.google.com/p/query-reviewer/[Query Reviewer]: This rails plugin not only runs "EXPLAIN" before each of your select queries in development, but provides a small DIV in the rendered output of each page with the summary of warnings for each query that it analyzed.
 * link:http://github.com/rails/exception_notification/tree/master[Exception Notifier]: Provides a mailer object and a default set of templates for sending email notifications when errors occur in a Rails application.
 * link:http://github.com/defunkt/exception_logger/tree/master[Exception Logger]: Logs your Rails exceptions in the database and provides a funky web interface to manage them.
 
@@ -736,6 +736,6 @@ To make life easier Rails offer plugins, some of them will help you to find erro
 
 http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/5[Lighthouse ticket]
 
-* November 3, 2008: Added RJS, memory leaks and plugins chapters by link:../authors.html#miloops[Emilio Tagua]
+* November 3, 2008: Accepted for publication. Added RJS, memory leaks and plugins chapters by link:../authors.html#miloops[Emilio Tagua]
 * October 19, 2008: Copy editing pass by link:../authors.html#mgunderloy[Mike Gunderloy]
 * September 16, 2008: initial version by link:../authors.html#miloops[Emilio Tagua]
diff --git a/railties/doc/guides/source/index.txt b/railties/doc/guides/source/index.txt
index 05d7deee6a..77f92daba7 100644
--- a/railties/doc/guides/source/index.txt
+++ b/railties/doc/guides/source/index.txt
@@ -42,7 +42,7 @@ This guide covers the find method defined in ActiveRecord::Base, as well as name
 .link:layouts_and_rendering.html[Layouts and Rendering in Rails]
 ***********************************************************
 This guide covers the basic layout features of Action Controller and Action View,
-including rendering and redirecting, using +content_for_ blocks, and working
+including rendering and redirecting, using +content_for+ blocks, and working
 with partials.
 ***********************************************************
 
@@ -92,14 +92,12 @@ Enjoy.
 
 .link:security.html[Securing Rails Applications]
 ***********************************************************
-This manual describes common security problems in web applications and how to
+This guide describes common security problems in web applications and how to
 avoid them with Rails.
 ***********************************************************
 
 .link:debugging_rails_applications.html[Debugging Rails Applications]
 ***********************************************************
-CAUTION: link:http://rails.lighthouseapp.com/projects/16213/tickets/5[Lighthouse Ticket]
-
 This guide describes how to debug Rails applications. It covers the different
 ways of achieving this and how to understand what is happening "behind the scenes"
 of your code.