byebug 3.5.1 → 4.0.0

data/CONTRIBUTING.md

@@ -1,20 +1,36 @@
-Thanks for your interest in contributing to Byebug!
+## Byebug as a C-extension
 
-To make your changes, follow this steps:
+Byebug is a gem developed as a C-extension. The debugger internal's
+functionality is implemented in C (the interaction with the TracePoint API).
+The rest of the gem is implemented in Ruby. Normally you won't need to touch
+the C-extension, but it will obviously depended on the bug you're trying to fix
+or the feature you are willing to add. You can learn more about C-extensions
+[here](http://tenderlovemaking.com/2009/12/18/writing-ruby-c-extensions-part-1.html)
+or
+[here](http://tenderlovemaking.com/2010/12/11/writing-ruby-c-extensions-part-2.html).
 
-* [Fork the project](https://help.github.com/fork-a-repo)
-* Create a topic branch - `git checkout -b my_branch`
-* Make sure the latest patch level of Ruby 2.0.0 or higher is installed.
-* Insert awesome code - See below
-* Push your branch to your forked repo - `git push origin my_branch`
-* [Make a pull request](https://help.github.com/articles/using-pull-requests)
 
-This gem uses `rake-compiler` to build native gems. Use `rake compile` to
-build the c-extension and then start the tests using `rake test`
+## Prerequisites
 
-```bash
-rake compile
-rake test
-```
+`Byebug` depends on the TracePoint API provided by `ruby-core`. This is a young
+API and a lot of bugs have been recently corrected. Without this fixes,
+`byebug` will fail to work properly, so make sure you have always the last
+patch level releases of Ruby installed.
 
-It's appreciated if you add tests for new functionality. Thanks!
+
+## Getting started
+
+Once you have a local clone of `byebug`, you can start digging in the source
+code. First run `bundle install` to get development & test dependencies
+installed. Also make sure you compile the C-extension using `bundle exec rake
+compile`, otherwise you won't be able to use your local clone. You can also run
+the test suite as the default rake task (`bundle exec rake`). This task is
+composed of 4 subtasks:
+
+    bundle exec rake compile # compiles the C-extension
+    bundle exec rake test # Run the test suite
+    bundle exec rake rubocop # Run RuboCop's checks on the Ruby files
+    bundle exec rake ccop # Run `indent`'s checks on the C files
+
+After having done this, just read the code and improve it! Your contribution is
+appreciated a lot!

data/GUIDE.md

@@ -1,147 +1,160 @@
 ### First Steps
 
 A handful of commands are enough to get started using `byebug`. The following
-session illustrates these commands.
+session illustrates these commands. Take the following sample file:
+
+```ruby
+#
+# The n'th triangle number: triangle(n) = n*(n+1)/2 = 1 + 2 + ... + n
+#
+def triangle(n)
+  tri = 0
+
+  0.upto(n) { |i| tri += i }
+
+  tri
+end
+
+t = triangle(3)
+puts t
 
 ```
-$ byebug triangle.rb
-[1, 10] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
-    1: # Compute the n'th triangle number: triangle(n) == (n*(n+1))/2
-=>  2: def triangle(n)
-    3:   tri = 0
-    4:   0.upto(n) do |i|
-    5:     tri += i
-    6:   end
-    7:   tri
-    8: end
-    9:
-   10: t = triangle(3)
+
+Let's debug it.
+
+```bash
+$ byebug /path/to/triangle.rb
+
+[1, 10] in /path/to/triangle.rb
+    1: #
+    2: # The n'th triangle number: triangle(n) = n*(n+1)/2 = 1 + 2 + ... + n
+    3: #
+=>  4: def triangle(n)
+    5:   tri = 0
+    6:
+    7:   0.upto(n) { |i| tri += i }
+    8:
+    9:   tri
+   10: end
 (byebug)
 ```
 
-We are currently stopped before the first executable line of the program: line 2
+We are currently stopped before the first executable line of the program: line 4
 of `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 2 is
+seem odd to be stopped before a function definition but in Ruby line 4 is
 executed.
 
 Byebug's prompt is `(byebug)`. If the program has died and you are in
 post-mortem debugging, `(byebug:post-mortem)` is used instead. If the program
-has terminated normally, the string this position will be `(byebug:ctrl)`. The
-commands available change depending on the program's state.
+has terminated normally and the `--no-quit` option has been specified in the
+command line, the prompt will be `(byebug:ctrl)` instead. The commands available
+change depending on the program's state.
 
 Byebug automatically lists 10 lines of code centered around the current line
-every time it is stopped. The current line is marked with `=>`, so the range
-byebug would like to show is [-3..6]. However since there aren't 5 lines before
-the current line, the range is moved _up_ so we can actually display 10 lines
-of code.
+every time it is stopped. The current line is marked with `=>`. If the range
+would overflow the beggining or the end of the file, byebug will move it
+accordingly so that only actual real lines of code are displayed.
 
 Now let us step through the program.
 
-```
+```bash
 (byebug) step
-[2, 11] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
-    2: def triangle(n)
-    3:   tri = 0
-    4:   0.upto(n) do |i|
-    5:     tri += i
-    6:   end
-    7:   tri
-    8: end
-    9:
-=> 10: t = triangle(3)
-   11: puts t
+
+[5, 14] in /path/to/triangle.rb
+    5:   tri = 0
+    6:
+    7:   0.upto(n) { |i| tri += i }
+    9:   end
+   10:
+   11:   tri
+   12: end
+   13:
+=> 14: triangle(3)
 (byebug) <RET> # hit enter
-[1, 10] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
-    1: # Compute the n'th triangle number: triangle(n) == (n*(n+1))/2
-    2: def triangle(n)
-=>  3:   tri = 0
-    4:   0.upto(n) do |i|
-    5:     tri += i
-    6:   end
-    7:   tri
-    8: end
-    9:
-   10: t = triangle(3)
+
+[1, 10] in /path/to/triangle.rb
+    1: #
+    2: # The n'th triangle number: triangle(n) = n*(n+1)/2 = 1 + 2 + ... + n
+    3: #
+    4: def triangle(n)
+=>  5:   tri = 0
+    6:
+    7:   0.upto(n) { |i| tri += i }
+    8:
+    9:   tri
+   10: end
 (byebug) p tri
 nil
 (byebug) step
-[1, 10] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
-    1: # Compute the n'th triangle number: triangle(n) == (n*(n+1))/2
-    2: def triangle(n)
-    3:   tri = 0
-=>  4:   0.upto(n) do |i|
-    5:     tri += i
-    6:   end
-    7:   tri
-    8: end
-    9:
-   10: t = triangle(3)
+
+[2, 11] in /path/to/triangle.rb
+    2: # The n'th triangle number: triangle(n) = n*(n+1)/2 = 1 + 2 + ... + n
+    3: #
+    4: def triangle(n)
+    5:   tri = 0
+    6:
+=>  7:   0.upto(n) { |i| tri += i }
+    8:
+    9:   tri
+   10: end
+   11:
 (byebug) p tri
 0
 ```
 
 The first `step` command runs the script one executable unit. The second command
-we entered was just hitting the return key; `byebug` remembers the last command
-you entered was `step` and it runs it again.
+we entered was just hitting the return key: `byebug` remembers the last command
+you entered was `step` and runs it again.
 
 One way to print the values of variables is `p` (there are other ways). When we
 look at the value of `tri` the first time, we see it is `nil`. Again we are
-stopped _before_ the assignment on line 3, and this variable hasn't been set
+stopped _before_ the assignment on line 5, and this variable hadn't been set
 previously. However after issuing another `step` command we see that the value
 is 0 as expected. If every time we stop we want to see the value of `tri` to see
 how things are going, there is a better way by setting a display expression:
 
-```
+```bash
 (byebug) display tri
 1: tri = 0
 ```
 
-Now let us run the program until we return from the function. We'll want to see
-which lines get run, so we turn on _line tracing_. If we don't want whole paths
-to be displayed when tracing, we can turn on _basename_.
+Now let us run the program until right before we return from the function. We'll
+want to see which lines get run, so we turn on _line tracing_. If we don't want
+whole paths to be displayed when tracing, we can turn on _basename_.
 
-```
-(byebug) display i
-2: i =
-(byebug) set tracing on
-line tracing is on.
-(byebug) set basename on
-basename is on.
-(byebug) finish
-Tracing: triangle.rb:5 tri += i
+```bash
+(byebug) set linetrace
+linetrace is on
+(byebug) set basename
+basename is on
+(byebug) finish 0
+Tracing: triangle.rb:7   0.upto(n) { |i| tri += i }
 1: tri = 0
-2: i = 0
-Tracing: triangle.rb:5 tri += i
+Tracing: triangle.rb:7   0.upto(n) { |i| tri += i }
 1: tri = 0
-2: i = 1
-Tracing: triangle.rb:5 tri += i
+Tracing: triangle.rb:7   0.upto(n) { |i| tri += i }
 1: tri = 1
-2: i = 2
-Tracing: triangle.rb:5 tri += i
+Tracing: triangle.rb:7   0.upto(n) { |i| tri += i }
 1: tri = 3
-2: i = 3
-Tracing: triangle.rb:7 tri
+Tracing: triangle.rb:9   tri
 1: tri = 6
-2: i =
-Tracing: triangle.rb:11 puts t
-1: tri =
-2: i =
-[2, 11] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
-    2: def triangle(n)
-    3:   tri = 0
-    4:   0.upto(n) do |i|
-    5:     tri += i
-    6:   end
-    7:   tri
-    8: end
-    9:
-   10: t = triangle(3)
-=> 11: puts t
-1: tri =
-2: i =
+1: tri = 6
+
+[4, 13] in /home/davidr/Proyectos/byebug/triangle.rb
+    4: def triangle(n)
+    5:   tri = 0
+    6:
+    7:   0.upto(n) { |i| tri += i }
+    8:
+    9:   tri
+=> 10: end
+   11:
+   12: t = triangle(3)
+   13: puts t
 (byebug) quit
-Really quit? (y/n) y
+Really quit? (y/n)
+y
 ```
 
 So far, so good. As you can see from the above to get out of `byebug`, one
@@ -157,67 +170,82 @@ 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.
 
-```bash
-$ byebug hanoi.rb
-[1, 10] in /home/davidr/Proyectos/byebug/old_doc/hanoi.rb
-    1: # Solves the classic Towers of Hanoi puzzle.
-=>  2: def hanoi(n,a,b,c)
-    3:   if n-1 > 0
-    4:     hanoi(n-1, a, c, b)
-    5:   end
-    6:   puts "Move disk %s to %s" % [a, b]
-    7:   if n-1 > 0
-    8:     hanoi(n-1, c, b, a)
-    9:   end
-   10: end
-(byebug)
+```ruby
+#
+# Solves the classic Towers of Hanoi puzzle.
+#
+def hanoi(n, a, b, c)
+  hanoi(n - 1, a, c, b) if n - 1 > 0
+
+  puts "Move disk #{a} to #{b}"
+
+  hanoi(n - 1, c, b, a) if n - 1 > 0
+end
+
+n_args = $ARGV.length
+
+fail('*** Need number of disks or no parameter') if n_args > 1
 ```
 
 Recall in the first section it was stated that before the `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 `def hanoi`.
 
+
 ```bash
+$ byebug path/to/hanoi.rb
+
+    1: #
+    2: # Solves the classic Towers of Hanoi puzzle.
+    3: #
+    4: def hanoi(n, a, b, c)
+    5:   hanoi(n - 1, a, c, b) if n - 1 > 0
+    6:
+    7:   puts "Move disk #{a} to #{b}"
+    8:
+    9:   hanoi(n - 1, c, b, a) if n - 1 > 0
+   10: end
 (byebug) private_methods
 [:public, :private, :include, :using, :define_method, :default_src_encoding, ...
 ```
 
 `private_methods` is not a byebug command but a Ruby feature. By default, when
-byebug doesn't understand a command, it will evaluate it as if it was a Ruby
-command. If you don't want this behaviour, you can use `set autoeval off` or
+`byebug` doesn't understand a command, it will evaluate it as if it was a Ruby
+command. If you don't want this behaviour, you can use `set noautoeval` or
 even drop it in your `.byebugrc` file if you want that behaviour permanently.
 The output of `private_methods`, thought, is unwieldy for our purpose: check
 whether `hanoi` method is in the list. Fortunately, byebug has nice formatting
 features: we can sort the output and put it into columns list using the print
-command `ps`.
+command `ps`. It also has a `width` setting that let's us adapt the width of
+the output so that it nicely fits our screen.
 
 ```bash
+(byebug) set width 80
+Maximum width of byebug's output is 80
 (byebug) ps private_methods
-Array             debug_program         open                        sprintf    
-Complex           default_src_encoding  p                           srand      
-DelegateClass     define_method         pp                          syscall    
-Digest            eval                  print                       system     
-Float             exec                  printf                      test       
-Hash              exit                  private                     throw      
-Integer           exit!                 proc                        trace_var  
-Pathname          fail                  process_options             trap       
-Rational          fork                  public                      untrace_var
-String            format                putc                        using      
-__callee__        gem                   puts                        warn       
-__dir__           gem_original_require  raise                     
-__method__        gets                  rand                      
-`                 global_variables      readline                  
-abort             include               readlines                 
-at_exit           initialize            require                   
-autoload          initialize_clone      require_relative          
-autoload?         initialize_copy       respond_to_missing?       
-binding           initialize_dup        select                    
-block_given?      iterator?             set_trace_func            
-caller            lambda                singleton_method_added    
-caller_locations  load                  singleton_method_removed  
-catch             local_variables       singleton_method_undefined
-dbg_print         loop                  sleep                     
-dbg_puts          method_missing        spawn                     
+Array             default_src_encoding  open                        sleep      
+Complex           define_method         p                           spawn      
+Digest            eval                  pp                          sprintf    
+Float             exec                  print                       srand      
+Hash              exit                  printf                      syscall    
+Integer           exit!                 private                     system     
+Pathname          fail                  proc                        test       
+Rational          fork                  public                      throw      
+String            format                putc                        timeout    
+URI               gem_original_require  puts                        trace_var  
+__callee__        gets                  raise                       trap       
+__dir__           global_variables      rand                        untrace_var
+__method__        include               readline                    using      
+`                 initialize            readlines                   warn       
+abort             initialize_clone      require                     y          
+at_exit           initialize_copy       require_relative          
+autoload          initialize_dup        respond_to_missing?       
+autoload?         iterator?             rubygems_require          
+binding           lambda                select                    
+block_given?      load                  set_trace_func            
+caller            local_variables       singleton_method_added    
+caller_locations  loop                  singleton_method_removed  
+catch             method_missing        singleton_method_undefined
 (byebug)
 ```
 
@@ -226,18 +254,19 @@ Now let's see what happens after stepping:
 ```bash
 (byebug) private_methods.member?(:hanoi)
 false
-(byebug:1) step
-[7, 16] in /home/davidr/Proyectos/byebug/old_doc/hanoi.rb
-    7:   if n-1 > 0
-    8:     hanoi(n-1, c, b, a)
-    9:   end
+(byebug) step
+
+[5, 14] in /path/to/hanoi.rb
+    5:   hanoi(n - 1, a, c, b) if n - 1 > 0
+    6:
+    7:   puts "Move disk #{a} to #{b}"
+    8:
+    9:   hanoi(n - 1, c, b, a) if n - 1 > 0
    10: end
    11:
-=> 12: i_args=ARGV.length
-   13: if i_args > 1
-   14:   puts "*** Need number of disks or no parameter"
-   15:   exit 1
-   16: end
+=> 12: n_args = $ARGV.length
+   13:
+   14: fail('*** Need number of disks or no parameter') if n_args > 1
 (byebug) private_methods.member?(:hanoi)
 true
 (byebug)
@@ -246,104 +275,102 @@ true
 Okay, lets go on and talk about program arguments.
 
 ```bash
-(byebug) ARGV
+(byebug) $ARGV
 []
 ```
 
-Ooops. We forgot to specify any parameters to this program. Let's try again. We
+Oops. We forgot to specify any parameters to this program. Let's try again. We
 can use the `restart` command here.
 
 ```bash
 (byebug) restart 3
 Re exec'ing:
-  /home/davidr/.rvm/gems/ruby-2.0.0-p195@byebug/gems/byebug-1.1.1/bin/byebug /home/davidr/Proyectos/byebug/old_doc/hanoi.rb 3
-[1, 10] in /home/davidr/Proyectos/byebug/old_doc/hanoi.rb
-    1: # Solves the classic Towers of Hanoi puzzle.
-=>  2: def hanoi(n,a,b,c)
-    3:   if n-1 > 0
-    4:     hanoi(n-1, a, c, b)
-    5:   end
-    6:   puts "Move disk %s to %s" % [a, b]
-    7:   if n-1 > 0
-    8:     hanoi(n-1, c, b, a)
-    9:   end
+  /path/to/bin/byebug /path/to/hanoi.rb 3
+
+[1, 10] in /path/to/hanoi.rb
+    1: #
+    2: # Solves the classic Towers of Hanoi puzzle.
+    3: #
+=>  4: def hanoi(n, a, b, c)
+    5:   hanoi(n - 1, a, c, b) if n - 1 > 0
+    6:
+    7:   puts "Move disk #{a} to #{b}"
+    8:
+    9:   hanoi(n - 1, c, b, a) if n - 1 > 0
    10: end
-(byebug) break 4
-Created breakpoint 1 at /home/davidr/Proyectos/byebug/old_doc/hanoi.rb:3
+(byebug) break 5
+Created breakpoint 1 at /path/to/hanoi.rb:5
 (byebug) continue
-Stopped by breakpoint 1 at /home/davidr/Proyectos/byebug/old_doc/hanoi.rb:3
-[1, 10] in /home/davidr/Proyectos/byebug/old_doc/hanoi.rb
-    1: # Solves the classic Towers of Hanoi puzzle.
-    2: def hanoi(n,a,b,c)
-=>  3:   if n-1 > 0
-    4:     hanoi(n-1, a, c, b)
-    5:   end
-    6:   puts "Move disk %s to %s" % [a, b]
-    7:   if n-1 > 0
-    8:     hanoi(n-1, c, b, a)
-    9:   end
+Stopped by breakpoint 1 at /path/to/hanoi.rb:5
+
+[1, 10] in /path/to/hanoi.rb
+    1: #
+    2: # Solves the classic Towers of Hanoi puzzle.
+    3: #
+    4: def hanoi(n, a, b, c)
+=>  5:   hanoi(n - 1, a, c, b) if n - 1 > 0
+    6:
+    7:   puts "Move disk #{a} to #{b}"
+    8:
+    9:   hanoi(n - 1, c, b, a) if n - 1 > 0
    10: end
 (byebug) display n
 1: n = 3
 (byebug) display a
-2: a = a
-(byebug) undisplay 2
-(byebug) display a.inspect
-3: a.inspect = :a
-(byebug) display b.inspect
-4: b.inspect = :b
+2: a = :a
+(byebug) display b
+3: b = :b
+(byebug) undisplay 3
 (byebug) continue
-Stopped by breakpoint 1 at /home/davidr/Proyectos/byebug/old_doc/hanoi.rb:3
-[1, 10] in /home/davidr/Proyectos/byebug/old_doc/hanoi.rb
-    1: # Solves the classic Towers of Hanoi puzzle.
-    2: def hanoi(n,a,b,c)
-=>  3:   if n-1 > 0
-    4:     hanoi(n-1, a, c, b)
-    5:   end
-    6:   puts "Move disk %s to %s" % [a, b]
-    7:   if n-1 > 0
-    8:     hanoi(n-1, c, b, a)
-    9:   end
-   10: end
+Stopped by breakpoint 1 at /path/to/hanoi.rb:5
 1: n = 2
-3: a.inspect = :a
-4: b.inspect = :c
-(byebug) c
-Stopped by breakpoint 1 at /home/davidr/Proyectos/byebug/old_doc/hanoi.rb:3
-[1, 10] in /home/davidr/Proyectos/byebug/old_doc/hanoi.rb
-    1: # Solves the classic Towers of Hanoi puzzle.
-    2: def hanoi(n,a,b,c)
-=>  3:   if n-1 > 0
-    4:     hanoi(n-1, a, c, b)
-    5:   end
-    6:   puts "Move disk %s to %s" % [a, b]
-    7:   if n-1 > 0
-    8:     hanoi(n-1, c, b, a)
-    9:   end
+2: a = :a
+[1, 10] in /path/to/hanoi.rb
+    1: #
+    2: # Solves the classic Towers of Hanoi puzzle.
+    3: #
+    4: def hanoi(n, a, b, c)
+=>  5:   hanoi(n - 1, a, c, b) if n - 1 > 0
+    6:
+    7:   puts "Move disk #{a} to #{b}"
+    8:
+    9:   hanoi(n - 1, c, b, a) if n - 1 > 0
    10: end
+
+(byebug) c
+Stopped by breakpoint 1 at /path/to/hanoi.rb:5
 1: n = 1
-3: a.inspect = :a
-4: b.inspect = :b
+2: a = :a
+
+[1, 10] in /path/to/hanoi.rb
+    1: #
+    2: # Solves the classic Towers of Hanoi puzzle.
+    3: #
+    4: def hanoi(n, a, b, c)
+=>  5:   hanoi(n - 1, a, c, b) if n - 1 > 0
+    6:
+    7:   puts "Move disk #{a} to #{b}"
+    8:
+    9:   hanoi(n - 1, c, b, a) if n - 1 > 0
+   10: end
 (byebug) set nofullpath
-Displaying frame's full file names is off.
+fullpath is off
 (byebug) where
---> #0  Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol) at .../byebug/old_doc/hanoi.rb:4
-    #1  Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol) at .../byebug/old_doc/hanoi.rb:8
-    #2  <top (required)> at .../byebug/old_doc/hanoi.rb:34
+--> #0  Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol) at .../shortpath/to/hanoi.rb:5
+    #1  Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol) at .../shortpath/to/hanoi.rb:5
+    #2  <top (required)> at .../Proyectos/byebug/hanoi.rb:28
 (byebug)
 ```
 
 In the above we added new commands: `break` (see [breakpoints]()), which
 indicates to stop just before that line of code is run, and `continue`, which
-resumes execution.  Notice the difference between `display a` and 
-`display a.inspect`. An implied string conversion is performed on the expression
-after it is evaluated. To remove a display expression `undisplay` is used. If we
+resumes execution. To remove a display expression `undisplay` is used. If we
 give a display number, just that display expression is removed.
 
 We also used a new command `where`(see [backtrace]()) to show the callstack. In
 the above situation, starting from the bottom line we see we called the `hanoi`
-method from line 34 of the file `hanoi.rb` and the `hanoi` method called itself
-two more times at line 4.
+method from line 28 of the file `hanoi.rb` and the `hanoi` method called itself
+two more times at line 5.
 
 In the callstack we show a _current frame_ mark, the frame number, the method
 being called, the names of the parameters, the types those parameters
@@ -357,47 +384,47 @@ Now let's move around the callstack.
 ```bash
 (byebug) undisplay
 Clear all expressions? (y/n) y
-(byebug) i_args
-NameError Exception: undefined local variable or method `i_args' for main:Object
-(byebug) frame -1
-[25, 34] in /home/davidr/Proyectos/byebug/old_doc/hanoi.rb
-   25:     exit 2
-   26:   end
-   27: end
-   28:
-   29: if n < 1 or n > 100
-   30:   puts "*** number of disks should be between 1 and 100"
-   31:   exit 2
-   32: end
-   33:
-=> 34: hanoi(n, :a, :b, :c)
-(byebug) i_args
+(byebug) n_args
+NameError Exception: undefined local variable or method `n_args' for main:Object
+(byebug) frame 2
+
+[19, 28] in /path/to/hanoi.rb
+   19:   begin
+   20:     n = $ARGV[0].to_i
+   21:   rescue ValueError
+   22:     raise("** Expecting an integer, got: #{$ARGV[0]}")
+   23:   end
+   24: end
+   25:
+   26: fail('*** Number of disks should be between 1 and 100') if n < 1 || n > 100
+   27:
+=> 28: hanoi(n, :a, :b, :c)
+(byebug) n_args
 0
 (byebug) p n
 3
 (byebug) down 2
-[1, 10] in /home/davidr/Proyectos/byebug/old_doc/hanoi.rb
-    1: # Solves the classic Towers of Hanoi puzzle.
-    2: def hanoi(n,a,b,c)
-    3:   if n-1 > 0
-=>  4:     hanoi(n-1, a, c, b)
-    5:   end
-    6:   puts "Move disk %s to %s" % [a, b]
-    7:   if n-1 > 0
-    8:     hanoi(n-1, c, b, a)
-    9:   end
+
+[1, 10] in /path/to/hanoi.rb
+    1: #
+    2: # Solves the classic Towers of Hanoi puzzle.
+    3: #
+    4: def hanoi(n, a, b, c)
+=>  5:   hanoi(n - 1, a, c, b) if n - 1 > 0
+    6:
+    7:   puts "Move disk #{a} to #{b}"
+    8:
+    9:   hanoi(n - 1, c, b, a) if n - 1 > 0
    10: end
-(byebug:1) p n
+(byebug) p n
 2
 ```
 
 Notice in the above to get the value of variable `n` we had to use a print
 command like `p n`. If we entered just `n`, that would be taken to mean byebug
-command `next`. In the current scope, variable `i_args` is not defined.
-However I can change to the top-most frame by using the `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 `up 3`. Note that in the outside
-frame #3, the value of `i_args` can be shown. Also note that the value of
+command `next`. In the current scope, variable `n_args` is not defined.  However
+I can change to the top-most frame by using the `frame 2` command. Notice that
+inside frame #2, the value of `n_args` can be shown. Also note that the value of
 variable `n` is different.
 
 
@@ -426,28 +453,27 @@ conditionally run this line if that file is invoked directly, but skip it if it
 is not. _NOTE: `byebug` resets `$0` to try to make things like this work._
 
 ```ruby
-if __FILE__ == $0
+if __FILE__ == $PROGRAM_NAME
   t = triangle(3)
   puts t
 end
 ```
 
-Okay, we're now ready to write our unit test. We'll use `minitest` which comes
-with the standard Ruby distribution.  Here's the test code; it should be in the
-same directory as `triangle.rb`.
+Okay, we're now ready to write our unit test and we'll use the `minitest`
+framework for that. Here's the test code, it should be placed in the same
+directory as `triangle.rb`.
 
 ```ruby
 require 'minitest/autorun'
 require_relative 'triangle.rb'
 
-class TestTri < Minitest::Unit::TestCase
+class TestTriangle < Minitest::Test
   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')
+
+    0.upto(5) { |i| solutions << triangle(i) }
+
+    assert_equal([0, 1, 3, 6, 10, 15], solutions, 'First 5 triangle numbers')
   end
 end
 ```
@@ -466,22 +492,23 @@ def test_basic
 Now we run the program, requiring `byebug`
 
 ```bash
-$ ruby -rbyebug test-triangle.rb
-Run options: --seed 13073
+$ ruby -rbyebug test_triangle.rb
+Run options: --seed 31679
 
-# Running tests:
+# Running:
 
-[2, 11] in test-triangle.rb
+
+[2, 11] in test_triangle.rb
     2: require_relative 'triangle.rb'
     3: 
-    4: class TestTri < Minitest::Unit::TestCase
+    4: class TestTriangle < Minitest::Test
     5:   def test_basic
     6:     byebug
 =>  7:     solutions = []
-    8:     0.upto(5) do |i|
-    9:       solutions << triangle(i)
-   10:     end
-   11:     assert_equal([0, 1, 3, 6, 10, 15], solutions,
+    8:
+    9:     0.upto(5) { |i| solutions << triangle(i) }
+   10:
+   11:     assert_equal([0, 1, 3, 6, 10, 15], solutions, 'First 5 triangle numbers')
 (byebug)
 ```
 
@@ -494,79 +521,32 @@ Now let's see where we are...
 (byebug) set nofullpath
 Displaying frame's full file names is off.
 (byebug) bt
---> #0  TestTri.test_basic at test-triangle.rb:7
-    #1  Minitest::Unit::TestCase.run(runner#Minitest::Unit) at .../2.0.0/minitest/unit.rb:1301
-    #2  Minitest::Unit.block in _run_suite(suite#Class, type#Symbol) at .../2.0.0/minitest/unit.rb:919
-     +-- #3  Array.map at .../2.0.0/minitest/unit.rb:912
-    #4  Minitest::Unit._run_suite(suite#Class, type#Symbol) at .../2.0.0/minitest/unit.rb:912
-    #5  Minitest::Unit.block in _run_suites(suites#Array, type#Symbol) at .../2.0.0/minitest/unit.rb:899
-     +-- #6  Array.map at .../2.0.0/minitest/unit.rb:899
-    #7  Minitest::Unit._run_suites(suites#Array, type#Symbol) at .../2.0.0/minitest/unit.rb:899
-    #8  Minitest::Unit._run_anything(type#Symbol) at .../2.0.0/minitest/unit.rb:867
-    #9  Minitest::Unit.run_tests at .../2.0.0/minitest/unit.rb:1060
-    #10 Minitest::Unit.block in _run(args#Array) at .../2.0.0/minitest/unit.rb:1047
-     +-- #11 Array.each at .../2.0.0/minitest/unit.rb:1046
-    #12 Minitest::Unit._run(args#Array) at .../2.0.0/minitest/unit.rb:1046
-    #13 Minitest::Unit.run(args#Array) at .../2.0.0/minitest/unit.rb:1035
-    #14 #<Class:Minitest::Unit>.block in autorun at .../2.0.0/minitest/unit.rb:789
+--> #0  TestTriangle.test_basic at .../Proyectos/byebug/test_triangle.rb:7
+    #1  block (3 levels) in Minitest::Test.run at .../lib/minitest/test.rb:108
+    #2  Minitest::Test.capture_exceptions at .../lib/minitest/test.rb:206
+    #3  block (2 levels) in Minitest::Test.run at .../lib/minitest/test.rb:105
+    #4  Minitest::Test.time_it at .../lib/minitest/test.rb:258
+    #5  block in Minitest::Test.run at .../lib/minitest/test.rb:104
+    #6  #<Class:Minitest::Runnable>.on_signal(name#String, action#Proc) at .../minitest-5.5.0/lib/minitest.rb:321
+    #7  Minitest::Test.with_info_handler(&block#Proc) at .../lib/minitest/test.rb:278
+    #8  Minitest::Test.run at .../lib/minitest/test.rb:103
+    #9  #<Class:Minitest>.run_one_method(klass#Class, method_name#String) at .../minitest-5.5.0/lib/minitest.rb:768
+    #10 #<Class:Minitest::Runnable>.run_one_method(klass#Class, method_name#String, reporter#Minitest::CompositeReporter) at .../minitest-5.5.0/lib/minitest.rb:295
+    #11 block (2 levels) in #<Class:Minitest::Runnable>.run(reporter#Minitest::CompositeReporter, options#Hash) at .../minitest-5.5.0/lib/minitest.rb:289
+    ͱ-- #12 Array.each at .../minitest-5.5.0/lib/minitest.rb:288
+    #13 block in #<Class:Minitest::Runnable>.run(reporter#Minitest::CompositeReporter, options#Hash) at .../minitest-5.5.0/lib/minitest.rb:288
+    #14 #<Class:Minitest::Runnable>.on_signal(name#String, action#Proc) at .../minitest-5.5.0/lib/minitest.rb:321
+    #15 #<Class:Minitest::Runnable>.with_info_handler(reporter#Minitest::CompositeReporter, &block#Proc) at .../minitest-5.5.0/lib/minitest.rb:308
+    #16 #<Class:Minitest::Runnable>.run(reporter#Minitest::CompositeReporter, options#Hash) at .../minitest-5.5.0/lib/minitest.rb:287
+    #17 block in #<Class:Minitest>.__run(reporter#Minitest::CompositeReporter, options#Hash) at .../minitest-5.5.0/lib/minitest.rb:150
+    ͱ-- #18 Array.map at .../minitest-5.5.0/lib/minitest.rb:150
+    #19 #<Class:Minitest>.__run(reporter#Minitest::CompositeReporter, options#Hash) at .../minitest-5.5.0/lib/minitest.rb:150
+    #20 #<Class:Minitest>.run(args#Array) at .../minitest-5.5.0/lib/minitest.rb:127
+    #21 block in #<Class:Minitest>.autorun at .../minitest-5.5.0/lib/minitest.rb:56
 (byebug)
 ```
 
-We get the same result as if we had run byebug from the outset, just faster!
-
-__NOTICE: In ruby-debug, debugger and older versions of byebug, this would not
-work as expected. If you are having issues, please upgrade to byebug >= 1.5.0__
-
-
-### Byebug.start with a block
-
-We saw that `Byebug.start()` and `Byebug.stop()` allow fine-grain control over
-where byebug tracking should occur.
-
-Rather than use an explicit `stop()`, you can also pass a block to the `start()`
-method. This causes `start()` to run and then `yield` to that block. When the
-block is finished, `stop()` is run. In other words, this wraps a
-`Byebug.start()` and `Byebug.stop()` around the block of code. But it also has a
-side benefit of ensuring that in the presence of an uncaught exception `stop` is
-run, without having to explicitly use `begin ... ensure Byebug.stop() end`.
-
-For example, in Ruby on 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 `start()` with a block; when the method wrapped
-this way finishes, byebug is turned off and the application proceeds at regular
-speed.
-
-Of course, inside the block you will probably want to enter the byebug using
-`Byebug.byebug`, otherwise there would be little point in using the `start`.
-For example, you can do this in `irb`:
-
-```bash
-$ irb
-2.0.0p195 :001 > require 'byebug'
- => true
-2.0.0p195 :002 > def foo
-2.0.0p195 :003?>   x=1
-2.0.0p195 :004?>   puts 'foo'
-2.0.0p195 :005?>   end
- => nil
-2.0.0p195 :006 > Byebug.start{byebug; foo}
-(irb) @ 6
-(byebug) s
-(irb) @ 3
-(byebug) s
-(irb) @ 4
-(byebug) p x
-1
-(byebug) s
-foo
- => true
-2.0.0p195 :007 >
-```
-
-There is a counter inside of `Byebug.start` method to make sure that this works
-when another `Byebug.start` method is called inside of the outer one. However,
-if you are stopped inside byebug, issuing another `byebug` call will not have
-any effect even if it is nested inside another `Byebug.start`.
+We get the same result as if we had run byebug from the outset.
 
 
 ### Debugging Oddities: How debugging Ruby may be different from other languages
@@ -577,7 +557,7 @@ seem or feel a little bit different and may confuse you. A number of these
 things aren't oddities of the debugger per se but differences 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 byebug may help you
+well if it is to be useful. In this respect, using Byebug may help you
 understand Ruby better.
 
 We've already seen one such difference: the fact that we stop on method
@@ -598,28 +578,37 @@ not necessarily go to the first statement after the method header. It's possible
 that the call will continue after a `yield` statement from a prior call.
 
 ```ruby
+#
 # Enumerator for primes
+#
 class SievePrime
-  @@odd_primes = []
-  def self.next_prime(&block)
+  def initialize
+    @odd_primes = []
+  end
+
+  def next_prime
     candidate = 2
     yield candidate
     not_prime = false
     candidate += 1
-    while true do
-      @@odd_primes.each do |p|
+
+    loop do
+      @odd_primes.each do |p|
         not_prime = (0 == (candidate % p))
         break if not_prime
       end
+
       unless not_prime
-        @@odd_primes << candidate
+        @odd_primes << candidate
         yield candidate
       end
+
       candidate += 2
     end
   end
 end
-SievePrime.next_prime do |prime|
+
+SievePrime.new.next_prime do |prime|
   puts prime
   break if prime > 10
 end
@@ -627,48 +616,50 @@ end
 
 ```bash
 $ byebug primes.rb
-[1, 10] in /home/davidr/Proyectos/byebug/old_doc/primes.rb
-    1: # Enumerator for primes
-=>  2: class SievePrime
-    3:   @@odd_primes = []
-    4:   def self.next_prime(&block)
-    5:     candidate = 2
-    6:     yield candidate
-    7:     not_prime = false
-    8:     candidate += 1
-    9:     while true do
-   10:       @@odd_primes.each do |p|
+[1, 10] in /path/to/primes.rb
+    1: #
+    2: # Enumerator for primes
+    3: #
+=>  4: class SievePrime
+    5:   def initialize
+    6:     @odd_primes = []
+    7:   end
+    8:
+    9:   def self.next_prime(&block)
+   10:    candidate = 2
 (byebug) set tracing
 line tracing is on.
 (byebug) set basename
 basename in on.
 (byebug) step 9
-Tracing: primes.rb:3 @@odd_primes = []
-Tracing: primes.rb:4 def self.next_prime(&block)
-Tracing: primes.rb:22 SievePrime.next_prime do |prime|
-Tracing: primes.rb:5 candidate = 2
-Tracing: primes.rb:6 yield candidate
-Tracing: primes.rb:23 puts prime
+Tracing: primes.rb:5   def initialize
+Tracing: primes.rb:9   def next_prime
+Tracing: primes.rb:31 SievePrime.new.next_prime do |prime|
+Tracing: primes.rb:6     @odd_primes = []
+Tracing: primes.rb:10     candidate = 2
+Tracing: primes.rb:11     yield candidate
+Tracing: primes.rb:32   puts prime
 2
-Tracing: primes.rb:24 break if prime > 10
-Tracing: primes.rb:7 not_prime = false
-Tracing: primes.rb:8 candidate += 1
-[3, 12] in /home/davidr/Proyectos/byebug/old_doc/primes.rb
-    3:   @@odd_primes = []
-    4:   def self.next_prime(&block)
-    5:     candidate = 2
-    6:     yield candidate
-    7:     not_prime = false
-=>  8:     candidate += 1
-    9:     while true do
-   10:       @@odd_primes.each do |p|
-   11:         not_prime = (0 == (candidate % p))
-   12:         break if not_prime
+Tracing: primes.rb:33   break if prime > 10
+Tracing: primes.rb:12     not_prime = false
+
+[7, 16] in /path/to/primes.rb
+    7:   end
+    8:
+    9:   def next_prime
+   10:     candidate = 2
+   11:     yield candidate
+=> 12:     not_prime = false
+   13:     candidate += 1
+   14:
+   15:     loop do
+   16:       @odd_primes.each do |p|
+   17:         not_prime = (0 == (candidate % p))
 (byebug)
 ```
 
-The loop between lines 23-26 gets interleaved between those of
-`Sieve::next_prime`, lines 6-19 above.
+The loop between lines 31-34 gets interleaved between those of
+`SievePrime#next_prime`, lines 9-28 above.
 
 
 #### No Parameter Values in a Call Stack
@@ -686,17 +677,11 @@ object can change.
 
 So at present, the name of the parameter is shown. The call-style setting
 ([callstyle]()) can be used to set whether the name is shown or the name and the
-_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.
+_current_ class of the object.
 
 
 #### Lines You Can Stop At
 
-As with the duplicate stops per control (e.g. `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.
 
 ```ruby
@@ -711,13 +696,418 @@ puts $1
 The stopping points that Ruby records are the last two lines, lines 5 and 6.
 
 Inside `byebug` you can get a list of stoppable lines for a file using the `info
-file` command with the attribute `breakpoints`.
+file` command.
+
+
+### Threading support
+
+Byebug supports debugging Ruby programs making use of multiple threads.
+
+Let's consider the following sample program:
+
+```ruby
+class Company
+  def initialize(task)
+    @tasks, @results = Queue.new, Queue.new
+
+    @tasks.push(task)
+  end
+
+  def run
+    manager = Thread.new { manager_routine }
+    employee = Thread.new { employee_routine }
+
+    sleep 6
+
+    go_home(manager)
+    go_home(employee)
+  end
+
+  #
+  # An employee doing his thing
+  #
+  def employee_routine
+    loop do
+      if @tasks.empty?
+        have_a_break(0.1)
+      else
+        work_hard(@tasks.pop)
+      end
+    end
+  end
+
+  #
+  # A manager doing his thing
+  #
+  def manager_routine
+    loop do
+      if @results.empty?
+        have_a_break(1)
+      else
+        show_off(@results.pop)
+      end
+    end
+  end
+
+  private
+
+  def show_off(result)
+    puts result
+  end
+
+  def work_hard(task)
+    task ** task
+  end
+
+  def have_a_break(amount)
+    sleep amount
+  end
+
+  def go_home(person)
+    person.kill
+  end
+end
+
+Company.new(10).run
+```
+
+The `Company` class simulates a real company. The company has a manager and an
+employee represented by 2 threads: they work concurrently to achieve the
+company's targets.
+
+* The employee looks for tasks to complete. If there are tasks, it works hard to
+complete them. Otherwise he has a quick break.
+
+```ruby
+#
+# An employee doing his thing
+#
+def employee_routine
+  loop do
+    if @tasks.empty?
+      have_a_break(0.1)
+    else
+      work_hard(@tasks.pop)
+    end
+  end
+end
+```
+
+* The manager, on the other hand, sits there all day and sporadically checks
+whether there are any results to show off.
+
+```ruby
+#
+# A manager doing his thing
+#
+def manager_routine
+  loop do
+    if @results.empty?
+      have_a_break(1)
+    else
+      show_off(@results.pop)
+    end
+  end
+end
+```
+
+We do some abstractions easily readable in the code. Our tasks are just a
+`Queue` of numbers, so are our results. What our employer does when he works is
+some calculation with those numbers and what the manager does with the results
+is printing them to the screen.
+
+We instantiate a new company with an initial task and after running that
+company we expect the result to be printed in the screen, but it is not.  Lets
+debug our sample program:
+
+```bash
+[1, 10] in /path/to/company.rb
+=>  1: class Company
+    2:   def initialize(task)
+    3:     @tasks, @results = Queue.new, Queue.new
+    4:
+    5:     @tasks.push(task)
+    6:   end
+    7:
+    8:   def run
+    9:     manager = Thread.new { manager_routine }
+   10:     employee = Thread.new { employee_routine }
+(byebug) l
+
+[11, 20] in /path/to/company.rb
+   11:
+   12:     sleep 6
+   13:
+   14:     go_home(manager)
+   15:     go_home(employee)
+   16:   end
+   17:
+   18:   #
+   19:   # An employee doing his thing
+   20:   #
+
+(byebug) c 12
+Stopped by breakpoint 1 at /path/to/company.rb:12
+
+[7, 16] in /path/to/company.rb
+    7:
+    8:   def run
+    9:     manager = Thread.new { manager_routine }
+   10:     employee = Thread.new { employee_routine }
+   11:
+=> 12:     sleep 6
+   13:
+   14:     go_home(manager)
+   15:     go_home(employee)
+   16:   end
+(byebug) th l
++ 1 #<Thread:0x0000000192f328 run> /path/to/company.rb:12
+  2 #<Thread:0x00000001ff9870@/path/to/company.rb:9 sleep>
+  3 #<Thread:0x00000001ff80d8@/path/to/company.rb:10 sleep>
+```
+
+What we have done here is just start our program and advance to the point
+inmediately after our `employee` and `manager` threads have been created. We
+can then check that the threads are there using the `thread list` command. Now
+we want to debug both of this threads to check what's happening and look for the
+bug.
+
+```bash
+(byebug) th switch 3
+
+[5, 14] in /path/to/company.rb
+    5:     @tasks.push(task)
+    6:   end
+    7:
+    8:   def run
+    9:     manager = Thread.new { manager_routine }
+=> 10:     employee = Thread.new { employee_routine }
+   11:
+   12:     sleep 6
+   13:
+   14:     go_home(manager)
+(byebug) th stop 1; th stop 2
+$ 1 #<Thread:0x00000001307310 sleep> /path/to/company.rb:12
+$ 2 #<Thread:0x000000018bf438 sleep> /path/to/company.rb:9
+(byebug) th l
+$ 1 #<Thread:0x00000001307310 sleep> /path/to/company.rb:12
+$ 2 #<Thread:0x000000018bf438@/path/to/company.rb:9 sleep> /path/to/company.rb:55
++ 3 #<Thread:0x00000001ff80d8@/path/to/company.rb:10 sleep> /path/to/company.rb:10
+```
+
+We have started by debugging the `employee` thread. To do that, we switch to
+that thread using the `thread switch 3` command. The thread number is the one
+specified by `thread list`, we know this is our worker thread because `thread
+list` specifies where the thread is defined in the file (and its current
+position if the thread is currently running, although this is only available
+since Ruby 2.2.1).
+
+After that we stopped the main thread and the worker thread, using the command
+`thread stop`. We do this because we want to focus on the employee thread first
+and don't want the program to finish while we are debugging. Notice that stopped
+threads are marked with the "$" symbol whereas the current thread is marked with
+the "+" symbol.
+
+```bash
+(byebug) s
+
+[17, 26] in /path/to/company.rb
+   17:
+   18:   #
+   19:   # An employee doing his thing
+   20:   #
+   21:   def employee_routine
+=> 22:     loop do
+   23:       if @tasks.empty?
+   24:         have_a_break(0.1)
+   25:       else
+   26:         work_hard(@tasks.pop)
+(byebug) s
+
+[18, 27] in /path/to/company.rb
+   18:   #
+   19:   # An employee doing his thing
+   20:   #
+   21:   def employee_routine
+   22:     loop do
+=> 23:       if @tasks.empty?
+   24:         have_a_break(0.1)
+   25:       else
+   26:         work_hard(@tasks.pop)
+   27:       end
+(byebug) n
+
+[21, 30] in /path/to/company.rb
+   21:   def employee_routine
+   22:     loop do
+   23:       if @tasks.empty?
+   24:         have_a_break(0.1)
+   25:       else
+=> 26:         work_hard(@tasks.pop)
+   27:       end
+   28:     end
+   29:   end
+   30:
+(byebug) s
+
+[49, 58] in /path/to/company.rb
+   49:   def show_off(result)
+   50:     puts result
+   51:   end
+   52:
+   53:   def work_hard(task)
+=> 54:     task ** task
+   55:   end
+   56:
+   57:   def have_a_break(amount)
+   58:     sleep amount
+(byebug) s
+
+[21, 30] in /path/to/company.rb
+   21:   #
+   22:   # An employee doing his thing
+   23:   #
+   24:   def employee_routine
+   25:     loop do
+=> 26:       if @tasks.empty?
+   27:         have_a_break(0.1)
+   28:       else
+   29:         work_hard(@tasks.pop)
+   30:       end
+(byebug) n
+
+[22, 31] in /path/to/company.rb
+   22:   # An employee doing his thing
+   23:   #
+   24:   def employee_routine
+   25:     loop do
+   26:       if @tasks.empty?
+=> 27:         have_a_break(0.1)
+   28:       else
+   29:         work_hard(@tasks.pop)
+   30:       end
+   31:     end
+(byebug) n
+
+[21, 30] in /path/to/company.rb
+   21:   #
+   22:   # An employee doing his thing
+   23:   #
+   24:   def employee_routine
+   25:     loop do
+=> 26:       if @tasks.empty?
+   27:         have_a_break(0.1)
+   28:       else
+   29:         work_hard(@tasks.pop)
+   30:       end
+   31:     end
+(byebug)
+```
+
+Everything seems fine in this thread. The first iteration the employee will do
+his job, and after that it will just check for new tasks and sleep. Let's debug
+the manager task now:
+
+```bash
+(byebug) th resume 2
+  2 #<Thread:0x000000019892d8@/path/to/company.rb:12 run> /path/to/company.rb:12
+(byebug) th switch 2
+  2 #<Thread:0x000000019892d8@/path/to/company.rb:12 sleep> /path/to/company.rb:12
+
+[7, 16] in /path/to/company.rb
+    7:
+    8:   #
+    9:   # A CEO running his company
+   10:   #
+   11:   def run
+=> 12:     manager = Thread.new { manager_routine }
+   13:     employee = Thread.new { employee_routine }
+   14:
+   15:     sleep 6
+   16:
+(byebug)
+```
+
+We used the command `thread resume` to restart the manager's thread and then
+switch to it using `thread switch`. It's important to resume the thread's
+execution before switching to it, otherwise we'll get a hang because we cannot
+run a sleeping thread.
+
+Now we can investigate the problem in the employer's side:
+
+``bash
+(byebug) s
+[30, 39] in /path/to/company.rb
+   30:
+   31:   #
+   32:   # A manager doing his thing
+   33:   #
+   34:   def manager_routine
+=> 35:     loop do
+   36:       if @results.empty?
+   37:         have_a_break(1)
+   38:       else
+   39:         show_off(@results.pop)
+(byebug) s
+
+[31, 40] in /path/to/company.rb
+   31:   #
+   32:   # A manager doing his thing
+   33:   #
+   34:   def manager_routine
+   35:     loop do
+=> 36:       if @results.empty?
+   37:         have_a_break(1)
+   38:       else
+   39:         show_off(@results.pop)
+   40:       end
+(byebug) n
+
+[32, 41] in /path/to/company.rb
+   32:   # A manager doing his thing
+   33:   #
+   34:   def manager_routine
+   35:     loop do
+   36:       if @results.empty?
+=> 37:         have_a_break(1)
+   38:       else
+   39:         show_off(@results.pop)
+   40:       end
+   41:     end
+(byebug) n
+
+[31, 40] in /path/to/company.rb
+   31:   #
+   32:   # A manager doing his thing
+   33:   #
+   34:   def manager_routine
+   35:     loop do
+=> 36:       if @results.empty?
+   37:         have_a_break(1)
+   38:       else
+   39:         show_off(@results.pop)
+   40:       end
+(byebug)
+``
+
+Now we can see the problem, the `@results` variable is always empty! The
+employee forgot to leave the results in his manager's deck. We fix it by
+changing the line
+
+```ruby
+work_hard(@tasks.pop)
+```
+
+in the `employee_routine` method with the line
+
+```ruby
+@results << work_hard(@tasks.pop)
+```
 
 To be continued...
-* more complex example with objects, pretty printing and irb.
-* line tracing and non-interactive tracing.
-* mixing in Byebug.debug with byebug
-* post-mortem debugging and setting up for that
+* More complex examples with objects, pretty printing and irb.
+* Line tracing and non-interactive tracing.
+* Post-mortem debugging.
 
 
 ## Getting in & out
@@ -726,75 +1116,91 @@ To be continued...
 
 There is a wrapper script called `byebug` which basically `require`'s the gem
 then loads `byebug` before its argument (the program to be debugged) is started.
-
-```bash
-byebug [byebug-options] [--] ruby-script ruby-script-arguments
-```
-
 If you don't need to pass dash options to your program, which might be confused
 with byebug options, then you don't need to add the `--`. To get a brief list of
 options and descriptions, use the `--help` option.
 
 ```bash
 $ byebug --help
-byebug 1.6.1
-Usage: byebug [options] <script.rb> -- <script.rb parameters>
-
-Options:
- -d, --debug               Set $DEBUG=true
- -I, --include PATH        Add PATH (single or multiple:path:list) to $LOAD_PATH
-     --no-quit             Do not quit when script finishes
-     --no-stop             Do not stop when script is loaded
-     --nx                  Don't run any byebug initialization files
-     --post-mortem         Enable post-mortem mode for uncaught exceptions
- -r, --require SCRIPT      Require library before script
-     --restart-script FILE Name of the script file to run. Erased after read
-     --script FILE         Name of the script file to run
-    -x, --trace            Turn on line tracing
-
-Common options:
-        --help             Show this message
-        --version          Print program version
-    -v                     Print version number, then turn on verbose mode
+
+  byebug 3.5.1
+
+  Usage: byebug [options] <script.rb> -- <script.rb parameters>
+
+    -d, --debug               Set $DEBUG=true
+    -I, --include list        Add to paths to $LOAD_PATH
+    -m, --[no-]post-mortem    Use post-mortem mode
+    -q, --[no-]quit           Quit when script finishes
+    -x, --[no-]rc             Run byebug initialization file
+    -s, --[no-]stop           Stop when script is loaded
+    -r, --require file        Require library before script
+    -R, --remote [host:]port  Remote debug [host:]port
+    -t, --[no-]trace          Turn on line tracing
+    -v, --version             Print program version
+    -h, --help                Display this message
+
 ```
 
 Many options appear as a long option name, such as `--help` and a short one
 letter option name, such as `-h`. The list of options is detailed below:
 
-* **-h | --help**. It causes `byebug` to print some basic help and exit
-* **-v | --version**. It causes `byebug` to print its version number and
-exit.
-* **-d | --debug**. Set `$DEBUG` to `true`. Compatible with Ruby's.
-* **-I | --include <path>**. Add `path` to load path. `path` can be a single
-path ar a colon separated path list.
-* **--post-mortem**. If your program raises an exception that isn't caught you
-can enter byebug for inspection of what went wrong. You may also want to use
-this option in conjunction with `--no-stop`. See also [Post-Mortem Debugging]().
-* **--no-quit**. Restart `byebug` when your program terminates normally.
-* **--no-stop**. Normally `byebug` stops before executing the first statement.
-If instead you want it to start running initially and perhaps break it later in
-the execution, use this option.
-* **--require | -r**. Require the library before executing the script. However,
-if the library happened to be `debug`, we'll just ignore the require since we're
-already a debugger. This option is compatible with Ruby's.
-* **--script <file>**. Script to run before byebug's execution.
-* **-x | --trace**. Turn on line tracing. Running `byebug --trace
-<rubyscript>.rb` is pretty much like running `ruby -rtracer
-<rubyscript>.rb`. If all you want to do however is get a linetrace, `tracer` is
-most likely faster than `byebug`
+#### -h | --help
 
-```bash
-$ time ruby -rtracer old_doc/gcd.rb 24 31 >/dev/null
+It causes `byebug` to print some basic help and exit
+
+
+#### -v | --version
+
+It causes `byebug` to print its version number and exit.
+
+
+#### -d | --debug
+
+Sets `$DEBUG` to `true`. Compatible with Ruby's flag.
+
+#### -I | --include <path>
+
+Adds `path` to load path. `path` can be a single path or a colon separated path
+list.
+
+#### -m | --post-mortem
+
+If your program raises an exception that isn't caught you can enter byebug for
+inspection of what went wrong. You may also want to use this option in
+conjunction with `--no-stop`. See also [Post-Mortem Debugging]().
+
+#### --no-quit
+
+Keep inside `byebug` after your program terminates normally.
 
-real  0m0.066s
-user  0m0.048s
-sys 0m0.016s
+#### --no-stop
 
-$ time byebug --trace old_doc/gcd.rb 24 31 >/dev/null
+Normally `byebug` stops before executing the first statement. If instead you
+want it to start running initially and perhaps break it later in the execution,
+use this option.
 
-real  0m0.660s
-user  0m0.588s
-sys 0m0.056s
+#### -r | --require <lib>
+
+Requires the library before executing the script.  This option is compatible
+with Ruby's.
+
+#### -t | --trace
+
+Turns on line tracing. Running `byebug --trace <rubyscript>.rb` is pretty much
+like running `ruby -rtracer <rubyscript>.rb`. If all you want to do however is
+get a line trace, `tracer` is most likely faster than `byebug`.
+
+```bash
+$ time byebug --trace --no-stop hanoi.rb > /dev/null
+
+real	0m0.743s
+user	0m0.668s
+sys	0m0.068s
+$ time ruby -rtracer hanoi.rb > /dev/null
+
+real	0m0.077s
+user	0m0.072s
+sys	0m0.004s
 ```
 
 ### Byebug default options
@@ -802,27 +1208,7 @@ sys 0m0.056s
 Byebug has many command-line options,; it seems that some people want to set
 them differently from the defaults. For example, some people may want
 `--no-quit` to be the default behavior. One could write a wrapper script or set
-a shell alias to handle this. But `byebug` has another way to do it. Before
-processing command options, if the file `$HOME/.byebugoptrc` is found, it is
-loaded. If you want to set the defaults in some other way, you can put Ruby code
-here and set variable `options` which is an OpenStruct. For example here's how
-you'd set `-no-quit` and a personal message.
-
-```ruby
-# This file contains how you want the default options to byebug to be set. Any
-# Ruby code can be put here.
-#
-# byebug # Uncomment if you want to debug byebug!
-options.control = false
-puts "rocky's byebugrc run"
-```
-
-Here are the default values in `options`
-
-```
-#<OpenStruct nx=false, quit=true, restart_script=nil, script=nil, stop=true,
-             tracing=false, verbose=false>
-```
+a shell alias to handle this.
 
 ### Command Files
 
@@ -841,8 +1227,6 @@ 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 `byebug`.
 
-* __Reads command files specified by the `--script` option.__
-
 You can also request the execution of a command file with the `source` command
 (see [Source]()).
 
@@ -917,7 +1301,7 @@ different computer than the one running the Ruby program.
 
 To setup remote debugging, drop the following somewhere before the point in the
 program that you want to debug (In Rails, the
-`config/environments/development.rb` could be a good canditate).
+`config/environments/development.rb` could be a good candidate).
 
 ```ruby
   require 'byebug'
@@ -1008,11 +1392,11 @@ short list of named classes of commands
 Type "help <command-name>" for help on a specific command
 
 Available commands:
-backtrace  delete   enable  help  method  ps       save    step       where
-break      disable  eval    info  next    putl     set     trace
-catch      display  exit    irb   p       quit     show    undisplay
-condition  down     finish  kill  pp      reload   skip    up
-continue   edit     frame   list  pry     restart  source  var
+backtrace  delete   enable  help  method  ps        save       step       where
+break      disable  eval    info  next    putl      set        trace      catch
+display    exit     irb     p     quit    show      undisplay  condition  down
+finish     kill     pp      skip  up      continue  edit       frame      list
+pry        restart  source  var
 ```
 
 With a command name as `help` argument, `byebug` displays short information on how to
@@ -1261,7 +1645,7 @@ got updated via a prior `list` command.
 
 ```
 $ byebug triangle.rb
-[1, 10] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
+[1, 10] in /path/to/triangle.rb
     1: # Compute the n'th triangle number, the hard way: triangle(n) == (n*(n+1))/2
 =>  2: def triangle(n)
     3:   tri = 0
@@ -1279,7 +1663,7 @@ $ byebug triangle.rb
 /home/davidr/Proyectos/byebug/old_doc/triangle.rb @ 2
 def triangle(n)
 (byebug) list # same line range as before going into irb
-[1, 10] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
+[1, 10] in /path/to/triangle.rb
     1: # Compute the n'th triangle number, the hard way: triangle(n) == (n*(n+1))/2
 =>  2: def triangle(n)
     3:   tri = 0