resolves #3114 log warning if footnoteref macro is found and compat mode is not enabled (PR #3115)

4 files changed, 35 insertions, 11 deletions

diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
index 16b0207c..1cde533a 100644
--- a/CHANGELOG.adoc
+++ b/CHANGELOG.adoc
@@ -61,6 +61,7 @@ Enhancements / Compliance::
   * modify Cell class to extend from AbstractBlock instead of AbstractNode (#2963)
   * implement block? and inline? methods on Column, both which return false (#2963)
   * drop verse table cell style (treat as normal table cell) (#3111)
+  * log warning if footnoteref macro is found and compat mode is not enabled (#3114)
 
 Improvements::
 
diff --git a/lib/asciidoctor/substitutors.rb b/lib/asciidoctor/substitutors.rb
index 6e7016e9..2a45a79c 100644
--- a/lib/asciidoctor/substitutors.rb
+++ b/lib/asciidoctor/substitutors.rb
@@ -859,8 +859,19 @@ module Substitutors
         # honor the escape
         next $&.slice 1, $&.length if $&.start_with? RS
 
-        # $1 is footnoteref (legacy)
-        id, text = $1 ? ($3 || '').split(',', 2) : [$2, $3]
+        # footnoteref
+        if $1
+          if $3
+            id, text = $3.split ',', 2
+            logger.warn %(found deprecated footnoteref macro: #{$&}; use footnote macro with target instead) unless doc.compat_mode
+          else
+            next $&
+          end
+        # footnote
+        else
+          id = $2
+          text = $3
+        end
 
         if id
           if text
diff --git a/test/document_test.rb b/test/document_test.rb
index 8c55a4db..68baa95f 100644
--- a/test/document_test.rb
+++ b/test/document_test.rb
@@ -1104,8 +1104,8 @@ context 'Document' do
     test 'outputs footnotes in footer' do
       input = <<~'EOS'
       A footnote footnote:[An example footnote.];
-      a second footnote with a reference ID footnoteref:[note2,Second footnote.];
-      finally a reference to the second footnote footnoteref:[note2].
+      a second footnote with a reference ID footnote:note2[Second footnote.];
+      and finally a reference to the second footnote footnote:note2[].
       EOS
 
       output = convert_string input
diff --git a/test/substitutions_test.rb b/test/substitutions_test.rb
index 800d2c99..f63336be 100644
--- a/test/substitutions_test.rb
+++ b/test/substitutions_test.rb
@@ -993,7 +993,7 @@ context 'Substitutions' do
     end
 
     test 'a footnoteref macro with id and single-line text should be registered and output as a footnote' do
-      para = block_from_string('Sentence text footnoteref:[ex1, An example footnote.].')
+      para = block_from_string 'Sentence text footnoteref:[ex1, An example footnote.].', attributes: { 'compat-mode' => '' }
       assert_equal %(Sentence text <sup class="footnote" id="_footnote_ex1">[<a id="_footnoteref_1" class="footnote" href="#_footnotedef_1" title="View footnote.">1</a>]</sup>.), para.sub_macros(para.source)
       assert_equal 1, para.document.catalog[:footnotes].size
       footnote = para.document.catalog[:footnotes].first
@@ -1003,7 +1003,7 @@ context 'Substitutions' do
     end
 
     test 'a footnoteref macro with id and multi-line text should be registered and output as a footnote without newlines' do
-      para = block_from_string("Sentence text footnoteref:[ex1, An example footnote\nwith wrapped text.].")
+      para = block_from_string "Sentence text footnoteref:[ex1, An example footnote\nwith wrapped text.].", attributes: { 'compat-mode' => '' }
       assert_equal %(Sentence text <sup class="footnote" id="_footnote_ex1">[<a id="_footnoteref_1" class="footnote" href="#_footnotedef_1" title="View footnote.">1</a>]</sup>.), para.sub_macros(para.source)
       assert_equal 1, para.document.catalog[:footnotes].size
       footnote = para.document.catalog[:footnotes].first
@@ -1013,7 +1013,7 @@ context 'Substitutions' do
     end
 
     test 'a footnoteref macro with id should refer to footnoteref with same id' do
-      para = block_from_string('Sentence text footnoteref:[ex1, An example footnote.]. Sentence text footnoteref:[ex1].')
+      para = block_from_string 'Sentence text footnoteref:[ex1, An example footnote.]. Sentence text footnoteref:[ex1].', attributes: { 'compat-mode' => '' }
       assert_equal %(Sentence text <sup class="footnote" id="_footnote_ex1">[<a id="_footnoteref_1" class="footnote" href="#_footnotedef_1" title="View footnote.">1</a>]</sup>. Sentence text <sup class="footnoteref">[<a class="footnote" href="#_footnotedef_1" title="View footnote.">1</a>]</sup>.), para.sub_macros(para.source)
       assert_equal 1, para.document.catalog[:footnotes].size
       footnote = para.document.catalog[:footnotes].first
@@ -1031,6 +1031,15 @@ context 'Substitutions' do
       end
     end
 
+    test 'using a footnoteref macro should generate a warning when compat mode is not enabled' do
+      input = 'Sentence text.footnoteref:[fn1,Commentary on this sentence.]'
+      using_memory_logger do |logger|
+        para = block_from_string input
+        para.sub_macros para.source
+        assert_message logger, :WARN, 'found deprecated footnoteref macro: footnoteref:[fn1,Commentary on this sentence.]; use footnote macro with target instead'
+      end
+    end
+
     test 'inline footnote macro can be used to define and reference a footnote reference' do
       input = <<~'EOS'
       You can download the software from the product page.footnote:sub[Option only available if you have an active subscription.]
@@ -1040,10 +1049,13 @@ context 'Substitutions' do
       If all else fails, you can give us a call.footnoteref:[sub]
       EOS
 
-      output = convert_string_to_embedded input
-      assert_css '#_footnotedef_1', output, 1
-      assert_css 'p a[href="#_footnotedef_1"]', output, 3
-      assert_css '#footnotes .footnote', output, 1
+      using_memory_logger do |logger|
+        output = convert_string_to_embedded input, attributes: { 'compat-mode' => '' }
+        assert_css '#_footnotedef_1', output, 1
+        assert_css 'p a[href="#_footnotedef_1"]', output, 3
+        assert_css '#footnotes .footnote', output, 1
+        assert logger.empty?
+      end
     end
 
     test 'should parse multiple footnote references in a single line' do