rdoc 6.15.1 → 7.1.0

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_ansi.rb

@@ -81,6 +81,10 @@ class RDoc::Markup::ToAnsi < RDoc::Markup::ToRdoc
     end
   end
 
+  def calculate_text_width(text)
+    text.gsub(/\e\[[\d;]*m/, '').size
+  end
+
   ##
   # Starts accepting with a reset screen
 

data/lib/rdoc/markup/to_bs.rb

@@ -65,6 +65,10 @@ class RDoc::Markup::ToBs < RDoc::Markup::ToRdoc
     end
   end
 
+  def calculate_text_width(text)
+    text.gsub(/_\x08/, '').gsub(/\x08./, '').size
+  end
+
   ##
   # Turns on or off regexp handling for +convert_string+
 

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,17 +312,26 @@ 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}\">"
             else
               "\n<h#{level}>"
             end
-    @res << to_html(heading.text)
-    unless @options.pipe then
-      @res << "<span><a href=\"##{label}\">&para;</a>"
-      @res << " <a href=\"#top\">&uarr;</a></span>"
+
+    if @options.pipe
+      @res << to_html(heading.text)
+    else
+      @res << "<a href=\"##{label}\">#{to_html(heading.text)}</a>"
     end
+
     @res << "</h#{level}>\n"
   end
 
@@ -360,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
@@ -379,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
 
@@ -398,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/to_rdoc.rb

@@ -250,8 +250,10 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
   # Adds +table+ to the output
 
   def accept_table(header, body, aligns)
+    header = header.map { |h| attributes h }
+    body = body.map { |row| row.map { |t| attributes t } }
     widths = header.zip(*body).map do |cols|
-      cols.map(&:size).max
+      cols.map { |col| calculate_text_width(col) }.max
     end
     aligns = aligns.map do |a|
       case a
@@ -264,16 +266,22 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
       end
     end
     @res << header.zip(widths, aligns).map do |h, w, a|
-      h.__send__(a, w)
+      extra_width = h.size - calculate_text_width(h)
+      h.__send__(a, w + extra_width)
     end.join("|").rstrip << "\n"
     @res << widths.map {|w| "-" * w }.join("|") << "\n"
     body.each do |row|
       @res << row.zip(widths, aligns).map do |t, w, a|
-        t.__send__(a, w)
+        extra_width = t.size - calculate_text_width(t)
+        t.__send__(a, w + extra_width)
       end.join("|").rstrip << "\n"
     end
   end
 
+  def calculate_text_width(text)
+    text.size
+  end
+
   ##
   # Applies attribute-specific markup to +text+ using RDoc::AttributeManager
 

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"

data/lib/rdoc/options.rb

@@ -378,6 +378,21 @@ class RDoc::Options
 
   attr_accessor :canonical_root
 
+  ##
+  # Custom footer content configuration for themes that support it.
+  # Currently only supported by the Aliki theme.
+  #
+  # A hash where keys are column titles and values are hashes of link text => URL pairs.
+  # Each column will be displayed in the upper footer section.
+  #
+  # Example:
+  #   {
+  #     "DOCUMENTATION" => {"Home" => "/index.html", "Guide" => "/guide.html"},
+  #     "RESOURCES" => {"RDoc" => "https://ruby.github.io/rdoc/", "GitHub" => "https://github.com/ruby/rdoc"}
+  #   }
+
+  attr_accessor :footer_content
+
   def initialize(loaded_options = nil) # :nodoc:
     init_ivars
     override loaded_options if loaded_options
@@ -396,10 +411,9 @@ class RDoc::Options
     @files = nil
     @force_output = false
     @force_update = true
-    @generator = nil
-    @generator_name = nil
-    @generator_options = []
+    @generator_name = "aliki"
     @generators = RDoc::RDoc::GENERATORS
+    @generator_options = []
     @hyperlink_all = false
     @line_numbers = false
     @locale = nil
@@ -435,6 +449,7 @@ class RDoc::Options
     @class_module_path_prefix = nil
     @file_path_prefix = nil
     @canonical_root = nil
+    @footer_content = nil
   end
 
   def init_with(map) # :nodoc:
@@ -463,6 +478,7 @@ class RDoc::Options
 
     @apply_default_exclude   = map['apply_default_exclude']
     @autolink_excluded_words = map['autolink_excluded_words']
+    @footer_content          = map['footer_content']
 
     @rdoc_include = sanitize_path map['rdoc_include']
     @static_path  = sanitize_path map['static_path']
@@ -499,6 +515,7 @@ class RDoc::Options
     @autolink_excluded_words = map['autolink_excluded_words'] if map.has_key?('autolink_excluded_words')
     @apply_default_exclude = map['apply_default_exclude'] if map.has_key?('apply_default_exclude')
     @canonical_root = map['canonical_root'] if map.has_key?('canonical_root')
+    @footer_content = map['footer_content'] if map.has_key?('footer_content')
 
     @warn_missing_rdoc_ref = map['warn_missing_rdoc_ref'] if map.has_key?('warn_missing_rdoc_ref')
 
@@ -1213,9 +1230,6 @@ Usage: #{opt.program_name} [options] [names...]
       opt.separator nil
     end
 
-    setup_generator 'darkfish' if
-      argv.grep(/\A(-f|--fmt|--format|-r|-R|--ri|--ri-site)\b/).empty?
-
     deprecated = []
     invalid = []
 
@@ -1233,10 +1247,7 @@ Usage: #{opt.program_name} [options] [names...]
       retry
     end
 
