Updated Debugging Rails applications guide styles, use backticks instead asteriks in method/command names.

1 files changed, 65 insertions, 67 deletions

diff --git a/railties/doc/guides/debugging/debugging_rails_applications.txt b/railties/doc/guides/debugging/debugging_rails_applications.txt
index 3a5f9d3e7e..eb1135d094 100644
--- a/railties/doc/guides/debugging/debugging_rails_applications.txt
+++ b/railties/doc/guides/debugging/debugging_rails_applications.txt
@@ -12,7 +12,7 @@ This guide covers how to debug Ruby on Rails applications. By referring to this
 
 === debug
 
-*debug* will return a <pre>-tag that has object dumped by YAML. Generating readable output to inspect any object.
+`debug` will return a <pre>-tag that has object dumped by YAML. Generating readable output to inspect any object.
 
 [source, html]
 ----------------------------------------------------------------------------
@@ -54,7 +54,7 @@ Displaying an instance variable, or any other object or method, in yaml format c
 </p>
 ----------------------------------------------------------------------------
 
-*to_yaml* converts the method to yaml format leaving it more readable and finally *simple_format* help us to render each line as in the console. This is how *debug* method does its magic.
+`to_yaml` converts the method to yaml format leaving it more readable and finally `simple_format` help us to render each line as in the console. This is how `debug` method does its magic.
 
 As a result of this, you will have something like this in your view:
 
@@ -72,7 +72,7 @@ attributes_cache: {}
 Title: Rails debugging guide
 ----------------------------------------------------------------------------
 
-Another great method for displaying object values is *inspect*, especially when working with arrays or hashes, it will print the object value as a string, for example:
+Another useful method for displaying object values is `inspect`, especially when working with arrays or hashes, it will print the object value as a string, for example:
 
 [source, html]
 ----------------------------------------------------------------------------
@@ -95,9 +95,9 @@ Title: Rails debugging guide
 
 === What is it?
 
-Rails makes use of ruby’s standard *logger*, *Log4r*, or another logger that provides a similar interface can also be substituted if you wish.
+Rails makes use of ruby’s standard `logger`, `Log4r`, or another logger that provides a similar interface can also be substituted if you wish.
 
-If you want to change the logger you can specify it in your *environment.rb* or any environment file.
+If you want to change the logger you can specify it in your `environment.rb` or any environment file.
 
 [source, ruby]
 ----------------------------------------------------------------------------
@@ -105,7 +105,7 @@ ActiveRecord::Base.logger = Logger.new(STDOUT)
 ActiveRecord::Base.logger = Log4r::Logger.new("Application Log")
 ----------------------------------------------------------------------------
 
-Or in the __Initializer__ section, add _any_ of the following
+Or in the `__Initializer__` section, add _any_ of the following
 
 [source, ruby]
 ----------------------------------------------------------------------------
@@ -114,13 +114,13 @@ config.logger = Log4r::Logger.new("Application Log")
 ----------------------------------------------------------------------------
 
 [TIP]
-By default, each log is created under "__RAILS_ROOT/log/__" and the log file name is "__environment_name.log__".
+By default, each log is created under `RAILS_ROOT/log/` and the log file name is `environment_name.log`.
 
 === Log levels
 
-When something is logged it's printed into the corresponding log if the message log level is equal or higher than the configured log level. If you want to know the current log level just call *ActiveRecord::Base.logger.level* method.
+When something is logged it's printed into the corresponding log if the message log level is equal or higher than the configured log level. If you want to know the current log level just call `ActiveRecord::Base.logger.level` method.
 
-The available log levels are: *:debug*, *:info*, *:warn*, *:error*, *:fatal*, each level has a log level number from 0 up to 4 respectively. To change the default log level, use
+The available log levels are: +:debug+, +:info+, +:warn+, +:error+, +:fatal+, each level has a log level number from 0 up to 4 respectively. To change the default log level, use
 
 [source, ruby]
 ----------------------------------------------------------------------------
@@ -131,11 +131,11 @@ ActiveRecord::Base.logger.level = 0 # at any time
 This is useful when you want to log under development or staging, but you don't want to flood your production log with unnecessary information.
 
 [TIP]
-Rails default log level is *info* in production mode and *debug* in development and test mode.
+Rails default log level is +info+ in production mode and +debug+ in development and test mode.
 
 === Sending messages
 
