rdoc 7.0.2 → 7.1.0

data/lib/rdoc/markup/heading.rb

@@ -1,84 +1,173 @@
 # frozen_string_literal: true
-##
-# A heading with a level (1-6) and text
 
-RDoc::Markup::Heading =
-  Struct.new :level, :text do
-
-  @to_html = nil
-  @to_label = nil
-
-  ##
-  # A singleton RDoc::Markup::ToLabel formatter for headings.
-
-  def self.to_label
-    @to_label ||= RDoc::Markup::ToLabel.new
-  end
-
-  ##
-  # A singleton plain HTML formatter for headings.  Used for creating labels
-  # for the Table of Contents
-
-  def self.to_html
-    return @to_html if @to_html
-
-    markup = RDoc::Markup.new
-    markup.add_regexp_handling RDoc::CrossReference::CROSSREF_REGEXP, :CROSSREF
-
-    @to_html = RDoc::Markup::ToHtml.new nil
-
-    def @to_html.handle_regexp_CROSSREF(target)
-      target.text.sub(/^\\/, '')
+module RDoc
+  class Markup
+    # IMPORTANT! This weird workaround is required to ensure that RDoc can correctly deserializing Marshal data from
+    # older rubies. Older rubies have `Heading` as a struct, so if we change it to a class, deserialization fails
+    if RUBY_VERSION.start_with?("4.")
+      class Heading < Element
+        #: String
+        attr_reader :text
+
+        #: Integer
+        attr_accessor :level
+
+        #: (Integer, String) -> void
+        def initialize(level, text)
+          super()
+
+          @level = level
+          @text = text
+        end
+
+        #: (Object) -> bool
+        def ==(other)
+          other.is_a?(Heading) && other.level == @level && other.text == @text
+        end
+      end
+    else
+      Heading = Struct.new(:level, :text)
     end
 
