rdoc 7.0.3 → 7.2.0

data/lib/rdoc/markup/to_html.rb

@@ -51,11 +51,10 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     @in_list_entry = nil
     @list = nil
     @th = nil
+    @in_tidylink_label = false
     @hard_break = "<br>\n"
 
     init_regexp_handlings
-
-    init_tags
   end
 
   # :section: Regexp Handling
@@ -72,6 +71,10 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     # external links
     @markup.add_regexp_handling(/(?:link:|https?:|mailto:|ftp:|irc:|www\.)#{URL_CHARACTERS_REGEXP_STR}+\w/,
                                 :HYPERLINK)
+
+    # suppress crossref: \#method \::method \ClassName \method_with_underscores
+    @markup.add_regexp_handling(/\\(?:[#:A-Z]|[a-z]+_[a-z0-9])/, :SUPPRESSED_CROSSREF)
+
     init_link_notation_regexp_handlings
   end
 
@@ -80,7 +83,6 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
 
   def init_link_notation_regexp_handlings
     add_regexp_handling_RDOCLINK
-    add_regexp_handling_TIDYLINK
   end
 
   def handle_RDOCLINK(url) # :nodoc:
@@ -88,6 +90,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     when /^rdoc-ref:/
       CGI.escapeHTML($')
     when /^rdoc-label:/
+      return CGI.escapeHTML(url) if in_tidylink_label?
       text = $'
 
       text = case text
@@ -113,11 +116,127 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     end
   end
 
-  ##
-  # +target+ is a <code><br></code>
+  def handle_PLAIN_TEXT(text)
+    emit_inline(convert_string(text))
+  end
+
+  def handle_REGEXP_HANDLING_TEXT(text)
+    emit_inline(text)
+  end
+
+  def handle_BOLD(nodes)
+    emit_inline('<strong>')
+    super
+    emit_inline('</strong>')
+  end
+
+  def handle_EM(nodes)
+    emit_inline('<em>')
+    super
+    emit_inline('</em>')
+  end
+
+  def handle_BOLD_WORD(word)
+    emit_inline('<strong>')
+    super
+    emit_inline('</strong>')
+  end
+
+  def handle_EM_WORD(word)
+    emit_inline('<em>')
+    super
+    emit_inline('</em>')
+  end
+
+  def handle_TT(code)
+    emit_inline('<code>')
+    super
+    emit_inline('</code>')
+  end
+
+  def handle_STRIKE(nodes)
+    emit_inline('<del>')
+    super
+    emit_inline('</del>')
+  end
+
+  def handle_HARD_BREAK
+    emit_inline('<br>')
+  end
+
+  def emit_inline(text)
+    @inline_output << text
+  end
+
+  # Returns true if we are processing inside a tidy link label.
+
+  def in_tidylink_label?
+    @in_tidylink_label
+  end
 
-  def handle_regexp_HARD_BREAK(target)
-    '<br>'
+  # Special handling for tidy link labels.
+  # When a tidy link is <tt>{rdoc-image:path/to/image.jpg:alt text}[http://example.com]</tt>,
+  # label part is normally considered RDOCLINK <tt>rdoc-image:path/to/image.jpg:alt</tt> and a text <tt>" text"</tt>
+  # but RDoc's test code expects the whole label part to be treated as RDOCLINK only in tidy link label.
+  # When a tidy link is <tt>{^1}[url]</tt> or <tt>{*1}[url]</tt>, the label part needs to drop leading * or ^.
+  # TODO: reconsider this workaround.
+
+  def apply_tidylink_label_special_handling(label, url)
+    # ^1 *1 will be converted to just 1 in tidy link label.
+    return label[1..] if label.match?(/\A[*^]\d+\z/)
+
+    # rdoc-image in label specially allows spaces in alt text.
+    return handle_RDOCLINK(label) if label.start_with?('rdoc-image:')
+  end
+
+  def handle_TIDYLINK(label_part, url)
+    # When url is an image, ignore label part (maybe bug?) and just generate img tag.
+    if url.match?(/\Ahttps?:\/\/.+\.(png|gif|jpg|jpeg|bmp)\z/)
+      emit_inline("<img src=\"#{CGI.escapeHTML(url)}\" />")
+      return
+    elsif url.match?(/\Ardoc-image:/)
+      emit_inline(handle_RDOCLINK(url))
+      return
+    end
+
+    if label_part.size == 1 && String === label_part[0]
+      raw_label = label_part[0]
+
+      @in_tidylink_label = true
+      special = apply_tidylink_label_special_handling(raw_label, url)
+      @in_tidylink_label = false
+
+      if special
+        tag = gen_url(CGI.escapeHTML(url), special)
+        unless tag.empty?
+          emit_inline(tag)
+          return
+        end
+      end
+    end
+
+    tag = gen_url(CGI.escapeHTML(url), '')
+    open_tag, close_tag = tag.split(/(?=<\/a>)/, 2)
+    valid_tag = open_tag && close_tag
+    emit_inline(open_tag) if valid_tag
+    @in_tidylink_label = true
+    traverse_inline_nodes(label_part)
+    @in_tidylink_label = false
+    emit_inline(close_tag) if valid_tag
+  end
+
+  def handle_inline(text) # :nodoc:
+    @inline_output = +''
+    super
+    out = @inline_output
+    @inline_output = nil
+    out
+  end
+
+  # Converts suppressed cross-reference +text+ to HTML by removing the leading backslash.
+
+  def handle_regexp_SUPPRESSED_CROSSREF(text)
+    convert_string(text.delete_prefix('\\'))
   end
 
   ##
@@ -132,9 +251,10 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   # <tt>link:</tt>::
   #   Reference to a local file relative to the output directory.
 
-  def handle_regexp_HYPERLINK(target)
-    url = CGI.escapeHTML(target.text)
+  def handle_regexp_HYPERLINK(text)
+    return convert_string(text) if in_tidylink_label?
 
+    url = CGI.escapeHTML(text)
     gen_url url, url
   end
 
@@ -147,27 +267,8 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   # For the +rdoc-label+ scheme the footnote and label prefixes are stripped
   # when creating a link.  All other contents will be linked verbatim.
 
-  def handle_regexp_RDOCLINK(target)
-    handle_RDOCLINK target.text
-  end
-
-  ##
-  # This +target+ is a link where the label is different from the URL
-  # <tt>label[url]</tt> or <tt>{long label}[url]</tt>
-
-  def handle_regexp_TIDYLINK(target)
-    text = target.text
-
-    if tidy_link_capturing?
-      return finish_tidy_link(text)
-    end
-
-    if text.start_with?('{') && !text.include?('}')
-      start_tidy_link text
-      return ''
-    end
-
-    convert_complete_tidy_link(text)
+  def handle_regexp_RDOCLINK(text)
+    handle_RDOCLINK text
   end
 
   # :section: Visitor
@@ -181,6 +282,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     @res = []
     @in_list_entry = []
     @list = []
+    @heading_ids = {}
   end
 
   ##
@@ -221,10 +323,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 +343,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
                   CGI.escapeHTML text
                 end
               else
+                klass = " class=\"#{format}\"" if format
                 CGI.escapeHTML text
               end
 
@@ -305,7 +413,14 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   def accept_heading(heading)
     level = [6, heading.level].min
 
-    label = heading.label @code_object
+    label = deduplicate_heading_id(heading.label(@code_object))
+    legacy_label = deduplicate_heading_id(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}\">"
@@ -354,6 +469,20 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
 
   # :section: Utilities
 
+  ##
+  # Returns a unique heading ID, appending -1, -2, etc. for duplicates.
+  # Matches GitHub's behavior for duplicate heading anchors.
+
+  def deduplicate_heading_id(id)
+    if @heading_ids.key?(id)
+      @heading_ids[id] += 1
+      "#{id}-#{@heading_ids[id]}"
+    else
+      @heading_ids[id] = 0
+      id
+    end
+  end
+
   ##
   # CGI-escapes +text+
 
@@ -362,14 +491,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 +514,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
 
@@ -396,15 +531,6 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     tags[open_tag ? 0 : 1]
   end
 
-  ##
-  # Maps attributes to HTML tags
-
-  def init_tags
-    add_tag :BOLD, "<strong>", "</strong>"
-    add_tag :TT,   "<code>",   "</code>"
-    add_tag :EM,   "<em>",     "</em>"
-  end
-
   ##
   # Returns the HTML tag for +list_type+, possible using a label from
   # +list_item+
@@ -454,141 +580,10 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   # Converts +item+ to HTML using RDoc::Text#to_html
 
   def to_html(item)
-    super convert_flow @am.flow item
-  end
-
-  private
-
-  def convert_flow(flow_items)
-    res = []
-
-    flow_items.each do |item|
-      case item
-      when String
-        append_flow_fragment res, convert_string(item)
-      when RDoc::Markup::AttrChanger
-        off_tags res, item
-        on_tags  res, item
-      when RDoc::Markup::RegexpHandling
-        append_flow_fragment res, convert_regexp_handling(item)
-      else
-        raise "Unknown flow element: #{item.inspect}"
-      end
-    end
-
-    res.join
-  end
-
-  def append_flow_fragment(res, fragment)
-    return if fragment.nil? || fragment.empty?
-
-    emit_tidy_link_fragment(res, fragment)
-  end
-
-  def append_to_tidy_label(fragment)
-    @tidy_link_buffer << fragment
-  end
-
-  ##
-  # Matches an entire tidy link with a braced label "{label}[url]".
-  #
-  # Capture 1: label contents.
-  # Capture 2: URL text.
-  # Capture 3: trailing content.
-  TIDY_LINK_WITH_BRACES = /\A\{(.*?)\}\[(.*?)\](.*)\z/
-
-  ##
-  # Matches the tail of a braced tidy link when the opening brace was
-  # consumed earlier while accumulating the label text.
-  #
-  # Capture 1: remaining label content.
-  # Capture 2: URL text.
-  # Capture 3: trailing content.
-  TIDY_LINK_WITH_BRACES_TAIL = /\A(.*?)\}\[(.*?)\](.*)\z/
-
-  ##
-  # Matches a tidy link with a single-word label "label[url]".
-  #
-  # Capture 1: the single-word label (no whitespace).
-  # Capture 2: URL text between the brackets.
-  TIDY_LINK_SINGLE_WORD = /\A(\S+)\[(.*?)\](.*)\z/
-
-  def convert_complete_tidy_link(text)
-    return text unless
-      text =~ TIDY_LINK_WITH_BRACES or text =~ TIDY_LINK_SINGLE_WORD
-
-    label = $1
-    url   = CGI.escapeHTML($2)
-
-    label_html = if /^rdoc-image:/ =~ label
-                   handle_RDOCLINK(label)
-                 else
-                   render_tidy_link_label(label)
-                 end
-
-    gen_url url, label_html
-  end
-
-  def emit_tidy_link_fragment(res, fragment)
-    if tidy_link_capturing?
-      append_to_tidy_label fragment
-    else
-      res << fragment
-    end
-  end
-
-  def finish_tidy_link(text)
-    label_tail, url, trailing = extract_tidy_link_parts(text)
-    append_to_tidy_label CGI.escapeHTML(label_tail) unless label_tail.empty?
-
-    return '' unless url
-
-    label_html = @tidy_link_buffer
-    @tidy_link_buffer = nil
-    link = gen_url(url, label_html)
-
-    return link if trailing.empty?
-
-    link + CGI.escapeHTML(trailing)
-  end
-
-  def extract_tidy_link_parts(text)
-    if text =~ TIDY_LINK_WITH_BRACES
-      [$1, CGI.escapeHTML($2), $3]
-    elsif text =~ TIDY_LINK_WITH_BRACES_TAIL
-      [$1, CGI.escapeHTML($2), $3]
-    elsif text =~ TIDY_LINK_SINGLE_WORD
-      [$1, CGI.escapeHTML($2), $3]
-    else
-      [text, nil, '']
-    end
-  end
-
-  def on_tags(res, item)
-    each_attr_tag(item.turn_on) do |tag|
-      emit_tidy_link_fragment(res, annotate(tag.on))
-      @in_tt += 1 if tt? tag
-    end
-  end
-
-  def off_tags(res, item)
-    each_attr_tag(item.turn_off, true) do |tag|
-      emit_tidy_link_fragment(res, annotate(tag.off))
-      @in_tt -= 1 if tt? tag
-    end
-  end
-
-  def start_tidy_link(text)
-    @tidy_link_buffer = String.new
-    append_to_tidy_label CGI.escapeHTML(text.delete_prefix('{'))
-  end
-
-  def tidy_link_capturing?
-    !!@tidy_link_buffer
-  end
-
-  def render_tidy_link_label(label)
-    RDoc::Markup::LinkLabelToHtml.render(label, @options, @from_path)
+    # Ideally, we should convert html characters at handle_PLAIN_TEXT or somewhere else,
+    # but we need to convert it here for now because to_html_characters converts pair of backticks to ’‘ and pair of double backticks to ”“.
+    # Known bugs: `...` in `<code>def f(...); end</code>` and `(c) in `<a href="(c)">` will be wrongly converted.
+    to_html_characters(handle_inline(item))
   end
 end
 

data/lib/rdoc/markup/to_html_crossref.rb

@@ -50,8 +50,6 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
     # will be processed as a tidylink first and will be broken.
     crossref_re = @options.hyperlink_all ? ALL_CROSSREF_REGEXP : CROSSREF_REGEXP
     @markup.add_regexp_handling crossref_re, :CROSSREF
-
-    add_regexp_handling_TIDYLINK
   end
 
   ##
@@ -63,8 +61,11 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
 
     name = name[1..-1] unless @show_hash if name[0, 1] == '#'
 
-    if !(name.end_with?('+@', '-@')) and name =~ /(.*[^#:])?@/
-      text ||= [CGI.unescape($'), (" at <code>#{$1}</code>" if $~.begin(1))].join("")
+    if !name.end_with?('+@', '-@') && match = name.match(/(.*[^#:])?@(.*)/)
+      context_name = match[1]
+      label = RDoc::Text.decode_legacy_label(match[2])
+      text ||= "#{label} at <code>#{context_name}</code>" if context_name
+      text ||= label
       code = false
     else
       text ||= name
@@ -80,9 +81,8 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   # example, ToHtml is found, even without the <tt>RDoc::Markup::</tt> prefix,
   # because we look for it in module Markup first.
 
-  def handle_regexp_CROSSREF(target)
-    name = target.text
-
+  def handle_regexp_CROSSREF(name)
+    return convert_string(name) if in_tidylink_label?
     return name if @options.autolink_excluded_words&.include?(name)
 
     return name if name =~ /@[\w-]+\.[\w-]/ # labels that look like emails
@@ -101,8 +101,8 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   # Handles <tt>rdoc-ref:</tt> scheme links and allows RDoc::Markup::ToHtml to
   # handle other schemes.
 
-  def handle_regexp_HYPERLINK(target)
-    url = target.text
+  def handle_regexp_HYPERLINK(url)
+    return convert_string(url) if in_tidylink_label?
 
     case url
     when /\Ardoc-ref:/
@@ -120,12 +120,14 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   # All other contents are handled by
   # {the superclass}[rdoc-ref:RDoc::Markup::ToHtml#handle_regexp_RDOCLINK]
 
-  def handle_regexp_RDOCLINK(target)
-    url = target.text
-
+  def handle_regexp_RDOCLINK(url)
     case url
     when /\Ardoc-ref:/
-      cross_reference $', rdoc_ref: true
+      if in_tidylink_label?
+        convert_string(url)
+      else
+        cross_reference $', rdoc_ref: true
+      end
     else
       super
     end
@@ -169,14 +171,34 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
       end
 
       if label
+        # Decode legacy labels (e.g., "What-27s+Here" -> "What's Here")
+        # then convert to GitHub-style anchor format
+        decoded_label = RDoc::Text.decode_legacy_label(label)
+        formatted_label = RDoc::Text.to_anchor(decoded_label)
+
+        # 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| decoded_label == 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
 
@@ -184,73 +206,30 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
     end
   end
 
-  def convert_flow(flow_items, &block)
-    res = []
-
-    i = 0
-    while i < flow_items.size
-      item = flow_items[i]
-
-      case item
-      when RDoc::Markup::AttrChanger
-        if !tidy_link_capturing? && (text = convert_tt_crossref(flow_items, i))
-          text = block.call(text, res) if block
-          append_flow_fragment res, text
-          i += 3
-          next
-        end
+  def handle_TT(code)
+    emit_inline(tt_cross_reference(code) || "<code>#{CGI.escapeHTML code}</code>")
+  end
 
-        off_tags res, item
-        on_tags  res, item
-        i += 1
-      when String
-        text = convert_string(item)
-        text = block.call(text, res) if block
-        append_flow_fragment res, text
-        i += 1
-      when RDoc::Markup::RegexpHandling
-        text = convert_regexp_handling(item)
-        text = block.call(text, res) if block
-        append_flow_fragment res, text
-        i += 1
-      else
-        raise "Unknown flow element: #{item.inspect}"
-      end
+  # Applies additional special handling on top of the one defined in ToHtml.
+  # When a tidy link is <tt>{Foo}[rdoc-ref:Foo]</tt>, the label part is surrounded by <tt><code></code></tt>.
+  # TODO: reconsider this workaround.
+  def apply_tidylink_label_special_handling(label, url)
+    if url == "rdoc-ref:#{label}" && cross_reference(label).include?('<code>')
+      "<code>#{convert_string(label)}</code>"
+    else
+      super
     end
-
-    res.join('')
   end
 
-  private
-
-  ##
-  # Detects <tt>...</tt> spans that contain a single cross-reference candidate.
-  # When the candidate occupies the whole span (aside from trailing
-  # punctuation), the tt markup is replaced by the resolved cross-reference.
-
-  def convert_tt_crossref(flow_items, index)
-    opener = flow_items[index]
-    return unless tt_tag?(opener.turn_on)
-
-    string = flow_items[index + 1]
-    closer = flow_items[index + 2]
-
-    return unless String === string
-    return unless RDoc::Markup::AttrChanger === closer
-    return unless tt_tag?(closer.turn_off, true)
+  def tt_cross_reference(code)
+    return if in_tidylink_label?
 
     crossref_regexp = @options.hyperlink_all ? ALL_CROSSREF_REGEXP : CROSSREF_REGEXP
-    match = crossref_regexp.match(string)
-    return unless match
-    return unless match.begin(1).zero?
-
-    trailing = match.post_match
-    # Only convert when the remainder is punctuation/whitespace so other tt text stays literal.
-    return unless trailing.match?(/\A[[:punct:]\s]*\z/)
-
-    text = cross_reference(string)
-    return if text == string
+    match = crossref_regexp.match(code)
+    return unless match && match.begin(1).zero?
+    return unless match.post_match.match?(/\A[[:punct:]\s]*\z/)
 
-    text
+    ref = cross_reference(code)
+    ref if ref != code
   end
 end