-To write in the current log use the *logger.(debug|info|warn|error|fatal)* method from within a controller, model or mailer:
+To write in the current log use the `logger.(debug|info|warn|error|fatal)` method from within a controller, model or mailer:
 
 [source, ruby]
 ----------------------------------------------------------------------------
@@ -205,7 +205,7 @@ $ sudo gem in ruby-debug
 
 In case you want to download a particular version or get the source code, refer to link:http://rubyforge.org/projects/ruby-debug/[project's page on rubyforge].
 
-Rails has built-in support for ruby-debug since April 28, 2007. Inside any Rails application you can invoke the debugger by calling the *debugger* method.
+Rails has built-in support for ruby-debug since April 28, 2007. Inside any Rails application you can invoke the debugger by calling the `debugger` method.
 
 Let's take a look at an example:
 
@@ -232,15 +232,13 @@ Make sure you have started your web server with the option --debugger:
 ----------------------------------------------------------------------------
 
 [TIP]
-----------------------------------------------------------------------------
-In development mode, you can dynamically *require 'ruby-debug'* instead of restarting the server, in case it was started without --debugger.
-----------------------------------------------------------------------------
+In development mode, you can dynamically `require \'ruby-debug\'` instead of restarting the server, in case it was started without `--debugger`.
 
 In order to use Rails debugging you'll need to be running either *WEBrick* or *Mongrel*. For the moment, no alternative servers are supported.
 
 === The shell
 
-As soon as your application calls the *debugger* method, the debugger will be started in a debugger shell inside the terminal window you've fired up your application server and you will be placed in the ruby-debug's prompt (rdb:n). The _n_ is the thread number.
+As soon as your application calls the `debugger` method, the debugger will be started in a debugger shell inside the terminal window you've fired up your application server and you will be placed in the ruby-debug's prompt `(rdb:n)`. The _n_ is the thread number.
 
 If you got there by a browser request, the browser will be hanging until the debugger has finished and the trace has completely run as any normal request.
 
@@ -251,7 +249,7 @@ For example:
 (rdb:7)
 ----------------------------------------------------------------------------
 
-Now it's time to play and dig into our application. The first we are going to do is ask our debugger for help... so we type: *help* (You didn't see that coming, right?)
+Now it's time to play and dig into our application. The first we are going to do is ask our debugger for help... so we type: `help` (You didn't see that coming, right?)
 
 ----------------------------------------------------------------------------
 (rdb:7) help
@@ -267,9 +265,9 @@ continue   edit     frame   method  putl  set      tmate   where
 ----------------------------------------------------------------------------
 
 [TIP]
-To view the help menu for any command use *help <command-name>* in active debug mode. For example: _help var_
+To view the help menu for any command use `help <command-name>` in active debug mode. For example: _help var_
 
-The second command before we move on, is one of the most useful command: *list* (or his shorthand *l*).
+The second command before we move on, is one of the most useful command: `list` (or his shorthand `l`).
 
 This command will give us a starting point of where we are by printing 10 lines centered around the current line; the current line here is line 6 and is marked by =>.
 
@@ -288,10 +286,10 @@ This command will give us a starting point of where we are by printing 10 lines
    10        format.xml  { render :xml => @posts }
 ----------------------------------------------------------------------------
 
-If we do it again, this time using just *l*, the next ten lines of the file will be printed out.
+If we do it again, this time using just `l`, the next ten lines of the file will be printed out.
 
 ----------------------------------------------------------------------------
-(rdb:7) list
+(rdb:7) l
 [11, 20] in /PathTo/project/app/controllers/posts_controller.rb
    11      end
    12    end
@@ -312,7 +310,7 @@ When we start debugging your application, we will be placed in different context
 
 A context will be created when a stopping point or an event is reached. It has information about the suspended program which enable a debugger to inspect the frame stack, evaluate variables from the perspective of the debugged program, and contains information about the place the debugged program is stopped.
 
-At any time we can call the *backtrace* command (or alias *where*) to print the backtrace of the application, this is very helpful to know how we got where we are. If you ever wondered about how you got somewhere in your code, then *backtrace* is your answer.
+At any time we can call the `backtrace` command (or alias `where`) to print the backtrace of the application, this is very helpful to know how we got where we are. If you ever wondered about how you got somewhere in your code, then `backtrace` is your answer.
 
 ----------------------------------------------------------------------------
 (rdb:5) where
@@ -327,7 +325,7 @@ At any time we can call the *backtrace* command (or alias *where*) to print the
 ...
 ----------------------------------------------------------------------------
 