-    unless @generator then
-      @generator = RDoc::Generator::Darkfish
-      @generator_name = 'darkfish'
-    end
+    setup_generator unless @generator
 
     if @pipe and not argv.empty? then
       @pipe = false

data/lib/rdoc/parser/c.rb

@@ -607,8 +607,6 @@ class RDoc::Parser::C < RDoc::Parser
       body = args[1]
       offset, = args[2]
 
-      comment.remove_private if comment
-
       # try to find the whole body
       body = $& if /#{Regexp.escape body}[^(]*?\{.*?^\}/m =~ file_content
 
@@ -621,11 +619,10 @@ class RDoc::Parser::C < RDoc::Parser
       override_comment = find_override_comment class_name, meth_obj
       comment = override_comment if override_comment
 
-      comment.normalize
       find_modifiers comment, meth_obj if comment
 
       #meth_obj.params = params
-      meth_obj.start_collecting_tokens
+      meth_obj.start_collecting_tokens(:c)
       tk = { :line_no => 1, :char_no => 1, :text => body }
       meth_obj.add_token tk
       meth_obj.comment = comment
@@ -639,10 +636,9 @@ class RDoc::Parser::C < RDoc::Parser
 
       find_body class_name, args[3], meth_obj, file_content, true
 
-      comment.normalize
       find_modifiers comment, meth_obj
 
-      meth_obj.start_collecting_tokens
+      meth_obj.start_collecting_tokens(:c)
       tk = { :line_no => 1, :char_no => 1, :text => body }
       meth_obj.add_token tk
       meth_obj.comment = comment
@@ -663,7 +659,6 @@ class RDoc::Parser::C < RDoc::Parser
       comment = find_override_comment class_name, meth_obj
 
       if comment then
-        comment.normalize
         find_modifiers comment, meth_obj
         meth_obj.comment = comment
 
@@ -742,7 +737,6 @@ class RDoc::Parser::C < RDoc::Parser
     end
 
     comment = new_comment comment, @top_level, :c
-    comment.normalize
 
     look_for_directives_in class_mod, comment
 
@@ -807,9 +801,6 @@ class RDoc::Parser::C < RDoc::Parser
   # Handles modifiers in +comment+ and updates +meth_obj+ as appropriate.
 
   def find_modifiers(comment, meth_obj)
-    comment.normalize
-    meth_obj.call_seq = comment.extract_call_seq
-
     look_for_directives_in meth_obj, comment
   end
 
@@ -823,10 +814,10 @@ class RDoc::Parser::C < RDoc::Parser
     comment = if @content =~ %r%Document-method:
                                 \s+#{class_name}#{prefix}#{name}
                                 \s*?\n((?>.*?\*/))%xm then
-                "/*#{$1}"
+                "/*\n#{$1}"
               elsif @content =~ %r%Document-method:
                                    \s#{name}\s*?\n((?>.*?\*/))%xm then
-                "/*#{$1}"
+                "/*\n#{$1}"
               end
 
     return unless comment
@@ -1061,10 +1052,13 @@ class RDoc::Parser::C < RDoc::Parser
   # Registers a singleton class +sclass_var+ as a singleton of +class_var+
 
   def handle_singleton(sclass_var, class_var)
-    class_name = @known_classes[class_var]
-
-    @known_classes[sclass_var]     = class_name
-    @singleton_classes[sclass_var] = class_name
+    if (klass = @classes[class_var])
+      @classes[sclass_var] = klass
+    end
+    if (class_name = @known_classes[class_var])
+      @known_classes[sclass_var]     = class_name
+      @singleton_classes[sclass_var] = class_name
+    end
   end
 
   ##
@@ -1102,35 +1096,10 @@ class RDoc::Parser::C < RDoc::Parser
   # Both :main: and :title: directives are deprecated and will be removed in RDoc 7.
 
   def look_for_directives_in(context, comment)
-    @preprocess.handle comment, context do |directive, param|
-      case directive
-      when 'main' then
-        @options.main_page = param
-
-        warn <<~MSG
-          The :main: directive is deprecated and will be removed in RDoc 7.
-
-          You can use these options to specify the initial page displayed instead:
-          - `--main=#{param}` via the command line
-          - `rdoc.main = "#{param}"` if you use `RDoc::Task`
-          - `main_page: #{param}` in your `.rdoc_options` file
-        MSG
-        ''
-      when 'title' then
-        @options.default_title = param if @options.respond_to? :default_title=
-
-        warn <<~MSG
-          The :title: directive is deprecated and will be removed in RDoc 7.
-
-          You can use these options to specify the title displayed instead:
-          - `--title=#{param}` via the command line
-          - `rdoc.title = "#{param}"` if you use `RDoc::Task`
-          - `title: #{param}` in your `.rdoc_options` file
-        MSG
-        ''
-      end
-    end
-
+    comment.text, format = @preprocess.run_pre_processes(comment.text, context, comment.line || 1, :c)
+    comment.format = format if format
+    @preprocess.run_post_processes(comment, context)
+    comment.normalized = true
     comment
   end
 

data/lib/rdoc/parser/changelog.rb

@@ -293,6 +293,10 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
       end
 
       def aref
+        commit
+      end
+
+      def legacy_aref
         "label-#{commit}"
       end
 
@@ -300,6 +304,10 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
         aref
       end
 
+      def legacy_label(context = nil)
+        legacy_aref
+      end
+
       def text
         case base
         when nil