-    @to_html
-  end
-
-  ##
-  # Calls #accept_heading on +visitor+
-
-  def accept(visitor)
-    visitor.accept_heading self
-  end
-
-  ##
-  # An HTML-safe anchor reference for this header.
-
-  def aref
-    "label-#{self.class.to_label.convert text.dup}"
-  end
-
-  ##
-  # Creates a fully-qualified label which will include the label from
-  # +context+.  This helps keep ids unique in HTML.
-
-  def label(context = nil)
-    label = aref
-
-    label = [context.aref, label].compact.join '-' if
-      context and context.respond_to? :aref
-
-    label
-  end
-
-  ##
-  # HTML markup of the text of this label without the surrounding header
-  # element.
-
-  def plain_html
-    text = self.text.dup
-
-    if matched = text.match(/rdoc-image:[^:]+:(.*)/)
-      text = matched[1]
+    # A heading with a level (1-6) and text
+    #
+    #  RDoc syntax:
+    #   = Heading 1
+    #   == Heading 2
+    #   === Heading 3
+    #
+    #  Markdown syntax:
+    #   # Heading 1
+    #   ## Heading 2
+    #   ### Heading 3
+    #
+    class Heading
+      # A singleton RDoc::Markup::ToLabel formatter for headings.
+      #: () -> RDoc::Markup::ToLabel
+      def self.to_label
+        @to_label ||= Markup::ToLabel.new
+      end
+
+      # A singleton plain HTML formatter for headings. Used for creating labels for the Table of Contents
+      #: () -> RDoc::Markup::ToHtml
+      def self.to_html
+        @to_html ||= begin
+          markup = Markup.new
+          markup.add_regexp_handling CrossReference::CROSSREF_REGEXP, :CROSSREF
+
+          to_html = Markup::ToHtml.new nil
+
+          def to_html.handle_regexp_CROSSREF(target)
+            target.text.sub(/^\\/, '')
+          end
+
+          to_html
+        end
+      end
+
+      # @override
+      #: (untyped) -> void
+      def accept(visitor)
+        visitor.accept_heading(self)
+      end
+
+      # An HTML-safe anchor reference for this header using GitHub-style formatting:
+      # - Lowercase
+      # - Spaces converted to hyphens
+      # - Special characters removed (except hyphens)
+      #
+      # Examples:
+      #   "Hello"       -> "hello"
+      #   "Hello World" -> "hello-world"
+      #   "Foo Bar Baz" -> "foo-bar-baz"
+      #
+      #: () -> String
+      def aref
+        self.class.to_label.convert text.dup
+      end
+
+      # An HTML-safe anchor reference using legacy RDoc formatting:
+      # - Prefixed with "label-"
+      # - Original case preserved
+      # - Spaces converted to + (URL encoding style)
+      # - Special characters percent-encoded
+      #
+      # Returns nil if it would be the same as the GitHub-style aref (no alias needed).
+      #
+      # Examples:
+      #   "hello"       -> "label-hello" (different due to label- prefix)
+      #   "Hello"       -> "label-Hello"
+      #   "Hello World" -> "label-Hello+World"
+      #   "Foo Bar Baz" -> "label-Foo+Bar+Baz"
+      #
+      #: () -> String?
+      def legacy_aref
+        "label-#{self.class.to_label.convert_legacy text.dup}"
+      end
+
+      # Creates a fully-qualified label (GitHub-style) which includes the context's aref prefix.
+      # This helps keep IDs unique in HTML when headings appear within class/method documentation.
+      #
+      # Examples (without context):
+      #   "Hello World" -> "hello-world"
+      #
+      # Examples (with context being class Foo):
+      #   "Hello World" -> "class-foo-hello-world"
+      #
+      # Examples (with context being method #bar):
+      #   "Hello World" -> "method-i-bar-hello-world"
+      #
+      #: (RDoc::Context?) -> String
+      def label(context = nil)
+        result = +""
+        result << "#{context.aref}-" if context&.respond_to?(:aref)
+        result << aref
+        result
+      end
+
+      # Creates a fully-qualified legacy label for backward compatibility.
+      # This is used to generate a secondary ID attribute on the heading's inner anchor,
+      # allowing old-style links (e.g., #label-Hello+World) to continue working.
+      #
+      # Examples (without context):
+      #   "hello"       -> "label-hello"
+      #   "Hello World" -> "label-Hello+World"
+      #
+      # Examples (with context being class Foo):
+      #   "hello"       -> "class-Foo-label-hello"
+      #   "Hello World" -> "class-Foo-label-Hello+World"
+      #
+      #: (RDoc::Context?) -> String
+      def legacy_label(context = nil)
+        result = +""
+        if context&.respond_to?(:legacy_aref)
+          result << "#{context.legacy_aref}-"
+        elsif context&.respond_to?(:aref)
+          result << "#{context.aref}-"
+        end
+        result << legacy_aref
+        result
+      end
+
+      # HTML markup of the text of this label without the surrounding header element.
+      #: () -> String
+      def plain_html
+        no_image_text = text
+
+        if matched = no_image_text.match(/rdoc-image:[^:]+:(.*)/)
+          no_image_text = matched[1]
+        end
+
+        self.class.to_html.to_html(no_image_text)
+      end
+
+      # @override
+      #: (PP) -> void
+      def pretty_print(q)
+        q.group 2, "[head: #{level} ", ']' do
+          q.pp text
+        end
+      end
     end
-
-    self.class.to_html.to_html(text)
   end
-
-  def pretty_print(q) # :nodoc:
-    q.group 2, "[head: #{level} ", ']' do
-      q.pp text
-    end
-  end
-
 end

data/lib/rdoc/markup/raw.rb

@@ -1,69 +1,66 @@
 # frozen_string_literal: true
-##
-# A section of text that is added to the output document as-is
 
-class RDoc::Markup::Raw
-
-  ##
-  # The component parts of the list
-
-  attr_reader :parts
-
-  ##
-  # Creates a new Raw containing +parts+
-
-  def initialize *parts
-    @parts = []
-    @parts.concat parts
-  end
-
-  ##
-  # Appends +text+
+module RDoc
+  class Markup
+    # A section of text that is added to the output document as-is
+    class Raw
+      # The component parts of the list
+      #: Array[String]
+      attr_reader :parts
+
+      # Creates a new Raw containing +parts+
+      #: (*String) -> void
+      def initialize(*parts)
+        @parts = parts
+      end
 