-You move anywhere you want in this trace using the *frame n* command, where _n_ is the specified frame number.
+You move anywhere you want in this trace using the `frame _n_` command, where _n_ is the specified frame number.
 
 ----------------------------------------------------------------------------
 (rdb:5) frame 2
@@ -337,17 +335,17 @@ You move anywhere you want in this trace using the *frame n* command, where _n_
 
 The available variables are the same as if we were running the code line by line, after all, that's what debugging is.
 
-Moving up and down the stack frame: You can use *up [n]* (*u* for abbreviated) and *down [n]* commands in order to change the context _n_ frames up or down the stack respectively. _n_ defaults to one.
+Moving up and down the stack frame: You can use `up [n]` (`u` for abbreviated) and `down [n]` commands in order to change the context _n_ frames up or down the stack respectively. _n_ defaults to one.
 
 === Threads
 
-The debugger can list, stop, resume and switch between running threads, the command *thread* (or the abbreviated *th*) is used an allows the following options:
+The debugger can list, stop, resume and switch between running threads, the command `thread` (or the abbreviated `th`) is used an allows the following options:
 
-* *thread* shows the current thread.
-* *thread list* command is used to list all threads and their statuses. The plus + character and the number indicates the current thread of execution.
-* *thread stop n* stop thread _n_.
-* *thread resume n* resume thread _n_.
-* *thread switch n* switch thread context to _n_.
+* `thread` shows the current thread.
+* `thread list` command is used to list all threads and their statuses. The plus + character and the number indicates the current thread of execution.
+* `thread stop _n_` stop thread _n_.
+* `thread resume _n_` resume thread _n_.
+* `thread switch _n_` switch thread context to _n_.
 
 This command is very helpful, among other occasions, when you are debugging concurrent threads and need to verify that there are no race conditions in your code.
 
@@ -363,7 +361,7 @@ In the following example we will print the instance_variables defined within the
 ["@_response", "@action_name", "@url", "@_session", "@_cookies", "@performed_render", "@_flash", "@template", "@_params", "@before_filter_chain_aborted", "@request_origin", "@_headers", "@performed_redirect", "@_request"]
 ----------------------------------------------------------------------------
 
-As you may have figured out, all variables that you can access from a controller are displayed, lets run the next line, we will use *next* (we will get later into this command).
+As you may have figured out, all variables that you can access from a controller are displayed, lets run the next line, we will use `next` (we will get later into this command).
 
 ----------------------------------------------------------------------------
 (rdb:11) next
@@ -381,12 +379,12 @@ And we'll ask again for the instance_variables.
 true
 ----------------------------------------------------------------------------
 
-Now @posts is a included in them, because the line defining it was executed.
+Now +@posts+ is a included in them, because the line defining it was executed.
 
 [TIP]
-You can also step into *irb* mode with the command *irb* (of course!). This way an irb session will be started within the context you invoked it. But you must know that this is an experimental feature.
+You can also step into *irb* mode with the command `irb` (of course!). This way an irb session will be started within the context you invoked it. But you must know that this is an experimental feature.
 
-To show variables and their values the *var* method is the most convenient way:
+To show variables and their values the `var` method is the most convenient way:
 
 ----------------------------------------------------------------------------
 var
@@ -413,29 +411,29 @@ You can also inspect for an object method this way:
 ----------------------------------------------------------------------------
 
 [TIP]
-Commands *p* (print) and *pp* (pretty print) can be used to evaluate Ruby expressions and display the value of variables to the console.
+Commands `p` (print) and `pp` (pretty print) can be used to evaluate Ruby expressions and display the value of variables to the console.
 
-We can use also *display* to start watching variables, this is a good way of tracking values of a variable while the execution goes on.
+We can use also `display` to start watching variables, this is a good way of tracking values of a variable while the execution goes on.
 
 ----------------------------------------------------------------------------
 (rdb:1) display @recent_comments
 1: @recent_comments =
 ----------------------------------------------------------------------------
 
-The variables inside the displaying list will be printed with their values after we move in the stack. To stop displaying a variable use *undisplay n* where _n_ is the variable number (1 in the last example).
+The variables inside the displaying list will be printed with their values after we move in the stack. To stop displaying a variable use `undisplay _n_` where _n_ is the variable number (1 in the last example).
 
 === Step by step
 
 Now you should know where you are in the running trace and be able to print the available variables. But lets continue and move on with the application execution.
 
-Use *step* (abbreviated *s*) to continue running your program until the next logical stopping point and return control to ruby-debug.
+Use `step` (abbreviated `s`) to continue running your program until the next logical stopping point and return control to ruby-debug.
 
 [TIP]
