rdoc-markdown 0.21.2 → 0.22.0

data/lib/rdoc/generator/markdown/inline.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+class RDoc::Generator::Markdown
+  # Native ToMarkdown inline callbacks and explicit-link label boundaries.
+  module Inline
+    # Escapes plain content without changing inline code or resolved references.
+    # @param text [String] Literal content.
+    # @return [String] GFM text.
+    def convert_string(text)
+      # Final definition HTML keeps literal backslashes before semicolons.
+      text = text.gsub("\\;") { "\\\\;" } if definition_body
+      Syntax.escape(text)
+    end
+
+    # Emits a plain-text node from RDoc's inline parser.
+    # @param text [String] Literal content.
+    # @return [void]
+    def handle_PLAIN_TEXT(text)
+      emit_inline(convert_string(text))
+    end
+
+    # Emits inline code, resolving only valid reference syntax outside link labels.
+    # @param text [String] Literal code.
+    # @return [void]
+    def handle_TT(text)
+      emit_inline(code_reference(text) || Syntax.code(text))
+    end
+
+    # Emits a tidy link without permitting nested links in its label.
+    # @param nodes [Array<String, Hash>] Native inline label nodes.
+    # @param url [String] Link target.
+    # @return [void]
+    def handle_TIDYLINK(nodes, url)
+      first = nodes.first
+      label = if nodes.size == 1 && String === first && first.match?(/\A[*^]\d+\z/)
+        first[1..]
+      else
+        dup.inline_nodes(nodes)
+      end
+      emit_inline(gen_url(url, label))
+    end
+
+    # Renders a label in an independent native inline buffer.
+    # @param nodes [Array<String, Hash>] Native inline label nodes.
+    # @return [String] Inline Markdown.
+    def inline_nodes(nodes)
+      @inline_output = +""
+      @in_link = true
+      @quote_converter ||= RDoc::Markup::ToHtml::QuoteConverter.new
+      traverse_inline_nodes(nodes)
+      @inline_output
+    end
+
+    # Uses RDoc's text-only quote policy without routing nodes through ToHtml.
+    # @param text [String] Inline RDoc source.
+    # @return [String] Inline Markdown with main's punctuation.
+    def handle_inline(text)
+      @quote_converter = RDoc::Markup::ToHtml::QuoteConverter.new
+      @markdown_links = MarkdownLinks.new(text)
+      super(@markdown_links.source)
+    end
+
+    # Emits protected Markdown links and literal tag-like code without nested links.
+    # @param token [String] Protected Markdown token or literal user input.
+    # @return [String] Native Markdown or escaped literal text.
+    def handle_regexp_markdown(token)
+      link = @markdown_links&.[](token)
+      return token unless link
+
+      node = link.node
+      type = node.type
+      return Syntax.code(node.string_content) if type == :code
+
+      label = dup.markdown_label(link.label)
+      link_node = type == :link
+      target = rendering.reference.resolve(node.url) if link_node
+      node.url = target.as_href(rendering.context.path) if target && emitted_reference?(target)
+      (in_link_label? && link_node) ? label : MarkdownLinks.render(link, label)
+    end
+
+    # Parses an original Markdown label with RDoc's surrounding inline semantics.
+    # @param text [String] Original link label source.
+    # @return [String] Inline Markdown without automatic nested links.
+    def markdown_label(text)
+      @markdown_links = MarkdownLinks.new(text)
+      inline_nodes(RDoc::Markup::InlineParser.new(@markdown_links.source).parse)
+    end
+
+    # Preserves the typography aliases used by RDoc's HTML formatter.
+    # @param text [String] Matched punctuation or symbol shorthand.
+    # @return [String] Unicode punctuation with RDoc's encoding fallback.
+    def handle_regexp_HTML_CHARACTERS(text)
+      name = RDoc::Markup::ToHtml::HTML_CHARACTER_ALIASES.fetch(text)
+      RDoc::Markup::ToHtml::TO_HTML_CHARACTERS[text.encoding].fetch(name)
+    end
+
+    # Converts quotes adjacent to words using RDoc's paragraph-scoped state.
+    # @param text [String] Matched quote.
+    # @return [String] Converted quote or escaped literal.
+    def handle_regexp_QUOTE_AFTER_WORD(text)
+      @quote_converter.convert(text, after_word: true) || convert_string(text)
+    end
+
+    # Converts quotes not adjacent to words using the same paragraph state.
+    # @param text [String] Matched quote.
+    # @return [String] Converted quote or escaped literal.
+    def handle_regexp_QUOTE_NOT_AFTER_WORD(text)
+      @quote_converter.convert(text, after_word: false) || convert_string(text)
+    end
+
+    # Escapes the visible part after RDoc's selective cross-reference suppression.
+    # @param text [String] Suppressed reference prefix.
+    # @return [String] Literal Markdown without the suppression backslash.
+    def handle_regexp_SUPPRESSED_CROSSREF(text)
+      convert_string(text.delete_prefix("\\"))
+    end
+
+    # Indicates the inline-only boundary where nested links are prohibited.
+    # @return [Boolean] Whether this visitor renders an explicit link label.
+    def in_link_label?
+      @in_link
+    end
+
+    # Formats native URL schemes and explicit RDoc references.
+    # @param url [String] RDoc target.
+    # @param label [String] Inline Markdown label.
+    # @return [String] Markdown link, image, or unresolved label.
+    def gen_url(url, label)
+      return explicit_reference(url.delete_prefix("rdoc-ref:"), label) if url.start_with?("rdoc-ref:")
+      return label_reference(url, label) if url.start_with?("rdoc-label:")
+
+      _, target, = parse_url(url)
+      unless target.match?(%r{\A(?:[a-z][a-z0-9+.-]*:|//|www\.|#)}i)
+        # Like page output paths, every dot in the file name becomes an underscore.
+        target = target.sub(%r{[^/]+\.(?:rb|rdoc)(?=[#?]|\z)}i) { |name| "#{name.tr(".", "_")}.md" }
+      end
+      return "![](#{target})" if target.match?(/\Ahttps?:.+\.(?:png|gif|jpe?g|bmp)\z/)
+
+      Syntax.link(label, target)
+    end
+
+    private
+
+    # Keeps the optional source anchor without parsing HTML attribute strings.
+    # @param url [String] Native rdoc-label URL.
+    # @param label [String] Inline Markdown label.
+    # @return [String] Anchored Markdown reference.
+    def label_reference(url, label)
+      target, id = url.delete_prefix("rdoc-label:").split(":", 2)
+      if id&.start_with?("foot")
+        return %(<sup><a id="#{CGI.escapeHTML(id)}" href="##{CGI.escapeHTML(target)}">#{label}</a></sup>)
+      end
+      anchor = Syntax.anchor(id) if id
+      "#{anchor}#{Syntax.link(label, "##{target}")}"
+    end
+
+    # Registers native reference handlers on the markup instance initialized by super.
+    # @return [void]
+    def configure_inline
+      @in_link = false
+      @markup.add_regexp_handling(/\0RDocMarkdownX*\d+\0/, :markdown)
+      # ToRdoc suppresses every backslash escape; main suppresses only references.
+      @markup.regexp_handlings.reject! { |_, name| name == :SUPPRESSED_CROSSREF }
+      @markup.add_regexp_handling(/\\(?:[#:A-Z]|[a-z]+_[a-z0-9])/, :SUPPRESSED_CROSSREF)
+      @markup.add_regexp_handling(/(?:link:|https?:|mailto:|ftp:|irc:|www\.)#{RDoc::Markup::ToHtml::URL_CHARACTERS_REGEXP_STR}+\w/o, :HYPERLINK)
+      @markup.add_regexp_handling(Regexp.union(RDoc::Markup::ToHtml::HTML_CHARACTER_ALIASES.keys), :HTML_CHARACTERS)
+      @markup.add_regexp_handling(/\b['"`]/, :QUOTE_AFTER_WORD)
+      @markup.add_regexp_handling(/\B['"`]/, :QUOTE_NOT_AFTER_WORD)
+      @markup.add_regexp_handling(RDoc::CrossReference::CROSSREF_REGEXP, :CROSSREF)
+      @markup.add_regexp_handling(RDoc::CrossReference::ALL_CROSSREF_REGEXP, :CROSSREF) if options.hyperlink_all
+    end
+  end
+end

data/lib/rdoc/generator/markdown/inline_html.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+class RDoc::Generator::Markdown
+  # Emits final inline HTML inside definition containers, without HTML conversion.
+  class InlineHtml
+    # Native inline formatting tags; transparent AST containers have no wrapper.
+    TAGS = {document: nil, paragraph: nil, escaped: nil, emph: "em", strong: "strong", strikethrough: "del"}.freeze
+
+    # Serializes only inline syntax already produced by the native formatter.
+    # @param markdown [String] Escaped native inline Markdown.
+    # @return [String] Final inline HTML, with no paragraph wrapper.
+    def self.render(markdown)
+      new.render_node(Commonmarker.parse(markdown.encode(Encoding::UTF_8), options: {extension: {autolink: false}}))
+    end
+
+    # Emits one parsed inline node and its children.
+    # @param node [Commonmarker::Node] Native inline syntax node.
+    # @return [String] Final inline HTML.
+    def render_node(node)
+      type = node.type
+      case type
+      when :text, :code
+        text = CGI.escapeHTML(node.string_content)
+        (type == :code) ? "<code>#{text}</code>" : text
+      when :html_inline then node.to_commonmark.delete_suffix("\n")
+      when :softbreak then "\n"
+      when :linebreak then "<br>\n"
+      when :image then image(node)
+      else
+        content = node.map { |child| render_node(child) }.join
+        return %(<a href="#{CGI.escapeHTML(node.url)}"#{title(node)}>#{content}</a>) if type == :link
+
+        tag = TAGS.fetch(type)
+        tag ? "<#{tag}>#{content}</#{tag}>" : content
+      end
+    end
+
+    private
+
+    # An image's alt text is plain text, including formatted labels' contents.
+    # @param node [Commonmarker::Node] Image node.
+    # @return [String] Final image HTML.
+    def image(node)
+      alt = Syntax.node_text(node)
+      %(<img src="#{CGI.escapeHTML(node.url)}" alt="#{CGI.escapeHTML(alt)}"#{title(node)}>)
+    end
+
+    # Escapes optional titles independently from the link or image destination.
+    # @param node [Commonmarker::Node] Link or image node.
+    # @return [String] Optional HTML title attribute.
+    def title(node)
+      value = node.title
+      %( title="#{CGI.escapeHTML(value)}") unless value.empty?
+    end
+  end
+end

data/lib/rdoc/generator/markdown/markdown_links.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+class RDoc::Generator::Markdown
+  # Protects Markdown links and tag-like code while RDoc parses surrounding markup.
+  class MarkdownLinks
+    # Keeps the typed node and original RDoc label together at the boundary.
+    Link = Data.define(:node, :label)
+
+    # RDoc source with collision-free tokens protecting Markdown links and code.
+    # @return [String] Prepared inline RDoc source.
+    attr_reader :source
+
+    # Finds complete Markdown links without interpreting RDoc code tags as prose.
+    # @param text [String] Original inline RDoc source.
+    def initialize(text)
+      @source = text
+      @nodes = {}
+      return if !(text.include?("](") || (text.include?("`") && text.include?("<")))
+
+      @source = text.encode(Encoding::UTF_8)
+      @line_offsets = [0]
+      @source.each_line { |line| @line_offsets << @line_offsets.last + line.bytesize }
+      @literal_ranges = Syntax.native_literal_ranges(@source)
+      buffer = @source.b
+      inline_edits.reverse_each { |range, token| buffer[range] = token }
+      @source = buffer.force_encoding(Encoding::UTF_8)
+    end
+
+    # Looks up only tokens created for this exact input.
+    # @param token [String] Inline parser token.
+    # @return [Link, nil] Protected Markdown node and its original label.
+    def [](token)
+      @nodes[token]
+    end
+
+    # Serializes a typed link, retaining titles and destination escaping.
+    # @param link [Link] Original link or image node.
+    # @param label [String] Natively formatted inline Markdown label.
+    # @return [String] Inline Markdown, never rendered HTML.
+    def self.render(link, label)
+      original = link.node
+      prefix = "!" if original.type == :image
+      node = Commonmarker.parse("#{prefix}[#{label}](markdown-target)").first_child.first_child
+      node.url = Syntax.target(original.url)
+      node.title = original.title
+      node.to_commonmark.delete_suffix("\n")
+    end
+
+    private
+
+    # Uses source byte positions; inline nodes inside outer links stay together.
+    # @return [Array<Array(Range, String)>] Nonoverlapping source replacements.
+    def inline_edits
+      prefix = "RDocMarkdown"
+      prefix += "X" while @source.include?(prefix)
+      edits = []
+      covered_until = nil
+      Commonmarker.parse(@source).walk do |node|
+        range = inline_range(node)
+        next if !range || (covered_until && range.begin < covered_until)
+
+        token = "\0#{prefix}#{@nodes.length}\0"
+        @nodes[token] = Link.new(node, original_label(node))
+        edits << [range, token]
+        covered_until = range.end
+      end
+      edits
+    end
+
+    # Keeps native RDoc links and code-tag boundaries ahead of Markdown spans.
+    # @param node [Commonmarker::Node] Candidate Markdown node.
+    # @return [Range<Integer>, nil] Replaceable Markdown link or tag-like code range.
+    def inline_range(node)
+      type = node.type
+      return unless [:link, :image, :code].include?(type)
+      return if type == :code && !node.string_content.include?("<")
+
+      range = Syntax.source_range(node, @line_offsets)
+      first = range.begin
+      bytes = @source.b
+      return unless bytes[range].start_with?("[", "![", "`")
+
+      previous = bytes[first - 1] unless first.zero?
+      return if type == :link && previous&.match?(/[A-Za-z0-9}]/)
+      return if Syntax.literal_position?(@literal_ranges, first)
+
+      range
+    end
+
+    # Retains RDoc label formatting instead of changing its emphasis conventions.
+    # @param node [Commonmarker::Node] Markdown link or image.
+    # @return [String] Label source, including native formatting delimiters.
+    def original_label(node)
+      children = node.to_a
+      return "" if children.empty?
+
+      range = Syntax.source_range(children.first, @line_offsets).begin...Syntax.source_range(children.last, @line_offsets).end
+      @source.b[range].force_encoding(Encoding::UTF_8)
+    end
+  end
+end

data/lib/rdoc/generator/markdown/paths.rb

@@ -2,15 +2,6 @@
 
 # Resolves source and generated documentation paths.
 module RDoc::Generator::Markdown::Paths
-  # Converts a qualified object name into a Markdown path.
-  #
-  # @param class_name [String] Qualified class or module name.
-  #
-  # @return [String] Relative Markdown path.
-  def turn_to_path(class_name)
-    "#{class_name.gsub("::", "/")}.md"
-  end
-
   # Builds the Markdown output path for an RDoc page.
   #
   # @param page [RDoc::TopLevel] Page object to render.
@@ -18,7 +9,7 @@ module RDoc::Generator::Markdown::Paths
   # @return [String] Relative Markdown path.
   def page_output_path(page)
     relative_name = page.relative_name
-    source_path = normalize_input_path_for_output(relative_name)
+    source_path = RDoc::Generator::Markdown::Paths.normalize_input_path(relative_name, source_dir)
     return source_path if relative_name.match?(/\.(?:md|markdown)\z/i)
 
     dirname = File.dirname(source_path)
@@ -35,26 +26,13 @@ module RDoc::Generator::Markdown::Paths
   #
   # @return [String] Relative Markdown path.
   def output_path_for(code_object)
-    turn_to_path(code_object.full_name)
-  end
-
-  # Rewrites local Markdown links relative to the current output file.
-  #
-  # @param markdown [String] Markdown content.
-  # @param current_output_path [String] Output path for the file being written.
-  #
-  # @return [String] Markdown with normalized internal links.
-  def normalize_internal_links(markdown, current_output_path:)
-    RDoc::Generator::Markdown::Paths.rewrite_internal_links(
-      markdown,
-      current_output_path,
-      generation_state
-    )
+    "#{code_object.full_name.gsub("::", "/")}.md"
   end
 
-  private :turn_to_path, :page_output_path, :output_path_for, :normalize_internal_links
+  private :page_output_path, :output_path_for
 
   # Rewrites links using explicit generated-path state.
+  # Code spans and fences are skipped; prose backticks are always escaped.
   #
   # @param markdown [String] Markdown content.
   # @param current_output_path [String] Output path for the current file.
@@ -64,8 +42,10 @@ module RDoc::Generator::Markdown::Paths
   def self.rewrite_internal_links(markdown, current_output_path, state)
     current_dir = Pathname.new(current_output_path).dirname
 
-    markdown.gsub(%r{\]\(([^)]+)\)}) do
-      target = Regexp.last_match(1)
+    markdown.gsub(/(?<!\\)(`+).+?\1|\]\(([^)]+)\)/m) do
+      next $& if $1
+
+      target = $2
       path = target.sub(/[?#].*\z/, "")
       suffix = target[path.length..]
 
@@ -95,27 +75,16 @@ module RDoc::Generator::Markdown::Paths
         .find { |candidate| state.known_output_paths.include?(candidate) }
   end
 
-  # Normalizes an input filename into an output-relative source path.
-  #
-  # @param path [String] RDoc input path.
-  #
-  # @return [String] Normalized path without root prefixes.
-  def normalize_input_path_for_output(path)
-    RDoc::Generator::Markdown::Paths.normalize_input_path(path, source_dir)
-  end
-
-  private :normalize_input_path_for_output
-
   # Normalizes an input path against an explicit source directory.
   #
   # @param path [String] RDoc input path.
   # @param source_dir [String] Absolute documentation source directory.
   #
-  # @return [String] Normalized path without root prefixes.
+  # @return [String] Normalized path without root or parent-directory prefixes.
   def self.normalize_input_path(path, source_dir)
     normalized = path.tr("\\", "/").sub(%r{\A\./}, "")
     normalized = normalized.sub(%r{\A#{Regexp.escape(source_dir)}/}, "")
-    normalized = normalized.sub(%r{\A/}, "")
+    normalized = normalized.sub(%r{\A(?:\.\./|/)+}, "")
 
     root_basename = File.basename(source_dir)
     normalized.sub(%r{\A#{Regexp.escape(root_basename)}/}, "")

data/lib/rdoc/generator/markdown/references.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+class RDoc::Generator::Markdown
+  # Native reference policy, independent of HTML rendering and output buffers.
+  module References
+    # Options attached to the RDoc context being documented.
+    # @return [RDoc::Options] Current options.
+    def options
+      rendering.context.options
+    end
+
+    # Resolves automatic references outside explicit link labels.
+    # @param name [String] Reference candidate.
+    # @return [String] Linked or literal Markdown.
+    def handle_regexp_CROSSREF(name)
+      text = convert_string(name)
+      return text if in_link_label? || options.autolink_excluded_words&.include?(name)
+      return text if name.match?(/@[\w-]+\.[\w-]/)
+
+      reference_link(name) || ((name.include?("#") && !name.start_with?("#")) ? Syntax.code(name) : text)
+    end
+
+    # Formats automatic URLs without linking URLs inside link labels.
+    # @param url [String] URL candidate.
+    # @return [String] Linked or literal Markdown.
+    def handle_regexp_HYPERLINK(url)
+      return convert_string(url) if in_link_label?
+
+      label = convert_string(url.sub(%r{\A(?:link|https?|mailto|ftp|irc):/*}, ""))
+      gen_url(url, label)
+    end
+
+    # Resolves explicit rdoc-ref schemes; other schemes use ToMarkdown.
+    # @param url [String] RDoc URL.
+    # @return [String] Native Markdown.
+    def handle_regexp_RDOCLINK(url)
+      return super unless url.start_with?("rdoc-ref:")
+
+      name = url.delete_prefix("rdoc-ref:")
+      in_link_label? ? convert_string(name) : explicit_reference(name)
+    end
+
+    # Reports missing explicit references and retains their visible labels.
+    # @param name [String] Reference name.
+    # @param label [String, nil] Optional native label.
+    # @return [String] Reference or visible fallback.
+    def explicit_reference(name, label = nil)
+      found = reference_link(name, label: label)
+      return found if found
+
+      text = label || convert_string(name)
+      puts "#{rendering.context.path}: `rdoc-ref:#{name}` can't be resolved for `#{text}`" if options.warn_missing_rdoc_ref
+      text
+    end
+
+    # Resolves a reference only when its owning page is emitted.
+    # @param name [String] Reference name.
+    # @param label [String, nil] Optional native label.
+    # @return [String, nil] Native link, unlinked code, or an unresolved reference.
+    def reference_link(name, label: nil)
+      target_name, section = split_reference(name)
+      local = target_name.empty?
+      ref = rendering.reference.resolve(target_name)
+      return if !ref && !(local && section)
+
+      text = reference_text(name, label, ref)
+      return text if ref && !emitted_reference?(ref)
+
+      path = ref ? ref.as_href(rendering.context.path) : ""
+      path = reference_section(path, ref, section) if section
+      Syntax.link(text, path)
+    end
+
+    private
+
+    # Main keeps file references inside code spans literal, not prose links.
+    # @param text [String] Inline code candidate.
+    # @return [String, nil] Code-formatted object link or literal-code fallback.
+    def code_reference(text)
+      return if in_link_label?
+
+      name = text.delete_prefix("\\")
+      return unless code_reference_syntax?(name)
+
+      target_name, = split_reference(name)
+      return if RDoc::TopLevel === rendering.reference.resolve(target_name)
+
+      linked = reference_link(name)
+      text.start_with?("\\") ? (Syntax.code(name) if linked) : linked
+    end
+
+    # Separates inline-code display policy from target resolution.
+    # @param name [String] Reference name.
+    # @param label [String, nil] Explicit native label.
+    # @param ref [RDoc::CodeObject, nil] Resolved target.
+    # @return [String] Native inline Markdown.
+    def reference_text(name, label, ref)
+      display = options.show_hash ? name : name.delete_prefix("#")
+      target, section = split_reference(display)
+      if section
+        return label if label
+
+        title = convert_string(RDoc::Text.decode_legacy_label(section))
+        return target.empty? ? title : "#{title} at #{Syntax.code(target)}"
+      end
+
+      plain = label ? label.delete("\\") : display
+      text = label || convert_string(display)
+      (!(RDoc::TopLevel === ref) && (!label || plain == name)) ? Syntax.code(plain) : text
+    end
+
+    # Matches both explicit method hashes and hyperlink-all method notation.
+    # @param name [String] Complete inline code text without suppression.
+    # @return [Boolean] Whether a reference starts the span and consumes its words.
+    def code_reference_syntax?(name)
+      patterns = [RDoc::CrossReference::CROSSREF_REGEXP]
+      patterns << RDoc::CrossReference::ALL_CROSSREF_REGEXP if options.hyperlink_all
+      patterns.any? do |pattern|
+        match = pattern.match(name)
+        match&.begin(1) == 0 && match.post_match.match?(/\A[[:punct:]\s]*\z/)
+      end
+    end
+
+    # Separates heading labels without mistaking unary operator method names.
+    # @param name [String] Reference name.
+    # @return [String, Array(String, String, nil)] Target and optional heading label.
+    def split_reference(name)
+      return name if name.end_with?("+@", "-@")
+
+      target, separator, section = name.partition("@")
+      [target, (section unless separator.empty?)]
+    end
+
+    # Tests the owning page rather than the individual member's identity.
+    # @param ref [RDoc::CodeObject] Resolved target.
+    # @return [Boolean] Whether that target has a generated page.
+    def emitted_reference?(ref)
+      owner = ref
+      owner = owner.parent until RDoc::ClassModule === owner || RDoc::TopLevel === owner
+      rendering.output_ids.include?(owner.object_id)
+    end
+
+    # Applies RDoc's canonical method, named-section, and page heading anchors.
+    # @param path [String] Relative RDoc target.
+    # @param ref [RDoc::CodeObject, nil] Target or a local heading reference.
+    # @param section [String] Encoded heading label.
+    # @return [String] Anchored target.
+    def reference_section(path, ref, section)
+      decoded = RDoc::Text.decode_legacy_label(section)
+      slug = RDoc::Text.to_anchor(decoded)
+      return "#{path}-#{slug}" if path.include?("#")
+
+      named = ref.sections.find { |candidate| candidate.title == decoded } if ref
+      anchor = if named
+        named.aref
+      elsif RDoc::ClassModule === ref
+        "#{ref.aref}-#{slug}"
+      else
+        slug
+      end
+      "#{path}##{anchor}"
+    end
+  end
+end