rdoc 7.2.0 → 8.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1acd5d230eb6cc33e92e6ead29ef4edfd11d238750073c151197675b9d2ecef7
-  data.tar.gz: 765310288cb7611ae3990d238a894e9bd1e2d3431c2389c412f0a9407699a4ad
+  metadata.gz: 8bd46d161ae9d2249a6e2ea1afdb46e08cdc737260427c472fe39981d6ea6d00
+  data.tar.gz: 81e455d982e6e564e84058ba420aa59ee9d7792f93de961051d705bada6cd4f0
 SHA512:
-  metadata.gz: b3f79da244c49a5f13485ca9cec594aebd9cbcf9e2a8be2543aa186947ea645aac4ec783f4d3a19b9197ffa7b9e3df53e89dc774adf7ef4c394597c186039a76
-  data.tar.gz: c13a7678b03b25bbe56c854f7314fe50b8df2784d85d04b765294f5fd32baefb92a702e66233007689f1c4a65d7141c6e428af89e5953ce5e19976418e0fd76b
+  metadata.gz: 3a9fb465374b2b6fa07e949c50284394377b48657de07da3a78604f2b646558a4ebe4dc06aaea4e773f185370256971c5563159ab1c0dab6bd5b65cc3e2a94f3
+  data.tar.gz: 99b8a3b9ac9b568a4ab8a23fa3cd5dd6b1385f562d800a54094d533bf153b3696337d217df999f94c88236049a357f3fa655b592cba7106f50829e9d72f4d02f

data/CONTRIBUTING.md

@@ -115,7 +115,6 @@ bundle exec rake verify_generated
 - `lib/rdoc/rd/block_parser.ry` → generates `block_parser.rb` via racc
 - `lib/rdoc/rd/inline_parser.ry` → generates `inline_parser.rb` via racc
 - `lib/rdoc/markdown.kpeg` → generates `markdown.rb` via kpeg
-- `lib/rdoc/markdown/literals.kpeg` → generates `literals.rb` via kpeg
 
 **Important:**
 
@@ -146,7 +145,7 @@ bundle exec rake coverage
 RDoc ships with two HTML themes:
 
 - **Aliki** (default) - Modern theme with improved styling and navigation
-- **Darkfish** (deprecated) - Classic theme, will be removed in v8.0
+- **Darkfish** (deprecated) - Classic theme, will be removed in v9.0
 
 New feature development should focus on the Aliki theme. Darkfish will continue to receive bug fixes but no new features.
 
@@ -160,13 +159,12 @@ lib/rdoc/
 ├── version.rb                 # Version constant
 ├── task.rb                    # Rake task integration
 ├── parser/                    # Source code parsers
-│   ├── ruby.rb                # Ruby code parser
+│   ├── ruby.rb                # Prism-based Ruby parser
 │   ├── c.rb                   # C extension parser
-│   ├── prism_ruby.rb          # Prism-based Ruby parser
 │   └── ...
 ├── generator/                 # Documentation generators
 │   ├── aliki.rb               # HTML generator (default theme)
-│   ├── darkfish.rb            # HTML generator (deprecated, will be removed in v8.0)
+│   ├── darkfish.rb            # HTML generator (deprecated, will be removed in v9.0)
 │   ├── markup.rb              # Markup format generator
 │   ├── ri.rb                  # RI command generator
 │   └── template/              # ERB templates
@@ -177,8 +175,7 @@ lib/rdoc/
 ├── markdown.kpeg              # Parser source (edit this)
 ├── markdown.rb                # Generated parser (do not edit)
 ├── markdown/                  # Markdown parsing
-│   ├── literals.kpeg          # Parser source (edit this)
-│   └── literals.rb            # Generated parser (do not edit)
+│   └── byte_runtime.rb        # Byte-offset parser runtime
 ├── rd/                        # RD format parsing
 │   ├── block_parser.ry        # Parser source (edit this)
 │   ├── block_parser.rb        # Generated parser (do not edit)

data/LICENSE.rdoc

@@ -1,3 +1,7 @@
+:stopdoc:
+SPDX-License-Identifier: Ruby or GPL-2.0-only
+:startdoc:
+
 = License
 
 RDoc is copyrighted free software.