-You can also use *step+ n* and *step- n* to move forward or backward _n_ steps respectively.
+You can also use `step+ _n_` and `step- _n_` to move forward or backward _n_ steps respectively.
 
-You may also use *next* which is similar to step, but function or method calls that appear within the line of code are executed without stopping. As with step, you may use plus sign to move _n_ steps.
+You may also use `next` which is similar to step, but function or method calls that appear within the line of code are executed without stopping. As with step, you may use plus sign to move _n_ steps.
 
-The difference between *next* and "step" is that *step* stops at the next line of code executed, doing just single step, while *next* moves to the next line without descending inside methods.
+The difference between `next` and `step` is that `step` stops at the next line of code executed, doing just single step, while `next` moves to the next line without descending inside methods.
 
 Lets run the next line in this example:
 
@@ -457,7 +455,7 @@ end
 ----------------------------------------------------------------------------
 
 [TIP]
-You can use ruby-debug while using script/console but remember to *require "ruby-debug"* before calling *debugger* method.
+You can use ruby-debug while using script/console but remember to `require "ruby-debug"` before calling `debugger` method.
 
 ----------------------------------------------------------------------------
 /PathTo/project $ script/console
@@ -494,7 +492,7 @@ We are at the end of the line, but... was this line executed? We can inspect the
 @attributes_cache = {}
 ----------------------------------------------------------------------------
 
-@recent_comments hasn't been defined yet, so we can assure this line hasn't been executed yet, lets move on this code.
++@recent_comments+ hasn't been defined yet, so we can assure this line hasn't been executed yet, lets move on this code.
 
 ----------------------------------------------------------------------------
 (rdb:1) next
@@ -507,26 +505,26 @@ We are at the end of the line, but... was this line executed? We can inspect the
 @recent_comments = []
 ----------------------------------------------------------------------------
 
-Now we can see how @comments relationship was loaded and @recent_comments defined because the line was executed.
+Now we can see how +@comments+ relationship was loaded and @recent_comments defined because the line was executed.
 
-In case we want deeper in the stack trace we can move single *steps* and go into Rails code, this is the best way for finding bugs in your code, or maybe in Ruby or Rails.
+In case we want deeper in the stack trace we can move single `steps` and go into Rails code, this is the best way for finding bugs in your code, or maybe in Ruby or Rails.
 
 === Breakpoints
 
 A breakpoint makes your application stop whenever a certain point in the program is reached and the debugger shell is invoked in that line.
 
-You can add breakpoints dynamically with the command *break* (or just *b*), there are 3 possible ways of adding breakpoints manually:
+You can add breakpoints dynamically with the command `break` (or just `b`), there are 3 possible ways of adding breakpoints manually:
 
