Image alt tag header formatting (#1320)

This allows us to parse the alt text from Markdown images, formatting a
header text correctly (using the alt text).

Without this PR, if a Markdown file has an image instead of a title,
that image will be used in the table of contents, which is unreadable
and undesirable.

Used in <rack/rack#2313>.

---------

Co-authored-by: Stan Lo <[email protected]>

Author: ioquatix

lib/rdoc/markdown.kpeg

@@ -992,9 +992,14 @@ Strike = &{ strike? }
          "~~"
          { strike a.join }
 
-# TODO alt text support
-Image = "!" ( ExplicitLink | ReferenceLink ):a
-        { "rdoc-image:#{a[/\[(.*)\]/, 1]}" }
+Image = "!" ExplicitLink:a
+        {
+          # Extract alt text and URL
+          alt_text = a[/\{(.*?)\}/, 1] || ""
+          url = a[/\[(.*?)\]/, 1] || ""
+
+          "rdoc-image:#{url}:#{alt_text}"
+        }
 
 Link =  ExplicitLink | ReferenceLink | AutoLink
 

lib/rdoc/markup/heading.rb

@@ -66,7 +66,13 @@ def label context = nil
   # element.
 
   def plain_html
-    self.class.to_html.to_html(text.dup)
+    text = self.text.dup
+
+    if matched = text.match(/rdoc-image:[^:]+:(.*)/)
+      text = matched[1]
+    end
+
+    self.class.to_html.to_html(text)
   end
 
   def pretty_print q # :nodoc:

lib/rdoc/markup/to_html.rb

@@ -98,7 +98,12 @@ def handle_RDOCLINK url # :nodoc:
 
       gen_url CGI.escapeHTML(url), CGI.escapeHTML(text)
     when /^rdoc-image:/
-      %[<img src=\"#{CGI.escapeHTML($')}\">]
+      url, alt = $'.split(":", 2) # Split the string after "rdoc-image:" into url and alt
+      if alt && !alt.empty?
+        %[<img src="#{CGI.escapeHTML(url)}" alt="#{CGI.escapeHTML(alt)}">]
+      else
+        %[<img src="#{CGI.escapeHTML(url)}">]
+      end
     when /\Ardoc-[a-z]+:/
       CGI.escapeHTML($')
     end

test/rdoc/test_rdoc_markdown.rb

@@ -511,7 +511,7 @@ def test_parse_html_no_html
   def test_parse_image
     doc = parse "image ![alt text](path/to/image.jpg)"
 
-    expected = doc(para("image rdoc-image:path/to/image.jpg"))
+    expected = doc(para("image rdoc-image:path/to/image.jpg:alt text"))
 
     assert_equal expected, doc
   end
@@ -523,7 +523,7 @@ def test_parse_image_link
 
     expected =
       doc(
-        para('{rdoc-image:path/to/image.jpg}[http://example.com]'))
+        para('{rdoc-image:path/to/image.jpg:alt text}[http://example.com]'))
 
     assert_equal expected, doc
   end

test/rdoc/test_rdoc_markup_heading.rb

@@ -26,4 +26,9 @@ def test_plain_html
     assert_equal 'Hello <strong>Friend</strong>!', @h.plain_html
   end
 
+  def test_plain_html_using_image_alt_as_text
+    h = RDoc::Markup::Heading.new 1, 'rdoc-image:foo.png:Hello World'
+
+    assert_equal 'Hello World', h.plain_html
+  end
 end