data/README.md

@@ -3,6 +3,10 @@
 - GitHub: [https://github.com/ruby/rdoc](https://github.com/ruby/rdoc)
 - Issues: [https://github.com/ruby/rdoc/issues](https://github.com/ruby/rdoc/issues)
 
+<p align="center" class="rdoc-logo">
+  <img src="rdoc-logo.svg" alt="RDoc" width="168" height="198">
+</p>
+
 ## Description
 
 RDoc produces HTML and command-line documentation for Ruby projects.  RDoc includes the `rdoc` and `ri` tools for generating and displaying documentation from the command-line.
@@ -37,7 +41,9 @@ rdoc --main README.md
 
 You'll find information on the various formatting tricks you can use in comment blocks in the documentation this generates.
 
-RDoc uses file extensions to determine how to process each file.  File names ending `.rb` and `.rbw` are assumed to be Ruby source.  Files ending `.c` are parsed as C files.  All other files are assumed to contain just Markup-style markup (with or without leading `#` comment markers).  If directory names are passed to RDoc, they are scanned recursively for C and Ruby source files only.
+RDoc uses file extensions to determine how to process each file.  File names ending `.rb` and `.rbw` are assumed to be Ruby source.  Files ending `.c` are parsed as C files.  Files ending `.rbs` are parsed as RBS signature files.  All other files are assumed to contain just Markup-style markup (with or without leading `#` comment markers).  If directory names are passed to RDoc, they are scanned recursively for C, Ruby, and RBS source files.
+
+RBS files can document classes, modules, methods, attributes, and constants.  When RBS declarations match objects already documented from Ruby source, their comments and type signatures extend the existing documentation.
 
 To generate documentation using `rake` see [RDoc::Task](https://ruby.github.io/rdoc/RDoc/Task.html).
 
@@ -159,7 +165,7 @@ To determine how well your project is documented run `rdoc -C lib` to get a docu
 RDoc ships with two built-in themes:
 
 - **Aliki** (default) - A modern, clean theme with improved navigation and search
-- **Darkfish** (deprecated) - The classic theme, will be removed in v8.0
+- **Darkfish** (deprecated) - The classic theme, will be removed in v9.0
 
 To use the Darkfish theme instead of the default Aliki theme:
 
@@ -180,6 +186,41 @@ There are also a few community-maintained themes for RDoc:
 
 Please follow the theme's README for usage instructions.
 
+## Live Preview Server
+
+RDoc includes a built-in server for previewing documentation while you edit source files. It parses your code once on startup, then watches for changes and auto-refreshes the browser.
+
+```shell
+rdoc --server
+```
+
+This starts a server at `http://localhost:4000`. You can specify a different port:
+
+```shell
+rdoc --server=8080
+```
+
+Or use the Rake task:
+
+```shell
+rake rdoc:server
+```
+
+### How It Works
+
+- Parses all source files on startup and serves pages from memory using the Aliki theme
+- A background thread polls file mtimes every second
+- When a file changes, only that file is re-parsed — the browser refreshes automatically
+- New files are detected and added; deleted files are removed
+
+**No external dependencies.** The server uses Ruby's built-in `TCPServer` (`socket` stdlib) — no WEBrick or other gems required.
+
+### Limitations
+
+- **Reopened classes and file deletion.** If a class is defined across multiple files (e.g. `Foo` in both `a.rb` and `b.rb`), deleting one file removes the entire class from the store, including parts from the other file. Saving the remaining file triggers a re-parse that restores it.
+- **Full cache invalidation.** Any file change clears all cached pages. This is simple and correct — rendering is fast (~ms per page), parsing is the expensive part and is done incrementally.
+- **No HTTPS or HTTP/2.** The server is intended for local development preview only.
+
 ## Bugs
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for information on filing a bug report.  It's OK to file a bug report for anything you're having a problem with.  If you can't figure out how to make RDoc produce the output you like that is probably a documentation bug.

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

data/doc/markup_reference/markdown.md

@@ -98,7 +98,9 @@ Use triple backticks with an optional language identifier:
     end
     ```
 
-Supported language for syntax highlighting: `ruby`, `rb` (alias to `ruby`), and `c`.
+Supported languages for syntax highlighting: `ruby` (and `rb` alias) with server-side
+highlighting, and `c`, `bash`/`sh`/`shell`/`console` with client-side JavaScript highlighting.
+Other info strings are accepted and added as a CSS class but receive no highlighting.
 
 ### Blockquotes
 
@@ -420,6 +422,9 @@ For example:
 * [Link to Blockquotes](#blockquotes)
 * [Link to Anchor Links](#anchor-links)
 
+When multiple headings produce the same anchor, RDoc appends `-1`, `-2`, etc.
+to subsequent duplicates, matching GitHub's behavior.
+
 ## Footnotes
 
 ### Reference Footnotes
@@ -535,7 +540,7 @@ See [rdoc.rdoc](rdoc.rdoc) for complete directive documentation.
 | Headings | `= Heading` | `# Heading` |
 | Bold | `*word*` | `**word**` |
 | Italic | `_word_` | `*word*` |
-| Monospace | `+word+` | `` `word` `` |
+| Monospace | `+word+` or `` `word` `` | `` `word` `` |
 | Links | `{text}[url]` | `[text](url)` |
 | Code blocks | Indent beyond margin | Indent 4 spaces or fence |
 | Block quotes | `>>>` | `>` |
@@ -551,8 +556,104 @@ See [rdoc.rdoc](rdoc.rdoc) for complete directive documentation.
 
 3. **Footnotes are collapsed** - Multiple paragraphs in a footnote become a single paragraph.
 
-4. **Syntax highlighting** - Only `ruby` and `c` are supported for fenced code blocks.
+4. **Syntax highlighting** - Only `ruby`/`rb` (server-side) and `c`, `bash`/`sh`/`shell`/`console` (client-side) receive syntax highlighting. Other info strings are accepted but not highlighted.
 
 5. **Fenced code blocks** - Only triple backticks are supported. Tilde fences (`~~~`) are not supported as they conflict with strikethrough syntax. Four or more backticks for nesting are also not supported.
 
 6. **Auto-linking** - RDoc automatically links class and method names in output, even without explicit link syntax.
+
+## Comparison with GitHub Flavored Markdown (GFM)
+
+This section compares RDoc's Markdown implementation with the
+[GitHub Flavored Markdown Spec](https://github.github.com/gfm/) (Version 0.29-gfm, 2019-04-06).
+
+### Block Elements
+
+| Feature | GFM | RDoc | Notes |
+|---------|:---:|:----:|-------|
+| ATX Headings (`#`) | ✅ | ✅ | Both support levels 1-6, optional closing `#` |
+| Setext Headings | ✅ | ✅ | `=` for H1, `-` for H2 |
+| Paragraphs | ✅ | ✅ | Full match |
+| Indented Code Blocks | ✅ | ✅ | 4 spaces or 1 tab |
+| Fenced Code (backticks) | ✅ 3+ | ⚠️ 3 only | RDoc doesn't support 4+ backticks for nesting |
+| Fenced Code (tildes) | ✅ `~~~` | ❌ | Conflicts with strikethrough syntax |
+| Info strings (language) | ✅ any | ⚠️ limited | `ruby`/`rb`, `c`, and `bash`/`sh`/`shell`/`console` highlighted; others accepted as CSS class |
+| Blockquotes | ✅ | ✅ | Full match, nested supported |
+| Lazy Continuation | ✅ | ⚠️ | Continuation text is included in blockquote but line break is lost (becomes a space) |
+| Bullet Lists | ✅ | ✅ | `*`, `+`, `-` supported |
+| Ordered Lists | ✅ `.` `)` | ⚠️ `.` only | RDoc doesn't support `)` delimiter; numbers are always renumbered from 1 |
+| Nested Lists | ✅ | ✅ | 4-space indentation |
+| Tables | ✅ | ✅ | Full alignment support |
+| Thematic Breaks | ✅ | ✅ | `---`, `***`, `___` |
+| HTML Blocks | ✅ 7 types | ⚠️ | See below |
+
+#### HTML Blocks
+
+GFM defines 7 types of HTML blocks:
+
+| Type | Description | GFM | RDoc | Notes |
+|------|-------------|:---:|:----:|-------|
+| 1 | `<script>`, `<pre>` | ✅ | ✅ | |
+| 1 | `<style>` | ✅ | ❌ | Available via `css` extension (disabled by default) |
+| 2 | HTML comments `<!-- -->` | ✅ | ✅ | |
+| 3 | Processing instructions `<? ?>` | ✅ | ❌ | |
+| 4 | Declarations `<!DOCTYPE>` | ✅ | ❌ | |
+| 5 | CDATA `<![CDATA[ ]]>` | ✅ | ❌ | |
+| 6 | Block-level tags | ✅ | ⚠️ | |
+| 7 | Any complete open/close tag | ✅ | ❌ | |
+
+RDoc uses a whitelist of block-level tags defined in
+[lib/rdoc/markdown.kpeg](https://github.com/ruby/rdoc/blob/master/lib/rdoc/markdown.kpeg)
+(see `HtmlBlockInTags`). HTML5 semantic elements like `<article>`, `<section>`,
+`<nav>`, `<header>`, `<footer>` are not supported.
+
+### Inline Elements
+
+| Feature | GFM | RDoc | Notes |
+|---------|:---:|:----:|-------|
+| Emphasis `*text*` `_text_` | ✅ | ⚠️ | Intraword emphasis not supported (see [Notes](#notes-and-limitations)) |
+| Strong `**text**` `__text__` | ✅ | ✅ | Full match |
+| Combined `***text***` | ✅ | ✅ | Full match |
+| Code spans | ✅ | ✅ | Multiple backticks supported |
+| Inline links | ✅ | ✅ | Full match |
+| Reference links | ✅ | ✅ | Full match |
+| Link titles | ✅ | ⚠️ | Parsed but not rendered |
+| Images | ✅ | ✅ | Full match |
+| Autolinks `<url>` | ✅ | ✅ | Full match |
+| Hard line breaks | ✅ | ⚠️ | 2+ trailing spaces only; backslash `\` at EOL not supported |
+| Backslash escapes | ✅ | ⚠️ | Subset of GFM's escapable characters (e.g., `~` not escapable) |
+| HTML entities | ✅ | ✅ | Named, decimal, hex |
+| Inline HTML | ✅ | ⚠️ | `<b>` converted to `<strong>`, `<i>` to `<em>`; `<strong>` itself is escaped |
+
+### GFM Extensions
+
+| Feature | GFM | RDoc | Notes |
+|---------|:---:|:----:|-------|
+| Strikethrough `~~text~~` | ✅ | ✅ | Full match |
+| Task Lists `[ ]` `[x]` | ✅ | ❌ | Not supported |
+| Extended Autolinks | ✅ | ⚠️ | See below |
+| Disallowed Raw HTML | ✅ | ❌ | No security filtering |
+
+#### GFM Extended Autolinks
+
+GFM automatically converts certain text patterns into links without requiring
+angle brackets (`<>`). RDoc also auto-links URLs and `www.` prefixes through
+its cross-reference system, but the behavior differs from GFM.
+
+GFM recognizes these patterns:
+
+- `www.example.com` — text starting with `www.` followed by a valid domain
+- `https://example.com` — URLs starting with `http://` or `https://`
+- `user@example.com` — valid email addresses
+
+RDoc auto-links `www.` prefixes and `http://`/`https://` URLs similarly to GFM.
+However, bare email addresses like `user@example.com` are not auto-linked;
+use `<user@example.com>` instead.
+
+### RDoc-Specific Features (not in GFM)
+
+- [Definition Lists](#definition-lists)
+- [Footnotes](#footnotes)
+- [Cross-references](#cross-references)
+- [Anchor Links](#anchor-links)
+- [Directives](#directives)

data/exe/rdoc

@@ -25,11 +25,11 @@ rescue Errno::ENOSPC
 rescue SystemExit
   raise
 rescue Exception => e
-  if $DEBUG_RDOC then
+  if $DEBUG_RDOC
     $stderr.puts e.message
     $stderr.puts "#{e.backtrace.join "\n\t"}"
     $stderr.puts
-  elsif Interrupt === e then
+  elsif Interrupt === e
     $stderr.puts
     $stderr.puts 'Interrupted'
   else