-* *break line*: set breakpoint in the _line_ in the current source file.
-* *break file:line [if expression]*: set breakpoint in the _line_ number inside the _file_. If an _expression_ is given it must evaluated to _true_ to fire up the debugger.
-* *break class(.|\#)method [if expression]*: set breakpoint in _method_ (. and \# for class and instance method respectively) defined in _class_. The _expression_ works the same way as with file:line.
+* `break line`: set breakpoint in the _line_ in the current source file.
+* `break file:line [if expression]`: set breakpoint in the _line_ number inside the _file_. If an _expression_ is given it must evaluated to _true_ to fire up the debugger.
+* `break class(.|\#)method [if expression]`: set breakpoint in _method_ (. and \# for class and instance method respectively) defined in _class_. The _expression_ works the same way as with file:line.
 
 ----------------------------------------------------------------------------
 (rdb:5) break 10
 Breakpoint 1 file /PathTo/project/vendor/rails/actionpack/lib/action_controller/filters.rb, line 10
 ----------------------------------------------------------------------------
 
-Use *info breakpoints n* or *info break n* lo list breakpoints, is _n_ is defined it shows that breakpoints, otherwise all breakpoints are listed.
+Use `info breakpoints _n_` or `info break _n_` lo list breakpoints, is _n_ is defined it shows that breakpoints, otherwise all breakpoints are listed.
 
 ----------------------------------------------------------------------------
 (rdb:5) info breakpoints
@@ -534,7 +532,7 @@ Num Enb What
   1 y   at filters.rb:10
 ----------------------------------------------------------------------------
 
-Deleting breakpoints: use the command *delete n* to remove the breakpoint number _n_ or all of them if _n_ is not specified.
+Deleting breakpoints: use the command `delete _n_` to remove the breakpoint number _n_ or all of them if _n_ is not specified.
 
 ----------------------------------------------------------------------------
 (rdb:5) delete 1
@@ -544,29 +542,29 @@ No breakpoints.
 
 Enabling/Disabling breakpoints:
 
-* *enable breakpoints*: allow a list _breakpoints_ or all of them if none specified, to stop your program (this is the default state when you create a breakpoint).
-* *disable breakpoints*: the _breakpoints_ will have no effect on your program.
+* `enable breakpoints`: allow a list _breakpoints_ or all of them if none specified, to stop your program (this is the default state when you create a breakpoint).
+* `disable breakpoints`: the _breakpoints_ will have no effect on your program.
 
 === Catching Exceptions
 
-The command *catch exception-name* (or just *cat exception-name*) can be used to intercept an exception of type _exception-name_ when there would otherwise be is no handler for it.
+The command `catch exception-name` (or just `cat exception-name`) can be used to intercept an exception of type _exception-name_ when there would otherwise be is no handler for it.
 
-To list existent catchpoints use *catch*.
+To list existent catchpoints use `catch`.
 
 === Resuming Execution
 
-* *continue* [line-specification] (or *c*): resume program execution, at the address where your script last stopped; any breakpoints set at that address are bypassed. The optional argument line-specification allows you to specify a line number to set a one-time breakpoint which is deleted when that breakpoint is reached.
-* *finish* [frame-number] (or *fin*): execute until selected stack frame returns. If no frame number is given, we run until the currently selected frame returns. The currently selected frame starts out the most-recent frame or 0 if no frame positioning (e.g up, down or frame) has been performed. If a frame number is given we run until frame frames returns.
+* `continue` [line-specification] (or `c`): resume program execution, at the address where your script last stopped; any breakpoints set at that address are bypassed. The optional argument line-specification allows you to specify a line number to set a one-time breakpoint which is deleted when that breakpoint is reached.
+* `finish` [frame-number] (or `fin`): execute until selected stack frame returns. If no frame number is given, we run until the currently selected frame returns. The currently selected frame starts out the most-recent frame or 0 if no frame positioning (e.g up, down or frame) has been performed. If a frame number is given we run until frame frames returns.
 
 === Editing
 
 At any time, you may use any of this commands to edit the code you are evaluating:
 
-* *edit [file:line]*: edit _file_ using the editor specified by the EDITOR environment variable. A specific _line_ can also be given.
-* *tmate n* (abbreviated *tm*): open the current file in TextMate. It uses n-th frame if _n_ is specified.
+* `edit [file:line]`: edit _file_ using the editor specified by the EDITOR environment variable. A specific _line_ can also be given.
+* `tmate _n_` (abbreviated `tm`): open the current file in TextMate. It uses n-th frame if _n_ is specified.
 
 === Quitting
-To exit the debugger, use the *quit* command (abbreviated *q*), or alias *exit*.
+To exit the debugger, use the `quit` command (abbreviated `q`), or alias `exit`.
 
 A simple quit tries to terminate all threads in effect. Therefore your server will be stopped and you will have to start it again.
 
@@ -574,17 +572,17 @@ A simple quit tries to terminate all threads in effect. Therefore your server wi
 
 There are some settings that can be configured in ruby-debug to make it easier to debug your code, being among others useful options:
 
-* *set reload*: Reload source code when changed.
-* *set autolist*: Execute 'list' command on every breakpoint.
-* *set listsize _n_*: Set number of source lines to list by default _n_.
-* *set forcestep*: Make sure 'next/step' commands always move to a new line
+* `set reload`: Reload source code when changed.
+* `set autolist`: Execute `list` command on every breakpoint.
+* `set listsize _n_`: Set number of source lines to list by default _n_.
+* `set forcestep`: Make sure `next` and `step` commands always move to a new line
 
-You can see the full list by using *help set* or *help set subcommand* to inspect any of them.
+You can see the full list by using `help set` or `help set subcommand` to inspect any of them.
 
 [TIP]
-You can include any number of this configuration lines inside a .rdebugrc file in your HOME directory, and ruby-debug will read it every time it is loaded
+You can include any number of this configuration lines inside a `.rdebugrc` file in your HOME directory, and ruby-debug will read it every time it is loaded
 
-The following lines are recommended to be included in .rdebugrc:
+The following lines are recommended to be included in `.rdebugrc`:
 
 ----------------------------------------------------------------------------
 set autolist