rdoc 7.1.0 → 8.0.0

data/lib/rdoc/markup/to_html_crossref.rb

@@ -8,9 +8,7 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
 
   # :stopdoc:
   ALL_CROSSREF_REGEXP = RDoc::CrossReference::ALL_CROSSREF_REGEXP
-  CLASS_REGEXP_STR    = RDoc::CrossReference::CLASS_REGEXP_STR
   CROSSREF_REGEXP     = RDoc::CrossReference::CROSSREF_REGEXP
-  METHOD_REGEXP_STR   = RDoc::CrossReference::METHOD_REGEXP_STR
   # :startdoc:
 
   ##
@@ -29,15 +27,19 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   # references are removed unless +show_hash+ is true.  Only method names
   # preceded by '#' or '::' are linked, unless +hyperlink_all+ is true.
 
-  def initialize(options, from_path, context, markup = nil)
+  def initialize(from_path, context, pipe: false, output_decoration: true,
+                 hyperlink_all: false, show_hash: false,
+                 autolink_excluded_words: [], warn_missing_rdoc_ref: true)
     raise ArgumentError, 'from_path cannot be nil' if from_path.nil?
 
-    super options, markup
+    super(pipe: pipe, output_decoration: output_decoration)
 
     @context       = context
     @from_path     = from_path
-    @hyperlink_all = @options.hyperlink_all
-    @show_hash     = @options.show_hash
+    @hyperlink_all = hyperlink_all
+    @show_hash     = show_hash
+    @autolink_excluded_words = autolink_excluded_words
+    @warn_missing_rdoc_ref = warn_missing_rdoc_ref
 
     @cross_reference = RDoc::CrossReference.new @context
   end
@@ -48,29 +50,30 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
 
     # The crossref must be linked before tidylink because Klass.method[:sym]
     # will be processed as a tidylink first and will be broken.
-    crossref_re = @options.hyperlink_all ? ALL_CROSSREF_REGEXP : CROSSREF_REGEXP
+    crossref_re = @hyperlink_all ? ALL_CROSSREF_REGEXP : CROSSREF_REGEXP
     @markup.add_regexp_handling crossref_re, :CROSSREF
-
-    add_regexp_handling_TIDYLINK
   end
 
   ##
   # Creates a link to the reference +name+ if the name exists.  If +text+ is
   # given it is used as the link text, otherwise +name+ is used.
+  # Returns +nil+ if the link target could not be resolved.
 
   def cross_reference(name, text = nil, code = true, rdoc_ref: false)
