From 0cd2b9a565bded2f1493f1733e02580d9c378988 Mon Sep 17 00:00:00 2001 From: singye3 Date: Thu, 19 Nov 2026 11:19:16 +0600 Subject: [PATCH] Support spaces in Markdown image alt text --- lib/rdoc/markdown.kpeg | 31 ++++++++++++++++++++++--- lib/rdoc/markdown.rb | 39 ++++++++++++++++++++++++++------ lib/rdoc/markup/formatter.rb | 18 ++++++++++++++- lib/rdoc/markup/heading.rb | 14 ++++++++++-- lib/rdoc/markup/to_html.rb | 2 +- lib/rdoc/markup/to_markdown.rb | 2 +- test/rdoc/markup/heading_test.rb | 12 ++++++++++ test/rdoc/markup/to_html_test.rb | 7 ++++++ test/rdoc/rdoc_markdown_test.rb | 28 ++++++++++++++++++++++- 9 files changed, 137 insertions(+), 16 deletions(-) diff --git a/lib/rdoc/markdown.kpeg b/lib/rdoc/markdown.kpeg index a059672735..207188045c 100644 --- a/lib/rdoc/markdown.kpeg +++ b/lib/rdoc/markdown.kpeg @@ -359,6 +359,31 @@ doc.parts end + ## + # Creates an rdoc-image link to `url` with `alt` text for rdoc inline + # formatting. A bare rdoc-image link ends at the first whitespace, so the + # link is wrapped in braces when `alt` contains whitespace. The braced form + # cannot hold braces, so such `alt` text keeps the bare form. + + def image url, alt + link = "rdoc-image:#{url}:#{alt}" + + if alt =~ /\s/ and alt !~ /[{}]/ then + "{#{link}}" + else + link + end + end + + ## + # Returns `label` for use as the label of an rdoc tidy link. A label that + # is a single rdoc-image link may already contain whitespace, so the braces + # added by #image are removed. + + def tidy_link_label label + label[/\A\{(rdoc-image:[^{}]+)\}\z/, 1] || label + end + ## # Finds a link reference for `label` and creates a new link to it with # `content` as the link text. If `label` was not encountered in the @@ -370,7 +395,7 @@ content.start_with? '^' and label.equal? content if ref = @references[label] then - "{#{content}}[#{ref}]" + "{#{tidy_link_label content}}[#{ref}]" elsif label.equal? content then "[#{content}]#{text}" else @@ -1063,7 +1088,7 @@ Strike = &{ strike? } { strike a.join } Image = "!" ExplicitLinkWithLabel:a - { "rdoc-image:#{a[:link]}:#{a[:label]}" } + { image a[:link], a[:label] } Link = ExplicitLink | ReferenceLink | AutoLink @@ -1076,7 +1101,7 @@ ReferenceLinkSingle = Label:content < (Spnl "[]")? > { link_to content, content, text } ExplicitLink = ExplicitLinkWithLabel:a - { "{#{a[:label]}}[#{rdoc_link_url_escape(a[:link])}]" } + { "{#{tidy_link_label a[:label]}}[#{rdoc_link_url_escape(a[:link])}]" } ExplicitLinkWithLabel = Label:label "(" @Sp Source:link Spnl Title @Sp ")" { { label: label, link: link } } diff --git a/lib/rdoc/markdown.rb b/lib/rdoc/markdown.rb index 97dd473523..cdb7485775 100644 --- a/lib/rdoc/markdown.rb +++ b/lib/rdoc/markdown.rb @@ -744,6 +744,31 @@ def inner_parse text # :nodoc: doc.parts end + ## + # Creates an rdoc-image link to `url` with `alt` text for rdoc inline + # formatting. A bare rdoc-image link ends at the first whitespace, so the + # link is wrapped in braces when `alt` contains whitespace. The braced form + # cannot hold braces, so such `alt` text keeps the bare form. + + def image url, alt + link = "rdoc-image:#{url}:#{alt}" + + if alt =~ /\s/ and alt !~ /[{}]/ then + "{#{link}}" + else + link + end + end + + ## + # Returns `label` for use as the label of an rdoc tidy link. A label that + # is a single rdoc-image link may already contain whitespace, so the braces + # added by #image are removed. + + def tidy_link_label label + label[/\A\{(rdoc-image:[^{}]+)\}\z/, 1] || label + end + ## # Finds a link reference for `label` and creates a new link to it with # `content` as the link text. If `label` was not encountered in the @@ -755,7 +780,7 @@ def link_to content, label = content, text = nil content.start_with? '^' and label.equal? content if ref = @references[label] then - "{#{content}}[#{ref}]" + "{#{tidy_link_label content}}[#{ref}]" elsif label.equal? content then "[#{content}]#{text}" else @@ -11179,7 +11204,7 @@ def _Strike return _tmp end - # Image = "!" ExplicitLinkWithLabel:a { "rdoc-image:#{a[:link]}:#{a[:label]}" } + # Image = "!" ExplicitLinkWithLabel:a { image a[:link], a[:label] } def _Image _save = self.pos @@ -11195,7 +11220,7 @@ def _Image self.pos = _save break end - @result = begin; "rdoc-image:#{a[:link]}:#{a[:label]}" ; end + @result = begin; image a[:link], a[:label] ; end _tmp = true unless _tmp self.pos = _save @@ -11343,7 +11368,7 @@ def _ReferenceLinkSingle return _tmp end - # ExplicitLink = ExplicitLinkWithLabel:a { "{#{a[:label]}}[#{rdoc_link_url_escape(a[:link])}]" } + # ExplicitLink = ExplicitLinkWithLabel:a { "{#{tidy_link_label a[:label]}}[#{rdoc_link_url_escape(a[:link])}]" } def _ExplicitLink _save = self.pos @@ -11354,7 +11379,7 @@ def _ExplicitLink self.pos = _save break end - @result = begin; "{#{a[:label]}}[#{rdoc_link_url_escape(a[:link])}]" ; end + @result = begin; "{#{tidy_link_label a[:label]}}[#{rdoc_link_url_escape(a[:link])}]" ; end _tmp = true unless _tmp self.pos = _save @@ -16775,12 +16800,12 @@ def _DefinitionListDefinition Rules[:_StrongStar] = rule_info("StrongStar", "\"**\" !@Whitespace @StartList:a (!\"**\" Inline:b { a << b })+ \"**\" { strong a.join }") Rules[:_StrongUl] = rule_info("StrongUl", "\"__\" !@Whitespace @StartList:a (!\"__\" Inline:b { a << b })+ \"__\" { strong a.join }") Rules[:_Strike] = rule_info("Strike", "&{ strike? } \"~~\" !@Whitespace @StartList:a (!\"~~\" Inline:b { a << b })+ \"~~\" { strike a.join }") - Rules[:_Image] = rule_info("Image", "\"!\" ExplicitLinkWithLabel:a { \"rdoc-image:\#{a[:link]}:\#{a[:label]}\" }") + Rules[:_Image] = rule_info("Image", "\"!\" ExplicitLinkWithLabel:a { image a[:link], a[:label] }") Rules[:_Link] = rule_info("Link", "(ExplicitLink | ReferenceLink | AutoLink)") Rules[:_ReferenceLink] = rule_info("ReferenceLink", "(ReferenceLinkDouble | ReferenceLinkSingle)") Rules[:_ReferenceLinkDouble] = rule_info("ReferenceLinkDouble", "Label:content < Spnl > !\"[]\" Label:label { link_to content, label, text }") Rules[:_ReferenceLinkSingle] = rule_info("ReferenceLinkSingle", "Label:content < (Spnl \"[]\")? > { link_to content, content, text }") - Rules[:_ExplicitLink] = rule_info("ExplicitLink", "ExplicitLinkWithLabel:a { \"{\#{a[:label]}}[\#{rdoc_link_url_escape(a[:link])}]\" }") + Rules[:_ExplicitLink] = rule_info("ExplicitLink", "ExplicitLinkWithLabel:a { \"{\#{tidy_link_label a[:label]}}[\#{rdoc_link_url_escape(a[:link])}]\" }") Rules[:_ExplicitLinkWithLabel] = rule_info("ExplicitLinkWithLabel", "Label:label \"(\" @Sp Source:link Spnl Title @Sp \")\" { { label: label, link: link } }") Rules[:_Source] = rule_info("Source", "(\"<\" < SourceContents > \">\" | < SourceContents >) { text }") Rules[:_SourceContents] = rule_info("SourceContents", "((!\"(\" !\")\" !\">\" Nonspacechar)+ | \"(\" SourceContents \")\")*") diff --git a/lib/rdoc/markup/formatter.rb b/lib/rdoc/markup/formatter.rb index b2e7435ecb..9277d9a243 100644 --- a/lib/rdoc/markup/formatter.rb +++ b/lib/rdoc/markup/formatter.rb @@ -65,9 +65,25 @@ def accept_document(document) ## # Adds a regexp handling for links of the form rdoc-...: + # + # A bare link ends at the first whitespace, so an rdoc-image link whose + # alt text contains spaces is wrapped in braces instead: + # + # {rdoc-image:path/to/image.png:alt text} + # + # Handlers receive the braced form as matched. Use #unwrap_rdoc_link to + # get the link itself. def add_regexp_handling_RDOCLINK - @markup.add_regexp_handling(/rdoc-[a-z]+:[^\s\]]+/, :RDOCLINK) + @markup.add_regexp_handling(/\{rdoc-image:[^{}]+\}|rdoc-[a-z]+:[^\s\]]+/, :RDOCLINK) + end + + ## + # Returns +link+ without the braces that may wrap an rdoc-image link + # matched by #add_regexp_handling_RDOCLINK. + + def unwrap_rdoc_link(link) + link.start_with?('{') ? link[1...-1] : link end ## diff --git a/lib/rdoc/markup/heading.rb b/lib/rdoc/markup/heading.rb index 0ceef85bd8..025e24727d 100644 --- a/lib/rdoc/markup/heading.rb +++ b/lib/rdoc/markup/heading.rb @@ -99,7 +99,7 @@ def aref # #: () -> String? def legacy_aref - "label-#{self.class.to_label.convert_legacy text.dup}" + "label-#{self.class.to_label.convert_legacy unbraced_text}" end # Creates a fully-qualified label (GitHub-style) which includes the context's aref prefix. @@ -149,7 +149,7 @@ def legacy_label(context = nil) # HTML markup of the text of this label without the surrounding header element. #: () -> String def plain_html - no_image_text = text + no_image_text = unbraced_text if matched = no_image_text.match(/rdoc-image:[^:]+:(.*)/) no_image_text = matched[1] @@ -165,6 +165,16 @@ def pretty_print(q) q.pp text end end + + private + + # The text with the braces around rdoc-image links removed. The braces + # only delimit an image whose alt text contains whitespace, so they are + # not part of the heading's plain text or legacy label. + #: () -> String + def unbraced_text + text.gsub(/\{(rdoc-image:[^{}]+)\}/, '\1') + end end end end diff --git a/lib/rdoc/markup/to_html.rb b/lib/rdoc/markup/to_html.rb index 6477f98910..f15065f193 100644 --- a/lib/rdoc/markup/to_html.rb +++ b/lib/rdoc/markup/to_html.rb @@ -382,7 +382,7 @@ def handle_regexp_HYPERLINK(text) # when creating a link. All other contents will be linked verbatim. def handle_regexp_RDOCLINK(text) - handle_RDOCLINK text + handle_RDOCLINK unwrap_rdoc_link(text) end # :section: Visitor diff --git a/lib/rdoc/markup/to_markdown.rb b/lib/rdoc/markup/to_markdown.rb index 24a0a2f4ac..f860c0025c 100644 --- a/lib/rdoc/markup/to_markdown.rb +++ b/lib/rdoc/markup/to_markdown.rb @@ -211,7 +211,7 @@ def handle_rdoc_link(url) # Converts the rdoc-...: links into a Markdown.style links. def handle_regexp_RDOCLINK(text) - handle_rdoc_link text + handle_rdoc_link unwrap_rdoc_link(text) end end diff --git a/test/rdoc/markup/heading_test.rb b/test/rdoc/markup/heading_test.rb index 6a12b85972..c059d9c543 100644 --- a/test/rdoc/markup/heading_test.rb +++ b/test/rdoc/markup/heading_test.rb @@ -27,6 +27,12 @@ def test_legacy_aref assert_equal 'label-Hello+Friend-21', @h.legacy_aref end + def test_legacy_aref_ignores_image_braces + h = RDoc::Markup::Heading.new 1, '{rdoc-image:foo.png:Hello World}' + + assert_equal 'label-rdoc-image-3Afoo.png-3AHello+World', h.legacy_aref + end + def test_legacy_label assert_equal 'label-Hello+Friend-21', @h.legacy_label assert_equal 'label-Hello+Friend-21', @h.legacy_label(nil) @@ -56,4 +62,10 @@ def test_plain_html_using_image_alt_as_text assert_equal 'Hello World', h.plain_html end + + def test_plain_html_using_braced_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 diff --git a/test/rdoc/markup/to_html_test.rb b/test/rdoc/markup/to_html_test.rb index 6d0107602c..71adc24445 100644 --- a/test/rdoc/markup/to_html_test.rb +++ b/test/rdoc/markup/to_html_test.rb @@ -793,8 +793,15 @@ def test_convert_RDOCLINK_ref assert_equal "\n

