[DOC] Improve formatting in Markdown files (#12322)

* Fix WASM bullet/code indentation

* Use `console` code highlighting where appropriate

… which handles the prefix `$` correctly.

* Migrate feature proposal template to MarkDown

* Set language on code blocks

NEWS.md

@@ -259,21 +259,24 @@ details of the default gems or bundled gems.
     * Other keys now have spaces around `=>`: `'{"user" => 1}'`, while previously they didn't: `'{"user"=>1}'`
 
 * Kernel#Float() now accepts a decimal string with decimal part omitted. [[Feature #20705]]
-  ```
+
+  ```rb
   Float("1.")    #=> 1.0 (previously, an ArgumentError was raised)
   Float("1.E-1") #=> 0.1 (previously, an ArgumentError was raised)
   ```
 
 * String#to_f now accepts a decimal string with decimal part omitted. [[Feature #20705]]
   Note that the result changes when an exponent is specified.
-  ```
+
+  ```rb
   "1.".to_f    #=> 1.0
   "1.E-1".to_f #=> 0.1 (previously, 1.0 was returned)
   ```
 
 * Object#singleton_method now returns methods in modules prepended to or included in the
   receiver's singleton class. [[Bug #20620]]
-  ```
+
+  ```rb
   o = Object.new
   o.extend(Module.new{def a = 1})
   o.singleton_method(:a).call #=> 1
@@ -288,17 +291,17 @@ details of the default gems or bundled gems.
 * Net::HTTP
 
     * Removed the following deprecated constants:
-        `Net::HTTP::ProxyMod`
+        * `Net::HTTP::ProxyMod`
-        `Net::NetPrivate::HTTPRequest`
+        * `Net::NetPrivate::HTTPRequest`
-        `Net::HTTPInformationCode`
+        * `Net::HTTPInformationCode`
-        `Net::HTTPSuccessCode`
+        * `Net::HTTPSuccessCode`
-        `Net::HTTPRedirectionCode`
+        * `Net::HTTPRedirectionCode`
-        `Net::HTTPRetriableCode`
+        * `Net::HTTPRetriableCode`
-        `Net::HTTPClientErrorCode`
+        * `Net::HTTPClientErrorCode`
-        `Net::HTTPFatalErrorCode`
+        * `Net::HTTPFatalErrorCode`
-        `Net::HTTPServerErrorCode`
+        * `Net::HTTPServerErrorCode`
-        `Net::HTTPResponseReceiver`
+        * `Net::HTTPResponseReceiver`
-        `Net::HTTPResponceReceiver`
+        * `Net::HTTPResponceReceiver`
 
       These constants were deprecated from 2012.
 

README.ja.md

@@ -40,11 +40,15 @@ https://www.ruby-lang.org/ja/downloads/
 
 ミラーをGitHubに公開しています． 以下のコマンドでリポジトリを取得できます．
 
-    $ git clone https://github.com/ruby/ruby.git
+```console
+$ git clone https://github.com/ruby/ruby.git
+```
 
 他のブランチの一覧は次のコマンドで見られます．
 
-    $ git ls-remote https://github.com/ruby/ruby.git
+```console
+$ git ls-remote https://github.com/ruby/ruby.git
+```
 
 Rubyリポジトリの本来のmasterは https://git.ruby-lang.org/ruby.git にあります．
 コミッタはこちらを使います．

benchmark/README.md

@@ -27,6 +27,7 @@ benchmark-driver benchmark/*.yml
 See also:
 
 ```console
+benchmark-driver --help
 Usage: benchmark-driver [options] RUBY|YAML...
     -r, --runner TYPE                Specify runner type: ips, time, memory, once, block (default: ips)
     -o, --output TYPE                Specify output type: compare, simple, markdown, record, all (default: compare)

doc/NEWS/NEWS-3.0.0.md

@@ -741,7 +741,7 @@ end
 foo(42)
 ```
 
-```
+```console
 $ typeprof test.rb
 # Classes
 class Object

doc/NEWS/NEWS-3.1.0.md

@@ -552,7 +552,7 @@ Example: `title = json[:article][:title]`
 
 If `json` is nil, it shows:
 
-```
+```console
 $ ruby test.rb
 test.rb:2:in `<main>': undefined method `[]' for nil:NilClass (NoMethodError)
 
@@ -562,7 +562,7 @@ title = json[:article][:title]
 
 If `json[:article]` returns nil, it shows:
 
-```
+```console
 $ ruby test.rb
 test.rb:2:in `<main>': undefined method `[]' for nil:NilClass (NoMethodError)
 

doc/NEWS/NEWS-3.2.0.md

@@ -623,13 +623,13 @@ The following deprecated methods are removed.
     Psych and fiddle supported the static build with specific version of libyaml
     and libffi sources. You can build psych with libyaml-0.2.5 like this.
 
-    ```bash
+    ```console
     $ ./configure --with-libyaml-source-dir=/path/to/libyaml-0.2.5
     ```
 
     And you can build fiddle with libffi-3.4.4 like this.
 
-    ```bash
+    ```console
     $ ./configure --with-libffi-source-dir=/path/to/libffi-3.4.4
     ```
 

doc/command_line/environment.md

@@ -8,7 +8,7 @@ of the invoked Ruby program.
 The examples here use command-line option `-e`,
 which passes the Ruby code to be executed on the command line itself:
 
-```sh
+```console
 $ ruby -e 'puts "Hello, World."'
 ```
 
@@ -18,7 +18,7 @@ The argument to option `-C` specifies a working directory
 for the invoked Ruby program;
 does not change the working directory for the current process:
 
-```sh
+```console
 $ basename `pwd`
 ruby
 $ ruby -C lib -e 'puts File.basename(Dir.pwd)'
@@ -35,7 +35,7 @@ The argument to option `-I` specifies a directory
 to be added to the array in global variable `$LOAD_PATH`;
 the option may be given more than once:
 
-```sh
+```console
 $ pushd /tmp
 $ ruby -e 'p $LOAD_PATH.size'
 8
@@ -54,7 +54,7 @@ The argument to option `-r` specifies a library to be required
 before executing the Ruby program;
 the option may be given more than once:
 
-```sh
+```console
 $ ruby -e 'p defined?(JSON); p defined?(CSV)'
 nil
 nil
@@ -83,10 +83,10 @@ these digits are prefixed with digit `0` to form an octal value:
 
 Examples:
 
-```sh
+```console
 $ ruby -0 -e 'p $/'
 "\x00"
-ruby -00 -e 'p $/'
+$ ruby -00 -e 'p $/'
 ""
 $ ruby -012 -e 'p $/'
 "\n"
@@ -109,7 +109,7 @@ these commonly write to `$stdout` or `$stderr`.
 The default value for `$DEBUG` is `false`;
 option `-d` (or `--debug`) sets it to `true`:
 
-```sh
+```console
 $ ruby -e 'p $DEBUG'
 false
 $ ruby -d -e 'p $DEBUG'
@@ -140,7 +140,7 @@ by setting the initial value of global variable `$-W`:
 The value of `$-W`, in turn, determines which warning messages (if any)
 are to be printed to `$stdout` (see Kernel#warn):
 
-```sh
+```console
 $ ruby -W1 -e 'p $foo'
 nil
 $ ruby -W2 -e 'p $foo'
@@ -151,14 +151,15 @@ nil
 Ruby code may also define warnings for certain categories;
 these are the default settings for the defined categories:
 
-```
+```ruby
 Warning[:experimental] # => true
 Warning[:deprecated]   # => false
 Warning[:performance]  # => false
 ```
 
 They may also be set:
-```
+
+```ruby
 Warning[:experimental] = false
 Warning[:deprecated]   = true
 Warning[:performance]  = true
@@ -166,7 +167,7 @@ Warning[:performance]  = true
 
 You can suppress a category by prefixing `no-` to the category name:
 
-```
+```console
 $ ruby -W:no-experimental -e 'p IO::Buffer.new'
 #<IO::Buffer>
 ```

doc/contributing/building_ruby.md

@@ -32,7 +32,7 @@
     the OS default place, typically using Homebrew on macOS, pass the
     `--with-opt-dir` (or `--with-gmp-dir` for gmp) option to `configure`.
 
-    ``` shell
+    ```sh
     configure --with-opt-dir=$(brew --prefix gmp):$(brew --prefix jemalloc)
     ```
 
@@ -43,7 +43,7 @@
     latter environment variable is not embedded and is only used when
     building the extension libraries.
 
-    ``` shell
+    ```sh
     export CONFIGURE_ARGS=""
     for ext in openssl readline libyaml zlib; do
       CONFIGURE_ARGS="${CONFIGURE_ARGS} --with-$ext-dir=$(brew --prefix $ext)"
@@ -71,7 +71,7 @@
         Download the latest tarball from [Download Ruby] page and extract
         it. Example for Ruby 3.0.2:
 
-        ``` shell
+        ```sh
         tar -xzf ruby-3.0.2.tar.gz
         cd ruby-3.0.2
         ```
@@ -80,20 +80,20 @@
 
         Checkout the CRuby source code:
 
-        ``` shell
+        ```sh
         git clone https://github.com/ruby/ruby.git
         cd ruby
         ```
 
         Generate the configure file:
 
-        ``` shell
+        ```sh
         ./autogen.sh
         ```
 
 2. Create a `build` directory separate from the source directory:
 
-    ``` shell
+    ```sh
     mkdir build && cd build
     ```
 
@@ -102,13 +102,13 @@
 
 3. We'll install Ruby in `~/.rubies/ruby-master`, so create the directory:
 
-    ``` shell
+    ```sh
     mkdir ~/.rubies
     ```
 
 4. Run configure:
 
-    ``` shell
+    ```sh
     ../configure --prefix="${HOME}/.rubies/ruby-master"
     ```
 
@@ -117,7 +117,7 @@
 
 5. Build Ruby:
 
-    ``` shell
+    ```sh
     make
     ```
 
@@ -125,7 +125,7 @@
 
 7. Install Ruby:
 
-    ``` shell
+    ```sh
     make install
     ```
 
@@ -159,7 +159,7 @@ In GNU make[^caution-gmake-3] and BSD make implementations, to run a specific ma
 parallel, pass the flag `-j<number of processes>`. For instance, to run tests
 on 8 processes, use:
 
-``` shell
+```sh
 make test-all -j8
 ```
 
@@ -169,7 +169,7 @@ Having the right `--jobs` flag will ensure all processors are utilized when
 building software projects. To do this effectively, you can set `MAKEFLAGS` in
 your shell configuration/profile:
 
-``` shell
+```sh
 # On macOS with Fish shell:
 export MAKEFLAGS="--jobs "(sysctl -n hw.ncpu)
 
@@ -193,7 +193,7 @@ certain features.  It can be useful in Ruby development because it allows for
 faster build times. Miniruby is built before Ruby. A functional Miniruby is
 required to build Ruby. To build Miniruby:
 
-``` shell
+```sh
 make miniruby
 ```
 
@@ -215,7 +215,7 @@ following make targets:
 You should configure Ruby without optimization and other flags that may
 interfere with debugging:
 
-``` shell
+```sh
 ./configure --enable-debug-env optflags="-O0 -fno-omit-frame-pointer"
 ```
 
@@ -225,7 +225,7 @@ Using the address sanitizer (ASAN) is a great way to detect memory issues. It
 can detect memory safety issues in Ruby itself, and also in any C extensions
 compiled with and loaded into a Ruby compiled with ASAN.
 
-``` shell
+```sh
 ./autogen.sh
 mkdir build && cd build
 ../configure CC=clang-18 cflags="-fsanitize=address -fno-omit-frame-pointer -DUSE_MN_THREADS=0" # and any other options you might like
@@ -239,7 +239,7 @@ two hours on my laptop); the `RUBY_TEST_TIMEOUT_SCALE` and
 `SYNTAX_SUGEST_TIMEOUT` variables are required to make sure tests don't
 spuriously fail with timeouts when in fact they're just slow.
 
-``` shell
+```sh
 RUBY_TEST_TIMEOUT_SCALE=5 SYNTAX_SUGGEST_TIMEOUT=600 make check
 ```
 
@@ -274,7 +274,7 @@ Please note, however, the following caveats!
 
 You need to be able to use gcc (gcov) and lcov visualizer.
 
-``` shell
+```sh
 ./autogen.sh
 ./configure --enable-gcov
 make

doc/contributing/documentation_guide.md

@@ -95,7 +95,7 @@ involving new files `doc/*.rdoc`:
 
     Example:
 
-    ```
+    ```c
     /*
      *  call-seq:
      *    each_byte {|byte| ... } -> self
@@ -173,12 +173,13 @@ Code that is a simple string should include the quote marks.
 Most often, the name of a class, module, or method
 is auto-linked:
 
-```
+```rdoc
 - Float.
 - Enumerable.
 - File.new
 - File#read.
 ```
+
 renders as:
 
 > - Float.
@@ -189,7 +190,7 @@ renders as:
 In general, \RDoc's auto-linking should not be suppressed.
 For example, we should write just plain _Float_ (which is auto-linked):
 
-```
+```rdoc
 Returns a Float.
 ```
 
@@ -200,13 +201,13 @@ which renders as:
 However, _do_ suppress auto-linking when the word in question
 does not refer to a Ruby entity (e.g., some uses of _Class_ or _English_):
 
-```
+```rdoc
 \Class variables can be tricky.
 ```
 
 renders as:
 
-> \\Class variables can be tricky.
+> Class variables can be tricky.
 
 Also, _do_ suppress auto-linking when the word in question
 refers to the current document
@@ -216,7 +217,7 @@ In this case you may consider forcing the name to
 [monofont](rdoc-ref:RDoc::MarkupReference@Monofont),
 which suppresses auto-linking, and also emphasizes that the word is a class name:
 
-```
+```rdoc
 A +Float+ object represents ....
 ```
 
@@ -231,7 +232,7 @@ you might write simply the lowercase _array_.
 
 Instead of:
 
-```
+```rdoc
 For an empty Array, ....
 ```
 
@@ -241,7 +242,7 @@ which renders as:
 
 you might write:
 
-```
+```rdoc
 For an empty array, ....
 ```
 
@@ -398,13 +399,13 @@ the method accepts, so those need to be documented using \RDoc directive
 
 For a singleton method, use the form:
 
-```
+```rdoc
 class_name.method_name(method_args) {|block_args| ... } -> return_type
 ```
 
 Example:
 
-```
+```rdoc
 *  call-seq:
 *    Hash.new(default_value = nil) -> new_hash
 *    Hash.new {|hash, key| ... } -> new_hash
@@ -413,19 +414,20 @@ Example:
 For an instance method, use the form
 (omitting any prefix, just as RDoc does for a Ruby-coded method):
 
-```
+```rdoc
 method_name(method_args) {|block_args| ... } -> return_type
 ```
+
 For example, in Array, use:
 
-```
+```rdoc
 *  call-seq:
 *    count -> integer
 *    count(obj) -> integer
 *    count {|element| ... } -> integer
 ```
 
-```
+```rdoc
 *  call-seq:
 *    <=> other -> -1, 0, 1, or nil
 ```
@@ -433,7 +435,7 @@ For example, in Array, use:
 For a binary-operator style method (e.g., Array#&),
 cite `self` in the call-seq (not, e.g., `array` or `receiver`):
 
-```
+```rdoc
 *  call-seq:
 *    self & other_array -> new_array
 ```
@@ -449,7 +451,7 @@ Arguments:
       or an explicit argument, use a `call-seq` with optional arguments.
       For example, use:
 
-        ```
+        ```rdoc
         *  call-seq:
         *    respond_to?(symbol, include_all = false) -> true or false
         ```
@@ -458,7 +460,7 @@ Arguments:
       use a `call-seq` with separate lines.
       For example, in Enumerable, use:
 
-        ```
+        ```rdoc
         *  call-seq:
         *    max    -> element
         *    max(n) -> array
@@ -472,7 +474,7 @@ Block:
 - If the method accepts a block, but returns an Enumerator when the block is omitted,
   the `call-seq` should show both forms:
 
-    ```
+    ```rdoc
     *  call-seq:
     *    array.select {|element| ... } -> new_array
     *    array.select -> new_enumerator
@@ -505,9 +507,7 @@ an entire paragraph.
 
 For `Array#count`, the synopsis is:
 
-```
+> Returns a count of specified elements.
-Returns a count of specified elements.
-```
 
 This is great as it is short and descriptive.  Avoid documenting
 too much in the synopsis, stick to the most important information
@@ -550,7 +550,7 @@ but return a new Enumerator if the block is not given;
 in that case, do not provide an example,
 but do state the fact (with the auto-linking uppercase Enumerator):
 
-```
+```rdoc
 *  With no block given, returns a new Enumerator.
 ```
 

doc/contributing/making_changes_to_stdlibs.md

@@ -14,7 +14,7 @@ You can find the list of maintainers [here](https://docs.ruby-lang.org/en/master
 
 First, install its dependencies using:
 
-```
+```shell
 bundle install
 ```
 
@@ -22,7 +22,7 @@ bundle install
 
 If the library has a `/ext` directory, it has C files that you need to compile with:
 
-```
+```shell
 bundle exec rake compile
 ```
 
@@ -32,18 +32,18 @@ All standard libraries use [test-unit](https://github.com/test-unit/test-unit) a
 
 To run all tests:
 
-```
+```shell
 bundle exec rake test
 ```
 
 To run a single test file:
 
-```
+```shell
 bundle exec rake test TEST="test/test_foo.rb"
 ```
 
 To run a single test case:
 
-```
+```shell
 bundle exec rake test TEST="test/test_foo.rb" TESTOPS="--name=/test_mytest/"
 ```

doc/contributing/reporting_issues.md

@@ -52,19 +52,30 @@ your feature it could help persuade Ruby core.
 
 Here is a template you can use for a feature proposal:
 
-```
+```markdown
-[Abstract]
+# Abstract
-  Briefly summarize your feature
+
-[Background]
+Briefly summarize your feature
-  Describe current behavior
+
-[Proposal]
+# Background
-  Describe your feature in detail
+
-[Use cases]
+Describe current behavior
-  Give specific example uses of your feature
+
-[Discussion]
+# Proposal
-  Describe why this feature is necessary and better than using existing features
+
-[See also]
+Describe your feature in detail
-  Link to other related resources (such as implementations in other languages)
+
+# Use cases
+
+Give specific example uses of your feature
+
+# Discussion
+
+Describe why this feature is necessary and better than using existing features
+
+# See also
+
+Link to other related resources (such as implementations in other languages)
 ```
 
 ## Backport requests

doc/contributing/testing_ruby.md

@@ -10,38 +10,38 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+
 
     This is a small test suite that runs on Miniruby (see [building Ruby](building_ruby.md#label-Miniruby+vs+Ruby)). We can run it with:
 
-    ```
+    ```sh
     make btest
     ```
 
     To run it with logs, we can use:
 
-    ```
+    ```sh
     make btest OPTS=-v
     ```
 
     To run individual bootstrap tests, we can either specify a list of filenames or use the `--sets` flag in the variable `BTESTS`:
 
-    ```
+    ```sh
-    make btest BTESTS="bootstraptest/test_fork.rb bootstraptest/tes_gc.rb"
+    make btest BTESTS="../bootstraptest/test_fork.rb ../bootstraptest/test_gc.rb"
     make btest BTESTS="--sets=fork,gc"
     ```
 
     If we want to run the bootstrap test suite on Ruby (not Miniruby), we can use:
 
-    ```
+    ```sh
     make test
     ```
 
     To run it with logs, we can use:
 
-    ```
+    ```sh
     make test OPTS=-v
     ```
 
     To run a file or directory with GNU make, we can use:
 
-    ```
+    ```sh
     make test/ruby/test_foo.rb
     make test/ruby/test_foo.rb TESTOPTS="-n /test_bar/"
     ```
@@ -50,44 +50,44 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+
 
     This is a more comprehensive test suite that runs on Ruby. We can run it with:
 
-    ```
+    ```sh
     make test-all
     ```
 
     We can run a specific test directory in this suite using the `TESTS` option, for example:
 
-    ```
+    ```sh
     make test-all TESTS=test/rubygems
     ```
 
     We can run a specific test file in this suite by also using the `TESTS` option, for example:
 
-    ```
+    ```sh
     make test-all TESTS=test/ruby/test_array.rb
     ```
 
     We can run a specific test in this suite using the `TESTS` option, specifying
     first the file name, and then the test name, prefixed with `--name`. For example:
 
-    ```
+    ```sh
     make test-all TESTS="../test/ruby/test_alias.rb --name=TestAlias#test_alias_with_zsuper_method"
     ```
 
     To run these specs with logs, we can use:
 
-    ```
+    ```sh
     make test-all TESTS=-v
     ```
 
     We can display the help of the `TESTS` option:
 
-    ```
+    ```sh
     make test-all TESTS=--help
     ```
 
     If we would like to run the `test/`, `bootstraptest/` and `spec/` test suites (the `spec/` is explained in a later section), we can run
 
-    ```
+    ```sh
     make check
     ```
 
@@ -95,37 +95,37 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+
 
     This is a test suite that exists in [the Ruby spec repository](https://github.com/ruby/spec) and is mirrored into the `spec/ruby` directory in the Ruby repository. It tests the behavior of the Ruby programming language. We can run this using:
 
-    ```
+    ```sh
     make test-spec
     ```
 
     To run a specific directory, we can use `SPECOPTS` to specify the directory:
 
-    ```
+    ```sh
     make test-spec SPECOPTS=spec/ruby/core/array
     ```
 
     To run a specific file, we can also use `SPECOPTS` to specify the file:
 
-    ```
+    ```sh
     make test-spec SPECOPTS=spec/ruby/core/array/any_spec.rb
     ```
 
     To run a specific test, we can use the `--example` flag to match against the test name:
 
-    ```
+    ```sh
     make test-spec SPECOPTS="../spec/ruby/core/array/any_spec.rb --example='is false if the array is empty'"
     ```
 
     To run these specs with logs, we can use:
 
-    ```
+    ```sh
     make test-spec SPECOPTS=-Vfs
     ```
 
     To run a ruby-spec file or directory with GNU make, we can use
 
-    ```
+    ```sh
     make spec/ruby/core/foo/bar_spec.rb
     ```
 
@@ -133,13 +133,13 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+
 
     The bundler test suite exists in [the RubyGems repository](https://github.com/rubygems/rubygems/tree/master/bundler/spec) and is mirrored into the `spec/bundler` directory in the Ruby repository. We can run this using:
 
-    ```
+    ```sh
     make test-bundler
     ```
 
     To run a specific bundler spec file, we can use `BUNDLER_SPECS` as follows:
 
-    ```
+    ```sh
     make test-bundler BUNDLER_SPECS=commands/exec_spec.rb
     ```
 
@@ -149,7 +149,7 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+
 
 If we see failing tests related to the zlib library on s390x CPU architecture, we can run the test suites with `DFLTCC=0` to pass:
 
-```
+```sh
 DFLTCC=0 make check
 ```
 

doc/distribution.md

@@ -19,7 +19,8 @@ See the Snapshots section of the [Ruby website](https://www.ruby-lang.org/en/dow
 This can be useful if the nightly tarball does not have all changes yet.
 
 At Ruby source tree cloned using git:
-```sh-session
+
+```console
 $ ./autogen.sh
 $ ./configure -C
 $ make

doc/exceptions.md

@@ -9,7 +9,7 @@ and may need to be handled.
 Code throughout the Ruby core, Ruby standard library, and Ruby gems generates exceptions
 in certain circumstances:
 
-```
+```rb
 File.open('nope.txt') # Raises Errno::ENOENT: "No such file or directory"
 ```
 
@@ -24,7 +24,7 @@ If an exception not _rescued_
 execution transfers to code in the Ruby interpreter
 that prints a message and exits the program (or thread):
 
-```
+```console
 $ ruby -e "raise"
 -e:1:in `<main>': unhandled exception
 ```
@@ -38,7 +38,7 @@ and may prevent the program from exiting.
 
 A simple example:
 
-```
+```rb
 begin
   raise 'Boom!'                # Raises an exception, transfers control.
   puts 'Will not get here.'
@@ -94,7 +94,7 @@ The rescue clause rescues both the specified class
 (or StandardError if none given) or any of its subclasses;
 see [Built-In Exception Class Hierarchy](rdoc-ref:Exception@Built-In+Exception+Class+Hierarchy).
 
-```
+```rb
 begin
   1 / 0 # Raises ZeroDivisionError, a subclass of StandardError.
 rescue
@@ -113,7 +113,7 @@ only that class (or one of its subclasses) is rescued;
 this example exits with a ZeroDivisionError,
 which was not rescued because it is not ArgumentError or one of its subclasses:
 
-```
+```rb
 begin
   1 / 0
 rescue ArgumentError
@@ -125,7 +125,7 @@ A `rescue` statement may specify multiple classes,
 which means that its code rescues an exception
 of any of the given classes (or their subclasses):
 
-```
+```rb
 begin
   1 / 0
 rescue FloatDomainError, ZeroDivisionError
@@ -139,7 +139,7 @@ An exception handler may contain multiple rescue clauses;
 in that case, the first clause that rescues the exception does so,
 and those before and after are ignored:
 
-```
+```rb
 begin
   Dir.open('nosuch')
 rescue Errno::ENOTDIR
@@ -161,7 +161,7 @@ A `rescue` statement may specify a variable
 whose value becomes the rescued exception
 (an instance of Exception or one of its subclasses:
 
-```
+```rb
 begin
   1 / 0
 rescue => x
@@ -188,7 +188,7 @@ there:
 
 Example:
 
-```
+```rb
 begin
   1 / 0
 rescue
@@ -212,7 +212,7 @@ elsewhere, the method returns `nil`.
 
 Example:
 
-```
+```rb
 begin
   raise('Boom 0')
 rescue => x0
@@ -246,7 +246,7 @@ The `else` clause:
 - Contains code that is to be executed if no exception is raised in the begin clause.
 - Ends with the first following `ensure` or `end` statement.
 
-```
+```rb
 begin
   puts 'Begin.'
 rescue
@@ -273,7 +273,7 @@ The ensure clause:
   and regardless of whether a raised exception is handled.
 - Ends with the first following `end` statement.
 
-```
+```rb
 def foo(boom: false)
   puts 'Begin.'
   raise 'Boom!' if boom
@@ -314,7 +314,7 @@ An exception handler may also be implemented as:
 
 - A method body:
 
-    ```
+    ```rb
     def foo(boom: false) # Serves as beginning of exception handler.
       puts 'Begin.'
       raise 'Boom!' if boom
@@ -327,7 +327,7 @@ An exception handler may also be implemented as:
 
 - A block:
 
-    ```
+    ```rb
     Dir.chdir('.') do |dir| # Serves as beginning of exception handler.
       raise 'Boom!'
     rescue
@@ -349,7 +349,7 @@ a rescuing clause:
   - Calls method `raise` with no argument,
     which raises the rescued exception:
 
-```
+```rb
 begin
   1 / 0
 rescue ZeroDivisionError
@@ -374,7 +374,7 @@ for example, if it must access a possibly-volatile resource
 it can be useful to try the access more than once
 (in the hope that it may become available):
 
-```
+```rb
 retries = 0
 begin
   puts "Try ##{retries}."
@@ -419,7 +419,7 @@ Each should be a subclass of one of the built-in exception classes
 (commonly StandardError or RuntimeError);
 see [Built-In Exception Class Hierarchy](rdoc-ref:Exception@Built-In+Exception+Class+Hierarchy).
 
-```
+```rb
 class MyException < StandardError; end
 ```
 

doc/fiber.md

@@ -6,7 +6,7 @@ Fibers provide a mechanism for cooperative concurrency.
 
 Fibers execute a user-provided block. During the execution, the block may call `Fiber.yield` or `Fiber.transfer` to switch to another fiber. `Fiber#resume` is used to continue execution from the point where `Fiber.yield` was called.
 
-``` ruby
+```rb
 #!/usr/bin/env ruby
 
 puts "1: Start program."
@@ -38,13 +38,13 @@ instrumentation.
 
 To set the scheduler for the current thread:
 
-``` ruby
+```rb
 Fiber.set_scheduler(MyScheduler.new)
 ```
 
 When the thread exits, there is an implicit call to `set_scheduler`:
 
-``` ruby
+```rb
 Fiber.set_scheduler(nil)
 ```
 
@@ -60,7 +60,7 @@ no changes.
 
 This is the interface you need to implement.
 
-``` ruby
+```rb
 class Scheduler
   # Wait for the specified process ID to exit.
   # This hook is optional.
@@ -166,7 +166,7 @@ program.
 
 Fibers can be used to create non-blocking execution contexts.
 
-``` ruby
+```rb
 Fiber.new do
   puts Fiber.current.blocking? # false
 
@@ -184,7 +184,7 @@ end.resume
 We also introduce a new method which simplifies the creation of these
 non-blocking fibers:
 
-``` ruby
+```rb
 Fiber.schedule do
   puts Fiber.current.blocking? # false
 end
@@ -196,7 +196,7 @@ fibers.
 
 You can also create blocking execution contexts:
 
-``` ruby
+```rb
 Fiber.new(blocking: true) do
   # Won't use the scheduler:
   sleep(n)

doc/ractor.md

@@ -259,7 +259,6 @@ r.take      # Receive from r's outgoing port
 The last example shows the following ractor network.
 
 ```
-
   +------+        +---+
   * main |------> * r *---+
   +------+        +---+   |
@@ -875,17 +874,17 @@ p Ractor.select(*rs, Ractor.current) #=> [:receive, "r0r10r9r8r7r6r5r4r3r2r1"]
 r.send "e0"
 p Ractor.select(*rs, Ractor.current)
 #=>
-#<Thread:0x000056262de28bd8 run> terminated with exception (report_on_exception is true):
+# <Thread:0x000056262de28bd8 run> terminated with exception (report_on_exception is true):
-Traceback (most recent call last):
+# Traceback (most recent call last):
-        2: from /home/ko1/src/ruby/trunk/test.rb:7:in `block (2 levels) in <main>'
+#         2: from /home/ko1/src/ruby/trunk/test.rb:7:in `block (2 levels) in <main>'
-        1: from /home/ko1/src/ruby/trunk/test.rb:7:in `loop'
+#         1: from /home/ko1/src/ruby/trunk/test.rb:7:in `loop'
-/home/ko1/src/ruby/trunk/test.rb:9:in `block (3 levels) in <main>': unhandled exception
+# /home/ko1/src/ruby/trunk/test.rb:9:in `block (3 levels) in <main>': unhandled exception
-Traceback (most recent call last):
+# Traceback (most recent call last):
-        2: from /home/ko1/src/ruby/trunk/test.rb:7:in `block (2 levels) in <main>'
+#         2: from /home/ko1/src/ruby/trunk/test.rb:7:in `block (2 levels) in <main>'
-        1: from /home/ko1/src/ruby/trunk/test.rb:7:in `loop'
+#         1: from /home/ko1/src/ruby/trunk/test.rb:7:in `loop'
-/home/ko1/src/ruby/trunk/test.rb:9:in `block (3 levels) in <main>': unhandled exception
+# /home/ko1/src/ruby/trunk/test.rb:9:in `block (3 levels) in <main>': unhandled exception
-        1: from /home/ko1/src/ruby/trunk/test.rb:21:in `<main>'
+#         1: from /home/ko1/src/ruby/trunk/test.rb:21:in `<main>'
-<internal:ractor>:69:in `select': thrown by remote Ractor. (Ractor::RemoteError)
+# <internal:ractor>:69:in `select': thrown by remote Ractor. (Ractor::RemoteError)
 ```
 
 ```ruby

doc/ruby/option_dump.md

@@ -5,7 +5,7 @@ see {Option --dump}[options_md.html#label--dump-3A+Dump+Items].
 
 For the examples here, we use this program:
 
-```sh
+```console
 $ cat t.rb
 puts 'Foo'
 ```
@@ -26,7 +26,7 @@ The supported dump items:
 - `parsetree`: {Abstract syntax tree}[https://en.wikipedia.org/wiki/Abstract_syntax_tree]
   (AST):
 
-    ```sh
+    ```console
     $ ruby --dump=parsetree t.rb
     ###########################################################
     ## Do NOT use this node dump for any purpose other than  ##
@@ -52,7 +52,7 @@ The supported dump items:
 
 - `parsetree_with_comment`: AST with comments:
 
-    ```sh
+    ```console
     $ ruby --dump=parsetree_with_comment t.rb
     ###########################################################
     ## Do NOT use this node dump for any purpose other than  ##
@@ -89,7 +89,7 @@ The supported dump items:
 
 - `yydebug`: Debugging information from yacc parser generator:
 
-    ```sh
+    ```
     $ ruby --dump=yydebug t.rb
     Starting parse
     Entering state 0

doc/ruby/options.md

@@ -5,13 +5,13 @@
 Some examples here use command-line option `-e`,
 which passes the Ruby code to be executed on the command line itself:
 
-```sh
+```console
 $ ruby -e 'puts "Hello, World."'
 ```
 
 Some examples here assume that file `desiderata.txt` exists:
 
-```
+```console
 $ cat desiderata.txt
 Go placidly amid the noise and the haste,
 and remember what peace there may be in silence.
@@ -44,7 +44,7 @@ argument values:
 
 Examples:
 
-```sh
+```console
 $ ruby -0 -e 'p $/'
 "\x00"
 ruby -00 -e 'p $/'
@@ -77,7 +77,7 @@ See also:
 Option `-a`, when given with either of options `-n` or `-p`,
 splits the string at `$_` into an array of strings at `$F`:
 
-```sh
+```console
 $ ruby -an -e 'p $F' desiderata.txt
 ["Go", "placidly", "amid", "the", "noise", "and", "the", "haste,"]
 ["and", "remember", "what", "peace", "there", "may", "be", "in", "silence."]
@@ -107,7 +107,7 @@ See also:
 Option `-c` specifies that the specified Ruby program
 should be checked for syntax, but not actually executed:
 
-```
+```console
 $ ruby -e 'puts "Foo"'
 Foo
 $ ruby -c -e 'puts "Foo"'
@@ -120,7 +120,7 @@ The argument to option `-C` specifies a working directory
 for the invoked Ruby program;
 does not change the working directory for the current process:
 
-```sh
+```console
 $ basename `pwd`
 ruby
 $ ruby -C lib -e 'puts File.basename(Dir.pwd)'
@@ -140,7 +140,7 @@ these commonly write to `$stdout` or `$stderr`.
 The default value for `$DEBUG` is `false`;
 option `-d` sets it to `true`:
 
-```sh
+```console
 $ ruby -e 'p $DEBUG'
 false
 $ ruby -d -e 'p $DEBUG'
@@ -154,7 +154,7 @@ Option `--debug` is an alias for option `-d`.
 Option `-e` requires an argument, which is Ruby code to be executed;
 the option may be given more than once:
 
-```
+```console
 $ ruby -e 'puts "Foo"' -e 'puts "Bar"'
 Foo
 Bar
@@ -170,7 +170,7 @@ but should not include arguments (which, if given, are ignored).
 Option `-E` requires an argument, which specifies either the default external encoding,
 or both the default external and internal encodings for the invoked Ruby program:
 
-```
+```console
 # No option -E.
 $ ruby -e 'p [Encoding::default_external, Encoding::default_internal]'
 [#<Encoding:UTF-8>, nil]
@@ -198,7 +198,7 @@ Option `--encoding` is an alias for option `-E`.
 Option `-F`, when given with option `-a`,
 specifies that its argument is to be the input field separator to be used for splitting:
 
-```sh
+```console
 $ ruby -an -Fs -e 'p $F' desiderata.txt
 ["Go placidly amid the noi", "e and the ha", "te,\n"]
 ["and remember what peace there may be in ", "ilence.\n"]
@@ -208,7 +208,7 @@ $ ruby -an -Fs -e 'p $F' desiderata.txt
 
 The argument may be a regular expression:
 
-```
+```console
 $ ruby -an -F'[.,]\s*' -e 'p $F' desiderata.txt
 ["Go placidly amid the noise and the haste"]
 ["and remember what peace there may be in silence"]
@@ -247,7 +247,7 @@ For a longer help message, use option `--help`.
 Option `-i` sets the \ARGF in-place mode for the invoked Ruby program;
 see ARGF#inplace_mode=:
 
-```
+```console
 $ ruby -e 'p ARGF.inplace_mode'
 nil
 $ ruby -i -e 'p ARGF.inplace_mode'
@@ -262,7 +262,7 @@ The argument to option `-I` specifies a directory
 to be added to the array in global variable `$LOAD_PATH`;
 the option may be given more than once:
 
-```sh
+```console
 $ pushd /tmp
 $ ruby -e 'p $LOAD_PATH.size'
 8
@@ -287,7 +287,7 @@ modifies line-ending processing by:
 
 Without option `-l` (unchopped):
 
-```sh
+```console
 $ ruby -n -e 'p $_' desiderata.txt
 "Go placidly amid the noise and the haste,\n"
 "and remember what peace there may be in silence.\n"
@@ -297,7 +297,7 @@ $ ruby -n -e 'p $_' desiderata.txt
 
 With option `-l' (chopped):
 
-```sh
+```console
 $ ruby -ln -e 'p $_' desiderata.txt
 "Go placidly amid the noise and the haste,"
 "and remember what peace there may be in silence."
@@ -320,9 +320,9 @@ See also:
 
 ### `-n`: Run Program in `gets` Loop
 
-Option `-n` runs your program in a Kernel#gets loop:
+Option `-n` runs your program in a `Kernel#gets` loop:
 
-```
+```ruby
 while gets
   # Your Ruby code.
 end
@@ -331,7 +331,7 @@ end
 Note that `gets` reads the next line and sets global variable `$_`
 to the last read line:
 
-```sh
+```console
 $ ruby -n -e 'puts $_' desiderata.txt
 Go placidly amid the noise and the haste,
 and remember what peace there may be in silence.
@@ -356,7 +356,7 @@ See also:
 
 Option `-p` is like option `-n`, but also prints each line:
 
-```sh
+```console
 $ ruby -p -e 'puts $_.size' desiderata.txt
 42
 Go placidly amid the noise and the haste,
@@ -387,7 +387,7 @@ The argument to option `-r` specifies a library to be required
 before executing the Ruby program;
 the option may be given more than once:
 
-```sh
+```console
 $ ruby -e 'p defined?(JSON); p defined?(CSV)'
 nil
 nil
@@ -413,7 +413,7 @@ in the invoked Ruby program:
 
 More than one custom option may be given:
 
-```
+```console
 $ cat t.rb
 p [$foo, $bar]
 $ ruby t.rb
@@ -439,7 +439,7 @@ the program is executed in the shell's current working directory
 
 This example uses adds path `'tmp/'` to the `PATH` environment variable:
 
-```sh
+```console
 $ export PATH=/tmp:$PATH
 $ echo "puts File.basename(Dir.pwd)" > /tmp/t.rb
 $ ruby -S t.rb
@@ -450,7 +450,7 @@ ruby
 
 Options `-v` prints the Ruby version and sets global variable `$VERBOSE`:
 
-```
+```console
 $ ruby -e 'p $VERBOSE'
 false
 $ ruby -v -e 'p $VERBOSE'
@@ -482,7 +482,7 @@ by setting the initial value of global variable `$-W`:
 The value of `$-W`, in turn, determines which warning messages (if any)
 are to be printed to `$stdout` (see Kernel#warn):
 
-```sh
+```console
 $ ruby -W1 -e 'p $foo'
 nil
 $ ruby -W2 -e 'p $foo'
@@ -493,14 +493,15 @@ nil
 Ruby code may also define warnings for certain categories;
 these are the default settings for the defined categories:
 
-```
+```rb
 Warning[:experimental] # => true
 Warning[:deprecated]   # => false
 Warning[:performance]  # => false
 ```
 
 They may also be set:
-```
+
+```rb
 Warning[:experimental] = false
 Warning[:deprecated]   = true
 Warning[:performance]  = true
@@ -508,7 +509,7 @@ Warning[:performance]  = true
 
 You can suppress a category by prefixing `no-` to the category name:
 
-```
+```console
 $ ruby -W:no-experimental -e 'p IO::Buffer.new'
 #<IO::Buffer>
 ```
@@ -529,7 +530,7 @@ The ruby code:
 
 Example:
 
-```sh
+```console
 $ cat t.txt
 Leading garbage.
 #!ruby
@@ -545,7 +546,7 @@ The optional argument specifies the directory where the text file
 is to be found;
 the Ruby code is executed in that directory:
 
-```sh
+```console
 $ cp t.txt /tmp/
 $ ruby -x/tmp t.txt
 tmp
@@ -567,7 +568,7 @@ See Thread::Backtrace.limit.
 
 Option `--copyright` prints a copyright message:
 
-```sh
+```console
 $ ruby --copyright
 ruby - Copyright (C) 1993-2024 Yukihiro Matsumoto
 ```
@@ -642,7 +643,7 @@ sets the default external encoding for the invoked Ruby program;
 for values of +encoding+,
 see {Encoding: Names and Aliases}[rdoc-ref:encodings.rdoc@Names+and+Aliases].
 
-```sh
+```console
 $ ruby -e 'puts Encoding::default_external'
 UTF-8
 $ ruby --external-encoding=cesu-8 -e 'puts Encoding::default_external'
@@ -664,7 +665,7 @@ sets the default internal encoding for the invoked Ruby program;
 for values of +encoding+,
 see {Encoding: Names and Aliases}[rdoc-ref:encodings.rdoc@Names+and+Aliases].
 
-```sh
+```console
 $ ruby -e 'puts Encoding::default_internal.nil?'
 true
 $ ruby --internal-encoding=cesu-8 -e 'puts Encoding::default_internal'

doc/windows.md

@@ -16,7 +16,7 @@ editor.
 
 Ruby core development can be done either in Windows `cmd` like:
 
-```
+```batch
 ridk enable ucrt64
 
 pacman -S --needed %MINGW_PACKAGE_PREFIX%-openssl %MINGW_PACKAGE_PREFIX%-libyaml %MINGW_PACKAGE_PREFIX%-libffi
@@ -34,7 +34,7 @@ make
 
 or in MSYS2 `bash` like:
 
-```
+```bash
 ridk enable ucrt64
 bash
 
@@ -85,14 +85,14 @@ make
 
     You can use [scoop](https://scoop.sh/) to install them like:
 
-    ```
+    ```batch
     scoop install git sed ruby
     ```
 
 5.  You need to install required libraries using [vcpkg](https://vcpkg.io/) on
     directory of ruby repository like:
 
-    ```
+    ```batch
     vcpkg --triplet x64-windows install
     ```
 
@@ -146,7 +146,7 @@ make
     install directory:      C:\usr\local
     ```
 
-    ```
+    ```batch
     C:
     cd \ruby
     win32\configure --prefix=/usr/local
@@ -163,7 +163,7 @@ make
     install directory:      C:\usr\local
     ```
 
-    ```
+    ```batch
     C:
     cd \ruby
     mkdir mswin32
@@ -182,7 +182,7 @@ make
     install directory:      C:\usr\local
     ```
 
-    ```
+    ```batch
     D:
     cd D:\build\ruby
     C:\src\ruby\win32\configure --prefix=/usr/local
@@ -199,7 +199,7 @@ make
     install directory:      C:\usr\local
     ```
 
-    ```
+    ```batch
     C:
     cd \ruby
     win32\configure --prefix=/usr/local --target=x64-mswin64
@@ -224,7 +224,7 @@ Ruby uses [vcpkg](https://vcpkg.io/) to manage dependencies on mswin platform.
 
 You can update and install it under the build directory like:
 
-```
+```batch
 nmake update-vcpkg # Update baseline version of vcpkg
 nmake install-vcpkg # Install vcpkg from build directory
 ```

doc/yjit/yjit.md

@@ -36,7 +36,7 @@ If you wish to learn more about the approach taken, here are some conference tal
 
 To cite YJIT in your publications, please cite the MPLR 2023 paper:
 
-```
+```BibTeX
 @inproceedings{yjit_mplr_2023,
 author = {Chevalier-Boisvert, Maxime and Kokubun, Takashi and Gibbs, Noah and Wu, Si Xing (Alan) and Patterson, Aaron and Issroff, Jemma},
 title = {Evaluating YJIT’s Performance in a Production Context: A Pragmatic Approach},
@@ -440,7 +440,7 @@ instructions below, but there are a few caveats listed further down.
 
 First, install Rosetta:
 
-```sh
+```console
 $ softwareupdate --install-rosetta
 ```
 
@@ -448,13 +448,13 @@ Now any command can be run with Rosetta via the `arch` command line tool.
 
 Then you can start your shell in an x86 environment:
 
-```sh
+```console
 $ arch -x86_64 zsh
 ```
 
 You can double check your current architecture via the `arch` command:
 
-```sh
+```console
 $ arch -x86_64 zsh
 $ arch
 i386
@@ -462,7 +462,7 @@ i386
 
 You may need to set the default target for `rustc` to x86-64, e.g.
 
-```sh
+```console
 $ rustup default stable-x86_64-apple-darwin
 ```
 

wasm/README.md

@@ -13,50 +13,58 @@
 ### Steps
 
 1. Download a prebuilt WASI SDK package from [WASI SDK release page](https://github.com/WebAssembly/wasi-sdk/releases).
+
 2. Set `WASI_SDK_PATH` environment variable to the root directory of the WASI SDK package.
-```console
+
-$ export WASI_SDK_PATH=/path/to/wasi-sdk-X.Y
+    ```console
-```
+    $ export WASI_SDK_PATH=/path/to/wasi-sdk-X.Y
+    ```
+
 3. Download a prebuilt binaryen from [Binaryen release page](https://github.com/WebAssembly/binaryen/releases)
+
 4. Set PATH environment variable to lookup binaryen tools
-```console
+
-$ export PATH=path/to/binaryen:$PATH
+    ```console
-```
+    $ export PATH=path/to/binaryen:$PATH
-5. Download the latest `config.guess` with WASI support, and run `./autogen.sh` to generate configure when you
+    ```
-   are building from the source checked out from Git repository
+
-```console
+5. Download the latest `config.guess` with WASI support, and run `./autogen.sh` to generate configure when you are building from the source checked out from Git repository
-$ ruby tool/downloader.rb -d tool -e gnu config.guess config.sub
+
-$ ./autogen.sh
+    ```console
-```
+    $ ruby tool/downloader.rb -d tool -e gnu config.guess config.sub
+    $ ./autogen.sh
+    ```
 
 6. Configure
-  - You can select which extensions you want to build.
+    - You can select which extensions you want to build.
-  - If you got `Out of bounds memory access` while running the produced ruby, you may need to increase the maximum size of stack.
+    - If you got `Out of bounds memory access` while running the produced ruby, you may need to increase the maximum size of stack.
-```console
+
-$ ./configure LDFLAGS="-Xlinker -zstack-size=16777216" \
+        ```console
-  --host wasm32-unknown-wasi \
+        $ ./configure LDFLAGS="-Xlinker -zstack-size=16777216" \
-  --with-destdir=./ruby-wasm32-wasi \
+          --host wasm32-unknown-wasi \
-  --with-static-linked-ext \
+          --with-destdir=./ruby-wasm32-wasi \
-  --with-ext=ripper,monitor
+          --with-static-linked-ext \
-```
+          --with-ext=ripper,monitor
+        ```
 
 7. Make
-```console
+
-$ make install
+    ```console
-```
+    $ make install
+    ```
 
 Now you have a WASI compatible ruby binary. You can run it by any WebAssembly runtime like [`wasmtime`](https://github.com/bytecodealliance/wasmtime), [`wasmer`](https://github.com/wasmerio/wasmer), [Node.js](https://nodejs.org/api/wasi.html), or browser with [WASI polyfill](https://www.npmjs.com/package/@wasmer/wasi).
 
 Note: it may take a long time (~20 sec) for the first time for JIT compilation
 
-```
+```console
 $ wasmtime ruby-wasm32-wasi/usr/local/bin/ruby --mapdir /::./ruby-wasm32-wasi/ -- -e 'puts RUBY_PLATFORM'
 wasm32-wasi
 ```
 
 Note: you cannot run the built ruby without a WebAssembly runtime, because of the difference of the binary file type.
 
-```
+```console
 $ ruby-wasm32-wasi/usr/local/bin/ruby -e 'puts "a"'
 bash: ruby-wasm32-wasi/usr/local/bin/ruby: cannot execute binary file: Exec format error