debug 1.9.2 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c242bce58b031f61da73507f6b42a26f1ed8322679d1f0b3460d8fbc8c4b7a23
-  data.tar.gz: 543feb5e53a2c99ba04583edae4a13378667c97b13662f5a4d456dd6bacb17b5
+  metadata.gz: fc4d6aa4412830633b73eebc239b7b27b17f100965bf4d8b916ce3f6311dfcbb
+  data.tar.gz: 11180fe8d9c9d3c9b170b6e817a39c6020dbfa831631a8bad9dc6d69d6a6235e
 SHA512:
-  metadata.gz: b5f6c58f38114e3179c3d5c062294ac276b53533fc4a6543114a883198318b672a8506990064f1b40d9f9597d3e1a933cb7c2363ea4cdd4ba0e0571279a80c73
-  data.tar.gz: 142a78dcdc449df6e0148857f992500aa88375707af067f36f1e3391fe2adb7ac8ff0f66623806c5488e94292167a369ca901084475e97b8dc38e32257ccbba0
+  metadata.gz: 0f7c076a9affef363d2a04b31484be5dd904bd750ec1a567adabbdaee0cf9a91bc162e564f504ae67711b5940aa34541300c56b81b60a6078b15296ebff2a72a
+  data.tar.gz: b912627acde3296f2e0701cf9a087d5f626181e04c994994a7ac9943ea38736734d4c2197f795573ca814fcface4c61b330f665aaa4c614f74bf1bfb85c7cb4f

data/README.md

