rdoc 6.14.2 → 6.15.0

data/lib/rdoc/markup/to_html.rb

@@ -158,19 +158,16 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   def handle_regexp_TIDYLINK(target)
     text = target.text
 
-    return text unless
-      text =~ /^\{(.*)\}\[(.*?)\]$/ or text =~ /^(\S+)\[(.*?)\]$/
-
-    label = $1
-    url   = CGI.escapeHTML($2)
+    if tidy_link_capturing?
+      return finish_tidy_link(text)
+    end
 
-    if /^rdoc-image:/ =~ label
-      label = handle_RDOCLINK(label)
-    else
-      label = CGI.escapeHTML(label)
+    if text.start_with?('{') && !text.include?('}')
+      start_tidy_link text
+      return ''
     end
 
-    gen_url url, label
+    convert_complete_tidy_link(text)
   end
 
   # :section: Visitor
@@ -458,4 +455,153 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     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)
+  end
+end
+
+##
+# Formatter dedicated to rendering tidy link labels without mutating the
+# calling formatter's state.
+
+class RDoc::Markup::LinkLabelToHtml < RDoc::Markup::ToHtml
+  def self.render(label, options, from_path)
+    new(options, from_path).to_html(label)
+  end
+
+  def initialize(options, from_path = nil)
+    super(options)
+
+    self.from_path = from_path if from_path
+  end
 end

data/lib/rdoc/markup/to_html_crossref.rb

@@ -184,38 +184,35 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
     end
   end
 
-  def convert_flow(flow)
+  def convert_flow(flow_items, &block)
     res = []
 
     i = 0
-    while i < flow.size
-      item = flow[i]
-      i += 1
+    while i < flow_items.size
+      item = flow_items[i]
+
       case item
-      when RDoc::Markup::AttrChanger then
-        # Make "+Class#method+" a cross reference
-        if tt_tag?(item.turn_on) and
-          String === (str = flow[i]) and
-          RDoc::Markup::AttrChanger === flow[i+1] and
-          tt_tag?(flow[i+1].turn_off, true) and
-          (@options.hyperlink_all ? ALL_CROSSREF_REGEXP : CROSSREF_REGEXP).match?(str) and
-          (text = cross_reference str) != str
-        then
-          text = yield text, res if defined?(yield)
-          res << text
-          i += 2
+      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
-      when String then
+        on_tags  res, item
+        i += 1
+      when String
         text = convert_string(item)
-        text = yield text, res if defined?(yield)
-        res << text
-      when RDoc::Markup::RegexpHandling then
+        text = block.call(text, res) if block
+        append_flow_fragment res, text
+        i += 1
+      when RDoc::Markup::RegexpHandling
         text = convert_regexp_handling(item)
-        text = yield text, res if defined?(yield)
-        res << text
+        text = block.call(text, res) if block
+        append_flow_fragment res, text
+        i += 1
       else
         raise "Unknown flow element: #{item.inspect}"
       end
@@ -223,4 +220,37 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
 
     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)
+
+    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
+
+    text
+  end
 end

data/lib/rdoc/options.rb

@@ -327,7 +327,7 @@ class RDoc::Options
 
   ##
   # Warn if rdoc-ref links can't be resolved
-  # Default is +false+
+  # Default is +true+
 
   attr_accessor :warn_missing_rdoc_ref
 

data/lib/rdoc/ri/task.rb

@@ -26,8 +26,8 @@ require_relative '../task'
 #   require 'rdoc/ri/task'
 #
 #   RDoc::RI::Task.new do |ri|
-#     ri.main = 'README.rdoc'
-#     ri.rdoc_files.include 'README.rdoc', 'lib/**/*.rb'
+#     ri.main = 'README.md'
+#     ri.rdoc_files.include 'README.md', 'lib/**/*.rb'
 #   end
 #
 # For further configuration details see RDoc::Task.

data/lib/rdoc/store.rb

@@ -720,10 +720,10 @@ class RDoc::Store
   end
 
   ##
-  # Returns the RDoc::TopLevel that is a text file and has the given +name+
+  # Returns the RDoc::TopLevel that is a file and has the given +name+
 
   def page(name)
-    @text_files_hash.each_value.find do |file|
+    @files_hash.each_value.find do |file|
       file.page_name == name or file.base_name == name
     end
   end

data/lib/rdoc/task.rb

