rdoc 7.0.4 → 7.1.0

data/lib/rdoc/generator/template/darkfish/class.rhtml

@@ -26,13 +26,14 @@
         <% if namespace[:self] %>
         <span><%= namespace[:name] %></span>
         <% else %>
-        <a href="<%= namespace[:path] %>"><%= namespace[:name] %></a><span class="separator">::</span>
+        <a href="<%= namespace[:path] %>"><%= namespace[:name] %></a><span>::</span>
         <% end %>
       </li>
       <% end %>
     </ol>
   <% end %>
 
+  <span id="<%= h klass.legacy_aref %>" class="legacy-anchor"></span>
   <h1 id="<%= h klass.aref %>" class="anchor-link <%= klass.type %>">
     <%= klass.type %> <%= klass.full_name %>
   </h1>
@@ -42,8 +43,9 @@
   </section>
 
   <%- klass.each_section do |section, constants, attributes| %>
+  <span id="<%= section.legacy_aref %>" class="legacy-anchor"></span>
   <section id="<%= section.aref %>" class="documentation-section anchor-link">
-    <%- if section.title %>
+    <%- if section.title then %>
     <header class="documentation-section-title">
       <h2>
         <%= section.title %>
@@ -54,13 +56,13 @@
     </header>
     <%- end %>
 
-    <%- if section.comment %>
+    <%- if section.comment then %>
     <div>
       <%= section.description %>
     </div>
     <%- end %>
 
-    <%- unless constants.empty? %>
+    <%- unless constants.empty? then %>
     <section class="constants-list">
       <header>
         <h3>Constants</h3>
@@ -68,9 +70,9 @@
       <dl>
       <%- constants.each do |const| %>
         <dt id="<%= const.name %>"><%= const.name %></dt>
-        <%- if const.comment %>
+        <%- if const.comment then %>
         <dd>
-          <%- if const.mixin_from %>
+          <%- if const.mixin_from then %>
             <div class="mixin-from">
               Included from <a href="<%= klass.aref_to(const.mixin_from.path) %>"><%= const.mixin_from.full_name %></a>
             </div>
@@ -85,7 +87,7 @@
     </section>
     <%- end %>
 
-    <%- unless attributes.empty? %>
+    <%- unless attributes.empty? then %>
     <section class="attribute-method-details method-section">
       <header>
         <h3>Attributes</h3>
@@ -101,12 +103,12 @@
         </div>
 
         <div class="method-description">
-        <%- if attrib.mixin_from %>
+        <%- if attrib.mixin_from then %>
           <div class="mixin-from">
             <%= attrib.singleton ? "Extended" : "Included" %> from <a href="<%= klass.aref_to(attrib.mixin_from.path) %>"><%= attrib.mixin_from.full_name %></a>
           </div>
         <%- end %>
-        <%- if attrib.comment %>
+        <%- if attrib.comment then %>
         <%= attrib.description.strip %>
         <%- else %>
         <p class="missing-docs">(Not documented)</p>
@@ -129,7 +131,7 @@
     <%- methods.each do |method| %>
       <div id="<%= method.aref %>" class="method-detail anchor-link <%= method.is_alias_for ? "method-alias" : '' %>">
         <div class="method-header">
-          <%- if (call_seq = method.call_seq) %>
+          <%- if (call_seq = method.call_seq) then %>
             <%- call_seq.strip.split("\n").each_with_index do |call_seq, i| %>
               <div class="method-heading">
                 <a href="#<%= method.aref %>" title="Link to this method">
@@ -141,7 +143,7 @@
                 </a>
               </div>
             <%- end %>
-          <%- elsif method.has_call_seq? %>
+          <%- elsif method.has_call_seq? then %>
             <div class="method-heading">
               <a href="#<%= method.aref %>" title="Link to this method">
                 <span class="method-name"><%= h method.name %></span>
@@ -168,19 +170,19 @@
           </div>
         <%- end %>
 
-        <%- unless method.skip_description? %>
+        <%- unless method.skip_description? then %>
         <div class="method-description">
-          <%- if method.mixin_from %>
+          <%- if method.mixin_from then %>
             <div class="mixin-from">
               <%= method.singleton ? "Extended" : "Included" %> from <a href="<%= klass.aref_to(method.mixin_from.path) %>"><%= method.mixin_from.full_name %></a>
             </div>
           <%- end %>
-          <%- if method.comment %>
+          <%- if method.comment then %>
           <%= method.description.strip %>
           <%- else %>
           <p class="missing-docs">(Not documented)</p>
           <%- end %>
-          <%- if method.calls_super %>
+          <%- if method.calls_super then %>
             <div class="method-calls-super">
               Calls superclass method
               <%=
@@ -192,7 +194,7 @@
         </div>
         <%- end %>
 
-        <%- unless method.aliases.empty? %>
+        <%- unless method.aliases.empty? then %>
         <div class="aliases">
           Also aliased as: <%= method.aliases.map do |aka|
             if aka.parent then # HACK lib/rexml/encodings