@@ -16,38 +16,38 @@ New debug.rb has several advantages:
      | Frontend    | [Console](https://github.com/ruby/debug#invoke-as-a-remote-debuggee) | [VSCode](https://github.com/ruby/debug#vscode-integration)                                  | [Chrome DevTool](#chrome-devtool-integration) |
      | ----------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------- |
      | Connection  | UDS, TCP/IP                                                          | UDS, TCP/IP                                                                                 | TCP/IP                                        |
-     | Requirement | No                                                                   | [vscode-rdbg](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg) | Chrome                                        |
+     | Requirement | None                                                                 | [vscode-rdbg](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg) | Chrome                                        |
 
 * Extensible: application can introduce debugging support in several ways:
   * By `rdbg` command
   * By loading libraries with `-r` command line option
   * By calling Ruby's method explicitly
 * Misc
-  * Support threads (almost done) and ractors (TODO).
-  * Support suspending and entering to the console debugging with `Ctrl-C` at most of timing.
+  * Support threads (almost done) and Ractors (TODO).
+  * Support suspending and entering the debug console with `Ctrl-C` at most of timing.
   * Show parameters on backtrace command.
-  * Support recording & replay debugging.
+  * Support recording and replay debugging.
 
 # Installation
 
-```
+```console
 $ gem install debug
 ```
 
-or specify `-Ipath/to/debug/lib` in `RUBYOPT` or each ruby command-line option, especially for debug this gem development.
+Alternatively, specify `-Ipath/to/debug/lib` in `RUBYOPT`, or as a Ruby command-line option
+This is especially useful for debugging this gem during development.
 
-If you use Bundler, write the following line to your Gemfile.
+If using Bundler, add the following to your Gemfile:
 
-```
+```ruby
 gem "debug", ">= 1.0.0"
 ```
 
-(The version constraint is important; `debug < 1.0.0` is an older,
-abandoned gem that is completely different from this product.)
+(The version constraint is important; `debug < 1.0.0` is an older, abandoned gem that is completely different from this product.)
 
 # HOW TO USE
 
-To use a debugger, roughly you will do the following steps:
+To use the debugger, you will do roughly the following steps:
 
 1. Set breakpoints.
 2. Run a program with the debugger.
@@ -63,22 +63,23 @@ To use a debugger, roughly you will do the following steps:
 
 ## Invoke with the debugger
 
-There are several options for (1) and (2). Please choose your favorite way.
+There are several ways to invoke the debugger, depending on your needs, preferences, and the environment.
 
 ### Modify source code with [`binding.break`](#bindingbreak-method) (similar to `binding.pry` or `binding.irb`)
 
-If you can modify the source code, you can use the debugger by adding `require 'debug'` at the top of your program and putting [`binding.break`](#bindingbreak-method) method into lines where you want to stop as breakpoints like `binding.pry` and `binding.irb`.
+If you can modify the source code, you can use the debugger by adding `require 'debug'` at the top of your program and putting [`binding.break`](#bindingbreak-method) method into lines where you want to stop as breakpoints.
+This is similar to how `binding.pry` and `binding.irb` work.
 
-You can also use its 2 aliases in the same way:
+`binding.break` has two aliases which do the same thing:
 
 - `binding.b`
 - `debugger`
 
 After that, run the program as usual and you will enter the debug console at breakpoints you inserted.
 
-The following example shows the demonstration of [`binding.break`](#bindingbreak-method).
+The following is an example of the [`binding.break`](#bindingbreak-method) method.
 
-```shell
+```console
 $ cat target.rb                        # Sample program
 require 'debug'
 
@@ -140,10 +141,11 @@ d => 4
 
 ### Invoke the program from the debugger as a traditional debuggers
 
-If you don't want to modify the source code, you can set breakpoints with a debug command `break` (`b` for short).
-Using `rdbg` command (or `bundle exec rdbg`) to launch the program without any modifications, you can run the program with the debugger.
+If you don't want to modify the source code, you can use the `rdbg` command (or `bundle exec rdbg`) to run the program with the debugger.
+This is similar to how you'd launch a program with `ruby program.rb`.
+Then you can set breakpoints with the debug command `break` (`b` for short).
 
-```shell
+```console
 $ cat target.rb                        # Sample program
 a = 1
 b = 2
@@ -166,9 +168,11 @@ DEBUGGER: Session start (pid: 7656)
 (rdbg)
 ```
 
-`rdbg` command suspends the program at the beginning of the given script (`target.rb` in this case) and you can use debug commands. `(rdbg)` is prompt. Let's set breakpoints on line 3 and line 5 with `break` command (`b` for short).
+The `rdbg` command suspends the program at the beginning of the given script (`target.rb` in this case) and you can use debug commands to control execution from there.
+`(rdbg)` is the console prompt.
+Let's set breakpoints on line 3 and line 5 with `break` command (`b` for short).
 
-```shell
+```console
 (rdbg) break 3                         # set breakpoint at line 3
 #0  BP - Line  /mnt/c/ko1/src/rb/ruby-debug/target.rb:3 (line)
 
@@ -180,9 +184,10 @@ DEBUGGER: Session start (pid: 7656)
 #1  BP - Line  /mnt/c/ko1/src/rb/ruby-debug/target.rb:5 (line)
 ```
 
-You can see that two breakpoints are registered. Let's continue the program by using the `continue` command.
+You can see that two breakpoints are registered.
+Let's continue the program by using the `continue` command.
 
-```shell
+```console
 (rdbg) continue
 [1, 7] in target.rb
       1| a = 1
@@ -199,11 +204,11 @@ Stop by #0  BP - Line  /mnt/c/ko1/src/rb/ruby-debug/target.rb:3 (line)
 (rdbg)
 ```
 
-You can see that we can stop at line 3.
-Let's see the local variables with the `info` command, and continue.
-You can also confirm that the program will suspend at line 5 and you can use the `info` command again.
+You can see that we stopped at line 3.
+Let's see the local variables with the `info` command, and continue execution with the `continue`.
+The program will then suspend at line 5 and you can use the `info` command again.
 
-```shell
+```console
 (rdbg) info
 =>#0    <main> at target.rb:3
 %self => main
@@ -237,25 +242,28 @@ d => 4
 [1, 2, 3, 4]
 ```
 
-By the way, using `rdbg` command you can suspend your application with `C-c` (SIGINT) and enter the debug console.
+NOTE: When using `rdbg` you can suspend your application with `C-c` (SIGINT) and enter the debug console.
 It will help if you want to know what the program is doing.
 
 ### Use `rdbg` with commands written in Ruby
 
-If you want to run a command written in Ruby like `rake`, `rails`, `bundle`, `rspec`, and so on, you can use `rdbg -c` option.
+If you want to run an executable written in Ruby like `rake`, `rails`, `bundle`, `rspec`, and so on, you can use `rdbg -c` option.
 
-* Without `-c` option, `rdbg <name>` means that `<name>` is Ruby script and invoke it like `ruby <name>` with the debugger.
-* With `-c` option, `rdbg -c <name>` means that `<name>` is a command in `PATH` and simply invokes it with the debugger.
+* Without the `-c` option, `rdbg <name>` means that `<name>` is a Ruby script and it is invoked like `ruby <name>` with the debugger.
+* With the `-c` option, `rdbg -c <name>` means that `<name>` is an executable in `PATH` and simply invokes it with the debugger.
 
 Examples:
+
 * `rdbg -c -- rails server`
 * `rdbg -c -- bundle exec ruby foo.rb`
 * `rdbg -c -- bundle exec rake test`
-* `rdbg -c -- ruby target.rb` is same as `rdbg target.rb`
+* `rdbg -c -- ruby target.rb` is the same as `rdbg target.rb`
 
-NOTE: `--` is needed to separate the command line options for `rdbg` and invoking command. For example, `rdbg -c rake -T` is recognized like `rdbg -c -T -- rake`. It should be `rdbg -c -- rake -T`.
+NOTE: `--` is needed to separate the command line options for `rdbg` from the executable being invoked, and its options.
+For example, `rdbg -c rake -T` would be parsed as `rdbg -c -T -- rake`, which is incorrect.
+It should be `rdbg -c -- rake -T`.
 
-NOTE: If you want to use bundler (`bundle` command), you need to write `gem debug` line in your `Gemfile`.
+NOTE: If you want to use Bundler (`bundle` executable), you need to add `gem 'debug'` to your `Gemfile`.
 
 ### Using VSCode
 
@@ -275,12 +283,13 @@ Please see the extension page for more details.
 
 ## Remote debugging
 
-You can use this debugger as a remote debugger. For example, it will help in the following situations:
+You can use this debugger as a remote debugger.
+For example, it will help in the following situations:
 
 * Your application does not run on TTY, and it is hard to use `binding.pry` or `binding.irb`.
   * Your application is running on a Docker container, and there is no TTY.
   * Your application is running as a daemon.
-  * Your application uses pipe for STDIN or STDOUT.
+  * Your application uses pipe for `STDIN` or `STDOUT`.
 * Your application is running as a daemon and you want to query the running status (checking a backtrace and so on).
 
 You can run your application as a remote debuggee, and the remote debugger console can attach to the debuggee anytime.
@@ -296,10 +305,11 @@ There are multiple ways to run your program as a debuggee:
 
 #### `rdbg --open` (or `rdbg -O` for short)
 
-You can run a script with `rdbg --open target.rb` command and run a `target.rb` as a debuggee program. It also opens the network port and suspends at the beginning of `target.rb`.
+Launch a script with `rdbg --open target.rb` to run `target.rb` as a debuggee program.
+It also opens the network port and suspends at the beginning of `target.rb`.
 
-```shell
-$ exe/rdbg --open target.rb
+```console
+$ rdbg --open target.rb
 DEBUGGER: Session start (pid: 7773)
 DEBUGGER: Debugger can attach via UNIX domain socket (/home/ko1/.ruby-debug-sock/ruby-debug-ko1-7773)
 DEBUGGER: wait for debugger connection...
@@ -309,7 +319,7 @@ By default, `rdbg --open` uses UNIX domain socket and generates the path name au
 
 You can connect to the debuggee with `rdbg --attach` command (`rdbg -A` for short).
 
-```shell
+```console
 $ rdbg -A
 [1, 7] in target.rb
 =>    1| a = 1
@@ -324,35 +334,41 @@ $ rdbg -A
 (rdbg:remote)
 ```
 
-If there are no other opening ports on the default directory, `rdbg --attach` command chooses the only one opening UNIX domain socket and connects to it. If there are more files, you need to specify the file.
+If there are no other files in the default directory, `rdbg --attach` will automatically connect to the UNIX domain socket listed.
+If there are multiple files, you need to specify which to use.
 
-When `rdbg --attach` connects to the debuggee, you can use any debug commands (set breakpoints, continue the program, and so on) like the local debug console. When a debuggee program exits, the remote console will also terminate.
+When `rdbg --attach` connects to the debuggee, you can use any debug commands (set breakpoints, continue the program, and so on) like the local debug console.
+When a debuggee program exits, the remote console will also terminate.
 
-NOTE: If you use the `quit` command, only the remote console exits and the debuggee program continues to run (and you can connect it again). If you want to exit the debuggee program, use `kill` command.
+NOTE: If you use the `quit` command, only the remote console exits and the debuggee program continues to run (and you can connect it again).
+If you want to exit the debuggee program, use `kill` command.
 
-If you want to use TCP/IP for the remote debugging, you need to specify the port and host with `--port` like `rdbg --open --port 12345` and it binds to `localhost:12345`.
+If you want to use TCP/IP for remote debugging, you need to specify the port and host with `--port` like `rdbg --open --port 12345` and it binds to `localhost:12345`.
+You can add an optional `--port_range` to try multiple ports in a reliable way.
+For example, `rdbg --open --port 12345 --port_range 10` will try to bind to 12345, 12346, 12347,… until it finds an available port.
 
 To connect to the debuggee, you need to specify the port.
 
-```shell
+```console
 $ rdbg --attach 12345
 ```
 
 If you want to choose the host to bind, you can use `--host` option.
-Note that all messages communicated between the debugger and the debuggee are *NOT* encrypted so please use remote debugging carefully.
+Messages communicated between the debugger and the debuggee are *NOT* encrypted so please use remote debugging carefully.
 
 #### `require 'debug/open'` in a program
 
-If you can modify the program, you can open the debugging port by adding `require 'debug/open'` line in the program.
+If you can modify the program, you can open the debugging port by adding `require 'debug/open'` in the program.
 
 If you don't want to stop the program at the beginning, you can also use `require 'debug/open_nonstop'`.
 Using `debug/open_nonstop` is useful if you want to open a backdoor to the application.
 However, it is also dangerous because it can become another vulnerability.
 Please use it carefully.
 
-By default, UNIX domain socket is used for the debugging port. To use TCP/IP, you can set the `RUBY_DEBUG_PORT` environment variable.
+By default, UNIX domain socket is used for the debugging port.
+To use TCP/IP, you can set the `RUBY_DEBUG_PORT` environment variable.
 
-```shell
+```console
 $ RUBY_DEBUG_PORT=12345 ruby target.rb
 ```
 
@@ -364,9 +380,7 @@ You can attach with external debugger frontend with VSCode and Chrome.
 $ rdbg --open=[frontend] target.rb
 ```
 
-will open a debug port and `[frontend]` can attach to the port.
-
-Also `open` command allows opening the debug port.
+This will open a debug port and the `[frontend]` can attach to the port.
 
 #### VSCode integration
 
@@ -374,9 +388,9 @@ Also `open` command allows opening the debug port.
 
 If you don't run a debuggee Ruby process on VSCode, you can attach it to VSCode later with the following steps.
 
-`rdbg --open=vscode` opens the debug port and tries to invoke the VSCode (`code` command).
+`rdbg --open=vscode` opens the debug port and tries to invoke the VSCode (`code` executable).
 
-```
+```console
 $ rdbg --open=vscode target.rb
 DEBUGGER: Debugger can attach via UNIX domain socket (/tmp/ruby-debug-sock-1000/ruby-debug-ko1-27706)
 DEBUGGER: wait for debugger connection...
@@ -384,11 +398,11 @@ Launching: code /tmp/ruby-debug-vscode-20211014-27706-gd7e85/ /tmp/ruby-debug-vs
 DEBUGGER: Connected.
 ```
 
-And it tries to invoke the new VSCode window and VSCode starts attaching to the debuggee Ruby program automatically.
+It tries to invoke the new VSCode window and VSCode will attach to the debuggee Ruby program automatically.
 
-You can also use `open vscode` command in REPL.
+You can also use `open vscode` in a REPL.
 
-```
+```console
 $ rdbg target.rb
 [1, 8] in target.rb
      1|
@@ -407,9 +421,9 @@ Launching: code /tmp/ruby-debug-vscode-20211014-28337-kg9dm/ /tmp/ruby-debug-vsc
 DEBUGGER: Connected.
 ```
 
-If the machine which runs the Ruby process doesn't have a `code` command, the following message will be shown:
+If the machine which runs the Ruby process doesn't have a `code` executable on `$PATH`, the following message will be shown:
 
-```
+```console
 (rdbg) open vscode
 DEBUGGER: wait for debugger connection...
 DEBUGGER: Debugger can attach via UNIX domain socket (/tmp/ruby-debug-sock-1000/ruby-debug-ko1-455)
@@ -425,15 +439,13 @@ If your application is running on a SSH remote host, please try:
 
 ```
 
-and try to use the proposed commands.
-
 Note that you can attach with `rdbg --attach` and continue REPL debugging.
 
 #### Chrome DevTool integration
 
-With `rdbg --open=chrome` command will show the following message.
+Using `rdbg --open=chrome` will show the following message:
 
-```
+```console
 $ rdbg target.rb --open=chrome
 DEBUGGER: Debugger can attach via TCP/IP (127.0.0.1:43633)
 DEBUGGER: With Chrome browser, type the following URL in the address-bar:
@@ -443,20 +455,25 @@ DEBUGGER: With Chrome browser, type the following URL in the address-bar:
 DEBUGGER: wait for debugger connection...
 ```
 
-Type `devtools://devtools/bundled/inspector.html?v8only=true&panel=sources&ws=127.0.0.1:57231/b32a55cd-2eb5-4c5c-87d8-b3dfc59d80ef` in the address bar on Chrome browser, and you can continue the debugging with chrome browser.
+Type the following in the address bar on Chrome browser, and you can continue the debugging with chrome browser:
+
+```txt
+devtools://devtools/bundled/inspector.html?v8only=true&panel=sources&ws=127.0.0.1:57231/b32a55cd-2eb5-4c5c-87d8-b3dfc59d80ef`
+```
 
-Also `open chrome` command works like `open vscode`.
+Similar to VSCode, you can use `open chrome` to open the debugger in Chrome.
 
-For more information about how to use Chrome debugging, you might want to read [here](https://developer.chrome.com/docs/devtools/).
+For more information about how to use Chrome debugging, [see the devtools docs](https://developer.chrome.com/docs/devtools/).
 
 ## Configuration
 
 You can configure the debugger's behavior with debug commands and environment variables.
-When the debug session is started, initial scripts are loaded so you can put your favorite configurations in the initial scripts.
+When the debug session is started, some [initialization scripts](#initial-scripts) (e.g., `~/.rdbgrc`) are loaded, allowing you to configure the debugger's behavior to your needs and preferences.
 
 ### Configuration list
 
-You can configure the debugger's behavior with environment variables and `config` command. Each configuration has an environment variable and a name which can be specified by `config` command.
+You can configure the debugger's behavior with environment variables and `config` command.
+Each configuration has an environment variable and a name which can be specified by `config` command.
 
 ```
 # configuration example
@@ -469,6 +486,7 @@ config set no_color true
 * UI
   * `RUBY_DEBUG_LOG_LEVEL` (`log_level`): Log level same as Logger (default: WARN)
   * `RUBY_DEBUG_SHOW_SRC_LINES` (`show_src_lines`): Show n lines source code on breakpoint (default: 10)
+  * `RUBY_DEBUG_SHOW_SRC_LINES_FRAME` (`show_src_lines_frame`): Show n lines source code on frame operations (default: 1)
   * `RUBY_DEBUG_SHOW_EVALEDSRC` (`show_evaledsrc`): Show actually evaluated source (default: false)
   * `RUBY_DEBUG_SHOW_FRAMES` (`show_frames`): Show n frames on breakpoint (default: 2)
   * `RUBY_DEBUG_USE_SHORT_PATH` (`use_short_path`): Show shorten PATH (like $(Gem)/foo.rb) (default: false)
@@ -477,6 +495,7 @@ config set no_color true
   * `RUBY_DEBUG_NO_RELINE` (`no_reline`): Do not use Reline library (default: false)
   * `RUBY_DEBUG_NO_HINT` (`no_hint`): Do not show the hint on the REPL (default: false)
   * `RUBY_DEBUG_NO_LINENO` (`no_lineno`): Do not show line numbers (default: false)
+  * `RUBY_DEBUG_NO_REPEAT` (`no_repeat`): Do not repeat last line when empty line (default: false)
   * `RUBY_DEBUG_IRB_CONSOLE` (`irb_console`): Use IRB as the console (default: false)
 
 * CONTROL
@@ -493,12 +512,13 @@ config set no_color true
   * `RUBY_DEBUG_INIT_SCRIPT` (`init_script`): debug command script path loaded at first stop
   * `RUBY_DEBUG_COMMANDS` (`commands`): debug commands invoked at first stop. Commands should be separated by `;;`
   * `RUBY_DEBUG_NO_RC` (`no_rc`): ignore loading ~/.rdbgrc(.rb) (default: false)
-  * `RUBY_DEBUG_HISTORY_FILE` (`history_file`): history file (default: ~/.rdbg_history)
+  * `RUBY_DEBUG_HISTORY_FILE` (`history_file`): history file (default: ${XDG_STATE_HOME-~/.local/state}/rdbg/history)
   * `RUBY_DEBUG_SAVE_HISTORY` (`save_history`): maximum save history lines (default: 10000)
 
 * REMOTE
   * `RUBY_DEBUG_OPEN` (`open`): Open remote port (same as `rdbg --open` option)
   * `RUBY_DEBUG_PORT` (`port`): TCP/IP remote debugging: port
+  * `RUBY_DEBUG_PORT_RANGE` (`port_range`): TCP/IP remote debugging: length of port range
   * `RUBY_DEBUG_HOST` (`host`): TCP/IP remote debugging: host (default: 127.0.0.1)
   * `RUBY_DEBUG_SOCK_PATH` (`sock_path`): UNIX Domain Socket remote debugging: socket path
   * `RUBY_DEBUG_SOCK_DIR` (`sock_dir`): UNIX Domain Socket remote debugging: socket directory
@@ -521,7 +541,7 @@ There are other environment variables:
 
 ### Initial scripts
 
-If there is `~/.rdbgrc`, the file is loaded as an initial script (which contains debug commands) when the debug session is started.
+If there is a `~/.rdbgrc` file it is loaded as an initialization script (which contains debug commands) when the debug session is started.
 
 * `RUBY_DEBUG_INIT_SCRIPT` environment variable can specify the initial script file.
 * You can specify the initial script with `rdbg -x initial_script` (like gdb's `-x` option).
@@ -529,7 +549,7 @@ If there is `~/.rdbgrc`, the file is loaded as an initial script (which contains
 Initial scripts are useful to write your favorite configurations.
 For example, you can set breakpoints with `break file:123` in `~/.rdbgrc`.
 
-If there are `~/.rdbgrc.rb` is available, it is also loaded as a ruby script at same timing.
+If there is a `~/.rdbgrc.rb` file it is also loaded as a Ruby script when the debug session is started.
 
 ## Debug command on the debug console
 
@@ -538,16 +558,19 @@ On the debug console, you can use the following debug commands.
 There are additional features:
 
 * `<expr>` without debug command is almost the same as `pp <expr>`.
-  * If the input line `<expr>` does *NOT* start with any debug command, the line `<expr>` will be evaluated as a Ruby expression, and the result will be printed with `pp` method. So that the input `foo.bar` is the same as `pp foo.bar`.
-  * If `<expr>` is recognized as a debug command, of course, it is not evaluated as a Ruby expression but is executed as debug command. For example, you can not evaluate such single-letter local variables `i`, `b`, `n`, `c` because they are single-letter debug commands. Use `p i` instead.
-  * So the author (Koichi Sasada) recommends using `p`, `pp` or `eval` command to evaluate the Ruby expression every time.
+  * If the input line `<expr>` does *NOT* start with any debug command, the line `<expr>` will be evaluated as a Ruby expression, and the result will be printed with `pp` method.
+    So that the input `foo.bar` is the same as `pp foo.bar`.
+  * If `<expr>` is recognized as a debug command, of course, it is not evaluated as a Ruby expression but is executed as debug command.
+    For example, you can not evaluate such single-letter local variables `i`, `b`, `n`, `c` because they are single-letter debug commands. Use `p i` instead.
+  * For consistency, the author (Koichi Sasada) recommends using the `p`, `pp`, or `eval` command to evaluate the Ruby expression every time.
 * `Enter` without any input repeats the last command (useful when repeating `step`s) for some commands.
 * `Ctrl-D` is equal to `quit` command.
 * [debug command compare sheet - Google Sheets](https://docs.google.com/spreadsheets/d/1TlmmUDsvwK4sSIyoMv-io52BUUz__R5wpu-ComXlsw0/edit?usp=sharing)
 
-You can use the following debug commands. Each command should be written in 1 line.
-The `[...]` notation means this part can be eliminated. For example, `s[tep]` means `s` or `step` is a valid command. `ste` is not valid.
-The `<...>` notation means the argument.
+You can use the following debug commands.
+Each command should be written in 1 line.
+The `[…]` notation means this part can be eliminated. For example, `s[tep]` means `s` or `step` is a valid command. `ste` is not valid.
+The `<…>` notation means the argument.
 
 ### Control flow
 
@@ -797,7 +820,7 @@ To switch to the IRB console, simply use the `irb` command in the debug console.
 
 Once activated, you'll notice the prompt changes to:
 
-```txt
+```console
 irb:rdbg(main):001>
 ```
 
@@ -824,9 +847,12 @@ You can start debugging without `rdbg` command by requiring the following librar
 You need to require one of them at the very beginning of the application.
 Using `ruby -r` (for example `ruby -r debug/start target.rb`) is another way to invoke with debugger.
 
-NOTE: Until Ruby 3.0, there is old `lib/debug.rb` standard library. So that if this gem is not installed, or if `Gemfile` missed to list this gem and `bundle exec` is used, you will see the following output:
+NOTE: Until Ruby 3.0, there is old `lib/debug.rb` in the standard library.
+`lib/debug.rb` was not maintained well in recent years, and the purpose of this library is to rewrite old `lib/debug.rb` with recent techniques.
+
+So, if this gem is not installed, or if the `Gemfile` doesn't include this gem and `bundle exec` is used, you will see the following output:
 
-```shell
+```console
 $ ruby -r debug -e0
 .../2.7.3/lib/ruby/2.7.0/x86_64-linux/continuation.so: warning: callcc is obsolete; use Fiber instead
 Debug.rb
@@ -836,16 +862,15 @@ Emacs support available.
 (rdb:1)
 ```
 
-`lib/debug.rb` was not maintained well in recent years, and the purpose of this library is to rewrite old `lib/debug.rb` with recent techniques.
-
 #### Start by method
 
-After loading `debug/session`, you can start a debug session with the following methods. They are convenient if you want to specify debug configurations in your program.
+After loading `debug/session`, you can start a debug session with the following methods.
+They are convenient if you want to specify debug configurations in your program.
 
 * `DEBUGGER__.start(**kw)`: start debug session with local console.
-* `DEBUGGER__.open(**kw)`: open debug port with configuration (without configurations open with UNIX domain socket)
-* `DEBUGGER__.open_unix(**kw)`: open debug port with UNIX domain socket
-* `DEBUGGER__.open_tcp(**kw)`: open debug port with TCP/IP
+* `DEBUGGER__.open(**kw)`: open debug port with configuration (without configurations open with UNIX domain socket).
+* `DEBUGGER__.open_unix(**kw)`: open debug port with UNIX domain socket.
+* `DEBUGGER__.open_tcp(**kw)`: open debug port with TCP/IP.
 
 For example:
 
@@ -859,24 +884,28 @@ DEBUGGER__.start(no_color: true,    # disable colorize
 
 ### `binding.break` method
 
-`binding.break` (or `binding.b`) set breakpoints at the written line. It also has several keywords.
+`binding.break` (or `binding.b`) sets a breakpoint at that line.
+It also has several keywords.
 
 If `do: 'command'` is specified, the debugger suspends the program, runs the `command` as a debug command, and continues the program.
 It is useful if you only want to call a debug command and don't want to stop there.
+For example:
 
-```
+```ruby
 def initialize
   @a = 1
   binding.b do: 'info \n watch @a'
 end
 ```
 
-In this case, execute the `info` command then register a watch breakpoint for `@a` and continue to run. You can also use `;;` instead of `\n` to separate your commands.
+In this case, execute the `info` command, then register a watch breakpoint for `@a` and continue to run.
+You can also use `;;` instead of `\n` to separate your commands.
 
 If `pre: 'command'` is specified, the debugger suspends the program and runs the `command` as a debug command, and keeps suspended.
 It is useful if you have operations before suspend.
+For example:
 
-```
+```ruby
 def foo
   binding.b pre: 'p bar()'
   ...
@@ -887,7 +916,7 @@ In this case, you can see the result of `bar()` every time you stop there.
 
 ## rdbg command help
 
-```
+```console
 exe/rdbg [options] -- [debuggee options]
 
 Debug console mode:
@@ -907,6 +936,7 @@ Debug console mode:
                                      Now rdbg, vscode and chrome is supported.
         --sock-path=SOCK_PATH        UNIX Domain socket path
         --port=PORT                  Listening TCP/IP port
+        --port-range=PORT_RANGE      Number of ports to try to connect to
         --host=HOST                  Listening TCP/IP host
         --cookie=COOKIE              Set a cookie for connection
         --session-name=NAME          Session name
@@ -955,7 +985,7 @@ NOTE
 
 # Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/debug.
+Bug reports and pull requests are welcome on GitHub at [https://github.com/ruby/debug]().
 This debugger is not mature so your feedback will help us.
 
 Please also check the [contributing guideline](/CONTRIBUTING.md).

data/debug.gemspec

@@ -14,6 +14,7 @@ Gem::Specification.new do |spec|
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/releases/tag/v#{spec.version}"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.