@@ -58,8 +58,8 @@ require 'rake/tasklib'
 #   require 'rdoc/task'
 #
 #   RDoc::Task.new do |rdoc|
-#     rdoc.main = "README.rdoc"
-#     rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+#     rdoc.main = "README.md"
+#     rdoc.rdoc_files.include("README.md", "lib/**/*.rb")
 #   end
 #
 # The +rdoc+ object passed to the block is an RDoc::Task object. See the
@@ -74,8 +74,8 @@ require 'rake/tasklib'
 #   require 'rdoc/task'
 #
 #   RDoc::Task.new :rdoc_dev do |rdoc|
-#     rdoc.main = "README.rdoc"
-#     rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+#     rdoc.main = "README.md"
+#     rdoc.rdoc_files.include("README.md", "lib/**/*.rb")
 #     rdoc.options << "--all"
 #   end
 #

data/lib/rdoc/version.rb

@@ -5,6 +5,6 @@ module RDoc
   ##
   # RDoc version you are using
 
-  VERSION = '6.14.2'
+  VERSION = '6.15.0'
 
 end

data/rdoc.gemspec

@@ -45,7 +45,7 @@ RDoc includes the +rdoc+ and +ri+ tools for generating and displaying documentat
     "History.rdoc",
     "LEGAL.rdoc",
     "LICENSE.rdoc",
-    "README.rdoc",
+    "README.md",
     "RI.md",
     "TODO.rdoc",
     "exe/rdoc",
@@ -60,7 +60,7 @@ RDoc includes the +rdoc+ and +ri+ tools for generating and displaying documentat
 
   s.files = (non_lib_files + template_files + lib_files).uniq
 
-  s.rdoc_options = ["--main", "README.rdoc"]
+  s.rdoc_options = ["--main", "README.md"]
   s.extra_rdoc_files += s.files.grep(%r[\A[^\/]+\.(?:rdoc|md)\z])
 
   s.required_ruby_version = Gem::Requirement.new(">= 2.6.0")
@@ -68,4 +68,5 @@ RDoc includes the +rdoc+ and +ri+ tools for generating and displaying documentat
 
   s.add_dependency 'psych', '>= 4.0.0'
   s.add_dependency 'erb'
+  s.add_dependency 'tsort'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rdoc
 version: !ruby/object:Gem::Version
-  version: 6.14.2
+  version: 6.15.0
 platform: ruby
 authors:
 - Eric Hodel
@@ -13,7 +13,7 @@ authors:
 - ITOYANAGI Sakura
 bindir: exe
 cert_chain: []
-date: 2025-07-03 00:00:00.000000000 Z
+date: 2025-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: psych
@@ -43,6 +43,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: tsort
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |
   RDoc produces HTML and command-line documentation for Ruby projects.
   RDoc includes the +rdoc+ and +ri+ tools for generating and displaying documentation from the command-line.
@@ -66,7 +80,7 @@ extra_rdoc_files:
 - History.rdoc
 - LEGAL.rdoc
 - LICENSE.rdoc
-- README.rdoc
+- README.md
 - RI.md
 - TODO.rdoc
 files:
@@ -77,7 +91,7 @@ files:
 - History.rdoc
 - LEGAL.rdoc
 - LICENSE.rdoc
-- README.rdoc
+- README.md
 - RI.md
 - TODO.rdoc
 - exe/rdoc
@@ -268,7 +282,7 @@ metadata:
   changelog_uri: https://github.com/ruby/rdoc/releases
 rdoc_options:
 - "--main"
-- README.rdoc
+- README.md
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement

data/README.rdoc