@@ -204,7 +206,7 @@
         </div>
         <%- end %>
 
-        <%- if method.is_alias_for %>
+        <%- if method.is_alias_for then %>
         <div class="aliases">
           Alias for: <a href="<%= klass.aref_to method.is_alias_for.path %>"><%= h method.is_alias_for.name %></a>
         </div>

data/lib/rdoc/generator/template/darkfish/css/rdoc.css

@@ -92,6 +92,25 @@ main .anchor-link:target {
   scroll-margin-top: 1rem;
 }
 
+/* Legacy anchor for backward compatibility with old label- prefix links */
+.legacy-anchor {
+  display: block;
+  position: relative;
+  visibility: hidden;
+  scroll-margin-top: 1rem;
+}
+
+/* When a legacy anchor is targeted, highlight the next heading sibling */
+.legacy-anchor:target + h1,
+.legacy-anchor:target + h2,
+.legacy-anchor:target + h3,
+.legacy-anchor:target + h4,
+.legacy-anchor:target + h5,
+.legacy-anchor:target + h6 {
+  margin-left: -10px;
+  border-left: 10px solid var(--border-color);
+}
+
 /* 4. Links */
 a {
   color: var(--link-color);

data/lib/rdoc/generator/template/darkfish/table_of_contents.rhtml

@@ -14,7 +14,7 @@
 <h1 class="class"><%= h @title %></h1>
 
 <%- simple_files = @files.select { |f| f.text? } %>
-<%- unless simple_files.empty? %>
+<%- unless simple_files.empty? then %>
 <h2 id="pages">Pages</h2>
 <ul>
 <%- simple_files.sort.each do |file| %>
@@ -23,7 +23,7 @@
 <%
    # HACK table_of_contents should not exist on Document
    table = file.parse(file.comment).table_of_contents
-   unless table.empty? %>
+   unless table.empty? then %>
     <ul>
     <%- table.each do |heading| %>
       <li><a href="<%= h file.path %>#<%= heading.aref %>"><%= heading.plain_html %></a></li>
@@ -44,7 +44,7 @@
    table.concat klass.parse(klass.comment_location).table_of_contents
    table.concat klass.section_contents
 
-   unless table.empty? %>
+   unless table.empty? then %>
     <ul>
 <%- table.each do |item| %>
   <%- label = item.respond_to?(:label) ? item.label(klass) : item.aref %>

data/lib/rdoc/markdown.kpeg

@@ -490,11 +490,7 @@
   # Wraps `text` in strike markup for rdoc inline formatting
 
   def strike text
-    if text =~ /\A[a-z\d.\/-]+\z/i then
-      "~#{text}~"
-    else
-      "<s>#{text}</s>"
-    end
+    "<del>#{text}</del>"
   end
 
   ##

data/lib/rdoc/markdown.rb

@@ -875,11 +875,7 @@ class RDoc::Markdown
   # Wraps `text` in strike markup for rdoc inline formatting
 
   def strike text
-    if text =~ /\A[a-z\d.\/-]+\z/i then
-      "~#{text}~"
-    else
-      "<s>#{text}</s>"
-    end
+    "<del>#{text}</del>"
   end
 
   ##

data/lib/rdoc/markup/attribute_manager.rb

@@ -89,12 +89,21 @@ class RDoc::Markup::AttributeManager
     add_word_pair "*", "*", :BOLD, true
     add_word_pair "_", "_", :EM, true
     add_word_pair "+", "+", :TT, true
+    add_word_pair "`", "`", :TT, true
 
     add_html "em", :EM, true
     add_html "i",  :EM, true
     add_html "b",  :BOLD, true
     add_html "tt",   :TT, true
     add_html "code", :TT, true
+    add_html "s",   :STRIKE, true
+    add_html "del", :STRIKE, true
+
+    @word_pair_chars = @matching_word_pairs.keys.join
+
+    # Matches a word pair delimiter (*, _, +, `) that is NOT already protected.
+    # Used by #protect_code_markup to escape delimiters inside <code>/<tt> tags.
+    @unprotected_word_pair_regexp = /([#{@word_pair_chars}])(?!#{PROTECT_ATTR})/
   end
 
   ##
@@ -164,7 +173,7 @@ class RDoc::Markup::AttributeManager
     }.keys
     return if tags.empty?
     tags = "[#{tags.join("")}](?!#{PROTECT_ATTR})"
-    all_tags = "[#{@matching_word_pairs.keys.join("")}](?!#{PROTECT_ATTR})"
+    all_tags = "[#{@word_pair_chars}](?!#{PROTECT_ATTR})"
 
     re = /(?:^|\W|#{all_tags})\K(#{tags})(\1*[#\\]?[\w:#{PROTECT_ATTR}.\/\[\]-]+?\S?)\1(?!\1)(?=#{all_tags}|\W|$)/
 
@@ -245,6 +254,23 @@ class RDoc::Markup::AttributeManager
     @str.gsub!(/\\(\\[#{Regexp.escape @protectable.join}])/m, "\\1")
   end
 
+  ##
+  # Protects word pair delimiters (*, _, +) inside
+  # <code> and <tt> tags from being processed as inline formatting.
+  # For example, *bold* in +*bold*+ will NOT be rendered as bold.
+
+  def protect_code_markup
+    @str.gsub!(/<(code|tt)>(.*?)<\/\1>/im) do
+      tag = $1
+      content = $2
+      # Protect word pair delimiters (*, _, +) from being processed
+      escaped = content.gsub(@unprotected_word_pair_regexp, "\\1#{PROTECT_ATTR}")
+      # Protect HTML-like tags from being processed (e.g., <del> inside code)
+      escaped = escaped.gsub(/<(?!#{PROTECT_ATTR})/, "<#{PROTECT_ATTR}")
+      "<#{tag}>#{escaped}</#{tag}>"
+    end
+  end
+
   ##
   # Unescapes regexp handling sequences of text
 
@@ -308,6 +334,7 @@ class RDoc::Markup::AttributeManager
     @str = str.dup
 
     mask_protected_sequences
+    protect_code_markup
 
     @attrs = RDoc::Markup::AttrSpan.new @str.length, @exclusive_bitmap
 

data/lib/rdoc/markup/document.rb

@@ -26,7 +26,7 @@ class RDoc::Markup::Document
   ##
   # Creates a new Document with +parts+
 
-  def initialize(*parts)
+  def initialize *parts
     @parts = []
     @parts.concat parts
 
@@ -148,7 +148,7 @@ class RDoc::Markup::Document
   ##
   # Appends +parts+ to the document
 
-  def push(*parts)
+  def push *parts
     self.parts.concat parts
   end
 

data/lib/rdoc/markup/formatter.rb

@@ -185,7 +185,7 @@ class RDoc::Markup::Formatter
   #
   #   alias accept_raw ignore
 
-  def ignore(*node)
+  def ignore *node
   end
 
   ##

data/lib/rdoc/markup/heading.rb

@@ -2,6 +2,33 @@
 
 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
+
     # A heading with a level (1-6) and text
     #
     #  RDoc syntax:
@@ -13,13 +40,8 @@ module RDoc
     #   # Heading 1
     #   ## Heading 2
     #   ### Heading 3
-    class Heading < Element
-      #: String
-      attr_reader :text
-
-      #: Integer
-      attr_accessor :level
-
+    #
+    class Heading
       # A singleton RDoc::Markup::ToLabel formatter for headings.
       #: () -> RDoc::Markup::ToLabel
       def self.to_label
@@ -43,38 +65,88 @@ module RDoc
         end
       end
 
-      #: (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
-
       # @override
       #: (untyped) -> void
       def accept(visitor)
         visitor.accept_heading(self)
       end
 
-      # An HTML-safe anchor reference for this header.
+      # 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
-        "label-#{self.class.to_label.convert text.dup}"
+        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 which will include the label from +context+. This helps keep ids unique in HTML.
+      # 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)
-        label = +""
-        label << "#{context.aref}-" if context&.respond_to?(:aref)
-        label << aref
-        label
+        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.

data/lib/rdoc/markup/indented_paragraph.rb

@@ -13,7 +13,7 @@ class RDoc::Markup::IndentedParagraph < RDoc::Markup::Raw
   # Creates a new IndentedParagraph containing +parts+ indented with +indent+
   # spaces
 
-  def initialize(indent, *parts)
+  def initialize indent, *parts
     @indent = indent
 
     super(*parts)

data/lib/rdoc/markup/list.rb

@@ -37,7 +37,7 @@ class RDoc::Markup::List
   # Creates a new list of +type+ with +items+.  Valid list types are:
   # +:BULLET+, +:LABEL+, +:LALPHA+, +:NOTE+, +:NUMBER+, +:UALPHA+
 
-  def initialize(type = nil, *items)
+  def initialize type = nil, *items
     @type = type
     @items = []
     @items.concat items
@@ -94,7 +94,7 @@ class RDoc::Markup::List
   ##
   # Appends +items+ to the list
 
-  def push(*items)
+  def push *items
     @items.concat items
   end
 

data/lib/rdoc/markup/list_item.rb

@@ -24,7 +24,7 @@ class RDoc::Markup::ListItem
   ##
   # Creates a new ListItem with an optional +label+ containing +parts+
 
-  def initialize(label = nil, *parts)
+  def initialize label = nil, *parts
     @label = label
     @parts = []
     @parts.concat parts
@@ -92,7 +92,7 @@ class RDoc::Markup::ListItem
   ##
   # Adds +parts+ to the ListItem
 
-  def push(*parts)
+  def push *parts
     @parts.concat parts
   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