-  def <<(text)
-    @parts << text
-  end
+      # Appends +text+
+      #: (String) -> void
+      def <<(text)
+        @parts << text
+      end
 
-  def ==(other) # :nodoc:
-    self.class == other.class and @parts == other.parts
-  end
+      #: (top) -> bool
+      def ==(other) # :nodoc:
+        self.class == other.class && @parts == other.parts
+      end
 
-  ##
-  # Calls #accept_raw+ on +visitor+
+      # Calls #accept_raw+ on +visitor+
+      # @override
+      #: (untyped) -> void
+      def accept(visitor)
+        visitor.accept_raw(self)
+      end
 
-  def accept(visitor)
-    visitor.accept_raw self
-  end
+      # Appends +other+'s parts
+      #: (Raw) -> void
+      def merge(other)
+        @parts.concat(other.parts)
+      end
 
-  ##
-  # Appends +other+'s parts
+      # @override
+      #: (PP) -> void
+      def pretty_print(q) # :nodoc:
+        self.class.name =~ /.*::(\w{1,4})/i
 
-  def merge(other)
-    @parts.concat other.parts
-  end
+        q.group(2, "[#{$1.downcase}: ", ']') do
+          q.seplist(@parts) do |part|
+            q.pp(part)
+          end
+        end
+      end
 
-  def pretty_print(q) # :nodoc:
-    self.class.name =~ /.*::(\w{1,4})/i
+      # Appends +texts+ onto this Paragraph
+      #: (*String) -> void
+      def push(*texts)
+        self.parts.concat(texts)
+      end
 
-    q.group 2, "[#{$1.downcase}: ", ']' do
-      q.seplist @parts do |part|
-        q.pp part
+      # The raw text
+      #: () -> String
+      def text
+        @parts.join(" ")
       end
     end
   end
-
-  ##
-  # Appends +texts+ onto this Paragraph
-
-  def push *texts
-    self.parts.concat texts
-  end
-
-  ##
-  # The raw text
-
-  def text
-    @parts.join ' '
-  end
-
 end

data/lib/rdoc/markup/table.rb

@@ -1,52 +1,60 @@
 # frozen_string_literal: true
-##
-# A section of table
 
-class RDoc::Markup::Table
-  # headers of each column
-  attr_accessor :header
+module RDoc
+  class Markup
+    # A section of table
+    class Table < Element
+      # Headers of each column
+      #: Array[String]
+      attr_accessor :header
 
-  # alignments of each column
-  attr_accessor :align
+      # Alignments of each column
+      #: Array[Symbol?]
+      attr_accessor :align
 
-  # body texts of each column
-  attr_accessor :body
+      # Body texts of each column
+      #: Array[String]
+      attr_accessor :body
 
-  # Creates new instance
-  def initialize(header, align, body)
-    @header, @align, @body = header, align, body
-  end
-
-  # :stopdoc:
-  def ==(other)
-    self.class == other.class and
-      @header == other.header and
-      @align == other.align and
-      @body == other.body
-  end
+      #: (Array[String], Array[Symbol?], Array[String]) -> void
+      def initialize(header, align, body)
+        @header, @align, @body = header, align, body
+      end
 
-  def accept(visitor)
-    visitor.accept_table @header, @body, @align
-  end
+      #: (Object) -> bool
+      def ==(other)
+        self.class == other.class && @header == other.header &&
+          @align == other.align && @body == other.body
+      end
 
-  def pretty_print(q)
-    q.group 2, '[Table: ', ']' do
-      q.group 2, '[Head: ', ']' do
-        q.seplist @header.zip(@align) do |text, align|
-          q.pp text
-          if align
-            q.text ":"
-            q.breakable
-            q.text align.to_s
-          end
-        end
+      # @override
+      #: (untyped) -> void
+      def accept(visitor)
+        visitor.accept_table(@header, @body, @align)
       end
