From 5d254e8869d818a0f488d1cb57ed2da6e413d443 Mon Sep 17 00:00:00 2001 From: Stan Lo Date: Tue, 6 Jan 2026 17:29:52 +0000 Subject: [PATCH] Allow using backticks to quote text in RDoc markup too Users can now use both '`' and '+' to make simple code blocks in RDoc markup. Using backticks to quote code has become a natural habit for many users, so it's common to see it being incorrectly used to contribute to Ruby documentation. But instead of "correcting" users' behaviour, we should just support it. It'll also allow us to partially migrate some RDoc markup to Markdown. --- doc/markup_reference/rdoc.rdoc | 17 +++++++++++++- lib/rdoc/markup/attribute_manager.rb | 3 ++- test/rdoc/markup/attribute_manager_test.rb | 27 +++++++++++++++++++++- 3 files changed, 44 insertions(+), 3 deletions(-) diff --git a/doc/markup_reference/rdoc.rdoc b/doc/markup_reference/rdoc.rdoc index cbb48fdbaf..534cb51a57 100644 --- a/doc/markup_reference/rdoc.rdoc +++ b/doc/markup_reference/rdoc.rdoc @@ -756,17 +756,32 @@ Rendered HTML: Monofont passage containing _italics_ and *bold*. A single word may be made monofont by a shorthand: -prefixed and suffixed plus-signs. +prefixed and suffixed plus-signs or backticks. Example input: +Monofont+ in a paragraph. + `Monofont` in a paragraph. + Rendered HTML: >>> +Monofont+ in a paragraph. + `Monofont` in a paragraph. + +Note: The shorthand (+...+ and `...`) only works for simple content +containing word characters, colons, periods, slashes, brackets, and hyphens. +Content containing HTML tags or other markup delimiters will not be matched. +For complex content, use the HTML tags or instead: + + +literal_plus+ shows: +literal_plus+ + + `literal_backtick` shows: `literal_backtick` + + content shows: content + ==== Strikethrough Text may be marked as strikethrough via HTML tag or . diff --git a/lib/rdoc/markup/attribute_manager.rb b/lib/rdoc/markup/attribute_manager.rb index 259d2a7712..79df273c13 100644 --- a/lib/rdoc/markup/attribute_manager.rb +++ b/lib/rdoc/markup/attribute_manager.rb @@ -89,6 +89,7 @@ def initialize add_word_pair "*", "*", :BOLD, true add_word_pair "_", "_", :EM, true add_word_pair "+", "+", :TT, true + add_word_pair "`", "`", :TT, true add_html "em", :EM, true add_html "i", :EM, true @@ -100,7 +101,7 @@ def initialize @word_pair_chars = @matching_word_pairs.keys.join - # Matches a word pair delimiter (*, _, +) that is NOT already protected. + # Matches a word pair delimiter (*, _, +, `) that is NOT already protected. # Used by #protect_code_markup to escape delimiters inside / tags. @unprotected_word_pair_regexp = /([#{@word_pair_chars}])(?!#{PROTECT_ATTR})/ end diff --git a/test/rdoc/markup/attribute_manager_test.rb b/test/rdoc/markup/attribute_manager_test.rb index c48954c8ea..903966b8e2 100644 --- a/test/rdoc/markup/attribute_manager_test.rb +++ b/test/rdoc/markup/attribute_manager_test.rb @@ -244,6 +244,31 @@ def test_convert_attrs_ignores_tt_inside_tt assert_equal 'foo +tt+ bar', output('foo +tt+ bar') end + def test_backtick_basic + assert_equal(["cat ", @tt_on, "and", @tt_off, " dog"], + @am.flow("cat `and` dog")) + + assert_equal(["cat ", @tt_on, "X::Y", @tt_off, " dog"], + @am.flow("cat `X::Y` dog")) + end + + def test_backtick_output + assert_equal 'cat and dog', output('cat `and` dog') + assert_equal 'cat X::Y dog', output('cat `X::Y` dog') + end + + def test_convert_attrs_ignores_backtick_inside_code + assert_equal 'foo `text` bar', output('foo `text` bar') + end + + def test_convert_attrs_ignores_backtick_inside_tt + assert_equal 'foo `text` bar', output('foo `text` bar') + end + + def test_backtick_escaped + assert_equal ['`text`'], @am.flow('\`text`') + end + def test_convert_attrs_ignores_del_inside_code assert_equal 'foo strike bar', output('foo strike bar') end @@ -367,7 +392,7 @@ def test_initial_html def test_initial_word_pairs word_pairs = @am.matching_word_pairs assert word_pairs.is_a?(Hash) - assert_equal(3, word_pairs.size) + assert_equal(4, word_pairs.size) end def test_mask_protected_sequence