-    lookup = name
-
-    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("")
+    # Strip '#' for link display text (e.g. #method shows as "method" in links)
+    display = !@show_hash && name.start_with?('#') ? name[1..] : name
+
+    if !display.end_with?('+@', '-@') && match = display.match(/(.*[^#:])?@(.*)/)
+      context_name = match[1]
+      label = convert_string(RDoc::Text.decode_legacy_label(match[2]))
+      text ||= "#{label} at <code>#{convert_string(context_name)}</code>" if context_name
+      text ||= label
       code = false
     else
-      text ||= name
+      text ||= convert_string(display)
     end
 
-    link lookup, text, code, rdoc_ref: rdoc_ref
+    link(name, text, code, rdoc_ref: rdoc_ref)
   end
 
   ##
@@ -80,10 +83,9 @@ 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
-
-    return name if @options.autolink_excluded_words&.include?(name)
+  def handle_regexp_CROSSREF(name)
+    return convert_string(name) if in_tidylink_label?
+    return name if @autolink_excluded_words&.include?(name)
 
     return name if name =~ /@[\w-]+\.[\w-]/ # labels that look like emails
 
@@ -93,20 +95,20 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
       # cross-references to "new" in text, for instance)
       return name if name =~ /\A[a-z]*\z/
     end
-
-    cross_reference name, rdoc_ref: false
+    cross_reference(name, rdoc_ref: false) || convert_string(name)
   end
 
   ##
   # 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:/
-      cross_reference $', rdoc_ref: true
+      ref = $'
+      cross_reference(ref, rdoc_ref: true) || convert_string(ref)
     else
       super
     end
@@ -120,12 +122,15 @@ 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
+        ref = $'
+        cross_reference(ref, rdoc_ref: true) || convert_string(ref)
+      end
     else
       super
     end
@@ -138,138 +143,119 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   def gen_url(url, text)
     if url =~ /\Ardoc-ref:/
       name = $'
-      cross_reference name, text, name == text, rdoc_ref: true
+      cross_reference(name, text, name == text, rdoc_ref: true) || text
     else
       super
     end
   end
 
   ##
-  # Creates an HTML link to +name+ with the given +text+.
+  # Creates an HTML link to +name+ with the given +html_string+.
+  # +html_string+ should be already escaped and may contain HTML tags.
+  # Returns the link HTML string, or +nil+ if the reference could not be resolved.
 
-  def link(name, text, code = true, rdoc_ref: false)
+  def link(name, html_string, code = true, rdoc_ref: false)
     if !(name.end_with?('+@', '-@')) and name =~ /(.*[^#:])?@/
       name = $1
       label = $'
     end
 
-    ref = @cross_reference.resolve name, text if name
+    ref = @cross_reference.resolve name if name
 
-    case ref
-    when String then
-      if rdoc_ref && @options.warn_missing_rdoc_ref
-        puts "#{@from_path}: `rdoc-ref:#{name}` can't be resolved for `#{text}`"
-      end
-      ref
-    else
-      path = ref ? ref.as_href(@from_path) : +""
+    # Non-text source files (C, Ruby, etc.) don't get HTML pages generated,
+    # so don't auto-link to them. Explicit rdoc-ref: links are still allowed.
+    if !rdoc_ref && RDoc::TopLevel === ref && !ref.text?
+      return
+    end
+
+    if ref
+      path = ref.as_href(@from_path)
 
       if code and RDoc::CodeObject === ref and !(RDoc::TopLevel === ref)
-        text = "<code>#{CGI.escapeHTML text}</code>"
+        html_string = "<code>#{html_string}</code>"
       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 << "-#{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}-#{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 << "##{formatted_label}"
-        end
+    elsif name
+      if rdoc_ref && @warn_missing_rdoc_ref
+        puts "#{@from_path}: `rdoc-ref:#{name}` can't be resolved for `#{html_string}`"
       end
-
-      "<a href=\"#{path}\">#{text}</a>"
+      return
+    else
+      # A bare label reference like @foo still produces a valid anchor link
+      return unless label
+      path = +""
     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
-
-        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
+    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 << "-#{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}-#{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
-        raise "Unknown flow element: #{item.inspect}"
+        path << "##{formatted_label}"
       end
     end
 
-    res.join('')
+    "<a href=\"#{path}\">#{html_string}</a>"
   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)
-
-    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/)
+  def handle_TT(code)
+    emit_inline(tt_cross_reference(code) || "<code>#{convert_string(code)}</code>")
+  end
 
-    text = cross_reference(string)
-    return if text == string
+  # 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
+  end
 
-    text
+  # Handles cross-reference and suppressed-crossref inside tt tag.
+  # Returns nil if code is not an existing cross-reference nor a suppressed-crossref.
+  def tt_cross_reference(code)
+    return if in_tidylink_label?
+
+    crossref_regexp = @hyperlink_all ? ALL_CROSSREF_REGEXP : CROSSREF_REGEXP
+    # REGEXP sometimes matches a string that starts with a backslash but is not a
+    # suppressed cross-reference (for example, `\+`), so the backslash-removed
+    # part needs to be checked against crossref_regexp.
+    match = crossref_regexp.match(code.delete_prefix('\\'))
+    return unless match && match.begin(1).zero?
+    return unless match.post_match.match?(/\A[[:punct:]\s]*\z/)
+
+    # cross_reference(file_page) may return a link without code tag.
+    # We need to check it because this method shouldn't return an html text without code tag.
+    if code.start_with?('\\')
+      # Remove leading backslash if crossref exists
+      "<code>#{convert_string(code[1..])}</code>" if cross_reference(code[1..])&.include?('<code>')
+    else
+      html = cross_reference(code)
+      html if html&.include?('<code>')
+    end
   end
 end

data/lib/rdoc/markup/to_html_snippet.rb

@@ -34,8 +34,8 @@ class RDoc::Markup::ToHtmlSnippet < RDoc::Markup::ToHtml
   # next word boundary after the given number of +characters+ or +paragraphs+
   # of text have been encountered.
 
-  def initialize(options, characters = 100, paragraphs = 3, markup = nil)
-    super options, markup
+  def initialize(characters = 100, paragraphs = 3)
+    super()
 
     @character_limit = characters
     @paragraph_limit = paragraphs
@@ -107,9 +107,9 @@ class RDoc::Markup::ToHtmlSnippet < RDoc::Markup::ToHtml
   def accept_verbatim(verbatim)
     throw :done if @characters >= @character_limit
     input = verbatim.text.rstrip
-
-    text = truncate input
-    text << ' ...' unless text == input
+    text = truncate(input, @character_limit - @characters)
+    @characters += input.length
+    text << " #{TO_HTML_CHARACTERS[text.encoding][:ellipsis]}" unless text == input
 
     super RDoc::Markup::Verbatim.new text
 
@@ -128,16 +128,8 @@ class RDoc::Markup::ToHtmlSnippet < RDoc::Markup::ToHtml
   ##
   # Removes escaping from the cross-references in +target+
 
-  def handle_regexp_CROSSREF(target)
-    target.text.sub(/\A\\/, '')
-  end
-
-  ##
-  # +target+ is a <code><br></code>
-
-  def handle_regexp_HARD_BREAK(target)
-    @characters -= 4
-    '<br>'
+  def handle_regexp_CROSSREF(text)
+    text.sub(/\A\\/, '')
   end
 
   ##
@@ -212,74 +204,82 @@ class RDoc::Markup::ToHtmlSnippet < RDoc::Markup::ToHtml
     end_accepting
   end
 
-  ##
-  # Converts flow items +flow+
+  def handle_PLAIN_TEXT(text) # :nodoc:
+    return if inline_limit_reached?
 
-  def convert_flow(flow)
-    throw :done if @characters >= @character_limit
+    truncated = truncate(text, @inline_character_limit)
+    @inline_character_limit -= text.size
+    emit_inline(convert_string(truncated))
+  end
 
-    res = []
-    @mask = 0
-
-    flow.each do |item|
-      case item
-      when RDoc::Markup::AttrChanger then
-        off_tags res, item
-        on_tags  res, item
-      when String then
-        text = convert_string item
-        res << truncate(text)
-      when RDoc::Markup::RegexpHandling then
-        text = convert_regexp_handling item
-        res << truncate(text)
-      else
-        raise "Unknown flow element: #{item.inspect}"
-      end
-
-      if @characters >= @character_limit then
-        off_tags res, RDoc::Markup::AttrChanger.new(0, @mask)
-        break
-      end
-    end
+  def handle_REGEXP_HANDLING_TEXT(text) # :nodoc:
+    return if inline_limit_reached?
 
-    res << ' ...' if @characters >= @character_limit
+    # We can't truncate text including html tags.
+    # Just emit as is, and count all characters including html tag part.
+    emit_inline(text)
+    @inline_character_limit -= text.size
+  end
 
-    res.join
+  def handle_BOLD(nodes)
+    super unless inline_limit_reached?
   end
 
-  ##
-  # Maintains a bitmask to allow HTML elements to be closed properly.  See
-  # RDoc::Markup::Formatter.
+  def handle_BOLD_WORD(word)
+    super unless inline_limit_reached?
+  end
 
-  def on_tags(res, item)
-    @mask ^= item.turn_on
+  def handle_EM(nodes)
+    super unless inline_limit_reached?
+  end
 
-    super
+  def handle_EM_WORD(word)
+    super unless inline_limit_reached?
   end
 
-  ##
-  # Maintains a bitmask to allow HTML elements to be closed properly.  See
-  # RDoc::Markup::Formatter.
+  def handle_TT(code)
+    super unless inline_limit_reached?
+  end
 
-  def off_tags(res, item)
-    @mask ^= item.turn_off
+  def handle_STRIKE(nodes)
+    super unless inline_limit_reached?
+  end
 
-    super
+  def handle_HARD_BREAK
+    super unless inline_limit_reached?
   end
 
-  ##
-  # Truncates +text+ at the end of the first word after the character_limit.
+  def handle_TIDYLINK(label_part, url)
+    traverse_inline_nodes(label_part) unless inline_limit_reached?
+  end
 
-  def truncate(text)
-    length = text.length
-    characters = @characters
-    @characters += length
+  def inline_limit_reached?
+    @inline_character_limit <= 0
+  end
 
-    return text if @characters < @character_limit
+  def handle_inline(text)
+    limit = @character_limit - @characters
+    return ['', 0] if limit <= 0
+    @inline_character_limit = limit
+    res = super
+    res << " #{TO_HTML_CHARACTERS[text.encoding][:ellipsis]}" if @inline_character_limit <= 0
+    @characters += limit - @inline_character_limit
+    res
+  end
+
+  def to_html(item)
+    throw :done if @characters >= @character_limit
+    handle_inline(item)
+  end
+
+  ##
+  # Truncates +text+ at the end of the first word after the limit.
 
-    remaining = @character_limit - characters
+  def truncate(text, limit)
+    return text if limit >= text.size
+    return '' if limit <= 0
 
-    text =~ /\A(.{#{remaining},}?)(\s|$)/m # TODO word-break instead of \s?
+    text =~ /\A(.{#{limit},}?)(\s|$)/m # TODO word-break instead of \s?
 
     $1
   end

data/lib/rdoc/markup/to_joined_paragraph.rb

@@ -8,11 +8,6 @@
 # other markup syntax items will not work.
 
 class RDoc::Markup::ToJoinedParagraph < RDoc::Markup::Formatter
-
-  def initialize # :nodoc:
-    super nil
-  end
-
   def start_accepting # :nodoc:
   end
 

data/lib/rdoc/markup/to_label.rb

@@ -14,24 +14,37 @@ class RDoc::Markup::ToLabel < RDoc::Markup::Formatter
   ##
   # Creates a new formatter that will output HTML-safe labels
 
-  def initialize(markup = nil)
-    super nil, markup
+  def initialize
+    super
 
     @markup.add_regexp_handling RDoc::CrossReference::CROSSREF_REGEXP, :CROSSREF
-    @markup.add_regexp_handling(/(((\{.*?\})|\b\S+?)\[\S+?\])/, :TIDYLINK)
 
-    add_tag :BOLD, '', ''
-    add_tag :TT,   '', ''
-    add_tag :EM,   '', ''
+    @res = []
+  end
+
+  def handle_PLAIN_TEXT(text)
+    @res << text
+  end
+
+  def handle_REGEXP_HANDLING_TEXT(text)
+    @res << text
+  end
+
+  def handle_TT(text)
+    @res << text
+  end
 
+  def extract_plaintext(text)
     @res = []
+    handle_inline(text)
+    @res.join
   end
 
   ##
   # Converts +text+ to an HTML-safe label using GitHub-style anchor formatting.
 
   def convert(text)
-    label = convert_flow @am.flow text
+    label = extract_plaintext(text)
 
     RDoc::Text.to_anchor(label)
   end
@@ -41,7 +54,7 @@ class RDoc::Markup::ToLabel < RDoc::Markup::Formatter
   # Used for generating backward-compatible anchor aliases.
 
   def convert_legacy(text)
-    label = convert_flow @am.flow text
+    label = extract_plaintext(text)
 
     CGI.escape(label).gsub('%', '-').sub(/^-/, '')
   end
@@ -50,23 +63,10 @@ class RDoc::Markup::ToLabel < RDoc::Markup::Formatter
   # Converts the CROSSREF +target+ to plain text, removing the suppression
   # marker, if any
 
-  def handle_regexp_CROSSREF(target)
-    text = target.text
-
+  def handle_regexp_CROSSREF(text)
     text.sub(/^\\/, '')
   end
 
-  ##
-  # Converts the TIDYLINK +target+ to just the text part
-
-  def handle_regexp_TIDYLINK(target)
-    text = target.text
-
-    return text unless text =~ /\{(.*?)\}\[(.*?)\]/ or text =~ /(\S+)\[(.*?)\]/
-
-    $1
-  end
-
   alias accept_blank_line         ignore
   alias accept_block_quote        ignore
   alias accept_heading            ignore
@@ -79,7 +79,6 @@ class RDoc::Markup::ToLabel < RDoc::Markup::Formatter
   alias accept_rule               ignore
   alias accept_verbatim           ignore
   alias end_accepting             ignore
-  alias handle_regexp_HARD_BREAK  ignore
   alias start_accepting           ignore
 
 end