-      q.breakable
-      q.group 2, '[Body: ', ']' do
-        q.seplist @body do |body|
-          q.group 2, '[', ']' do
-            q.seplist body do |text|
+
+      # @override
+      #: (untyped) -> String
+      def pretty_print(q)
+        q.group 2, '[Table: ', ']' do
+          q.group 2, '[Head: ', ']' do
+            q.seplist @header.zip(@align) do |text, align|
               q.pp text
+              if align
+                q.text ":"
+                q.breakable
+                q.text align.to_s
+              end
+            end
+          end
+          q.breakable
+          q.group 2, '[Body: ', ']' do
+            q.seplist @body do |body|
+              q.group 2, '[', ']' do
+                q.seplist body do |text|
+                  q.pp text
+                end
+              end
             end
           end
         end

data/lib/rdoc/markup/to_html.rb

@@ -221,10 +221,15 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
 
   def accept_verbatim(verbatim)
     text = verbatim.text.rstrip
+    format = verbatim.format
 
     klass = nil
 
-    content = if verbatim.ruby? or parseable? text then
+    # Apply Ruby syntax highlighting if
+    # - explicitly marked as Ruby (via ruby? which accepts :ruby or :rb)
+    # - no format specified but the text is parseable as Ruby
+    # Otherwise, add language class when applicable and skip Ruby highlighting
+    content = if verbatim.ruby? || (format.nil? && parseable?(text))
                 begin
                   tokens = RDoc::Parser::RipperStateLex.parse text
                   klass  = ' class="ruby"'
@@ -236,6 +241,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
                   CGI.escapeHTML text
                 end
               else
+                klass = " class=\"#{format}\"" if format
                 CGI.escapeHTML text
               end
 
@@ -306,6 +312,13 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     level = [6, heading.level].min
 
     label = heading.label @code_object
+    legacy_label = heading.legacy_label @code_object
+
+    # Add legacy anchor before the heading for backward compatibility.
+    # This allows old links with label- prefix to still work.
+    if @options.output_decoration && !@options.pipe
+      @res << "\n<span id=\"#{legacy_label}\" class=\"legacy-anchor\"></span>"
+    end
 
     @res << if @options.output_decoration
               "\n<h#{level} id=\"#{label}\">"
@@ -362,14 +375,18 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   end
 
   ##
-  # Generate a link to +url+ with content +text+.  Handles the special cases
-  # for img: and link: described under handle_regexp_HYPERLINK
+  # Generates an HTML link or image tag for the given +url+ and +text+.
+  #
+  # - Image URLs (http/https/link ending in .gif, .png, .jpg, .jpeg, .bmp)
+  #   become <img> tags
+  # - File references (.rb, .rdoc, .md) are converted to .html paths
+  # - Anchor URLs (#foo) pass through unchanged for GitHub-style header linking
+  # - Footnote links get wrapped in <sup> tags
 
   def gen_url(url, text)
     scheme, url, id = parse_url url
 
