rdoc 6.17.0 → 8.1.0

data/RI.md

@@ -1,7 +1,7 @@
 # `ri`: Ruby Information
 
-`ri` (<b>r</b>uby <b>i</b>nformation) is the Ruby command-line utility
-that gives fast and easy on-line access to Ruby documentation.
+`ri` (<b>r</b>uby <b>i</b>nformation) is a Ruby command-line utility
+that gives fast and easy online access to Ruby documentation.
 
 `ri` can show documentation for Ruby itself and for its installed gems:
 
@@ -45,10 +45,10 @@ the [Ruby online documentation](https://docs.ruby-lang.org/en/master):
 
 - The `ri` documentation is always available, even when you do not have internet access
   (think: airplane mode).
-- If you are working in a terminal window, typing `ri _whatever_` (or just `ri`)
+- If you are working in a terminal window, typing `ri <whatever>` (or just `ri`)
   may be faster than navigating to a browser window and searching for documentation.
 - If you are working in an
-  [irb \(interactive Ruby\)](https://ruby.github.io/irb/index.html)
+  [IRB \(Interactive Ruby\)][9]
   session, you _already_ have immediate access to `ri`:
   just type `'show_doc'`.
 
@@ -82,7 +82,7 @@ In both modes, static and interactive,
 `ri` responds to an input _name_ that specifies what is to be displayed:
 a document, multiple documents, or other information:
 
-- Static mode (in the shell): type `'ri _name_'`;
+- Static mode (in the shell): run `ri <name>`;
   examples (output omitted):
 
     ```sh
@@ -109,17 +109,17 @@ a document, multiple documents, or other information:
 These example `ri` commands cite names for class and module documents
 (see [details and examples][3]):
 
-| Command                      | Shows                                                      |
-|------------------------------|------------------------------------------------------------|
-| ri File                      | Document for Ruby class File.                              |
-| ri File::Stat                | Document for Ruby nested class File::Stat.                 |
-| ri Enumerable                | Document for Ruby module Enumerable.                       |
-| ri Arr                       | Document for Ruby class Array (unique initial characters). |
-| ri Nokogiri::HTML4::Document | Document for gem class Nokogiri::HTML4::Document.          |
-| ri Nokogiri                  | Document for gem module Nokogiri.                          |
+| Command                        | Shows                                                        |
+|--------------------------------|--------------------------------------------------------------|
+| `ri File`                      | Document for Ruby class `File`.                              |
+| `ri File::Stat`                | Document for Ruby nested class `File::Stat`.                 |
+| `ri Enumerable`                | Document for Ruby module `Enumerable`.                       |
+| `ri Arr`                       | Document for Ruby class `Array` (unique initial characters). |
+| `ri Nokogiri::HTML4::Document` | Document for gem class `Nokogiri::HTML4::Document`.          |
+| `ri Nokogiri`                  | Document for gem module `Nokogiri`.                          |
 <br>
 
-If [option \\--all][4]
+If [option `--all`][4]
 is in effect, documents for the methods in the named class or module
 are included in the display.
 
@@ -128,16 +128,16 @@ are included in the display.
 These example `ri` commands cite names for method documents
 (see [details and examples][5]):
 
-| Command                              | Shows                                                                            |
-|--------------------------------------|----------------------------------------------------------------------------------|
-| ri IO::readlines                     | Document for Ruby class method IO::readlines.                                    |
-| ri IO#readlines                      | Document for Ruby instance method IO::readlines.                                 |
-| ri IO.readlines                      | Documents for Ruby instance method IO::readlines and class method IO::readlines. |
-| ri ::readlines                       | Documents for all class methods ::readlines.                                     |
-| ri #readlines                        | Documents for all instance methods #readlines.                                   |
-| ri .readlines, ri readlines          | Documents for class methods ::readlines and instance methods #readlines.         |
-| ri Nokogiri::HTML4::Document::parse  | Document for gem class method Nokogiri::HTML4::Document::parse.                  |
-| ri Nokogiri::HTML4::Document#fragment | Document for gem instance method Nokogiri::HTML4::Document#fragment.            |
+| Command                                 | Shows                                                                                |
+|-----------------------------------------|--------------------------------------------------------------------------------------|
+| `ri IO::readlines`                      | Document for Ruby class method `IO::readlines`.                                      |
+| `ri IO#readlines`                       | Document for Ruby instance method `IO#readlines`.                                    |
+| `ri IO.readlines`                       | Documents for Ruby class method `IO::readlines` and instance method `IO#readlines`.  |
+| `ri ::readlines`                        | Documents for all class methods `::readlines`.                                       |
+| `ri #readlines`                         | Documents for all instance methods `#readlines`.                                     |
+| `ri .readlines`, `ri readlines`         | Documents for all class methods `::readlines` and all instance methods `#readlines`. |
+| `ri Nokogiri::HTML4::Document::parse`   | Document for gem class method `Nokogiri::HTML4::Document::parse`.                    |
+| `ri Nokogiri::HTML4::Document#fragment` | Document for gem instance method `Nokogiri::HTML4::Document#fragment`.               |
 <br>
 
 ### Names for Page Documents
@@ -145,12 +145,12 @@ These example `ri` commands cite names for method documents
 These example `ri` commands cite names for page documents
 (see [details and examples][6]):
 
-| Command                        | Shows                                            |
-|--------------------------------|--------------------------------------------------|
-| ri ruby:syntax/assignment.rdoc | Document for Ruby page assignment.               |
-| ri ruby:syntax/assignment      | Same document, if no other syntax/assignment.*.  |
-| ri ruby:assignment             | Same document, if no other */assignment.*.       |
-| ri nokogiri:README.md          | Document for page README.md.                     |
+| Command                          | Shows                                              |
+|----------------------------------|----------------------------------------------------|
+| `ri ruby:syntax/assignment.rdoc` | Document for Ruby page "assignment".               |
+| `ri ruby:syntax/assignment`      | Same document, if no other "syntax/assignment.\*". |
+| `ri ruby:assignment`             | Same document, if no other "\*/assignment.\*".     |
+| `ri nokogiri:README.md`          | Document for page "README.md".                     |
 <br>
 
 ### Names for Lists
@@ -158,14 +158,14 @@ These example `ri` commands cite names for page documents
 These example `ri` commands cite names for lists
 (see [details and examples][7]):
 
-| Command       | Shows                   |
-|---------------|-------------------------|
-| ri ruby:      | List of Ruby pages.     |
-| ri nokogiri:  | List of Nokogiri pages. |
+| Command        | Shows                   |
+|----------------|-------------------------|
+| `ri ruby:`     | List of Ruby pages.     |
+| `ri nokogiri:` | List of Nokogiri pages. |
 <br>
 
 There are more lists available;
-see [option \\--list][8].
+see [option `--list`][8].
 
 ## Pro Tips
 
@@ -175,8 +175,8 @@ If you are a frequent `ri` user,
 you can save time by keeping open a dedicated command window
 with either of:
 
-- A running [interactive ri][2] session.
-- A running [irb session][9];
+- A running [interactive `ri`][2] session.
+- A running [`irb` session][9];
   type `'show_doc'` to enter `ri`, newline to exit.
 
 When you switch to that window, `ri` is ready to respond quickly,
@@ -199,7 +199,7 @@ $ RI_PAGER="grep . | less" ri Array
 ```
 
 See the documentation for your chosen pager programs
-(e.g, type `'grep --help'`, `'less --help'`).
+(e.g, run `grep --help`, `less --help`).
 
 ### Links  in `ri` Output
 
@@ -254,10 +254,10 @@ When you see:
 - `ri` output can be large;
   to save space, an example may pipe it to one of these:
 
-    - [head](https://www.man7.org/linux/man-pages/man1/head.1.html): leading lines only.
-    - [tail](https://www.man7.org/linux/man-pages/man1/tail.1.html): trailing lines only.
-    - [wc -l](https://www.man7.org/linux/man-pages/man1/wc.1.html): line count only.
-    - [grep](https://www.man7.org/linux/man-pages/man1/grep.1.html): selected lines only.
+    - [`head`](https://www.man7.org/linux/man-pages/man1/head.1.html): leading lines only.
+    - [`tail`](https://www.man7.org/linux/man-pages/man1/tail.1.html): trailing lines only.
+    - [`wc -l`](https://www.man7.org/linux/man-pages/man1/wc.1.html): line count only.
+    - [`grep`](https://www.man7.org/linux/man-pages/man1/grep.1.html): selected lines only.
 
 - An example that involves a gem assumes that gems `nokogiri` and `minitest` are installed.
 
@@ -268,15 +268,15 @@ in the `ri` document for a class, module, method, or page.
 
 See also:
 
-- [Pager][10].
-- [Links in ri Output][11].
+- [Pager][10]
+- [Links in `ri` Output][11]
 
 ### Class and Module Documents
 
 The document for a class or module shows:
 
-- The class or module name, along with its parent class if any.
-- Where it's defined (Ruby core or gem).
+- The class or module name, along with its parent class, if any.
+- Where it's defined (Ruby core or a gem).
 - When each exists:
 
     - The names of its included modules.
@@ -335,7 +335,7 @@ $ ri IO | grep "^= "
 
 The document for a method includes:
 
-- The source of the method: `'(from ruby core)'` or `'(from gem _gem_)'`.
+- The source of the method: `'(from ruby core)'` or `'(from gem <gem>)'`.
 - The calling sequence(s) for the method.
 - The text of its embedded documentation (if it exists).
 
@@ -374,7 +374,7 @@ the number of such implementations depends on the _name_:
 - Within a class:
 
     Each of these commands shows documents
-    for methods in Ruby class `IO` (output omitted):
+    for methods in the Ruby class `IO` (output omitted):
 
     ```sh
     $ ri IO::readlines # Class method ::readlines.
@@ -467,7 +467,7 @@ rdoc:
 
 ## `ri` Lists
 
-The list of Ruby pages is available via _name_ `'ruby:'`:
+The list of Ruby pages is available via the _name_ `'ruby:'`:
 
 ```sh
 $ ri ruby: | head
@@ -497,7 +497,7 @@ syntax/refinements.rdoc
 win32/README.win32
 ```
 
-The list of gem pages is available via _name_ `'_gem_name_'`:
+The list of gem pages is available via the _name_ `'<gem_name>:'`:
 
 ```sh
 $ ri nokogiri: | head
@@ -509,9 +509,9 @@ lib/nokogiri/css/tokenizer.rex
 
 See also:
 
-- [Option \\--list][8]:
+- [Option `--list`][8]:
   lists classes and modules.
-- [Option \\--list-doc-dirs][12]:
+- [Option `--list-doc-dirs`][12]:
   lists `ri` source directories.
 
 ## `ri` Information
@@ -519,12 +519,12 @@ See also:
 With certain options,
 an `ri` command may display information other than documents or lists:
 
-- [Option \\--help or -h][13]:
+- [Option `--help` or `-h`][13]:
   Shows `ri` help text.
-- [option \\--version or -v][14]:
+- [Option `--version` or `-v`][14]:
   Shows `ri` version.
-- [Option \\--dump=FILEPATH][15]:
-  Shows dump of `ri` cache file at the given filepath.
+- [Option `--dump=FILEPATH`][15]:
+  Shows a dump of `ri` cache file at the given filepath.
 
 ## Static Mode
 
@@ -549,7 +549,7 @@ elements.  Any object may be an Array element.
 
 `ri` also responds in static mode when certain options are given,
 even when no _name_ is given;
-see [ri Information][16].
+see [`ri` Information][16].
 
 ## Interactive Mode
 
@@ -565,18 +565,18 @@ Enter a blank line to exit.
 
 ```
 
-A command in interactive mode are similar to one in static mode,
+A command in interactive mode is similar to one in static mode,
 except that it:
 
-- Omits command word `ri`; you just type the _name_.
+- Omits the command word `ri`; you just type the _name_.
 - Omits options; in interactive mode the only options in effect
   are those taken from environment variable `RI`.
   See [Options][17].
 - Supports tab auto-completion for the name of a class, module, or method;
-  when, for example, you type `"Arr\t"` (here `"\t` represents the tab character),
+  when, for example, you type `"Arr\t"` (here `\t` represents the tab character),
   `ri` "completes" the text as `'Array '`.
 
-See also [ri at the Ready][18].
+See also [`ri` at the Ready][18].
 
 ## Pager
 
@@ -592,7 +592,7 @@ which is the program whose name is the first-found among:
 
 If none is found, the output goes directly to `$stdout`, with no pager.
 
-If you set environment variable `RI_PAGER` or `PAGER`,
+If you set the environment variable `RI_PAGER` or `PAGER`,
 its value should be the name of an executable program
 that will accept the `ri` output (such as `'pager'`, `'less'`, or `'more'`).
 
@@ -601,9 +601,9 @@ See also [Output Filters][19].
 ## Options
 
 Options may be given on the `ri` command line;
-those should be whitespace-separated, and must precede the given _name_, if any.
+those should be whitespace-separated and must precede the given _name_, if any.
 
-Options may also be specified in environment variable `RI`;
+Options may also be specified in the environment variable `RI`;
 those should also be whitespace-separated.
 
 An option specified in environment variable `RI`
@@ -643,21 +643,21 @@ $ ri --list --no-gems| wc -l
 
 #### Options `--home`, `--no-home`
 
-Option `--home` (the default) specifies that `ri` is to include source directory
+Option `--home` (the default) specifies that `ri` is to include the source directory
 in `~/.rdoc` if it exists;
-option `--no-home` may be used to exclude them.
+option `--no-home` may be used to exclude it.
 
 #### Options `--list-doc-dirs`, `--no-list-doc-dirs`
 
 Option `--list-doc-dirs` specifies that a list of the `ri` source directories
 is to be displayed;
-default is `--no-list-doc-dirs`.
+the default is `--no-list-doc-dirs`.
 
 #### Option `--no-standard`
 
 Option `--no-standard` specifies that documents from the standard libraries
 are not to be included;
-default is to include documents from the standard libraries.
+the default is to include documents from the standard libraries.
 
 #### Options `--site`, `--no-site`
 
@@ -680,7 +680,7 @@ specifies that `ri` is to enter interactive mode (ignoring the _name_ if given);
 the option is the default when no _name_ is given;
 option `--no-interactive` (the default)
 specifies that `ri` is not to enter interactive mode,
-regardless of whether _name_ is given.
+regardless of whether a _name_ is given.
 
 ### Information Options
 
@@ -785,7 +785,7 @@ is not to be displayed.
 
 #### Options `--all`, `-a`, `--no-all`
 
-Option `--all` (aliased as `-a`) specifies that when _name_ identifies a class or module,
+Option `--all` (aliased as `-a`) specifies that when a _name_ identifies a class or module,
 the documents for all its methods are included;
 option `--no-all` (the default) specifies that the method documents are not to be included:
 
@@ -809,16 +809,16 @@ the default port is `8214`.
 `ri` by default reads data from directories installed by Ruby and gems.
 
 You can create your own `ri` source files.
-This command creates `ri` source files in local directory `my_ri`,
-from Ruby source files in local directory `my_sources`:
+This command creates `ri` source files in the local directory `my_ri`,
+from Ruby source files in the local directory `my_sources`:
 
 ```sh
 $ rdoc --op my_ri --format=ri my_sources
 ```
 
 Those files may then be considered for any `ri` command
-by specifying option `--doc-dir=my_ri`;
-see [option \\--doc-dir][20].
+by specifying the option `--doc-dir=my_ri`;
+see [option `--doc-dir`][20].
 
 [1]: rdoc-ref:RI.md@Static+Mode
 [2]: rdoc-ref:RI.md@Interactive+Mode
@@ -828,7 +828,7 @@ see [option \\--doc-dir][20].
 [6]: rdoc-ref:RI.md@Page+Documents
 [7]: rdoc-ref:RI.md@ri+Lists
 [8]: rdoc-ref:RI.md@Options+--list-2C+-l-2C+--no-list
-[9]: https://docs.ruby-lang.org/en/master/IRB.html
+[9]: https://ruby.github.io/irb/
 [10]: rdoc-ref:RI.md@Pager
 [11]: rdoc-ref:RI.md@Links+in+ri+Output
 [12]: rdoc-ref:RI.md@Options+--list-doc-dirs-2C+--no-list-doc-dirs