C

\n", result end + def test_convert_RDOCLINK_image_braced_alt_with_spaces + result = @to.convert 'see {rdoc-image:path/to/image.jpg:alt text} here' + + assert_equal "\n

see \"alt here

\n", result + end + def test_convert_RDOCLINK_escape_image assert_escaped '"' + assert_escaped '}' end def test_convert_RDOCLINK_escape_label_id diff --git a/test/rdoc/rdoc_markdown_test.rb b/test/rdoc/rdoc_markdown_test.rb index d98d9ede3f..5789877a47 100644 --- a/test/rdoc/rdoc_markdown_test.rb +++ b/test/rdoc/rdoc_markdown_test.rb @@ -719,11 +719,27 @@ 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:alt text")) + expected = doc(para("image {rdoc-image:path/to/image.jpg:alt text}")) assert_equal expected, doc end + def test_parse_image_alt_with_braces + doc = parse "![alt {text}](path/to/image.jpg)" + + expected = doc(para("rdoc-image:path/to/image.jpg:alt {text}")) + + assert_equal expected, doc + end + + def test_parse_image_to_html_alt_with_spaces + doc = parse "image ![alt text](path/to/image.jpg) after" + + expected = "\n

image \"alt after

\n" + + assert_equal expected, @to_html.convert(doc) + end + def test_parse_image_link @parser.html = true @@ -736,6 +752,16 @@ def test_parse_image_link assert_equal expected, doc end + def test_parse_image_reference_link + doc = parse "[![alt text](path/to/image.jpg)][ref]\n\n[ref]: http://example.com\n" + + expected = + doc( + para('{rdoc-image:path/to/image.jpg:alt text}[http://example.com]')) + + assert_equal expected, doc + end + def test_parse_line_break doc = parse "Some text \nwith extra lines"