-    if %w[http https link].include?(scheme) and
-       url =~ /\.(gif|png|jpg|jpeg|bmp)$/ then
+    if %w[http https link].include?(scheme) && url =~ /\.(gif|png|jpg|jpeg|bmp)\z/
       "<img src=\"#{url}\" />"
     else
       if scheme != 'link' and %r%\A((?!https?:)(?:[^/#]*/)*+)([^/#]+)\.(rb|rdoc|md)(?=\z|#)%i =~ url
@@ -381,9 +398,11 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
 
       link = "<a#{id} href=\"#{url}\">#{text}</a>"
 
-      link = "<sup>#{link}</sup>" if /"foot/ =~ id
-
-      link
+      if /"foot/.match?(id)
+        "<sup>#{link}</sup>"
+      else
+        link
+      end
     end
   end
 
@@ -400,9 +419,10 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   # Maps attributes to HTML tags
 
   def init_tags
-    add_tag :BOLD, "<strong>", "</strong>"
-    add_tag :TT,   "<code>",   "</code>"
-    add_tag :EM,   "<em>",     "</em>"
+    add_tag :BOLD,   "<strong>", "</strong>"
+    add_tag :TT,     "<code>",   "</code>"
+    add_tag :EM,     "<em>",     "</em>"
+    add_tag :STRIKE, "<del>",    "</del>"
   end
 
   ##

data/lib/rdoc/markup/to_html_crossref.rb

@@ -169,14 +169,33 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
       end
 
       if label
+        # Convert label to GitHub-style anchor format
+        # First convert + to space (URL encoding), then apply GitHub-style rules
+        formatted_label = RDoc::Text.to_anchor(label.tr('+', ' '))
+
+        # Case 1: Path already has an anchor (e.g., method link)
+        #   Input:  C1#method@label -> path="C1.html#method-i-m"
+        #   Output: C1.html#method-i-m-label
         if path =~ /#/
-          path << "-label-#{label}"
-        elsif ref&.sections&.any? { |section| label == section.title }
-          path << "##{label}"
+          path << "-#{formatted_label}"
+
+        # Case 2: Label matches a section title
+        #   Input:  C1@Section -> path="C1.html", section "Section" exists
+        #   Output: C1.html#section (uses section.aref for GitHub-style)
+        elsif (section = ref&.sections&.find { |s| label.tr('+', ' ') == s.title })
+          path << "##{section.aref}"
+
+        # Case 3: Ref has an aref (class/module context)
+        #   Input:  C1@heading -> path="C1.html", ref=C1 class
+        #   Output: C1.html#class-c1-heading
         elsif ref.respond_to?(:aref)
-          path << "##{ref.aref}-label-#{label}"
+          path << "##{ref.aref}-#{formatted_label}"
+
+        # Case 4: No context, just the label (e.g., TopLevel/file)
+        #   Input:  README@section -> path="README_md.html"
+        #   Output: README_md.html#section
         else
-          path << "#label-#{label}"
+          path << "##{formatted_label}"
         end
       end
 

data/lib/rdoc/markup/to_label.rb

@@ -28,11 +28,21 @@ class RDoc::Markup::ToLabel < RDoc::Markup::Formatter
   end
 
   ##
-  # Converts +text+ to an HTML-safe label
+  # Converts +text+ to an HTML-safe label using GitHub-style anchor formatting.
 
   def convert(text)
     label = convert_flow @am.flow text
 
+    RDoc::Text.to_anchor(label)
+  end
+
+  ##
+  # Converts +text+ to an HTML-safe label using legacy RDoc formatting.
+  # Used for generating backward-compatible anchor aliases.
+
+  def convert_legacy(text)
+    label = convert_flow @am.flow text
+
     CGI.escape(label).gsub('%', '-').sub(/^-/, '')
   end
 

data/lib/rdoc/markup/verbatim.rb

@@ -70,7 +70,7 @@ class RDoc::Markup::Verbatim < RDoc::Markup::Raw
 
   def ruby?
     @format ||= nil # TODO for older ri data, switch the tree to marshal_dump
-    @format == :ruby
+    @format == :ruby || @format == :rb
   end
 
   ##

data/lib/rdoc/markup.rb

@@ -16,7 +16,7 @@
 #
 # - +rdoc+:
 #   the +RDoc+ markup format;
-#   see RDoc::MarkupReference.
+#   see {RDoc Markup Reference}[rdoc-ref:doc/markup_reference/rdoc.rdoc]
 # - +markdown+:
 #   The +markdown+ markup format as described in
 #   the {Markdown Guide}[https://www.markdownguide.org];
@@ -102,7 +102,7 @@
 #
 # = \RDoc Markup Reference
 #
-# See RDoc::MarkupReference.
+# See {RDoc Markup Reference}[rdoc-ref:doc/markup_reference/rdoc.rdoc]
 #
 #--
 # Original Author:: Dave Thomas,  dave@pragmaticprogrammer.com
@@ -210,6 +210,7 @@ https://github.com/ruby/rdoc/issues
   autoload :BlankLine,             "#{__dir__}/markup/blank_line"
   autoload :BlockQuote,            "#{__dir__}/markup/block_quote"
   autoload :Document,              "#{__dir__}/markup/document"
+  autoload :Element,               "#{__dir__}/markup/element"
   autoload :HardBreak,             "#{__dir__}/markup/hard_break"
   autoload :Heading,               "#{__dir__}/markup/heading"
   autoload :Include,               "#{__dir__}/markup/include"