debugger2 1.0.0.beta1

data/doc/ruby-debug.texi

@@ -0,0 +1,3791 @@
+\input texinfo      @c -*-texinfo-*-
+@setfilename ruby-debug.info
+
+@set DBG ruby-debug
+@set ttrdebug @code{rdebug}
+@set ttDBG @code{@value{DBG}}
+@set Emacs @sc{gnu} Emacs
+
+@c Karl Berry informs me that this will add straight quotes in 
+@c typewriter text.
+@c See the "Inserting Quote Characters" node in the Texinfo manual
+@set txicodequoteundirected
+@set txicodequotebacktick
+@set RDEBUG_VERSION 0.11.6
+
+@macro Example {}
+@iftex
+@cartouche
+@end iftex
+@smallexample
+@end macro
+
+@macro EndExample {}
+@iftex
+@end cartouche
+@end iftex
+@end smallexample
+@end macro
+
+@macro DBG {}
+@value{DBG}
+@end macro
+
+@macro ttDBG {}
+@value{ttrdebug}
+@end macro
+
+@c How to show optional variables.
+@macro ovar{varname}
+@r{[}@var{\varname\}@r{]}
+@end macro
+
+@settitle ruby-debug
+@setchapternewpage odd
+@c %**end of header
+
+@include version.texi
+
+@finalout
+
+@c THIS MANUAL REQUIRES TEXINFO 4.0 OR LATER.
+
+@c This is a dir.info fragment to support semi-automated addition of
+@c manuals to an info tree.
+@dircategory Programming & development tools.
+@direntry
+* ruby-debug: (ruby-debug).    Ruby Debugger
+@end direntry
+
+@titlepage
+@title Debugging with @code{ruby-debug}
+@sp 1
+@subtitle @value{EDITION} Edition
+@subtitle @value{UPDATED-MONTH}
+@author Rocky Bernstein, Kent Sibilev, and Mark Moseley
+@page
+@ifset WHERETO
+@tex
+{\parskip=0pt
+\hfill (Send bugs and comments on ruby-debug to fill in...)\par
+\hfill {\it Debugging with {\tt ruby-debug}\par
+\hfill \TeX{}info \texinfoversion\par
+}
+@end tex
+@end ifset
+@end titlepage
+@page
+
+@ifnottex
+@node Top, Summary, (dir), (dir)
+@top Debugging with ruby-debug
+
+This file describes ruby-debug, the Ruby Debugger, 
+version @value{RDEBUG_VERSION}
+
+This is the @value{EDITION} Edition, @value{UPDATED}
+@c Copyright (C) 2007 ...
+
+@menu
+* Summary::                     Overview of Debugger with sample sessions
+* Invocation::                  Getting in and out
+* Debugger Command Reference::  rdebug command reference
+* Post-Mortem Debugging::       Debugging on an uncaught exception
+* Debugger Module and Class::   ruby-debug's Debugger module and class
+
+Appendix
+* Using from GitHub::
+
+Indexes (nodes containing large menus)
+* Class Module Index::        An item for Class, Module, and Methods.
+* Command Index::             An item for each command name.
+* General Index::             An item for each concept.
+@end menu
+
+@end ifnottex
+
+@contents
+
+@node Summary
+@chapter Summary of @code{ruby-debug}
+
+The purpose of a debugger such as @DBG{} is to allow you to see what is
+going on ``inside'' a Ruby program while it executes.
+
+@ttDBG{} can do four main kinds of things (plus other things in support of
+these) to help you catch bugs in the act:
+
+@itemize @bullet
+@item
+Start your script, specifying anything that might affect its behavior.
+
+@item
+Make your script stop on specified conditions.
+
+@item
+Examine what has happened, when your script has stopped.
+
+@item
+Change things in your script, so you can experiment with correcting the
+effects of one bug and go on to learn about another.
+@end itemize
+
+Although you can use @value{ttrdebug} to invoke your Ruby programs via
+a debugger at the outset, there are other ways to use and enter the
+debugger. 
+
+@menu
+* First Sample Session::   A Simple Sample @code{rdebug} session
+* Second Sample Session::  Second Session Delving a little deeper @code{rdebug} session
+* Unit Testing Session::   Using the debugger in unit testing
+* Debugger.start with a block::   Using the Debugger.start with a block
+* Debugging Oddities::     How debugging Ruby may be different...
+@end menu
+
+@node First Sample Session
+@section The First Sample @code{rdebug} Session (@code{list}, @code{display}, @code{print}, and @code{quit})
+
+You can use this manual at your leisure to read all about @value{ttDBG}.
+However, a handful of commands are enough to get started using the
+debugger.  The following sections illustrates these commands.
+
+@iftex
+In this sample session, we emphasize user input like this: @b{input},
+to make it easier to pick out from the surrounding output.
+@end iftex
+
+Below is Ruby code to compute a triangle number of a given
+length.@footnote{There are of course shorter ways to define @code{triangle}
+such as:
+@smallexample
+  def triangle(n) (n * (n+1)) / 2 end
+@end smallexample
+The code we use in this example and the next is more for pedagogical
+purposes than how to write short Ruby code.}
+
+
+@smallexample
+$ @b{rdebug triangle.rb}
+triangle.rb:4 def hanoi(n,a,b,c)
+(rdb:1) @b{list}
+[-1, 8] in ./triangle.rb
+   1  #!/usr/bin/env ruby
+   2  # Compute the n'th triangle number - the hard way
+   3  # triangle(n) == (n * (n+1)) / 2
+=> 4  def triangle(n)
+   5    tri = 0
+   6    0.upto(n) do |i|
+   7      tri += i
+   8    end
+(rdb:1) @b{l}
+[9, 18] in ./triangle.rb
+   9    tri
+   10  end
+   11  
+   12  t = triangle(3)
+   13  puts t
+(rdb:1) @b{list 1,100}
+[1, 100] in ./triangle.rb
+   1  #!/usr/bin/env ruby
+   2  # Compute the n'th triangle number - the hard way
+   3  # triangle(n) == (n * (n+1)) / 2
+=> 4  def triangle(n)
+   5    tri = 0
+   6    0.upto(n) do |i|
+   7      tri += i
+   8    end
+   9    tri
+   10  end
+   11  
+   12  t = triangle(3)
+   13  puts t
+(rdb:1) 
+@end smallexample
+
+@noindent
+
+There are lots of command options, but we don't need them for now. See
+@ref{rdebug command-line options} for a full list of command options.
+
+Position information consists of a filename and line number,
+e.g.@: @code{triangle.rb:4}. We are currently stopped before the first
+executable line of the program; this is line 4 of
+@code{triangle.rb}. If you are used to less dynamic languages and have
+used debuggers for more statically compiled languages like C, C++, or
+Java, it may seem odd to be stopped before a function definition.  But
+in Ruby line 4 is executed, the name @code{triangle} (probably) does
+not exist so issuing a method call of @code{triangle} will raise a
+``method not found'' error.
+
+@DBG{}'s prompt is @code{(rdb:@emph{n})}. The @emph{n} is the thread
+number. Here it is 1 which is usually the case for the main thread. If
+the program has died and you are in post-mortem debugging, there is no
+thread number. In this situation, the string @code{post-mortem} is
+used in place of a thread number. If the program has terminated
+normally, the string this position will be @code{ctrl}. The commands
+which are available change depending on the program state.
+
+The first command, @code{list} (@pxref{List}), prints 10 lines
+centered around the current line; the current line here is line 4 and
+is marked by @code{=>}, so the range the debugger would like to show
+is -1..8. However since there aren't 5 lines before the current line,
+those additional lines---``lines'' -1 and 0---are dropped and we print
+the remaining 8 lines.  The @code{list} command can be abbreviated
+with @code{l} which is what we use next. Notice that when we use this
+a second time, we continue listing from the place we last left
+off. The desired range of lines this time is lines 9 to 18; but since
+the program ends at line 13, only the remaining 5 lines are shown.
+
+If you want to set how many lines to print by default rather than use
+the initial number of lines, 10, use the @code{set listsize} command
+(@pxref{Listsize}). To see the entire program in one shot, we gave an
+explicit starting and ending line number.
+
+If you use a front-end to the debugger such as the Emacs interface,
+@c (@pxref{GNU Emacs})
+you probably won't use @code{list} all that much.
+
+Now let us step through the program.
+
+@smallexample
+(rdb:1) @b{step}
+triangle.rb:12
+t = triangle(3)
+(rdb:1) @b{@key{<RET>}}
+triangle.rb:5
+tri = 0
+(rdb:1) @b{p tri}
+nil
+(rdb:1) @b{step}
+triangle.rb:6
+0.upto(n) do |i|
+(rdb:1) @b{p tri}
+0
+@end smallexample
+
+The first @kbd{step} command (@pxref{Step}) runs the script one
+executable unit. The second command we entered was just hitting the
+return key; @ttDBG{} remembers the last command you entered was
+@code{step}, so it runs that last command again.
+
+One way to print the values of variables uses @code{p}. (Of course,
+there are of course lots of other ways too.). When we look at the
+value of @code{tri} the first time, we see it is @code{nil}. Again we
+are stopped @emph{before} the assignment on line 5, and this variable
+hasn't been set previously. However after issuing another ``step''
+command we see that the value is 0 as expected.
+
+However if every time we stop we want to see the value of @code{tri}
+to see how things are going stop, there is a better way by setting a
+display expression (@pxref{DisplayCommands}).
+
+@smallexample
+(rdb:1) @b{display tri}
+1: tri = 0
+@end smallexample
+
+Now let us run the program until we return from the function. However
+we'll want to see which lines get run.
+
+@smallexample
+(rdb:1) @b{display i}
+2: i =
+(rdb:1) @b{set linetrace on}
+line tracing is on.
+(rdb:1) @b{finish}
+Tracing(1):triangle.rb:7 tri += i
+1: tri = 0
+2: i = 0
+Tracing(1):triangle.rb:7 tri += i
+1: tri = 0
+2: i = 1
+Tracing(1):triangle.rb:7 tri += i
+1: tri = 1
+2: i = 2
+Tracing(1):triangle.rb:7 tri += i
+1: tri = 3
+2: i = 3
+Tracing(1):triangle.rb:9 tri
+1: tri = 6
+2: i = 3
+6
+Tracing(1):triangle.rb:13 puts t
+1: tri =
+2: i = 
+1: tri =
+2: i = 
+triangle.rb:13
+puts t
+(rdb:1) @b{quit}
+Really quit? (y/n) @b{y}
+@end smallexample
+
+So far, so good. A you can see from the above to get out of the
+debugger, one can issue a @code{quit} command. (@code{q} and
+@code{exit} are just as good. If you want to quit without being
+prompted, suffix the command with an exclamation mark, e.g.\@code{q!}.
+
+@node Second Sample Session
+@section Sample Session 2: Delving Deeper (@code{where}, @code{frame}, @code{restart}, @code{autoeval}, @code{break}, @code{ps})
+
+In this section we'll introduce breakpoints, the call stack and
+restarting.  So far we've been doing pretty good in that we've not
+encountered a bug to fix. Let's try another simple example. Okay
+here's the program.
+
+Below we will debug a simple Ruby program to solve the classic Towers
+of Hanoi puzzle. It is augmented by the bane of programming: some
+command-parameter processing with error checking.
+
+@smallexample
+$ @b{rdebug hanoi.rb}
+hanoi.rb:3 def hanoi(n,a,b,c)
+(rdb:1) @b{list 1,100}
+[1, 100] in ./hanoi.rb
+   1  #!/usr/bin/ruby
+   2
+=> 3  def hanoi(n,a,b,c)
+   4    if n-1 > 0
+   5      hanoi(n-1, a, c, b)
+   6    end
+   7    puts "Move disk %s to %s" % [a, b]
+   8    if n-1 > 0
+   9      hanoi(n-1, c, b, a)
+   10   end
+   11 end
+   12
+   13 i_args=ARGV.length
+   14 if i_args > 1
+   15   puts "*** Need number of disks or no parameter"
+   16   exit 1
+   17 end
+   18
+   19 n=3
+   20
+   21 if i_args > 0
+   22   begin
+   23     n = ARGV[0].to_i
+   24   rescue ValueError, msg
+   25     print "** Expecting an integer, got: %s" % ARGV[0].to_s
+   26     exit 2
+   27   end
+   28 end
+   29
+   30 if n < 1 or n > 100
+   31   puts "*** number of disks should be between 1 and 100"
+   32   exit 2
+   33 end
+   34
+   35 hanoi(n, :a, :b, :c)
+(rdb:1)
+@end smallexample
+
+Recall in the first section I said that before the @code{def} is run
+the method it names is undefined. Let's check that out. First let's
+see what private methods we can call before running @code{def hanoi}
+
+@smallexample
+(rdb:1) @b{set autoeval on}
+autoeval is on.
+(rdb:1) @b{private_methods}
+[:require_relative, :Digest, :default_src_encoding, :debug_program, ... 
+@end smallexample
+
+The @code{set autoeval} (@pxref{Autoeval}) command causes any commands
+that are not normally understood to be debugger commands to get
+evaluated as though they were Ruby commands. I use this a lot, so I
+set this by putting it the command file @code{.rdebugrc},
+@pxref{Command Files}, that gets read when @code{ruby-debug} starts.
+
+As showing the list output of @code{private_methods}, I find this kind
+of list unwieldy. What you are supposed to notice here is that
+method @code{hanoi} is not in this list. When you ask
+@code{ruby-debug} for a list of method names via @code{method
+instance}, it doesn't show output in this way; @code{ruby-debug} can
+sort and put into columns lists like this using the print command, @code{ps}.
+
+
+@smallexample
+(rdb:1) @b{ps private_methods}
+Array         debug_program         p                           spawn
+Complex       default_src_encoding  pp                          sprintf
+Digest        eval                  print                       srand
+Float         exec                  printf                      syscall
+Integer       exit                  proc                        system
+Pathname      exit!                 process_options             test
+Rational      fail                  putc                        throw
+String        fork                  puts                        trace_var
+__callee__    format                raise                       trap
+__method__    gem                   rand                        untrace_var
+`             gets                  readline                    warn
+abort         global_variables      readlines                   whence_file
+at_exit       initialize            remove_instance_variable    y
+autoload      initialize_copy       require
+autoload?     iterator?             require_relative
+binding       lambda                select
+block_given?  load                  set_trace_func
+caller        local_variables       singleton_method_added
+catch         loop                  singleton_method_removed
+dbg_print     method_missing        singleton_method_undefined
+dbg_puts      open                  sleep
+@end smallexample
+
+Now let's see what happens after stepping:
+
+@smallexample
+(rdb:1) @b{private_methods.member?(:hanoi)}
+false
+(rdb:1) @b{step}
+hanoi.rb:13
+i_args=ARGV.length
+(rdb:1) @b{private_methods.member?(:hanoi)}
+true
+(rdb:1)
+@end smallexample
+
+Okay, now where were we?
+
+@smallexample
+(rdb:1) @b{list}
+[8, 17] in ./hanoi.rb
+   8      if n-1 > 0
+   9         hanoi(n-1, c, b, a)
+   10      end
+   11  end
+   12
+=> 13  i_args=ARGV.length
+   14  if i_args > 1
+   15      puts "*** Need number of disks or no parameter"
+   16      exit 1
+   17  end
+(rdb:1) @b{ARGV}
+[]
+@end smallexample
+
+Ooops. We forgot to specify any parameters to this program. Let's try
+again. We can use the @code{restart} command here.
+
+@smallexample
+(rdb:1) @b{restart 3}
+Re exec'ing:
+        /usr/bin/rdebug hanoi.rb 3
+hanoi.rb:3
+def hanoi(n,a,b,c)
+(rdb:1) @b{break 4}
+Breakpoint 1 file hanoi.rb, line 4
+(rdb:1) @b{continue}
+Breakpoint 1 at hanoi.rb:4
+./hanoi.rb:4 if n-1 > 0
+(rdb:1) @b{display n}
+1: n = 3
+(rdb:1) @b{display a}
+2: a = a
+(rdb:1) @b{undisplay 2}
+(rdb:1) @b{display a.inspect}
+3: a.inspect = :a
+(rdb:1) @b{display b.inspect}
+4: b.inspect = :b
+(rdb:1) @b{continue}
+Breakpoint 1 at hanoi.rb:4
+1: n = 2
+3: a.inspect = :a
+4: b.inspect = :c
+./hanoi.rb:4 
+if n-1 > 0
+(rdb:1) @b{c}
+Breakpoint 1 at hanoi.rb:4
+1: n = 1
+3: a.inspect = :a
+4: b.inspect = :b
+./hanoi.rb:4 
+if n-1 > 0
+(rdb:1) @b{where}
+--> #0 Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol) at line hanoi.rb:4
+    #1 Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol) at line hanoi.rb:5
+    #2 Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol) at line hanoi.rb:5
+    #3 at line hanoi.rb:35
+(rdb:1) 
+@end smallexample
+
+In the above we added a new command, @code{break}
+(@pxref{Breakpoints}) which indicates to go into the debugger just
+before that line of code is run. And @code{continue} resumes
+execution.  Notice the difference between @code{display a} and
+@code{display a.inspect}. An implied string conversion is performed on
+the expression after it is evaluated. To remove a display expression
+we used @code{undisplay} is used. If we give a display number, just
+that display expression is removed.
+
+Above we also used a new command @code{where} (@pxref{Backtrace} to
+show the call stack. In the above situation, starting from the bottom
+line we see we called the hanoi from line 35 of the file
+@code{hanoi.rb} and the hanoi method called itself two more times at
+line 5.
+
+In the call stack we show the file line position in the same format
+when we stop at a line. Also we see the names of the parameters and
+the types that those parameters @emph{currently} have. It's possible
+that when the program was called the parameter had a different type,
+since the types of variables can change dynamically. You alter the
+style of what to show in the trace (@pxref{Callstyle}).
+
+Let's explore a little more. Now were were we? 
+
+@smallexample
+(rdb:1) @b{list}
+   1  #!/usr/bin/ruby
+   2
+   3  def hanoi(n,a,b,c)
+=> 4      if n-1 > 0
+   5         hanoi(n-1, a, c, b)
+   6      end
+   7      puts "Move disk %s to %s" % [a, b]
+   8      if n-1 > 0
+(rdb:1) @b{undisplay}
+Clear all expressions? (y/n) @b{y}
+(rdb:1) @b{i_args}
+NameError Exception: undefined local variable or method `i_args' for main:Object
+(rdb:1) @b{frame -1}
+#3 at line hanoi.rb:35
+(rdb:1) @b{i_args}
+1
+(rdb:1) @b{p n}
+3
+(rdb:1) @b{down 2}
+#2 Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol) at line hanoi.rb:5
+(rdb:1) @b{p n}
+2
+@end smallexample
+
+Notice in the above to get the value of variable @code{n}, I have to
+use a print command like @code{p n}; If I entered just @code{n}, that
+would be taken to mean the debugger command ``next''. In the current
+scope, variable @code{i_args} is not defined. However I can change to
+the top-most frame by using the @code{frame} command. Just as with
+arrays, -1 means the last one. Alternatively using frame number 3
+would have been the same thing; so would issuing @code{up 3}.
+
+Note that in the outside frame 3, the value of @code{i_args} can be
+shown. Also note that the value of variable @code{n} is different.
+
+@node Unit Testing Session
+@section Using the debugger in unit testing (@code{ruby-debug/debugger}, @code{Debugger.start})
+
+In the previous sessions we've been calling the debugger right at the
+outset. I confess that this mode of operation is usually not how I use
+the debugger.
+
+There are a number of situations where calling the debugger at the outset is
+impractical for a couple of reasons.
+
+@enumerate
+@item 
+The debugger just doesn't work when run at the outset.  By necessity
+any debugging changes to the behavior or the program in slight and
+subtle ways, and sometimes this can hinder finding bugs.
+@item 
+There's a lot of code which that needs to get run before the part you
+want to inspect. Running this code takes time and you don't want the
+overhead of the debugger.
+@end enumerate
+
+In this section we'll show how to enter the code in the middle
+of your program, while delving more into the debugger operation.
+
+In this section we will also use unit testing. Using unit tests will
+greatly reduce the amount of debugging needed, while at the same time, 
+will increase the quality of your program.
+
+What we'll do is take the @code{triangle} code from the first session
+and write a unit test for that. In a sense we did write a mini-test
+for the program which was basically the last line where we printed the
+value of triangle(3). This test however wasn't automated: the
+implication is that someone would look at the output and verify that
+what was printed is what was expected.
+
+And before we can turn that into something that can be
+@code{required}, we probably want to remove that output. However I
+like to keep in that line so that when I look at the file, I have an
+example of how to run it.  Therefore we will conditionally run this
+line if that file is invoked directly, but skip it if it is
+not.@footnote{@code{rdebug} resets @code{$0} to try to make things
+like this work.}
+@smallexample
+  if __FILE__ == $0 
+    t = triangle(3)
+    puts t
+  end
+@end smallexample
+
+Let's call this file @code{tri2.rb}.
+
+Okay, we're now ready to write our unit test. We'll use
+@code{"test/unit"} which comes with the standard Ruby distribution.
+Here's the test code; it should be in the same directory as tri2.rb.
+
+@smallexample
+  #!/usr/bin/env ruby
+  require 'test/unit'
+  require_relative './tri2.rb'
+
+  class TestTri < Test::Unit::TestCase
+    def test_basic
+     solutions = []
+     0.upto(5) do |i|
+        solutions << triangle(i)
+      end
+      assert_equal([0, 1, 3, 6, 10, 15], solutions,
+                   'Testing the first 5 triangle numbers')
+    end
+  end
+@end smallexample
+
+If you run it will work. However if you run @code{rdebug} initially,
+you will not get into the test, because @code{test/unit} wants to be
+the main program. So here is a situation where one may need to modify
+the program to add an explicit @emph{entry} into the
+debugger.@footnote{For some versions of rake and @code{rdebug} you can
+in fact set a breakpoint after running @code{rdebug}
+initially. Personally though I find it much simpler and more reliable
+to modify the code as shown here.}
+
+One way to do this is to add the following before the place you want
+to stop:
+@smallexample
+  require 'ruby-debug'
+  debugger
+@end smallexample
+
+Let's add this code just after entering @code{test_basic}:
+@smallexample
+  ... 
+  def test_basic
+    @b{require "ruby-debug"}
+    @b{debugger}
+    solutions = []
+   ...
+@end smallexample
+
+Now we run the program..
+@smallexample
+  $ @b{ruby test-tri.rb}
+  Loaded suite test-tri
+  Started
+  test-tri.rb:9
+  solutions = []
+  (rdb:1)
+@end smallexample
+and we see that we are stopped at line 9 just before the
+initialization of the list @code{solutions}.
+
+Now let's see where we are...
+
+@smallexample
+(rdb:1) @b{where}
+--> #0 TestTri.test_basic at line /home/rocky/ruby/test-tri.rb:9
+(rdb:1) 
+@end smallexample
+
+Something seems wrong here; @code{TestTri.test_basic} indicates that
+we are in class @code{TestTri} in method @code{test_basic}. However we
+don't see the call to this like we did in the last example when we
+used the @code{where} command. This is because the debugger really
+didn't spring into existence until after we already entered that
+method, and Ruby doesn't keep call stack information around in a
+way that will give the information we show when running @code{where}.
+
+If we want call stack information, we have to turn call-stack tracking
+on @emph{beforehand}. This is done by adding @code{Debugger.start}.
+
+Here's what our test program looks like so after we modify it to start
+tracking calls from the outset
+
+@smallexample
+#!/usr/bin/env ruby
+require 'test/unit'
+require 'tri2.rb'
+require 'ruby-debug'
+@b{Debugger.start}
+
+class TestTri < Test::Unit::TestCase
+  def test_basic
+    @b{debugger}
+    solutions = []
+    0.upto(5) do |i|
+      solutions << triangle(i)
+    end
+    assert_equal([0, 1, 3, 6, 10, 15], solutions,
+                 "Testing the first 5 triangle numbers")
+  end
+end
+@end smallexample
+
+Now when we run this:
+@smallexample
+$ @b{ruby test-tri2.rb}
+Loaded suite test-tri2
+Started
+test-tri2.rb:11
+solutions = []
+(rdb:1) @b{where}
+--> #0 TestTri.test_basic at line test-tri2.rb:11
+    #1 MiniTest::Unit::TestCase.run(runner#MiniTest::Unit)
+       at line /usr/local/lib/ruby/1.9.1/minitest/unit.rb:458
+    #2 MiniTest::Unit.run_test_suites
+       at line /usr/local/lib/ruby/1.9.1/minitest/unit.rb:426
+    #3 MiniTest::Unit.run
+       at line /usr/local/lib/ruby/1.9.1/minitest/unit.rb:393
+    #4 at line /usr/local/lib/ruby/1.9.1/minitest/unit.rb:334
+(rdb:1) 
+@end smallexample
+
+Much better. But again let me emphasize that the parameter types are
+those of the corresponding variables that @emph{currently} exist, and
+this might have changed since the time when the call was made.
+
+@node Debugger.start with a block
+@section Using the @code{Debugger.start} with a block
+
+We saw that @code{Debugger.start()} and @code{Debugger.stop()} allow
+fine-grain control over where the debugger tracking should occur. 
+
+Rather than use an explicit @code{stop()}, you can also pass a block
+to the @code{start()} method. This causes @code{start()} to run and
+then @code{yield} to that block. When the block is finished,
+@code{stop()} is run. In other words, this wraps a
+@code{Debugger.start()} and @code{Debugger.stop()} around the block of
+code. But it also has a side benefit of ensuring that in the presence
+of an uncaught exception @code{stop} is run, without having to
+explicitly use @code{begin} ... @code{ensure Debugger.stop() end}.
+
+For example, in Ruby Rails you might want to debug code in one of the
+controllers without causing any slowdown to any other code. And
+this can be done by wrapping the controller in a @code{start()} with a
+block; when the method wrapped this way finishes the debugger is
+turned off, and the application proceeds at regular speed.
+
+Of course, inside the block you will probably want to enter the
+debugger using @code{Debugger.debugger()}, otherwise there would
+little point in using the @code{start}. For example, you can do this
+in @code{irb}:
+
+@smallexample
+$ @b{irb}
+irb(main):001:0> @b{require 'ruby-debug'}
+=> true
+irb(main):002:0> @b{def foo}
+irb(main):003:1> @b{x=1}
+irb(main):004:1> @b{puts 'foo'}
+irb(main):005:1> @b{end}
+=> nil
+irb(main):006:0> @b{Debugger.start@{debugger; foo@}}
+(irb):3
+
+(rdb:1) @b{s}
+(irb):4
+
+(rdb:1) @b{p x}
+1
+(rdb:1) @b{s}
+foo
+=> true
+irb(main):007:0> 
+@end smallexample
+
+There is a counter inside of @code{Debugger.start} method to make sure
+that this works when another @code{Debugger.start} method is called
+inside of outer one. However if you are stopped inside the debugger,
+issuing another @code{debugger} call will not have any effect even if
+it is nested inside another @code{Debugger.start}.
+
+@node Debugging Oddities
+@section How debugging Ruby may be different than debugging other Languages
+
+If you are used to debugging in other languages like C, C++, Perl,
+Java or even Bash@footnote{this is just an excuse to put in a
+shameless plug for my bash debugger @url{http://bashdb.sf.net}}, there
+may be a number of things that seem or feel a little bit different and
+may confuse you. A number of these things aren't oddities of the
+debugger per se, so much as a difference in how Ruby works compared to
+those other languages. Because Ruby works a little differently from
+those other languages, writing a debugger has to also be a little
+different as well if it is to be useful.
+
+In this respect, using the debugger may help you understand Ruby
+better.
+
+We've already seen two examples of such differences. One difference is
+the fact that we stop on method definitions or @code{def}'s and that is
+because these are in fact executable statements. In other compiled
+languages this would not happen because that's already been done when
+you compile the program (or in Perl when it scans in the program). The
+other difference we saw was in our inability to show call stack parameter
+types without having made arrangements for the debugger to track
+this. In other languages call stack information is usually available
+without asking assistance of the debugger.@footnote{However in C, and
+C++ generally you have to ask the compiler to add such information.}
+
+In this section we'll consider some other things that might throw
+off new users to Ruby who are familiar with other languages and
+debugging in them.
+
+@menu
+* Stack No Longer Shows Scope Nesting::
+* Bouncing Around in Blocks (e.g. Iterators)::
+* No Parameter Values in a Call Stack::
+* Lines You Can Stop At::
+@end menu
+
+@node Stack No Longer Shows Scope Nesting
+@subsection Stack No Longer Shows Scope Nesting
+In the Ruby 1.8 ruby-debug, backtraces will show more stack frames 
+that you might find in other languages, such as C. In the Ruby 1.9
+ruby-debug, this is no longer the case.
+
+@node Bouncing Around in Blocks (e.g. Iterators)
+@subsection Bouncing Around in Blocks (e.g.@: Iterators)
+
+When debugging languages with coroutines like Python and Ruby, a
+method call may not necessarily go to the first statement after the
+method header. It's possible the call will continue after a
+@code{yield} statement from a prior call. 
+
+@smallexample
+ 1 #!/usr/bin/env ruby
+ 2 # Enumerator for primes
+ 3 class SievePrime
+ 4   @@@@odd_primes = []
+ 5   def self.next_prime(&block)
+ 6     candidate = 2
+ 7     yield candidate
+ 8     not_prime = false
+ 9     candidate += 1
+10     while true do
+11       @@@@odd_primes.each do |p|
+12         not_prime = (0 == (candidate % p))
+13         break if not_prime
+14       end
+15       unless not_prime
+16         @@@@odd_primes << candidate
+17         yield candidate 
+18       end
+19       candidate += 2
+20     end
+21   end
+22 end
+23 SievePrime.next_prime do |prime|
+24   puts prime
+25   break if prime > 10
+26 end
+@end smallexample
+
+@smallexample
+$ @b{rdebug primes.rb}
+primes.rb:3
+class SievePrime
+(rdb:1) @b{set linetrace on}
+line tracing is on.
+(rdb:1) @b{step 9}
+Tracing(1):primes.rb:4 @@odd_primes = []
+Tracing(1):primes.rb:5 def self.next_prime(&block)
+Tracing(1):primes.rb:23 SievePrime.next_prime do |prime|
+Tracing(1):primes.rb:6 candidate = 2
+Tracing(1):primes.rb:7 yield candidate
+Tracing(1):primes.rb:24 puts prime
+2
+Tracing(1):primes.rb:25 break if prime > 10
+Tracing(1):primes.rb:8 not_prime = false
+Tracing(1):primes.rb:9 candidate += 1
+primes.rb:9
+candidate += 1
+(rdb:1) 
+@end smallexample
+
+The loop between lines 23--26 gets interleaved between those of
+@code{Sieve::next_prime}, lines 6--19 above. 
+
+A similar kind of thing can occur in debugging programs with many threads. 
+
+@node No Parameter Values in a Call Stack
+@subsection No Parameter Values in a Call Stack
+In traditional debuggers in a call stack you can generally see the
+names of the parameters and the values that were passed in.
+
+Ruby is a very dynamic language and it tries to be efficient within
+the confines of the language definition. Values generally aren't taken
+out of a variable or expression and pushed onto a stack. Instead a new
+scope created and the parameters are given initial values. Parameter
+passing is by @emph{reference}, not by value as it is say Algol, C, or
+Perl. During the execution of a method, parameter values can
+change---and often do. In fact even the @emph{class} of the object can
+change.
+
+So at present, the name of the parameter shown. The call-style setting
+@pxref{Callstyle} can be used to set whether the name is shown or the
+name and the @emph{current} class of the object. 
+
+It has been contemplated that a style might be added which saves on
+call shorter ``scalar'' types of values and the class name. 
+
+@node Lines You Can Stop At
+@subsection Lines You Can Stop At
+As with the duplicate stops per control (e.g.@: @code{if} statement),
+until tools like debuggers get more traction among core ruby
+developers there are going to be weirdness. Here we describe the
+stopping locations which effects the breakpoint line numbers you can
+stop at. 
+
+Consider the following little Ruby program.
+
+@smallexample
+'Yes it does' =~ /
+(Yes) \s+
+it  \s+
+does
+/ix 
+puts $1
+@end smallexample
+
+The stopping points that Ruby records are the last two lines, lines 5
+and 6.
+
+Inside @code{ruby-debug} you an get a list of stoppable lines for a
+file using the @code{info file} command with the attribute
+@code{breakpoints}.
+
+@ifset FINISHED
+To be continued...
+
+@itemize @bullet
+@item more complex example with objects, pretty printing and irb.
+@item line tracing and non-interactive tracing.
+@item mixing in Debugger.debug with rdebug
+@item post-mortem debugging and setting up for that
+@item threading?
+@item references to videos
+@end itemize
+@end ifset
+
+@node Invocation
+@chapter Getting in and out
+
+@menu
+* Starting the debugger::    How to enter the debugger
+* Command Files::            Command files
+* Quitting the debugger::    How to leave the debugger (quit, kill)
+* Calling from Program::     Calling the debugger from inside your program
+@end menu
+
+It is also possible to enter the debugger when you have an uncaught
+exception. See See also @ref{Post-Mortem Debugging}. 
+
+@node Starting the debugger
+@section Starting the debugger
+
+Although one can enter @DBG{} via Emacs (described in a later section)
+and possibly others interfaces, probably the most familiar thing to do
+is invoke the debugger from a command line.
+
+A wrapper shell script called @code{rdebug} basically @code{require}'s
+the gem package @code{ruby-debug} and then loads @code{rdebug}.
+
+@smallexample
+rdebug [rdebug-options] [--] @var{ruby-script} @var{ruby-script-arguments...}
+@end smallexample
+
+If you don't need to pass dash options to your program which might get
+confused with the debugger options, then you don't need to add the
+@option{--}.
+
+To get a brief list of options and descriptions, use the @code{--help}
+option.
+
+@smallexample
+$ @b{rdebug --help}
+rdebug @value{RDEBUG_VERSION}
+Usage: rdebug [options] <script.rb> -- <script.rb parameters>
+
+Options:
+    -A, --annotate LEVEL             Set annotation level
+    -c, --client                     Connect to remote debugger
+        --cport PORT                 Port used for control commands
+    -d, --debug                      Set $DEBUG=true
+        --emacs                      Activates full Emacs support
+        --emacs-basic                Activates basic Emacs mode
+    -h, --host HOST                  Host name used for remote debugging
+    -I, --include PATH               Add PATH to $LOAD_PATH
+        --keep-frame-binding         Keep frame bindings
+    -m, --post-mortem                Activate post-mortem mode
+        --no-control                 Do not automatically start control thread
+        --no-quit                    Do not quit when script finishes
+        --no-rewrite-program         Do not set $0 to the program being debugged
+        --no-stop                    Do not stop when script is loaded
+    -nx                              Not run debugger initialization files (e.g. .rdebugrc        
+    -p, --port PORT                  Port used for remote debugging
+    -r, --require SCRIPT             Require the library, before executing your script
+        --restart-script FILE        Name of the script file to run. Erased after read    
+        --script FILE                Name of the script file to run
+    -s, --server                     Listen for remote connections
+    -w, --wait                       Wait for a client connection, implies -s option
+    -x, --trace                      Turn on line tracing
+
+Common options:
+        --verbose                    Turn on verbose mode
+        --help                       Show this message
+        --version                    Print the version
+    -v                               Print version number, then turn on verbose mode
+@end smallexample
+
+Options for the @code{rdebug} are shown in the following list.  
+
+@menu
+* rdebug command-line options::   Options you can pass to rdebug
+* rdebug default options::        How to Set Default Command-Line Options
+@end menu
+
+@node rdebug command-line options
+@subsection Options you can pass to rdebug
+
+You can run @DBG{} in various alternative modes---for example, as a
+program that interacts directly with the program in the same process
+on the same computer or via a socket to another process possibly on a
+different computer. 
+
+Many options appear as a long option name, such as @option{--help}, and
+a short one letter option name, such as @option{-h}. A double dash
+(@option{--} is used to separate options which go to @code{rdebug} from
+options that are intended to go to your Ruby script. Options (if any)
+to @code{rdebug} should come first. If there is no possibility of the
+Ruby script to be debugged getting confused with @code{rdebug}'s
+option the double dash can be omitted.
+
+@table @code
+@item --help
+@cindex @option{-h}
+@cindex @option{--help}
+This option causes @ttDBG{} to print some basic help and exit.
+
+@item -v | --version
+@cindex @option{-v}
+This option causes @ttDBG{} to print its version number and exit.
+
+@item -A | --annotate @var{level}
+@cindex @option{-A}
+@cindex @option{--annotation} @var{level}
+Set gdb-style annotation @var{level}, a number. Additional information is output
+automatically when program state is changed. This can be used by
+front-ends such as GNU Emacs to post this updated information without
+having to poll for it.
+@item -c | --client
+@cindex @option{-c}
+@cindex @option{--client}
+Connect to remote debugger. The remote debugger should have been set
+up previously our you will get a connection error and @code{rdebug}
+will terminate. 
+
+@item --cport @var{port}
+@cindex @option{--cport} @var{port}
+Port used for control commands.
+
+@item --debug
+@cindex @option{--debug}
+Set @code{$DEBUG} to @code{true}. This option is compatible with
+Ruby's.
+
+@item --emacs
+Activates GNU Emacs mode.
+@c @pxref{GNU Emacs}. 
+Debugger output is tagged in such a way to allow GNU Emacs to track
+where you are in the code.
+
+@item --emacs-basic
+Activates full GNU Emacs mode.
+@c (@pxref{GNU Emacs}). 
+This is the equivalent of setting the options @option{--emacs-basic},
+@code{annotate=3}, @option{--no-stop}, @option{-no-control} and
+@option{--post-mortem}.
+
+@item -h | --host @var{host-address}
+Connect host address for remote debugging.
+
+@item -I --include @var{PATH}
+@cindex @option{-I} @var{PATH}
+@cindex @option{--include} @var{PATH}
+Add @var{PATH} to @code{$LOAD_PATH}
+
+@item --keep-frame-binding
+@cindex @option{--keep-frame-binding}
+Bindings are used to set the proper environment in evaluating
+expression inside the debugger. Under normal circumstances, I don't
+believe most people will ever need this option.
+
+By default, the debugger doesn't create binding object for each frame
+when the frame is created, i.e. when a call is performed. Creating a
+binding is an expensive operation and has been a major source of
+performance problems.
+
+Instead, the debugger creates a binding when there is a need to
+evaluate expressions. The artificial binding that is created might be
+different from the real one.  In particular, in performing constant
+and module name resolution.
+
+However it's still possible to restore the old, slower behavior by
+using this option or by setting @code{Debugger.keep_frame_binding =
+true}. There are two possibilities for which you might want to use
+this option. 
+
+First, if you think there's a bug in the evaluation of variables, you
+might want to set this to see if this corrects things.
+
+Second, since the internal structures that are used here @code{FRAME}
+and @code{SCOPE} are not part of the Ruby specification, it is
+possible they can change with newer releases; so here this option this
+may offer a remedy. (But you'll probably also have to hack the C code
+since it's likely under this scenario that ruby-debug will no longer
+compile.) In fact, in Ruby 1.9 these structures have changed and that
+is partly why this debugger doesn't work on Ruby 1.9.
+
+@item -m | --post-mortem
+@cindex @option{-m}
+@cindex @option{--post-mortem}
+If your program raises an exception that isn't caught you can enter
+the debugger for inspection of what went wrong. You may also want to
+use this option in conjunction with @option{--no-stop}. See also 
+@ref{Post-Mortem Debugging}. 
+
+@item --no-control
+@cindex @option{--no-control}
+Do not automatically start control thread.
+
+@item --no-quit
+@cindex @option{--no-quit}
+Restart the debugger when your program terminates normally.
+
+@item --no-rewrite-program
+@cindex @option{--no-rewrite-program}
+Normally @code{rdebug} will reset the program name @code{$0} from its
+name to the debugged program, and set the its name in variable
+@code{$RDEBUG_0}. In the unlikely even you don't want this use this option.
+
+@item --no-stop
+@cindex @option{--no-stop}
+Normally the @code{rdebug} stops before executing the first
+statement. If instead you want it to start running initially and will
+perhaps break it later in the running, use this options.
+
+@item -p | --port @var{port}
+@cindex @option{-p} @var{port}
+@cindex @option{--port} @var{port}
+Port used for remote debugging.
+
+@item -r | --require @var{library}
+@cindex @option{-r}
+@cindex @option{--require}
+Require the library, before executing your script. However if the
+library happened to be @code{debug}, we'll just ignore the require
+(since we're already a debugger). This option is compatible with Ruby's.
+
+@item --script @var{file}
+@cindex @option{--script}
+Require the library, before executing your script. However if the
+library hap-pend to be @code{debug}, we'll just ignore the require
+(since we're already a debugger). This option is compatible with Ruby's.
+
+@item -s | --server
+@cindex @option{-s}
+@cindex @option{--server}
+Debug the program but listen for remote connections on the default
+port or port set up via the @option{--port} option. See also @option{--wait}.
+
+@item -w | --wait
+@cindex @option{-w}
+@cindex @option{--wait}
+Debug the program but stop waiting for a client connection first. This
+option automatically sets @option{--server} option.
+
+@item -x | --trace
+@cindex @option{-x}
+@cindex @option{--trace}
+Turn on line tracing. Running @command{rdebug --trace @emph{rubyscript.rb}}
+is much like running: @command{ruby -rtracer @emph{rubyscript.rb}}
+
+If all you want to do however is get a linetrace, @code{tracer}, not
+@code{rdebug}, may be faster:
+@smallexample
+$ @b{time ruby -rtracer gcd.rb 34 21 > /dev/null}
+
+real	0m0.266s
+user	0m0.008s
+sys	0m0.000s
+$ @b{time rdebug --trace gcd.rb 34 21 > /dev/null}
+
+real	0m0.875s
+user	0m0.448s
+sys	0m0.056s
+$
+@end smallexample
+
+@end table
+
+@node rdebug default options
+@subsection How to Set Default Command-Line Options
+
+@DBG{} has many command-line options; it seems that some people want
+to set them differently from the our defaults. For example, some
+people may want @option{--no-quit --no-control} to be the default
+behavior. One could write a wrapper script or set a shell alias to
+handle this. @DBG{} has another way to do this as well. Before
+processing command options if the file @code{$HOME/.rdboptrc} is found
+(or, on Windows, @code{$HOME/rdbopt.ini}, it is loaded. 
+If you want to set the defaults in some other way, you
+can put Ruby code here and set variable @code{options} which is an
+OpenStruct. For example here's how you'd set @option{-no-quit} and
+change the default control port to 5000.
+
+@smallexample
+# This file contains how you want the default options to ruby-debug
+# to be set. Any Ruby code can be put here.
+#
+# debugger # Uncomment if you want to debug rdebug!
+options.control = false
+options.port = 5000
+puts "rocky's rdboptrc run"
+@end smallexample
+
+Here are the default values in @code{options}
+@smallexample
+#<OpenStruct server=false, client=false, frame_bind=false, cport=8990, tracing=false, nx=false, post_mortem=false, port=8989, verbose_long=false, annotate=nil, control=true, restart_script=nil, quit=true, no_rewrite_program=false, stop=true, script=nil, host=nil, wait=false>
+@end smallexample
+
+
+@node Command Files
+@section Command files
+
+@cindex command files
+A command file for @DBG{} is a file of lines that are @DBG{}
+commands.  Comments (lines starting with @kbd{#}) may also be included.
+An empty line in a command file does nothing; it does not mean to repeat
+the last command, as it would from the terminal.
+
+@cindex init file
+@cindex @file{.rdebugrc}
+When you start @value{DBG}, it automatically executes commands from its
+@dfn{init files}, normally called @file{.rdebugrc}.
+
+On some configurations of @value{DBG}, the init file may be known by a
+different name. In particular on MS-Windows (but not cygwin)
+@file{rdebug.ini} is used.
+
+During startup, @DBG{} does the following:
+
+@enumerate
+@item
+Processes command line options and operands.
+
+@item
+Reads the init file in your current directory, if any, and failing
+that the home directory. The home directory is the directory named in
+the @code{HOME} or @code{HOMEPATH} environment variable. 
+
+Thus, you can have more than one init file, one generic in your home
+directory, and another, specific to the program you are debugging, in
+the directory where you invoke @DBG{}.
+
+@item
+Reads command files specified by the @samp{--script} option.
+@end enumerate
+
+You can also request the execution of a command file with the
+@code{source} command, @pxref{Source}.
+
+@node Quitting the debugger
+@section Quitting the debugger
+
+@cindex interrupt
+An interrupt (often @kbd{C-c}) does not exit from @value{DBG}, but
+rather terminates the action of any @DBG command that is in
+progress and returns to @value{DBG} command level.  Inside a debugger
+command interpreter, use @code{quit} command (@pxref{Control, ,Quitting
+the debugger}).
+
+There way to terminate the debugger is to use the @code{kill}
+command. This does more forceful @code{kill -9}. It can be used in
+cases where @code{quit} doesn't work.
+
+@node Calling from Program
+@section Calling the debugger from inside your Ruby program
+
+Running a program from the debugger adds a bit of overhead and slows
+down your program a little.
+
+Furthermore, by necessity, debuggers change the operation of the
+program they are debugging. And this can lead to unexpected and
+unwanted differences. It has happened so often that the term
+``Heisenbugs'' (see @url{http://en.wikipedia.org/wiki/Heisenbug}) was
+coined to describe the situation where the addition of the use of a
+debugger (among other possibilities) changes behavior of the program
+so that the bug doesn't manifest itself anymore.
+
+There is another way to get into the debugger which adds no overhead
+or slowdown until you reach the point at which you want to start
+debugging. However here you must change the script and make an
+explicit call to the debugger. Because the debugger isn't involved
+before the first call, there is no overhead and the script will run
+at the same speed as if there were no debugger.
+
+There are three parts to calling the debugger from inside the script,
+``requiring'' the debugger code, telling the debugger to start
+tracking things and then making the call calling the debugger to
+stop. 
+
+To get the debugger class accessible from your Ruby program:
+
+@smallexample
+require 'ruby-debug'
+@end smallexample 
+After @code{require 'ruby-debug'}, it's possible to set some of the
+debugger variables influence preferences. For example if you want to
+have @ttDBG run a @code{list} command every time it stops you set the
+variable @code{Debugger.settings[:autolist]}. @pxref{Debugger.settings} has a
+list of variable settings and the default values. Debugger settings
+can also be set in @code{.rdebugrc} as debugger
+commands. @pxref{Command Files}
+
+To tell the debugger to start tracking things:
+
+@smallexample
+Debugger.start
+@end smallexample 
+
+There is also a @code{Debugger.stop} to turn off debugger tracking. If
+speed is crucial, you may want to start and stop this around certain
+sections of code. Alternatively, instead of issuing an explicit
+@code{Debugger.stop} you can add a block to the @code{Debugger.start}
+and debugging is turned on for that block. If the block of code raises
+an uncaught exception that would cause the block to terminate, the
+@code{stop} will occur.  See @ref{Debugger.start with a block}.
+
+And finally to enter the debugger:
+
+@smallexample
+debugger
+@end smallexample 
+
+As indicated above, when @code{debugger} is run a @code{.rdebugrc}
+profile is read if that file exists.
+
+You may want to do enter the debugger at several points in the program
+where there is a problem you want to investigate. And since
+@code{debugger} is just a method call it's possible enclose it in a
+conditional expression, for example:
+@smallexample
+debugger if 'bar' == foo and 20 == iter_count
+@end smallexample 
+
+Although each step does a very specific thing which offers great
+flexibility, in order to make getting into the debugger easier the
+three steps have been rolled into one command:
+@smallexample
+require "ruby-debug/debugger"
+@end smallexample 
+
+@node Debugger Command Reference
+@chapter @code{ruby-debug} Command Reference
+
+@menu
+* Command Interfaces::       The kinds of interface used to interact with ruby-debug
+* Command Syntax::           How to give commands to the ruby-debug
+* Command Output::           How rdebug presents its output
+* Help::                     How to ask for help (help)
+* Control::                  Controlling the debugger (quit, restart, interrupt)
+* DisplayCommands::          Executing expressions on stop (display, undisplay)
+* PrintCommands::            Evaluating and Printing Expressions (p, pp, ps, pp, irb)
+* PrintVars::                Printing Variables (var)
+* List::                     Examining Program Source Files (list)
+* Edit::                     Editing source files (edit)
+* FrameCommands::            Examining the stack frame (where, up, down, frame)
+* Stopping::                 Stopping and continuing (break, watch, step, cont...)
+* ruby-debug settings::      rdebug-settings (set args, set autoeval, ...)
+* Program Information::      Program Status  (info)
+@end menu
+
+@node Command Interfaces
+@section Command Interfaces
+There are several ways one can talk to @code{ruby-debug} and get
+results. The simplest way is via a command-line interface directly
+talking to the debugger. This is referred to below as a ``Local
+Interface''. It's also possible to run the debugger and set up a port
+by which some other process can connect and control the debug
+session. This is called a ``Remote Interface''. When you want to gain
+access to a remote interface you need to run @code{ruby-debug} using a
+``Control Interface''. This interface might not be the same process as
+the process running the debugged program and might not even be
+running on the same computer.
+
+Other front-ends may use one of these and build on top and provide
+other (richer) interfaces. Although many of the commands are available
+on all interfaces some are not. Most of the time in this manual when
+we talk about issuing commands describing the responses elicited,
+we'll assume we are working with the local interface.
+
+@node Command Syntax
+@section Command Syntax
+Usually a command is put on a single line. There is no limit on how long
+it can be.  It starts with a command name, which is followed by
+arguments whose meaning depends on the command name.  For example, the
+command @code{step} accepts an argument which is the number of times to
+step, as in @code{step 5}.  You can also use the @code{step} command with no
+arguments.  Some commands do not allow any arguments.
+
+Multiple commands can be put on a line by separating each with a
+semicolon (@code{;}). You can disable the meaning of a semicolon to
+separate commands by escaping it with a backslash. 
+
+For example, if you have @code{autoeval} (@ref{Autoeval}) set, you
+might want to enter the following code to compute the 5th Fibonacci
+number:
+@smallexample
+# Compute the 5 Fibonaci number
+(rdb:1) set autoeval on
+(rdb:1) fib1=0; fib2=1; 5.times @{|temp| temp=fib1; fib1=fib2; fib2 += temp @}
+SyntaxError Exception: compile error
+/usr/bin/irb:10: syntax error, unexpected $end, expecting '@}'
+ 5.times @{|temp| temp=fib1
+                          ^
+(rdb:1) fib1=0\; fib2=1\; 5.times @{|temp| temp=fib1\; fib1=fib2\; fib2 += temp @}
+5
+(rdb:1) fib2
+fib2
+8
+@end smallexample
+You might also consider using the @code{irb} command, @ref{irb}, and
+then you won't have to escape semicolons.
+
+A blank line as input (typing just @key{<RET>}) means to repeat the
+previous command.  
+
+In the ``local'' interface, the Ruby Readline module is used. It
+handles line editing and retrieval of previous commands. Up arrow, for
+example moves to the previous debugger command; down arrow moves to
+the next more recent command (provided you are not already at the last
+command). Command history is saved in file @code{.rdebug_hist}. A
+limit is put on the history size. You can see this with the @code{show
+history size} command. See @ref{History} for history parameters.
+
+@node Command Output
+@section Command Output
+
+In the command-line interface, when @code{ruby-debug} is waiting for
+input it presents a prompt of the form
+@code{(rdb:}@emph{x}@code{)}. If debugging locally, @emph{x} will be
+the thread number. Usual the main thread is 1, so often you'll see
+@code{(rdb:1)}. In the control interface though @emph{x} will be
+@code{ctrl} and in post-mortem debugging @code{post-mortem}.
+
+In the local interface, whenever @code{ruby-debug} gives an error
+message such as for an invalid command, or an invalid location
+position, it will generally preface the message with
+@code{***}. However if annotation mode is on that the message is put
+in a @code{begin-error} annotation and no @code{***} appears.
+
+@node Help
+@section Getting help (@samp{help})
+@cindex on-line documentation
+@menu
+* Help for Subcommands::
+@end menu
+
+Once inside @code{ruby-debug} you can always ask it for information on
+its commands, using the command @code{help}.
+
+@table @code
+@kindex h @r{(@code{help})}
+@kindex help @ovar{command-name}
+@item help
+@itemx h
+You can use @code{help} (abbreviated @code{h}) with no arguments to
+display a short list of named classes of commands:
+
+@flushleft
+@smallexample
+(rdb:1) @b{help}
+ruby-debug help v@value{RDEBUG_VERSION}
+Type 'help <command-name>' for help on a specific command
+
+Available commands:
+backtrace  delete   enable  help  list    ps       save    thread     where
+break      disable  eval    info  method  putl     set     trace
+catch      display  exit    irb   next    quit     show    undisplay
+condition  down     finish  jump  p       reload   source  up
+continue   edit     frame   kill  pp      restart  step    var
+@end smallexample
+@end flushleft
+@c the above line break eliminates huge line overfull...
+
+@end table 
+
+@table @code
+@item help @var{command}
+With a command name as @code{help} argument, @DBG displays short
+information on how to use that command.
+
+@smallexample
+(rdb:1) @b{help list}
+ruby-debug help v@value{RDEBUG_VERSION}
+l[ist]		list forward
+l[ist] -	list backward
+l[ist] =	list current line
+l[ist] nn-mm	list given lines
+* NOTE - to turn on autolist, use 'set autolist'
+(rdb:1)
+@end smallexample
+@end table
+
+@node Help for Subcommands
+@subsection Help on Subcommands
+A number of commands have many sub-parameters or
+@emph{subcommands}. These include @code{info}, @code{set},
+@code{show}, @code{enable} and @code{disable}.
+
+When you ask for help for one of these commands, you will get help for
+all of the subcommands that that command offers. Sometimes you may
+want help that subcommand and to do this just follow the command with
+its subcommand name. For example @code{help set annotate} will just
+give help about the annotate command. Furthermore it will give longer
+help than the summary information that appears when you ask for
+help. You don't need to list the full subcommand name, but just enough
+of the letters to make that subcommand distinct from others will
+do. For example, @code{help set an} is the same as @code{help set annotate}.
+
+Some examples follow.
+@example
+(rdb:1) @b{help info}
+Generic command for showing things about the program being debugged.
+-- 
+List of info subcommands:
+--  
+info args -- Argument variables of current stack frame
+info breakpoints -- Status of user-settable breakpoints
+info catch -- Exceptions that can be caught in the current stack frame
+info display -- Expressions to display when program stops
+info file -- Info about a particular file read in
+info files -- File names and timestamps of files read in
+info global_variables -- Global variables
+info instance_variables -- Instance variables of the current stack frame
+info line -- Line number and file name of current position in source file
+info locals -- Local variables of the current stack frame
+info program -- Execution status of the program
+info stack -- Backtrace of the stack
+info thread -- List info about thread NUM
+info threads -- information of currently-known threads
+info variables -- Local and instance variables of the current stack frame
+@end example
+
+@example
+(rdb:1) @b{help info breakpoints}
+Status of user-settable breakpoints.
+Without argument, list info about all breakpoints.  With an
+integer argument, list info on that breakpoint.
+@end example
+
+@example
+(rdb:1) @b{help info br}
+Status of user-settable breakpoints.
+Without argument, list info about all breakpoints.  With an
+integer argument, list info on that breakpoint.
+@end example
+
+@node Control
+@section Controlling the debugger (@samp{quit}, @samp{restart}, @samp{interrupt}, @samp{source})
+
+@menu
+* Quit::      Quitting the debugger (quit)
+* Restart::   Restarting Script execution (restart)
+* Interrupt:: Interrupting the debugger (interrupt)
+* Source::    Running Debugger commands (source)
+@end menu
+
+@node Quit
+@subsection Quit (@samp{quit})
+@table @code
+@kindex quit @r{[}unconditionally@r{]}
+@kindex q @r{(@code{quit})}
+@item quit @r{[}unconditionally@r{]}
+@item exit
+@itemx q
+
+To exit @value{DBG}, use the @code{quit} command (abbreviated
+@code{q}), or alias @code{exit}.
+
+A simple @code{quit} tries to terminate all threads in effect.
+
+Normally if you are in an interactive session, this command will
+prompt to ask if you really want to quit. If you don't want any
+questions asked, enter the ``unconditionally''.
+
+@end table
+
+@node Restart
+@subsection Restart (@samp{restart})
+@table @code
+@kindex restart @r{[}@var{program args}@r{]}
+@kindex R @r{(@code{restart})}
+@item restart
+@itemx R 
+
+Restart the program. This is a re-exec - all debugger state is
+lost. If command arguments are passed those are used. Otherwise the
+last program arguments used in the last invocation are used.
+
+In not all cases will you be able to restart the program. First, the
+program should have been invoked at the outset rather than having been
+called from inside your program or invoked as a result of post-mortem
+handling. 
+
+Also, since this relies on the the OS @code{exec} call, this command
+is available only if your OS supports that @code{exec}; OSX for
+example does not (yet).
+@end table
+
+@node Interrupt
+@subsection Interrupt (@samp{interrupt})
+@table @code
+@kindex interrupt
+@kindex i
+@item interrupt
+@itemx i
+Interrupt the program. Useful if there are multiple threads running.
+@end table
+
+@node Source
+@subsection Running Debugger Commands (@samp{source})
+@table @code
+@kindex source @var{filename}
+@item source @var{filename}
+Execute the command file @var{filename}.
+
+The lines in a command file are executed sequentially.  They are not
+printed as they are executed.  If there is an error, execution
+proceeds to the next command in the file. For information about
+command files that get run automatically on startup, @pxref{Command Files}.
+@end table
+
+@node DisplayCommands
+@section Executing expressions on stop (@samp{display}, @samp{undisplay})
+@cindex automatic display
+@cindex display of expressions
+
+If you find that you want to print the value of an expression
+frequently (to see how it changes), you might want to add it to the
+@dfn{automatic display list} so that @value{DBG} evaluates a statement
+each time your program stops or the statement is shown in line tracing.
+Each expression added to the list is given a number to identify it; to
+remove an expression from the list, you specify that number.  The
+automatic display looks like this:
+
+@smallexample
+(rdb:1) display n
+1: n = 3
+@end smallexample
+
+@noindent
+This display shows item numbers, expressions and their current values.  
+If the expression is undefined or illegal the expression will be
+printed but no value will appear.
+
+@smallexample
+(rdb:1) display undefined_variable
+2: undefined_variable =
+(rdb:1) display 1/0
+3: 1/0 = 
+@end smallexample
+
+Note: this command uses @code{to_s} to in expressions; for example an
+array @code{[1, 2]} will appear as @code{12}. For some datatypes like
+an Array, you may want to call the @code{inspect} method, for example
+@code{display ARGV.inspect} rather than @code{display ARGV}.
+
+@table @code
+@kindex display @ovar{expr}
+@item display @var{expr}
+Add the expression @var{expr} to the list of expressions to display
+each time your program stops or a line is printed when linetracing is
+on (@pxref{DisplayCommands}).
+
+@item display
+Display the current values of the expressions on the list, just as is
+done when your program stops. 
+
+@kindex undisplay @ovar{num}
+@item undisplay @ovar{num}
+@itemx delete display @var{num}
+Remove item number @var{num} from the list of expressions to display.
+
+@kindex info display
+@item info display
+Show all display expressions
+
+@ifset GDB_COMPLETED
+@code{undisplay} does not repeat if you press @key{RET} after using it.
+(Otherwise you would just get the error @samp{No display number @dots{}}.)
+@end ifset
+
+@kindex disable display
+@item disable display @var{dnums}@dots{}
+Disable the display of item numbers @var{dnums}.  A disabled display
+item is not printed automatically, but is not forgotten.  It may be
+enabled again later.
+
+@kindex enable display
+@item enable display @var{dnums}@dots{}
+Enable display of item numbers @var{dnums}.  It becomes effective once
+again in auto display of its expression, until you specify otherwise.
+
+@end table
+
+@node PrintCommands
+@section Evaluating and Printing Expressions (@samp{p}, @samp{pp}, @samp{putl}, @samp{ps}, @samp{irb})
+
+One way to examine and change data in your script is with the
+@code{eval} command (abbreviated @code{p}). A similar command is
+@code{pp} which tries to pretty print the result. Finally @code{irb} is
+useful when you anticipate examining or changing a number of things,
+and prefer not to have to preface each command, but rather work as one
+does in @code{irb}.
+
+@menu
+* eval::          eval or print an expression (eval, p)
+* pp::            pretty print an expression (pp, ps, putl)
+* irb::           running irb using the current context
+@end menu
+
+@node eval
+@subsection Printing an expression (@samp{eval}, @samp{p})
+@table @code
+@kindex eval @var{expr} 
+@kindex p @r{(@code{eval})}
+@item eval @var{expr}
+@itemx p @var{expr}
+
+Use @code{eval} or @code{p} to evaluate a Ruby expression, @var{expr},
+same as you would if you were in @code{irb}. If there are many expressions
+you want to look at, you may want to go into irb from the debugger.
+@smallexample
+@group
+(rdb:p) p n
+3
+(rdb:1) p "the value of n is #@{n@}"
+"the value of n is 3"
+(rdb:1)
+@end group
+@end smallexample
+@end table
+
+@node pp
+@subsection Pretty-Printing an expression (@samp{pp}, @samp{putl}, @samp{ps}))
+@table @code
+@item pp
+@kindex pp @var{expr}
+Evaluates and pretty-prints @var{expr}
+@smallexample
+@group
+(rdb:1) @b{p $LOAD_PATH}
+["/home/rocky/lib/ruby", "/usr/lib/ruby/site_ruby/1.8", "/usr/lib/ruby/site_ruby/1.8/i586-linux", "/usr/lib/ruby/1.8"]
+(rdb:1) @b{pp $LOAD_PATH}
+["/home/rocky/lib/ruby",
+ "/usr/lib/ruby/site_ruby/1.8",
+ "/usr/lib/ruby/site_ruby/1.8/i586-linux",
+ "/usr/lib/ruby/1.8"]
+@end group
+@end smallexample
+@kindex putl
+@item putl
+If the value you want to print is an array, sometimes a columnized
+list looks nicer:
+@smallexample
+@group
+(rdb:1) @b{putl $LOAD_PATH}
+/home/rocky/lib/ruby                    /usr/lib/ruby/site_ruby/1.8
+/usr/lib/ruby/site_ruby/1.8/i586-linux  /usr/lib/ruby/1.8
+@end group
+@end smallexample
+
+Note however that entries are sorted to run down first rather than
+across. So in the example above the second entry in the list is 
+@code{/usr/lib/ruby/site_ruby/1.8/i586-linux} and the @emph{third} entry is 
+@code{/usr/lib/ruby/site_ruby/1.8}.
+
+If the value is not an array @code{putl} will just call pretty-print.
+@kindex ps
+@item ps
+Sometimes you may want to print the array not only columnized, but
+sorted as well. The list of debugger help commands appears this way,
+and so does the output of the @code{method} commands.
+
+@smallexample
+@group
+(rdb:1) ps Kernel.private_methods
+Digest                   initialize                  y
+Pathname                 initialize_copy           
+Rational                 location_of_caller        
+active_gem_with_options  method_added              
+alias_method             method_removed            
+append_features          method_undefined          
+attr                     module_function           
+attr_accessor            private                   
+attr_reader              protected                 
+attr_writer              public                    
+class_variable_get       remove_class_variable     
+class_variable_set       remove_const              
+define_method            remove_instance_variable  
+extend_object            remove_method             
+extended                 singleton_method_added    
+gcd                      singleton_method_removed  
+gem_original_require     singleton_method_undefined
+include                  timeout                   
+included                 undef_method              
+@end group
+@end smallexample
+
+If the value is not an array, @code{ps} will just call pretty-print.
+See also the @code{methods}.
+@end table
+
+@node irb
+@subsection Run irb (@samp{irb})
+@table @code
+@kindex irb 
+@item irb
+Run an interactive ruby session (@code{irb}) with the bindings
+environment set to the state you are in the program.
+
+When you leave irb and go back to the debugger command prompt we show
+again the file, line and text position of the program in the same way
+as when entered the debugger. If you issue a @command{list} without
+location information, the default location used is the current line
+rather than the position may have gotten updated via a prior
+@command{list} command.
+@smallexample
+triangle.rb:4
+def triangle(n)
+(rdb:1) @b{list}
+[-1, 8] in /home/rocky/ruby/triangle.rb
+   1  #!/usr/bin/env ruby
+   2  # Compute the n'th triangle number - the hard way
+   3  # triangle(n) == (n * (n+1)) / 2
+=> 4  def triangle(n)
+   5    tri = 0
+   6    0.upto(n) do |i|
+   7      tri += i
+   8    end
+@b{irb}
+>> @b{(0..6).inject@{|sum, i| sum +=i@}}
+=> 21
+>> @b{exit}
+triangle.rb:4
+def triangle(n)
+(rdb:1) @b{list # Note we get the same line range as before going into irb}
+[-1, 8] in /home/rocky/ruby/triangle.rb
+   1  #!/usr/bin/env ruby
+   2  # Compute the n'th triangle number - the hard way
+   3  # triangle(n) == (n * (n+1)) / 2
+=> 4  def triangle(n)
+   5    tri = 0
+   6    0.upto(n) do |i|
+   7      tri += i
+   8    end
+@end smallexample
+
+@end table
+
+@node PrintVars
+@section Printing Variables (@samp{var}, @samp{method})
+
+@table @code
+@item var const @var{object}
+@kindex var const @var{expr}
+Show the constants of @var{object}. This is basically listing
+variables and their values in @var{object}@code{.constant}.
+@item var instance @var{object}
+@kindex var instance @var{expr}
+Show the instance variables of @var{object}. This is basically listing
+@var{object}@code{.instance_variables}.
+@item info instance_variables
+@kindex info instance_variables
+Show instance_variables of @code{@@self}
+@item info locals
+@kindex info locals
+Show local variables
+@item info globals
+@kindex info globals
+Show global variables
+@item info variables
+@kindex info variables
+Show local and instance variables of @code{@@self}
+@item method instance @var{object}
+@kindex method instance @var{object}
+Show methods of @var{object}. Basically this is the same as running
+@code{ps object.instance_methods(false)} on @var{object}.
+@item method iv @var{object}
+@kindex method iv @var{object}
+Show method instance variables of @var{object}. Basically this is the same as running
+@smallexample
+  obj.instance_variables.each do |v| 
+     puts "%s = %s\n" % [v, obj.instance_variable_get(v)]
+  end  
+@end smallexample
+on @var{object}.
+@item signature @var{object}
+@kindex method signature @var{object}
+Show procedure signature of method @var{object}. 
+@emph{This command is available only if the nodewrap is installed.}
+@smallexample
+  def mymethod(a, b=5, &bock) 
+  end
+  (rdb:1) @b{method sig mymethod}
+  Mine#mymethod(a, b=5, &bock)
+@end smallexample
+on @var{object}.
+@item method @var{class-or-module}
+@kindex method @var{class-or-module}
+Show methods of the class or module, @var{class-or-module}. Basically
+this is the same as running @code{ps object.methods} on @var{class-or-module}.
+on @var{class-or-module}.
+@end table
+
+@node List
+@section Examining Program Source Files (@samp{list})
+
+@cindex current line
+@value{DBG} can print parts of your script's source.  When your script
+stops, @value{DBG} spontaneously prints the line where it stopped and
+the text of that line. Likewise, when you select a stack frame
+(@pxref{Selection}) @value{DBG} prints the line where execution in
+that frame has stopped.  Implicitly there is a default line
+location. Each time a list command is run that implicit location is
+updated, so that running several list commands in succession shows a
+contiguous block of program text.
+
+You can print other portions of source files by giving an explicit
+position as a parameter to the list command.
+
+If you use @value{DBG} through its Emacs interface, you may prefer to
+use Emacs facilities to view source. 
+@c @pxref{GNU Emacs}.
+
+@kindex list @ovar{line-number}
+@kindex l @r{(@code{list})}
+To print lines from a source file, use the @code{list} command
+(abbreviated @code{l}).  By default, ten lines are printed. Fewer may
+appear if there fewer lines before or after the current line to center
+the listing around.
+
+There are several ways to specify what part of the file you want to print.
+Here are the forms of the @code{list} command.
+
+@table @code
+@item list @var{line-number}
+@itemx l @var{line-number}
+Print lines centered around line number @var{line-number} in the
+current source file.
+
+@item list
+@itemx l
+Print more lines.  If the last lines printed were printed with a
+@code{list} command, this prints lines following the last lines
+printed; however, if the last line printed was a solitary line printed
+as part of displaying a stack frame (@pxref{Frames}), this prints lines
+centered around that line.
+
+@item list -
+@itemx l -
+Print lines just before the lines last printed.
+@item list @var{first}-@var{last}
+Print lines between @var{first} and @var{last} inclusive.
+
+@item list =
+Print lines centered around where the script is stopped.
+@end table
+
+Repeating a @code{list} command with @key{RET} discards the argument,
+so it is equivalent to typing just @code{list}.  This is more useful
+than listing the same lines again.  An exception is made for an
+argument of @samp{-}; that argument is preserved in repetition so that
+each repetition moves up in the source file.
+
+@node Edit
+@section Editing Source files (@samp{edit})
+
+To edit the lines in a source file, use the @code{edit} command.  The
+editing program of your choice is invoked with the current line set to
+the active line in the program.  Alternatively, you can give a line
+specification to specify what part of the file you want to print if
+you want to see other parts of the program.
+
+You can customize to use any editor you want by using the
+@code{EDITOR} environment variable. The only restriction is that your
+editor (say @code{ex}), recognizes the following command-line syntax:
+@smallexample
+ex +@var{number} file
+@end smallexample
+The optional numeric value +@var{number} specifies the number of the
+line in the file where to start editing.  For example, to configure
+@value{DBG} to use the @code{vi} editor, you could use these commands
+with the @code{sh} shell:
+@smallexample
+EDITOR=/usr/bin/vi
+export EDITOR
+gdb @dots{}
+@end smallexample
+or in the @code{csh} shell,
+@smallexample
+setenv EDITOR /usr/bin/vi
+gdb @dots{}
+@end smallexample
+
+@table @code
+@kindex edit @ovar{line-specification}
+@item edit @ovar{line specification}
+Edit line specification using the editor specified by the
+@code{EDITOR} environment variable.
+@end table
+
+@node FrameCommands
+@section Examining the Stack Frame (@samp{where}, @samp{up}, @samp{down}, @samp{frame})
+
+When your script has stopped, one thing you'll probably want to know
+is where it stopped and some idea of how it got there.
+
+@cindex call stack
+Each time your script performs a function or sends a message to a
+method, or enters a block, information about this action is saved.
+The frame stack then is this a history of the blocks that got you to
+the point that you are currently stopped at.@footnote{More accurately
+we should call this a ``block stack''; but we'll use the name that is
+more commonly used. And internally in Ruby, there is ``FRAME''
+structure which is yet slightly different.}
+
+@cindex selected block
+One entry in call stack is @dfn{selected} by @DBG{} and many
+@DBG commands refer implicitly to the selected block.  In
+particular, whenever you ask @DBG to list lines without giving
+a line number or location the value is found in the selected frame.
+There are special @DBG commands to select whichever frame you
+are interested in. @xref{Selection, ,Selecting a frame}.
+
+When your program stops, @DBG{} automatically selects the
+currently executing frame and describes it briefly, similar to the
+@code{frame} command.
+
+After switching frames, when you issue a @code{list} command without
+any position information, the position used is location in the frame
+that you just switched between, rather than a location that got
+updated via a prior @code{list} command.
+
+@menu
+* Frames::                      Stack frames
+* Backtrace::                   Backtraces (where)
+* Selection::                   Selecting a frame (up, down, frame)
+
+@end menu
+
+@node Frames
+@subsection Stack frames
+
+@cindex frame, definition
+@cindex stack frame
+The block stack is divided up into contiguous pieces called @dfn{stack
+frames}, @dfn{frames}, or @dfn{blocks} for short; each frame/block has
+a scope associated with it; It contains a line number and the
+source-file name that the line refers. If the frame/block is the beginning
+of a method or function it also contains the function name.
+
+@cindex initial frame
+@cindex outermost frame
+@cindex innermost frame
+When your script is started, the stack has only one frame, that of the
+function @code{main}.  This is called the @dfn{initial} frame or the
+@dfn{outermost} frame.  Each time a function is called, a new frame is
+made.  Each time a function returns, the frame for that function invocation
+is eliminated.  If a function is recursive, there can be many frames for
+the same function.  The frame for the function in which execution is
+actually occurring is called the @dfn{innermost} frame.  This is the most
+recently created of all the stack frames that still exist.
+
+@cindex frame number
+@value{DBG} assigns numbers to all existing stack frames, starting with
+zero for the innermost frame, one for the frame that called it,
+and so on upward.  These numbers do not really exist in your script;
+they are assigned by @value{DBG} to give you a way of designating stack
+frames in @value{DBG} commands.
+
+@node Backtrace
+@subsection Backtraces (@samp{where})
+
+@cindex backtraces
+@cindex tracebacks
+@cindex stack traces
+A backtrace is essentially the same as the call stack: a summary of
+how your script got where it is.  It shows one line per frame, for
+many frames, starting with the place that you are stopped at (frame
+zero), followed by its caller (frame one), and on up the stack.
+
+@table @code
+@kindex where
+@kindex w @r{(@code{where})}
+@itemx where
+Print the entire stack frame; @code{info stack} is an alias for this command.
+Each frame is numbered and can be referred to in the @code{frame}
+command; @code{up} and @code{down} add or subtract respectively to
+frame numbers shown.  The position of the current frame is marked with
+@code{-->}.
+
+@smallexample
+(rdb:1) where
+--> #0 Object.gcd(a#Fixnum, b#Fixnum) at line /tmp/gcd.rb:6
+    #1 at line /tmp/gcd.rb:19
+@end smallexample
+
+@ifset FINISHED
+@item backtrace @var{n}
+@itemx bt @var{n}
+@itemx where @var{n}
+@itemx T @var{n}
+Similar, but print only the innermost @var{n} frames.
+
+@item backtrace -@var{n}
+@itemx bt -@var{n}
+@itemx where -@var{n}
+@itemx T -@var{n}
+Similar, but print only the outermost @var{n} frames.
+@end ifset
+@end table
+
+@node Selection
+@subsection Selecting a frame (@samp{up}, @samp{down}, @samp{frame})
+
+Commands for listing source code in your script work on whichever
+stack frame is selected at the moment.  Here are the commands for
+selecting a stack frame; all of them finish by printing a brief
+description of the stack frame just selected.
+
+@table @code
+@kindex up @ovar{n}
+@item up @ovar{n}
+Move @var{n} frames up the stack.  For positive numbers @var{n}, this
+advances toward the outermost frame, to higher frame numbers, to
+frames that have existed longer.  Using a negative @var{n} is the same thing
+as issuing a @code{down} command of the absolute value of the @var{n}.
+Using zero for @var{n} does no frame adjustment, but since the current
+position is redisplayed, it may trigger a resynchronization if there is
+a front end also watching over things. 
+
+@var{n} defaults to one. You may abbreviate @code{up} as @code{u}.
+
+@kindex down @ovar{n}
+@item down @ovar{n}
+Move @var{n} frames down the stack.  For positive numbers @var{n}, this
+advances toward the innermost frame, to lower frame numbers, to frames
+that were created more recently.  Using a negative @var{n} is the same
+as issuing a @code{up} command of the absolute value of the @var{n}.
+Using zero for @var{n} does no frame adjustment, but since the current
+position is redisplayed, it may trigger a resynchronization if there is
+a front end also watching over things. 
+
+@var{n} defaults to one.
+@end table
+
+@table @code
+@kindex frame @r{[}@ovar{n} @r{[}thread @var{thread-num}@r{]}@r{]}
+@cindex current stack frame
+@item frame @ovar{n} @r{[}thread @var{thread-num}@r{]}
+The @code{frame} command allows you to move from one stack frame to
+another, and to print the stack frame you select.  @var{n} is the the
+stack frame number or 0 if no frame number is given; @code{frame 0}
+then will always show the current and most recent stack frame.
+
+If a negative number is given, counting is from the other end of the
+stack frame, so @code{frame -1} shows the least-recent, outermost or
+most ``main'' stack frame.
+
+Without an argument, @code{frame} prints the current stack
+frame. Since the current position is redisplayed, it may trigger a
+resynchronization if there is a front end also watching over
+things. 
+
+If a thread number is given then we set the context for evaluating
+expressions to that frame of that thread. 
+@end table
+
+@node Stopping
+@section Stopping and Resuming Execution
+
+One important use of a debugger is to stop your program @emph{before}
+it terminates, so that if your script runs into trouble you can
+investigate and find out why. However should your script accidentally
+continue to termination, it can be arranged for @DBG to not to leave
+the debugger without your explicit instruction. That way, you can
+restart the program using the same command arguments.
+
+Inside @value{DBG}, your script may stop for any of several reasons,
+such as a signal, a breakpoint, or reaching a new line after a
+debugger command such as @code{step}.  You may then examine and
+change variables, set new breakpoints or remove old ones, and then
+continue execution.  
+
+@menu
+* Breakpoints::          Breakpoints (break, catch, delete)
+* Disabling::            Disabling breakpoints (disable, enable)
+* Conditions::                      Break conditions (condition)
+* Resuming Execution::   Resuming execution (continue, step, next, finish)
+@end menu
+
+@node Breakpoints
+@subsection Breakpoints (@samp{break}, @samp{catch}, @samp{delete})
+
+@cindex breakpoints
+A @dfn{breakpoint} makes your script stop whenever a certain point in
+the program is reached.  For each breakpoint, you can add conditions to
+control in finer detail whether your script stops.  
+
+You specify the place where your script should stop with the
+@code{break} command and its variants.
+
+@cindex breakpoint numbers
+@cindex numbers for breakpoints
+@value{ttDBG} assigns a number to each breakpoint when
+you create it; these numbers are successive integers starting with
+one.  In many of the commands for controlling various features of
+breakpoints you use the breakpoint number to say which breakpoint you
+want to change. Each breakpoint may be @dfn{enabled} or
+@dfn{disabled}; if disabled, it has no effect on your script until you
+enable it again.
+
+
+@table @code
+@kindex break @ovar{location}
+@kindex b @r{(@code{break})}
+@item break
+Set a breakpoint at the current line.
+
+@item break @var{linenum}
+Set a breakpoint at line @var{linenum} in the current source file.
+The current source file is the last file whose source text was printed.
+The breakpoint will stop your script just before it executes any of the
+code on that line.
+
+@item break @var{filename}:@var{linenum}
+Set a breakpoint at line @var{linenum} in source file @var{filename}.
+
+What may be a little tricky when specifying the filename is getting
+the name recognized by the debugger. If you get a message the message
+``@code{No source file named ...}'', then you may need to qualify the
+name more fully. To see what files are loaded you can use the @code{info
+files} or @code{info file} commands. If you want the name @code{rdebug} thinks
+of as the current file, use @code{info line}.
+
+Here's an example:
+@example
+$ @b{rdebug ~/ruby/gcd.rb 3 5}
+/home/rocky/ruby/gcd.rb:4   # Note this is the file name
+def gcd(a, b)
+(rdb:1) @b{break gcd.rb:6}
+*** No source file named gcd.rb
+(rdb:1) @b{info line}
+Line 4 of "/home/rocky/ruby/gcd.rb"
+(rdb:1) @b{break /home/rocky/ruby/gcd.rb:6}
+Breakpoint 1 file /home/rocky/ruby/gcd.rb, line 6
+(rdb:1) @b{break ~/ruby/gcd.rb:10}  # tilde expansion also works
+Breakpoint 2 file /home/rocky/ruby/gcd.rb, line 10
+(rdb:1) @b{info file gcd.rb}
+File gcd.rb is not cached
+(rdb:1) @b{info file /home/rocky/ruby/gcd.rb}
+File /home/rocky/ruby/gcd.rb
+         19 lines
+@end example
+
+@item break @var{class}:@var{method}
+Set a breakpoint in class @var{class} method @var{method}. You can
+also use a period @code{.} instead of a colon @code{:}. Note that two
+colons @code{::} are not used. Also note a class @emph{must} be
+specified here. If the method you want to stop in is in the main class
+(i.e. the class that @code{self} belongs to at the start of the
+program), then use the name @code{Object}.
+
+@kindex catch @ovar{exception} @r{[} on | 1 | off | 0 @r{]}
+@kindex cat @r{(@code{catch})} 
+@item catch @ovar{exception} @r{[} on | 1 | off | 0 @r{]}
+Set catchpoint to an exception. Without an exception name show catchpoints.
+
+With an ``on'' or ``off'' parameter, turn handling the exception on or
+off. To delete all exceptions type ``catch off''.
+
+@cindex delete breakpoints
+@kindex delete @ovar{breakpoints}
+@kindex del @r{(@code{delete})}
+@item delete @ovar{breakpoints}
+Delete the breakpoints specified as arguments. 
+
+If no argument is specified, delete all breakpoints (@DBG asks
+confirmation.  You can abbreviate this command as @code{del}.
+@kindex info breakpoints
+@cindex @code{$_} and @code{info breakpoints}
+@item info breakpoints @ovar{n}
+@itemx info break @ovar{n}
+Print a table of all breakpoints set and not deleted, with the
+following columns for each breakpoint:
+
+@table @emph
+@item Breakpoint Numbers (@samp{Num})
+@item Enabled or Disabled (@samp{Enb})
+Enabled breakpoints are marked with @samp{1}.  @samp{0} marks breakpoints
+that are disabled (not enabled).
+@item File and Line (@samp{file:line})
+The filename and line number inside that file where of breakpoint in
+the script. The file and line are separated with a colon.
+@item Condition
+A condition (an arithmetic expression) which when true causes the
+breakpoint to take effect.
+@end table
+@noindent
+If a breakpoint is conditional, @code{info break} shows the condition on
+the line following the affected breakpoint; breakpoint commands, if any,
+are listed after that.
+
+@code{info break} with a breakpoint number @var{n} as argument lists
+only that breakpoint.
+
+Examples:
+@example
+(rdb:1) @b{info break}
+Breakpoints at following places:
+Num  Enb What
+1    y   gcd.rb:3
+2    y   gcb.rb:28 if n > 1
+(rdb:1) @b{info break 2}
+2    y   gcb.rb:28 if n > 1
+@end example
+@end table
+
+@node Disabling
+@subsection Disabling breakpoints (@samp{disable}, @samp{enable})
+
+Rather than deleting a breakpoint, you might
+prefer to @dfn{disable} it.  This makes the breakpoint inoperative as if
+it had been deleted, but remembers the information on the breakpoint so
+that you can @dfn{enable} it again later.
+
+You disable and enable breakpoints and catchpoints with the
+@code{enable} and @code{disable} commands, optionally specifying one
+or more breakpoint numbers as arguments.  Use @code{info break} to
+print a list of breakpoints and catchpoints if you do not know which
+numbers to use.
+
+A breakpoint or catchpoint can have any different
+states of enablement:
+
+@itemize @bullet
+@item
+Enabled.  The breakpoint stops your program.  A breakpoint set
+with the @code{break} command starts out in this state.
+@item
+Disabled.  The breakpoint has no effect on your program.
+@end itemize
+
+You can use the following commands to enable or disable breakpoints
+and catchpoints:
+
+@table @code
+@kindex disable breakpoints
+@item disable @var{breakpoints}
+Disable the specified breakpoints---or all breakpoints, if none are
+listed.  A disabled breakpoint has no effect but is not forgotten.  All
+options such as ignore-counts, conditions and commands are remembered in
+case the breakpoint is enabled again later.  You may abbreviate
+@code{disable} as @code{dis}.
+
+@kindex enable breakpoints
+@item enable @var{breakpoints}
+Enable the specified breakpoints (or all defined breakpoints).  They
+become effective once again in stopping your program.
+
+@end table
+
+Breakpoints that you set are initially enabled; subsequently, they
+become disabled or enabled only when you use one of the commands
+above.  (The command @code{until} can set and delete a breakpoint of
+its own, but it does not change the state of your other breakpoints;
+see @ref{Resuming Execution, ,Resuming Execution}.)
+
+@node Conditions
+@subsection Break conditions (@samp{condition})
+@cindex conditional breakpoints
+@cindex breakpoint conditions
+
+The simplest sort of breakpoint breaks every time your script reaches
+a specified place.  You can also specify a @dfn{condition} for a
+breakpoint.  A condition is just a Ruby expression.  
+
+Break conditions can be specified when a breakpoint is set, by using
+@samp{if} in the arguments to the @code{break} command. A breakpoint
+with a condition evaluates the expression each time your script
+reaches it, and your script stops only if the condition is
+@emph{true}. They can also be changed at any time
+with the @code{condition} command.
+
+@ifset FINISHED
+You can also use the @code{if} keyword with the @code{watch} command.
+The @code{catch} command does not recognize the @code{if} keyword;
+@code{condition} is the only way to impose a further condition on a
+catchpoint.
+@end ifset
+
+@table @code
+@kindex condition
+@item condition @var{bnum} @var{expression}
+Specify @var{expression} as the break condition for breakpoint
+@var{bnum}.  After you set a condition, breakpoint @var{bnum} stops
+your program only if the value of @var{expression} is true (nonzero).
+
+@item condition @var{bnum}
+Remove the condition from breakpoint number @var{bnum}.  It becomes
+an ordinary unconditional breakpoint.
+@end table
+
+@ifset FINISHED
+When you use @code{condition}, @DBG checks @var{expression}
+immediately for syntactic correctness, and to determine whether
+symbols in it have referents in the context of your breakpoint.  If
+@var{expression} uses symbols not referenced in the context of the
+breakpoint, @DBG prints an error message:
+
+@example
+No symbol "foo" in current context.
+@end example
+@end ifset
+
+@noindent
+The debugger does not actually evaluate @var{expression} at the time
+the @code{condition} command (or a command that sets a breakpoint with
+a condition, like @code{break if @dots{}}) is given, however.
+
+Examples;
+@example
+condition 1 x>5   # Stop on breakpoint 0 only if x>5 is true.
+condition 1       # Change that! Unconditionally stop on breakpoint 1.
+@end example
+
+@node Resuming Execution
+@subsection Resuming Execution (@samp{step}, @samp{next}, @samp{finish}, @samp{continue}, @samp{jump})
+
+A typical technique for using stepping is to set a breakpoint
+(@pxref{Breakpoints}) at the beginning of the function or the section
+of your script where a problem is believed to lie, run your script
+until it stops at that breakpoint, and then step through the suspect
+area, examining the variables that are interesting, until you see the
+problem happen.
+
+@cindex stepping
+@cindex continuing
+@cindex resuming execution
+@dfn{Continuing} means resuming program execution until your script
+completes normally.  In contrast, @dfn{stepping} means executing just
+one more ``step'' of your script, where ``step'' may mean either one
+line of source code.  Either when continuing or when stepping,
+your script may stop even sooner, due to a breakpoint or a signal.
+
+@menu
+* Step::          running the next statement (step)
+* Next::          running the next statement skipping over functions (next)
+* Finish::        running until the return of a function or ``source'' (finish)
+* Continue::      continuing execution (continue)
+* Jump::          jumping to a new line (jump)
+@end menu
+
+@node Step
+@subsubsection Step (@samp{step})
+@table @code
+@kindex step @r{[}+@r{]} @ovar{count}
+@kindex s @r{(@code{step})}
+@item step @r{[}+-@r{]} @ovar{count}
+Continue running your program until the next logical stopping point
+and return control to @value{DBG}. This command is abbreviated
+@code{s}.
+
+Like, the programming Lisp, Ruby tends implemented in a highly
+expression-oriented manner. Therefore things that in other languages
+that may appear to be a single statement are implemented in Ruby as
+several expressions. For example, in an ``if'' statement or looping
+statements a stop is made after the expression is evaluated but before
+the test on the expression is made. 
+
+So it is common that a lines in the program will have several stopping
+points where in other debuggers of other languages there would be only
+one. Or you may have several statements listed on a line.
+
+When stepping it is not uncommon to want to go to a different line on
+each step. If you want to make sure that on a step you go to a
+@emph{different} position, add a plus sign (@samp{+}). 
+
+@emph{Note: step+ with a number count is not the same as issuing 
+count step+ commands. Instead it uses count-1 step commands followed
+by a step+ command. For example, @code{step+ 3} is the
+same as @code{step; step; step+}, not @code{step+; step+; step+}}
+
+If you find yourself generally wanting to use @code{step+} rather
+than @code{step}, you may want to consider using @code{set
+forcestep}, (@pxref{Forcestep}).
+
+If you have @code{forcestep} set on but want to temporarily disable it
+for the next step command, append a minus, or @code{step-}.
+
+With a count, @code{step} will continue running as normal, but do so
+@var{count} times.  If a breakpoint is reached, or a signal not
+related to stepping occurs before @var{count} steps, stepping stops
+right away.
+@end table
+
+@node Next
+@subsubsection Next (@samp{next})
+@table @code
+@kindex next @r{[}+-@r{]} @ovar{count}
+@kindex n @r{(@code{next})}
+@item next @r{[}+@r{]} @ovar{count}
+This is similar to @code{step}, but function or method calls that
+appear within the line of code are executed without stopping. As with
+step, if you want to make sure that on a step you go to a
+@emph{different} position, add a plus sign (@samp{+}).  Similarly,
+appending a minus disables a @code{forcestep} temporarily, and an
+argument @var{count} is a repeat count, as for @code{step}.
+@end table
+
+@node Finish
+@subsubsection Finish (@samp{finish})
+@table @code
+@kindex finish @ovar{frame-number}
+@item finish @ovar{frame-number}
+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@: @code{up}, @code{down} or @code{frame}) has
+been performed. If a frame number is given we run until @var{frame} frames
+returns.
+
+If you want instead to terminate the program and debugger entirely,
+use @code{quit} (@pxref{Quitting the debugger, ,Quitting the debugger}).
+
+@end table
+
+@node Continue
+@subsubsection Continue (@samp{continue})
+@table @code
+@kindex continue @ovar{line-specification}
+@kindex c @r{(@code{continue})}
+@item continue @ovar{line-specification}
+@itemx c @ovar{line-specification}
+Resume program execution, at the address where your script last
+stopped; any breakpoints set at that address are bypassed.  
+
+The optional argument @var{line-specification} allows you to specify a
+line number to set a one-time breakpoint which is deleted when that
+breakpoint is reached.
+
+Should the program stop before that breakpoint is reached, for
+example, perhaps another breakpoint is reached first, in
+a listing of the breakpoints you won't see this entry in the list of
+breakpoints.
+@end table
+
+@node Jump
+@subsubsection Jump (@samp{jump})
+@table @code
+@kindex jump @r{[}+-@r{]} @ovar{line}
+@item jump @r{[}+-@r{]} @ovar{line}
+Change the next line to execute to the given line number.
+@end table
+
+@node ruby-debug settings
+@section ruby-debug settings (@samp{set args}, @samp{set autoeval}..)
+
+You can alter the way ruby-debug interacts with you using @code{set}
+commands. 
+
+The various parameters to @code{set} are given below. Each parameter
+name needs to to be only enough to make it unique. For example
+@code{set force} is a suitable abbreviation for @code{set forcestep}.
+The letter case is not important, so @code{set FORCE} or @code{set
+Force} are also suitable abbreviations.
+
+Many @code{set} commands are either ``on'' or ``off'', and you can
+indicate which way you want set by supplying the corresponding
+word. The number 1 can be used for ``on'' and 0 for ``off''. If none
+of these is given, we will assume ``on''. A deprecated way of turning
+something off is by prefacing it with ``no''.
+
+Each @code{set} command has a corresponding @code{show} command which
+allows you to see the current value.
+
+@menu
+* Args::                 Annotation Level
+* Autoeval::             Evaluate unrecognized commands
+* Autolist::             Execute ``list'' command on every breakpoint
+* Autoirb::              Invoke IRB on every stop
+* Autoreload::           Reload source code when changed
+* Basename::             Report file basename only showing file names
+* Callstyle::            Show Report file basename only showing file names
+* Forcestep::            Make sure 'next/step' commands always move to a new line
+* Fullpath::             Display full file names in frames
+* History::              Generic command for showing command history parameters.
+* Keepframebindings::    Save frame binding on each call
+* Linetrace::            line execution tracing
+* Linetrace+::           line tracing style
+* Listsize::             Number of lines to try to show in a 'list' command
+* Post-mortem::          Whether post-mortem handling is in effect.
+* Trace::                Display stack trace when 'eval' raises exception
+* Width::                Number of characters the debugger thinks are in a line
+@end menu
+
+@node Args
+@subsection Set/Show args
+
+@table @code
+@kindex set args @ovar{parameters}
+@item set args @ovar{parameters}
+Specify the arguments to be used if your program is rerun.  If
+@code{set args} has no arguments, @code{restart} executes your program
+with no arguments.  Once you have run your program with arguments,
+using @code{set args} before the next @code{restart} is the only way to run
+it again without arguments.
+
+@kindex show args
+@item show args
+Show the arguments to give your program when it is started.
+@end table
+
+@node Autoeval
+@subsection Set/Show auto-eval
+
+@table @code
+@kindex set autoeval @r{[} on | 1 | off | 0 @r{]}
+@item set autoeval @r{[} on | 1 | off | 0 @r{]}
+Specify that debugger input that isn't recognized as a command should
+be passed to Ruby for evaluation (using the current debugged program
+namespace). Note however that we @emph{first} check input to see if it
+is a debugger command and @emph{only} if it is not do we consider it
+as Ruby code. This means for example that if you have variable called
+@code{n} and you want to see its value, you could use @code{p n},
+because just entering @code{n} will be interpreted as the debugger
+``next'' command.
+
+See also @ref{irb} and @ref{Autoirb}.
+
+When autoeval is set on, you'll get a different error message when you
+invalid commands are encountered. Here's a session fragment to show
+the difference
+@smallexample
+(rdb:1) @b{stepp}
+Unknown command
+(rdb:1) @b{set autoeval on}
+autoeval is on.
+(rdb:1) @b{stepp}
+NameError Exception: undefined local variable or method `stepp' for ...
+@end smallexample
+
+@kindex show autoeval 
+@item show args
+Shows whether Ruby evaluation of debugger input should occur or not.
+@end table
+
+@node Autolist
+@subsection Execute ``list'' command on every breakpoint
+
+@node Autoirb
+@subsection Set/Show auto-irb
+
+@table @code
+@kindex set autoirb @r{[} on | 1 | off | 0 @r{]}
+@item set autoirb @r{[} on | 1 | off | 0 @r{]}
+
+When your program stops, normally you go into a debugger command loop
+looking for debugger commands. If instead you would like to directly
+go into an irb shell, set this on. See also @ref{Autoeval} or
+@ref{irb} if you tend to use debugger commands but still want Ruby
+evaluation occasionally.
+
+@kindex show autoirb
+@item show autoirb
+Shows whether the debugger will go into irb on stop or not.
+@end table
+
+@node Autoreload
+@subsection Set/Show auto-reload
+@table @code
+@kindex set autoreload @r{[} on | 1 | off | 0 @r{]}
+Set this on if the debugger should check to see if the source has
+changed since the last time it reread in the file if it has.
+@end table
+
+@node Basename
+@subsection Set/Show basename
+
+@table @code
+@kindex set basename @r{[} on | 1 | off | 0 @r{]}
+@item set basename @r{[} on | 1 | off | 0 @r{]}
+Source filenames are shown as the shorter ``basename''
+only. (Directory paths are omitted). This is useful in running the
+regression tests and may useful in showing debugger examples as in
+this text. You may also just want less verbose filename display.
+
+By default filenames are shown as with their full path.
+
+@kindex show basename
+@item show basename
+Shows the whether filename display shows just the file basename or not.
+@end table
+
+@node Callstyle
+@subsection Set/Show call style
+
+@table @code
+@ifset FINISHED
+@kindex set callstyle @r{[} short | last | tracked @r{]}
+@item set forcestep @r{[} short | last | tracked @r{]}
+@else
+@kindex set callstyle @r{[} short | last 
+@item set forcestep @r{[} short | last 
+@end ifset
+
+Sets how you want call parameters displayed; @code{short} shows just
+the parameter names; 
+@ifset FINISHED
+@code{last} shows the parameter names and the
+class of these variables as they currently exist. Note the type could
+have changed between when the call and its current
+values.
+@end ifset
+@code{tracked} is the most accurate but this adds
+overhead. On every call, scalar values of the parameters get
+saved. For non-scalar values the class is saved. 
+@end table
+
+@node Forcestep
+@subsection Set/Show Forces Different Line Step/Next
+
+@table @code
+@kindex set forcestep @r{[} on | 1 | off | 0 @r{]}
+@item set forcestep @r{[} on | 1 | off | 0 @r{]}
+
+Due to the interpretive, expression-oriented nature of the Ruby
+Language and implementation, each line often contains many possible
+stopping points, while in a debugger it is often desired to treat each
+line as an individual stepping unit. 
+
+Setting forcestep on will cause each @code{step} or @code{next}
+command to stop at a different line number. See also @ref{Step} and
+@ref{Next}.
+
+@kindex show forcestep
+@item show forcestep
+Shows whether forcestep is in effect or not.
+@end table
+
+@node Fullpath
+@subsection Set/Show Frame full path
+
+@node History
+@subsection Command History Parameters
+@table @code
+@item show commands
+@kindex show commands
+Display the last ten commands in the command history.
+
+@item show commands @var{n}
+@kindex show commands @var{n}
+Print ten commands centered on command number @var{n}.
+
+@item show history filename
+@kindex show history filename
+Show the filename in which to record the command history
+(the list of previous commands of which a record is kept).
+
+@item set history save @r{[} on | 1 | off | 0 @r{]}
+@kindex set history save @r{[} on | 1 | off | 0 @r{]}
+Set whether to save the history on exit.
+
+@item show history save
+@kindex show history save
+Show saving of the history record on exit.
+
+@item set history size @var{number}
+@kindex set history size @var{number}
+Set the maximum number of commands to save in the history.
+
+@item show history size
+@kindex show history size
+Show the size of the command history, i.e. the number of previous
+commands to keep a record of.
+@end table
+
+@node Keepframebindings
+@subsection Save frame binding on each call
+
+@node Linetrace
+@subsection Set/Show Line tracing
+
+@table @code
+@kindex set linetrace @r{[} on | 1 | off | 0 @r{]}
+@item set linetrace @r{[} on | 1 | off | 0 @r{]}
+
+Setting linetrace on will cause lines to be shown before run.
+
+@kindex show linetrace
+@item show linetrace
+Shows whether line tracing is in effect or not.
+@end table
+
+@node Linetrace+
+@subsection Set/Show Line tracing style
+
+@table @code
+@kindex set linetrace+ @r{[} on | 1 | off | 0 @r{]}
+@item set linetrace+ @r{[} on | 1 | off | 0 @r{]}
+
+Setting linetrace+ on will cause consecutive trace lines not to be a
+duplicate of the preceding line-trace line. Note however that this
+setting doesn't by itself turn on or off line tracing. 
+
+@kindex show linetrace+
+@item show linetrace
+Shows whether the line tracing style is to show all lines or remove 
+duplicates linetrace lines when it is a repeat of the previous line.
+@end table
+
+@node Listsize
+@subsection Set/Show lines in a List command
+
+@table @code
+@kindex set listsize @var{number-of-lines}
+@item set listsize @var{number-of-lines}
+Set number of lines to try to show in a @code{list} command.
+@kindex show listsize
+@item show listsize
+Shows the list-size setting.
+@end table
+
+@node Post-mortem
+@subsection Show Post-mortem handling
+@table @code
+@kindex show post-mortem
+Shows wither post-mortem debugging is in effect. Right now we don't
+have the ability to change the state inside the debugger.
+@end table
+
+@node Trace
+@subsection Display stack trace when 'eval' raises exception
+
+@node Width
+@subsection Set/Show Line width
+
+@table @code
+@kindex set width @var{column-width}
+@item set width @var{column-width}
+Set number of characters the debugger thinks are in a line.
+We also change OS environment variable @code{COLUMNS}. 
+@kindex show width
+@item show width
+Shows the current width setting.
+@end table
+
+@node Program Information
+@section Program Information (@samp{info})
+
+This @code{info} command (abbreviated @code{i}) is for describing the
+state of your program.  For example, you can list the current
+parameters with @code{info args}, or list the breakpoints you have set
+with @code{info breakpoints} or @code{info watchpoints}.  You can get
+a complete list of the @code{info} sub-commands with @w{@code{help
+info}}.
+
+@table @code
+@kindex info args
+
+@item info args
+Method arguments of the current stack frame.
+@kindex info breakpoints
+
+@item info breakpoints
+Status of user-settable breakpoints
+@kindex info display
+
+@item info display
+All display expressions.
+@kindex info files
+
+@item info files
+Source files in the program.
+@kindex info file
+
+@item info file @var{filename} @ovar{all|lines|mtime|sha1}
+Information about a specific file. Parameter @code{lines} gives the
+number of lines in the file, @code{mtime} shows the modification time
+of the file (if available), @code{sha1} computes a SHA1 has of the
+data of the file. @code{all} gives all of the above information.
+
+@kindex info line
+@item info line
+Line number and file name of current position in source.
+@kindex info locals
+@item info locals
+Local variables of the current stack frame.
+@kindex info program
+@item info program
+Display information about the status of your program: whether it is
+running or not and why it stopped. If an unhandled exception occurred,
+the exception class and @code{to_s} method is called.
+@kindex info stack
+@item info stack
+Backtrace of the stack. An alias for @code{where}. @xref{Backtrace}.
+@kindex info thread
+@item info thread @ovar{thread-number} @r{[} terse | verbose@r{]}
+If no thread number is given, we list info for all
+threads. @code{terse} and @code{verbose} options are possible. If terse,
+just give summary thread name information. See information under @code{info threads} for
+more detail about this summary information.
+
+If @code{verbose} is appended to the end of the command, then the entire
+stack trace is given for each thread.
+
+@kindex info threads @r{[} terse | verbose@r{]}
+@item info threads
+
+List information about currently-known threads. This information
+includes whether the thread is current (+), if it is suspended ($), or
+ignored (!); the thread number and the top stack item. If
+@code{verbose} is given then the entire stack frame is shown. Here is
+an example:
+
+@smallexample
+(rdb:7) info threads
+  1 #<Thread:0xb7d08704 sleep>	./test/thread1.rb:27
+ !2 #<Debugger::DebugThread:0xb7782e4c sleep>	
+  3 #<Thread:0xb777e220 sleep>	./test/thread1.rb:11
+  4 #<Thread:0xb777e144 sleep>	./test/thread1.rb:11
+  5 #<Thread:0xb777e07c sleep>	./test/thread1.rb:11
+  6 #<Thread:0xb777dfb4 sleep>	./test/thread1.rb:11
++ 7 #<Thread:0xb777deec run>	./test/thread1.rb:14
+(rdb:1) 
+@end smallexample
+
+Thread 7 is the current thread since it has a plus sign in front. Thread 2 is
+ignored since it has a @code{!}. A ``verbose'' listing of the above:
+
+@smallexample
+(rdb:7) info threads verbose
+  1 #<Thread:0xb7d08704 sleep>	
+	#0 Integer.join at line test/thread1.rb:27
+	#1 at line test/thread1.rb:27
+ !2 #<Debugger::DebugThread:0xb7782e4c sleep>	
+  3 #<Thread:0xb777e220 sleep>	
+	#0 sleep(count#Fixnum) at line test/thread1.rb:11
+	#1 Object.fn(count#Fixnum, i#Fixnum) at line test/thread1.rb:11
+	#2 at line test/thread1.rb:23
+  4 #<Thread:0xb777e144 sleep>	
+	#0 sleep(count#Fixnum) at line test/thread1.rb:11
+	#1 Object.fn(count#Fixnum, i#Fixnum) at line test/thread1.rb:11
+	#2 at line test/thread1.rb:23
+  5 #<Thread:0xb777e07c sleep>	
+	#0 sleep(count#Fixnum) at line test/thread1.rb:11
+	#1 Object.fn(count#Fixnum, i#Fixnum) at line test/thread1.rb:11
+	#2 at line test/thread1.rb:23
+  6 #<Thread:0xb777dfb4 sleep>	
+	#0 sleep(count#Fixnum) at line test/thread1.rb:11
+	#1 Object.fn(count#Fixnum, i#Fixnum) at line test/thread1.rb:11
+	#2 at line test/thread1.rb:23
++ 7 #<Thread:0xb777deec run>	
+	#0 Object.fn(count#Fixnum, i#Fixnum) at line test/thread1.rb:14
+	#1 at line test/thread1.rb:23
+@end smallexample
+
+@kindex info variables
+@item info variables
+Local and instance variables.
+@end table
+
+@node Post-Mortem Debugging
+@chapter Post-Mortem Debugging
+@cindex post-mortem debugging
+
+It is also to possible enter the debugger when you have an uncaught
+exception that is about to terminate our program. This is called
+@emph{post-mortem debugging}. In this state many, of the debugger commands
+for examining variables and moving around in the stack still
+work. However some commands, such as those which imply a continuation
+of running code, no longer work.
+
+The most reliable way to set up post-mortem debugging is to use the
+@option{--post-mortem} option in invoking @code{rdebug}. See @ref{rdebug
+command-line options}. This traps/wraps at the debugger ``load'' of
+your Ruby script.  When this is done, your program is stopped after
+the exception takes place, but before the stack has been
+unraveled. (Alas, it would be nice to if one could allow resetting the
+exception and continuing, but details of code in Ruby 1.8's
+@code{eval.c} prevent this.)
+
+If however you haven't invoked @code{rdebug} at the outset, but
+instead call @code{ruby-debug} from inside your program, to set up
+post-mortem debugging set the @code{post_mortem} key in
+@code{Debugger.start}. Here's an example modified from
+@url{http://www.datanoise.com/articles/2006/12/20/post-mortem-debugging}:
+
+@smallexample
+    $ @b{cat t.rb }
+    require 'rubygems'
+    require 'ruby-debug' ; Debugger.start(:post_mortem => true)
+
+    def t1
+      raise 'test'
+    end
+    def t2
+      t1
+    end
+    t2
+
+    $ @b{ruby t.rb }
+    t.rb:8: raise 'test'
+    (rdb:post-mortem) @b{l=}
+    [3, 12] in t.rb
+       3  
+       4  Debugger.start
+       5  Debugger.post_mortem
+       6  
+       7  def t1
+    => 8    raise 'test'
+       9  end
+       10  def t2
+       11    t1
+       12  end
+    (rdb:post-mortem)
+@end smallexample
+
+Alternatively you can call @code{Debugger.post_mortem()} after rdebug has
+been started. The @code{post_mortem()} method can be called in two
+ways. Called without a block, it installs a global @code{at_exit()} hook
+that intercepts exceptions not handled by your Ruby script. In
+contrast to using the @option{--post-mortem} option, when this hook
+occurs after the call stack has been rolled back. (I'm not sure if
+this in fact makes any difference operationally; I'm just stating it
+because that's how it works.)
+
+If you know that a particular block of code raises an exception you
+can enable post-mortem mode by wrapping this block inside a
+@code{Debugger.post_mortem} block
+
+@smallexample
+def offender
+  1/0 
+end
+...
+require "ruby-gems"
+require "ruby-debug"
+Debugger.post_mortem do
+  ...
+  offender
+  ...
+end
+@end smallexample 
+
+Once inside the debugger in post-mortem debugging, the prompt should
+be @code{(rdb:post-mortem)}.
+
+@node Debugger Module and Class
+@chapter The Debugger Module and Class
+
+@menu
+* Debugger Module::            ruby-debug's Debugger module
+* Debugger Class::             Debugger class
+* Kernel routines::            Routines added to Kernel
+@end menu
+
+@node Debugger Module
+@section The Debugger Module
+
+@menu
+* Debugger.run::      
+@ifset LATER
+* Debugger.post-mortem:: 
+@end ifset
+* Debugger.context::
+* Debugger.settings::
+@end menu
+
+@node Debugger.run
+@subsection @code{Debugger.start}, @code{Debugger.started?}, @code{Debugger.stop}, @code{Debugger.run_script}
+
+In order to provide better debugging information regarding the stack
+frame(s) across all threads, ruby-debug has to intercept each call,
+save some information and on return remove it. Possibly, in Ruby 1.9
+possibly this will not be needed. Therefore one has to issue call to
+indicate start saving information and another call to stop. Of course,
+If you call ruby-debug from the outset via @code{rdebug} this is done
+for you.
+
+@table @code
+@item Debugger.start(@ovar{options}) @ovar{block}
+@vindex @code{Debugger.start(options)}
+@vindex @code{Debugger.start(block)}
+Turn on add additional instrumentation code to facilitate debugging. A
+system even table hook is installed and some variables are set up to
+access thread frames.
+
+This needs to be done before entering the debugger; therefore a call
+to the debugger issue a @code{Debugger.start} call if necessary.
+
+If called without a block, @code{Debugger.start} returns @code{true} if
+the debugger was already started. But if you want to know if the
+debugger has already been started @code{Debugger.started?} can tell
+you.
+
+If a block is given, the debugger is started and @code{yields} to
+block. When the block is finished executing, the debugger stopped with
+the @code{Debugger.stop method}. You will probably want to put a call
+to @code{debugger} somwhere inside that block
+
+But if you want to completely stop debugger, you must call
+@code{Debugger.stop} as many times as you called Debugger.start
+method.
+
+The first time Debugger.start is called there is also some additional
+setup to make the @code{restart} command work. In particular, @code{$0} and
+@code{ARGV} are used to set internal debugger variables. 
+
+Therefore you should make try to make sure that when
+@code{Debugger.start} is called neither of these variables has been
+modified. If instead you don't want this behavior you can pass an
+options has and set the @code{:init} key to @code{false}. That is
+@smallexample
+  Debugger.start(:init => false) # or Debugger.start(@{:init => false@})
+@end smallexample
+
+If you want post-mortem debugging, you can also supply
+@code{:post_mortem => true} in @code{Debugger.start}.
+
+@item Debugger.started?
+@vindex @code{Debugger.started?}
+Boolean. Return @code{true} if debugger has been started.
+
+@item Debugger.stop
+@vindex @code{Debugger.stop}
+Turn off instrumentation to allow debugging. Return @code{true} is returned
+if the debugger is disabled, otherwise it returns @code{false}.
+@emph{Note that if you want to stop debugger, you must call Debugger.stop
+as many times as you called the @code{Debugger.start} method.}
+
+@item Debugger.run_script(@var{debugger-command-file}, out = handler.interface)
+@vindex @code{Debugger.run_script}
+Reads/runs the given file containing debugger commands. @code{.rdebugrc} is run this way.
+
+@item Debugger.last_exception
+@vindex @code{Debugger.last_exception}
+If not @code{nil}, this contains @code{$!} from the last exception.
+
+@end table
+
+@node Debugger.context
+@subsection @code{Debugger.context}
+As mentioned previously, @code{Debugger.start} instruments additional
+information to be obtained about the current block/frame stack. Here
+we describe these additional @code{Debugger.context} methods. 
+
+Were a frame position is indicated, it is optional. The top or current frame 
+position (position zero) is used if none is given.
+
+@table @code
+@item Debugger.context.frame_args @ovar{frame-position=0}
+@vindex @code{Debugger.context.frame_args}
+If track_frame_args? is true, return information saved about call
+arguments (if any saved) for the given frame position.
+
+@item Debugger.context.frame_args_info @ovar{frame-position=0}
+@vindex @code{Debugger.context.frame_args_info}
+
+@item Debugger.context.frame_class @ovar{frame-position=0}
+@vindex @code{Debugger.context.frame_args_info}
+Return the class of the current frame stack.
+
+@item Debugger.context.frame_file @ovar{frame-position=0}
+@vindex @code{Debugger.context.frame_file}
+Return the filename of the location of the indicated frame position.
+
+@item Debugger.context.frame_id @ovar{frame-position=0}
+@vindex @code{Debugger.context.frame_id}
+Same as @code{Debugger.context.method}.
+
+@item Debugger.context.frame_line @ovar{frame-position=0}
+@vindex @code{Debugger.context.frame_line}
+Return the filename of the location of the indicated frame position.
+
+@item Debugger.context.frame_method @ovar{frame-position=0}
+@vindex @code{Debugger.context.frame_method}
+Symbol of the method name of the indicated frame position.
+
+@item Debugger.context.stack_size
+@vindex @code{Debugger.context.stack_size}
+Return the number the size of the frame stack. Note this may be less
+that the actual frame stack size if debugger recording
+(@code{Debugger.start}) was turned on at after some blocks were added
+and not finished when the @code{Debugger.start} was issued.
+@end table
+
+@node Debugger.settings
+@subsection @code{Debugger.settings}
+@vindex @code{Debugger.settings}
+Symbols listed here are keys into the Array @code{Debugger.settings}.
+These can be set any time after the @code{ruby-debug} is loaded. For example:
+@smallexample
+  require "ruby-debug/debugger"
+  Debugger.settings[:autoeval] = true  # try eval on unknown debugger commands
+  Debugger.listsize = 20  # Show 20 lines in a list command
+@end smallexample
+
+@table @code
+@item :argv
+Array of String. @code{argv[0]} is the debugged program name and
+@code{argv[1..-1]} are the command arguments to it.
+@item :autoeval
+Boolean. True if auto autoeval on. @xref{Autoeval}.
+@item :autoirb
+Fixnum: 1 if on or 0 if off. @xref{Autoirb}.
+@item :autolist
+Fixnum: 1 if on or 0 if off.
+@item :basename
+Boolean. True if basename on. @xref{Basename}.
+@item :callstyle
+Symbol: @code{:short} or @code{:last}. @xref{Callstyle}.
+@item :debuggertesting
+Boolean. True if currently testing the debugger.
+@item :force_stepping
+Boolean. True if stepping should go to a line different from the last
+step. @xref{Forcestep}.
+@item :full_path
+Boolean. @xref{Fullpath}.
+@item :listsize
+Fixnum. Number of lines to show in a @code{list} command. @xref{Listsize}.
+@item :reload_source_on_change
+Boolean. True if we should reread the source every time it changes. @xref{Autoreload}.
+@item :stack_trace_on_error
+Boolean. True if we should produce a stack trace on error. @xref{Trace}.
+@item :width
+Fixnum. Number of characters the debugger thinks are in a line. @xref{Width}.
+@end table
+
+@node Debugger Class
+@section The @code{Debugger} Class
+@menu
+* Debugger.Breakpoint::  Debugger::Breakpoint
+* Debugger.Context::     Debugger::Context
+* Debugger.Command::     Debugger::Command
+@end menu
+
+@table @code
+@item add_breakpoint(file, line, expr)
+@vindex @code{Debugger.add_breakpoint}
+Adds a breakpoint in file @var{file}, at line @var{line}. If
+@var{expr} is not nil, it is evaluated and a breakpoint takes effect
+at the indicated position when that expression is true. You should
+verify that @var{expr} is syntactically valid or a @code{SyntaxError}
+exception, and unless your code handles this the debugged program may
+terminate.
+
+@item remove_breakpoint(bpnum)
+@vindex @code{Debugger.remove_breakpoint}
+When a breakpoint is added, it is assigned a number as a way to
+uniquely identify it. (There can be more than one breakpoint on a
+given line.) To remove a breakpoint, use @code{remove_breakpoint} with
+breakpoint number @var{bpnum}.
+
+@item breakpoints
+@vindex @code{Debugger.breakpoints}
+Return a list of the breakpoints that have been added but not removed.
+@end table
+
+@node Debugger.Breakpoint
+@subsection The @code{Debugger::Breakpoint} Class
+Breakpoint are objects in the @code{Debugger::Breakpoint} class. 
+@table @code
+@item enabled?
+@vindex @code{Debugger::Breakpoints.enabled?}
+Returns whether breakpoint is enabled or not.
+
+@item enabled=
+@vindex @code{Debugger::Breakpoints.enabled=}
+Sets whether breakpoint is enabled or not.
+
+@item expr
+@vindex @code{Debugger::Breakpoints.expr}
+Expression which has to be true at the point where the breakpoint is
+set before we stop.
+
+@item expr=
+@vindex @code{Debugger::Breakpoints.expr=}
+
+@item hit_condition
+@item hit_condition=
+@vindex @code{Debugger::Breakpoints.condition}
+@vindex @code{Debugger::Breakpoints.condition=}
+
+@item hit_count
+@vindex @code{Debugger::Breakpoints.hit_count}
+Returns the hit count of the breakpoint.
+
+@item hit_value
+@vindex @code{Debugger::Breakpoints.hit_value}
+Returns the hit value of the breakpoint.
+
+@item hit_value=
+@vindex @code{Debugger::Breakpoints.hit_value=}
+Sets the hit value of the breakpoint.
+
+@item id
+@cindex @code{Debugger::Breakpoints.id}
+A numeric name for the breakpoint which is used in listing breakpoints
+and removing, enabling or disabling the breakpoint
+
+@item pos
+@vindex @code{Debugger::Breakpoints.pos=}
+Returns the line number of this breakpoint.
+@item pos=
+@vindex @code{Debugger::Breakpoints.pos=}
+Sets the line number of this breakpoint.
+
+@item source
+@vindex @code{Debugger::Breakpoints.source}
+Returns the file name in which the breakpoint occurs.
+
+@item source=
+@vindex @code{Debugger::Breakpoints.source=}
+Sets the file name in which the breakpoint occurs.
+@end table
+
+@node Debugger.Context
+@subsection The @code{Debugger::Context} Class
+Callbacks in @code{Debugger:Context} get called 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.
+
+@table @code
+@item at_line(@var{file}, @var{line})
+@vindex Debugger::Context::at_line(@var{file}, @var{line})
+This routine is called when the debugger encounters a ``line'' event for
+which it has been indicated we want to stop at, such as by hitting a
+breakpoint or by some sort of stepping.
+
+@item at_return(@var{file}, @var{line})
+@vindex Debugger::Context::at_return(@var{file}, @var{line})
+This routine is called when the debugger encounters a ``return'' event for
+which it has been indicated we want to stop at, such as by hitting a
+@code{finish} statement.
+
+@item debug_load(@var{file}, @var{stop-initially})
+@vindex Debugger::Context::debug_load(@var{file}, @var{stop-initially})
+This method should be used to debug a file. If the file terminates
+normally, @code{nil} is returned. If not a backtrace is returned.
+
+The @var{stop-initially} parameter indicates whether the program
+should stop after loading. If an explicit call to the debugger is in
+the debugged program, you may want to set this @code{false}.
+@end table
+
+@node Debugger.Command
+@subsection The @code{Debugger::Command} Class
+
+Each command you run is in fact its own class. Should you want to extend
+ruby-debug, it's pretty easy to do since after all ruby-debug is Ruby.
+
+Each @code{Debugger#Command} class should have the a @code{regexp}
+method. This method returns regular expression for command-line
+strings that match your command. It's up to you to make sure this
+regular expression doesn't conflict with another one. If it does, it's
+undefined which one will get matched and run
+
+In addition the instance needs these methods:
+@table @code
+@item execute
+Code which gets run when you type a command (string) that matches the
+commands regular expression.
+@item help
+A string which gets displayed when folks as for help on that command
+@item help_command
+A name used the help system uses to show what commands are available.
+@end table
+
+Here's a small example of a new command:
+@smallexample
+module Debugger
+  class MyCommand < Command
+  def regexp
+    /^\s*me$/ # Regexp that will match your command
+  end
+
+  def execute
+    puts "hi" # What you want to happen when your command runs
+  end
+  class << self
+    def help_command
+      'me' # String name of command
+    end
+    def help(cmd)
+   # Some sort of help text.
+   %@{This does whatever it is I want to do@}
+   end
+  end
+end
+@end smallexample
+
+Now here's an example of how you can load/use it:
+@smallexample
+  require 'rubygems'
+  require 'ruby-debug'
+  require '/tmp/mycmd.rb' # or wherever
+  Debugger.start
+  x=1
+  debugger
+  y=2
+@end smallexample
+
+And now an example of invoking it:
+@smallexample
+ruby /tmp/testit.rb:
+/tmp/testit.rb:7
+y=2
+(rdb:1) help
+ruby-debug help v0.10.3
+Type 'help <command-name>' for help on a specific command
+Available commands:
+backtrace delete  enable help method putl    set    trace
+break     disable eval   info next   quit    show   undisplay
+catch     display exit   irb  p      reload  source up
+condition down    finish list pp     restart step   var
+continue edit     frame  me   ps     save    thread where
+                  ^^ This is you
+
+(rdb:1) help me
+This does whatever it is I want to do
+(rdb:1) me
+hi
+(rdb:1) 
+@end smallexample
+
+@node Kernel routines
+@section Additions to @code{Kernel}
+
+@table @code
+
+@item debugger @ovar{steps=1}
+@vindex @code{Kernel::debugger}
+Enters the debugger in the current thread after a stepping @var{steps} line-event steps.
+Before entering the debugger startup script is read.
+
+Setting @var{steps} to 0 will cause a break in the debugger subroutine
+and not wait for eany line event to occur. This could be useful you
+want to stop right after the last statement in some scope.
+
+Consider this example:
+@smallexample
+$ cat scope-test.rb
+
+require 'rubygems'
+require 'ruby-debug' ; Debugger.start
+1.times do 
+   a = 1
+   debugger   # implied steps=1
+ end
+y = 1
+
+$ scope-test.rb:8
+y = 1
+(rdb:1) p a
+NameError Exception: undefined local variable or method `a' for main:Object
+(rdb:1)
+@end smallexample
+The debugger will get at the line event which follows @samp{a=1}. This
+is outside the @code{do} block scope where @var{a} is defined. If
+instead you want to stop before leaving the @code{do} loop it is
+possibly to stop right inside the @code{debugger}; call with 0 zero parameter:
+@smallexample
+$ cat scope-test.rb
+
+require 'rubygems'
+require 'ruby-debug' ; Debugger.start
+1.times do 
+   a = 1
+   debugger(0)
+end
+y = 1
+
+$ scope-test.rb:8
+../lib/ruby-debug-base.rb:175
+Debugger.current_context.stop_frame = 0
+(rdb:1) where
+--> #0 Kernel.debugger(steps#Fixnum) at line ../lib/ruby-debug-base.rb:175
+    #1 at line scope-test.rb:6
+    #2 at line scope-test.rb:4
+(rdb:1) up
+#1 at line scope-test.rb:6
+(rdb:1) p a
+1
+(rdb:1)
+@end smallexample
+As seen above you will have to position the frame up one to be back in
+your debugged program rather than in the debugger.
+
+@item breakpoint @ovar{steps=1}
+@vindex @code{Kernel::breakpoint}
+An alias for debugger.  
+
+@item binding_n @ovar{n=0}
+@vindex @code{Kernel::binding_n}
+Returns a @samp{binding()} for the @var{n}-th call frame. Note however
+that you need to first call @samp{Debugger.start} before issuing this
+call.
+
+@end table
+
+@node Using from GitHub
+@appendix Building and Installing from the GitHub Repository
+
+Here are Unix-centric instructions. If you have Microsoft Windows or
+OSX some of the below may need adjusting.
+
+@menu
+* Prerequisites::
+* Package Checkout::
+* Trying Out::
+* Running Regression Tests::
+* Building the Documentation and Emacs files::
+* Building for Microsoft Windows::
+@end menu
+
+@node Prerequisites
+@section Prerequisites: To build the package you'll need at a minimum:
+
+@itemize @bullet
+@item 
+Ruby (of course). Currently only version 1.8.6 and above but not 
+version 1.9.@emph{x} work.
+@item
+Ruby development headers. This typically includes a file called @file{ruby.h}
+@item 
+A C compiler like GNU C (@code{gcc})
+@item
+Rake
+@item
+Subversion (@code{svn}).
+@end itemize
+
+If you want to build the documentation and install Emacs files, you'll
+also need:
+
+@itemize @bullet
+@item 
+ a POSIX shell like bash
+@item
+ autoconf
+@item
+ automake
+@item
+ GNU Make
+@item
+ texinfo
+@end itemize
+
+@node Package Checkout
+@section Basic Package Checkout and Installation 
+
+Check out the trunk of repository following the instructions at 
+@url{http://rubyforge.org/scm/?group_id=1900}  For example on a Unixy system,
+this may work:
+
+@smallexample
+  mkdir ruby-debug
+  cd ruby-debug
+  svn checkout svn://rubyforge.org/var/svn/ruby-debug/trunk trunk
+@end smallexample
+
+In order to make the Ruby gems, @code{ruby-debug} and
+@code{ruby-debug-base}, get yourself into the trunk directory after
+the code has been checked out and run:
+
+@smallexample
+  cd trunk # This is the same trunk checked out above.
+  rake package
+@end smallexample
+
+If all goes well you should have some gem files put in the directory
+@code{pkg}. Use the gem command to install that. 
+
+@smallexample
+  sudo gem install ruby-debug-*.gem   # See gem help for other possibilities
+@end smallexample
+
+If all goes well the rdebug script has been installed ruby-debug is
+now ready to run. But if everything goes well you might want to run
+the built-in regression tests to make sure everything is okay.
+See step 3 below.
+
+If the gem install didn't work,'t there may be a problem with your C
+compiler or the Ruby headers are not installed.
+
+@node Trying Out
+@section Trying Out without Installing
+
+You don't have to build a gem file to try out ruby debug. In fact when
+developing new features for ruby-debug, developers often you want to
+try it out @emph{before} installing.  If you have a problem in the latter
+part of step 1 you may want to try this approach since we go into a
+little more detail as to what happens under the covers when you do the
+gem install.
+
+Run (from trunk)
+@smallexample
+  rake lib
+@end smallexample
+
+This creates a Makefile and builds the ruby-debug shared library. (On
+Unix the name is @code{ruby_debug.so}).
+
+Once this is done you can run the debugger as you would rdebug using the
+script @code{runner.sh}. For example (again from trunk)
+
+@smallexample
+  ./runner.sh ~/my-ruby-program.rb
+@end smallexample
+
+@node Running Regression Tests
+@section Running the Regression Tests
+  
+We've put together some basic tests to make sure ruby-debug is doing
+what we think it should do. To run these (from @code{trunk}):
+
+@smallexample
+  rake test
+@end smallexample
+
+If you didn't build the ruby-debug shared library and skipped step 2,
+don't worry @code{rake test} will do step 2 for you. You should see a
+line that ends something like:
+
+@smallexample
+  Finished in 2.767579 seconds.
+
+  12 tests, 35 assertions, 0 failures, 0 errors
+@end smallexample
+
+The number of seconds, tests, and assertions may be different from the
+above. However you @emph{should} see exactly ``0 failures, 0 errors.''
+
+@node Building the Documentation and Emacs files
+@section Building the Documentation and Testing/Installing Emacs Files
+
+Of course, I recommend you read the ruby-debug manual that comes with
+the package. If you have the prerequisites described above, run this
+once:
+@smallexample
+  sh ./autogen.sh
+@end smallexample
+
+Then run:
+@smallexample
+  ./configure
+  make
+  make test           # Runs Emacs regression tests
+  sudo make install   # Or arrange to do this as root
+@end smallexample
+
+@node Building for Microsoft Windows
+@section Building for Microsoft Windows
+
+Microsoft Windows is ``special'' and building @code{ruby-debug-base}
+on it requires extra care. A problem here seems to be that the
+``One-click'' install is compiled using Microsoft Visual Studio C, version 6
+which is not sold anymore and is rather old.
+
+Instead I suggest building via mingw/msys.
+@url{http://eigenclass.org/hiki.rb?cmd=view&p=cross+compiling+rcovrt&key=mingw}
+has instructions on how to do. Some amendments to these instructions.
+
+First, those instructions are a little GNU/Linux centric. If you are
+using Ubuntu or Debian, then this should be the easiest to follow the
+instructions. On Ubuntu or Debian there is a mingw3 Debian
+package. Installing that will give you the cross compiler that is a
+prerequisite. Alternatively if you are running MS Windows I notice
+that cygwin also has a mingw package. Or possibly you could use MinGW
+directly. For other OS's you might have to build a cross-compiler,
+i.e. gcc which emits win32 code and can create a win32 DLL.
+
+After you have a cross compiler you need to download the Ruby source
+and basically build a ruby interpreter. The cross-compile.sh script
+works although when I downloaded it, it had lots of blank space at the
+beginning which will mess up the Unix magic interpretation. That is
+remove the blanks in front of @code{#/bin/sh}.
+
+On my system, this script fails in running @code{make ruby} because the
+fake.rb that got created needed to have a small change:
+
+@smallexample
+
+	    ALT_SEPARATOR = "\"; \
+@end smallexample
+should be:
+@smallexample
+	    ALT_SEPARATOR = "\\"; \
+@end smallexample
+
+After fixing this, run @code{make ruby}. Also, I needed to run
+@code{make rubyw}.
+
+And then @code{make install} as indicated. 
+
+Once all of that's in place, the place you want be is in
+@code{ruby-debug/trunk/ext/win32}, not @code{ruby-debug/ext}. 
+
+So let's say you've installed the cross-compiled install ruby in
+@code{/usr/local/ruby-mingw32/}. Here then are the commands to build @code{ruby-debug-base-}@emph{xxx}@code{-mswin32.gem}:
+@smallexample
+   cd .../ruby-debug/trunk/ext/win32 
+   ruby -I /usr/local/ruby-mingw32/lib/ruby/1.8/i386-mingw32 ../extconf.rb
+   make # Not rake
+   cd ../..   # back in ruby-debug/trunk
+   rake win32_gem
+@end smallexample
+
+@node Class Module Index
+@unnumbered Class, Module Method Index
+@printindex vr
+
+@node Command Index
+@unnumbered Command Index
+@printindex ky
+
+@node General Index
+@unnumbered General Index
+@printindex cp
+
+@tex
+% I think something like @colophon should be in texinfo.  In the
+% meantime:
+\long\def\colophon{\hbox to0pt{}\vfill
+\centerline{The body of this manual is set in}
+\centerline{\fontname\tenrm,}
+\centerline{with headings in {\bf\fontname\tenbf}}
+\centerline{and examples in {\tt\fontname\tentt}.}
+\centerline{{\it\fontname\tenit\/},}
+\centerline{{\bf\fontname\tenbf}, and}
+\centerline{{\sl\fontname\tensl\/}}
+\centerline{are used for emphasis.}\vfill}
+\page\colophon
+% Blame: doc@cygnus.com, 1991.
+@end tex
+
+@bye