@@ -1,144 +0,0 @@
-= \RDoc - Ruby Documentation System
-
-home :: https://github.com/ruby/rdoc
-rdoc :: https://ruby.github.io/rdoc
-bugs :: https://github.com/ruby/rdoc/issues
-code quality :: https://codeclimate.com/github/ruby/rdoc
-
-== Description
-
-RDoc produces HTML and command-line documentation for Ruby projects.  RDoc
-includes the +rdoc+ and +ri+ tools for generating and displaying documentation
-from the command-line.
-
-== Generating Documentation
-
-Once installed, you can create documentation using the +rdoc+ command
-
-  $ rdoc [options] [names...]
-
-For an up-to-date option summary, type
-
-  $ rdoc --help
-
-A typical use might be to generate documentation for a package of Ruby
-source (such as RDoc itself).
-
-  $ rdoc
-
-This command generates documentation for all the Ruby and C source
-files in and below the current directory.  These will be stored in a
-documentation tree starting in the subdirectory +doc+.
-
-You can make this slightly more useful for your readers by having the
-index page contain the documentation for the primary file.  In our
-case, we could type
-
-  % rdoc --main README.rdoc
-
-You'll find information on the various formatting tricks you can use
-in comment blocks in the documentation this generates.
-
-RDoc uses file extensions to determine how to process each file.  File names
-ending +.rb+ and +.rbw+ are assumed to be Ruby source.  Files
-ending +.c+ are parsed as C files.  All other files are assumed to
-contain just Markup-style markup (with or without leading '#' comment
-markers).  If directory names are passed to RDoc, they are scanned
-recursively for C and Ruby source files only.
-
-To generate documentation using +rake+ see RDoc::Task[https://ruby.github.io/rdoc/RDoc/Task.html].
-
-To generate documentation programmatically:
-
-  gem 'rdoc'
-  require 'rdoc/rdoc'
-
-  options = RDoc::Options.new
-  options.files = ['a.rb', 'b.rb']
-  options.setup_generator 'darkfish'
-  # see RDoc::Options
-
-  rdoc = RDoc::RDoc.new
-  rdoc.document options
-  # see RDoc::RDoc
-
-You can specify the target files for document generation with +.document+ file in the project root directory.
-+.document+ file contains a list of file and directory names including comment lines starting with '#'.
-See https://github.com/ruby/rdoc/blob/master/.document as an example.
-
-== Writing Documentation
-
-To write documentation for RDoc place a comment above the class, module,
-method, constant, or attribute you want documented:
-
-  ##
-  # This class represents an arbitrary shape by a series of points.
-
-  class Shape
-
-    ##
-    # Creates a new shape described by a +polyline+.
-    #
-    # If the +polyline+ does not end at the same point it started at the
-    # first pointed is copied and placed at the end of the line.
-    #
-    # An ArgumentError is raised if the line crosses itself, but shapes may
-    # be concave.
-
-    def initialize polyline
-      # ...
-    end
-
-  end
-
-The default comment markup format is the RDoc::Markup format.
-TomDoc[rdoc-ref:RDoc::TomDoc], Markdown[rdoc-ref:RDoc::Markdown] and
-RD[rdoc-ref:RDoc::RD] format comments are also supported.  You can set the
-default comment format for your entire project by creating a
-<tt>.rdoc_options</tt> file.  See RDoc::Options@Saved+Options for instructions
-on creating one.  You can also set the comment format for a single file
-through the +:markup:+ directive, but this is only recommended if you wish to
-switch markup formats.  See RDoc::Markup@Other+directives.
-
-Comments can contain directives that tell RDoc information that it cannot
-otherwise discover through parsing.  See RDoc::Markup@Directives to control
-what is or is not documented, to define method arguments or to break up
-methods in a class by topic.  See RDoc::Parser::Ruby for directives used to
-teach RDoc about metaprogrammed methods.
-
-See RDoc::Parser::C for documenting C extensions with RDoc.
-
-To determine how well your project is documented run <tt>rdoc -C lib</tt> to
-get a documentation coverage report.  <tt>rdoc -C1 lib</tt> includes parameter
-names in the documentation coverage report.
-
-== Theme Options
-
-There are a few community-maintained themes for \RDoc:
-
-- rorvswild-theme-rdoc[https://github.com/BaseSecrete/rorvswild-theme-rdoc]
-- hanna[https://github.com/jeremyevans/hanna] (a fork maintained by {Jeremy Evans}[https://github.com/jeremyevans])
-
-Please follow the theme's README for usage instructions.
-
-== Bugs
-
-See CONTRIBUTING.rdoc for information on filing a bug report.  It's OK to file
-a bug report for anything you're having a problem with.  If you can't figure
-out how to make RDoc produce the output you like that is probably a
-documentation bug.
-
-== License
-
-RDoc is Copyright (c) 2001-2003 Dave Thomas, The Pragmatic Programmers.
-Portions (c) 2007-2011 Eric Hodel.  Portions copyright others, see individual
-files and LEGAL.rdoc for details.
-
-RDoc is free software, and may be redistributed under the terms specified in
-LICENSE.rdoc.
-
-== Warranty
-
-This software is provided "as is" and without any express or implied
-warranties, including, without limitation, the implied warranties of
-merchantability and fitness for a particular purpose.