Asciidoctor: Force callouts into source listing (#530)

Asciidoc automatically adds callouts to all source listing regardless of
whether you ask for them or not and we rely on this behavior in the
Elasticsearch docs. This emulates it in asciidoctor. It isn't super
clean because we have to edit the text on the way in, but that is life
sometimes.

Author: nik9000

resources/asciidoctor/lib/elastic_compat_preprocessor/extension.rb

@@ -31,8 +31,38 @@
 # Because asciidoctor clears attributes set in a block. See
 # https://github.com/asciidoctor/asciidoctor/issues/2993
 #
+# Turns
+#   ["source","sh",subs="attributes"]
+#   --------------------------------------------
+#   wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}.zip
+#   wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}.zip.sha512
+#   shasum -a 512 -c elasticsearch-{version}.zip.sha512 <1>
+#   unzip elasticsearch-{version}.zip
+#   cd elasticsearch-{version}/ <2>
+#   --------------------------------------------
+#   <1> Compares the SHA of the downloaded `.zip` archive and the published checksum, which should output
+#       `elasticsearch-{version}.zip: OK`.
+#   <2> This directory is known as `$ES_HOME`.
+#
+# Into
+#   ["source","sh",subs="attributes,callouts"]
+#   --------------------------------------------
+#   wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}.zip
+#   wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}.zip.sha512
+#   shasum -a 512 -c elasticsearch-{version}.zip.sha512 <1>
+#   unzip elasticsearch-{version}.zip
+#   cd elasticsearch-{version}/ <2>
+#   --------------------------------------------
+#   <1> Compares the SHA of the downloaded `.zip` archive and the published checksum, which should output
+#       `elasticsearch-{version}.zip: OK`.
+#   <2> This directory is known as `$ES_HOME`.
+# Because asciidoc adds callouts to all "source" blocks. We'd *prefer* to do
+# this in the tree processor because it is less messy but we can't because
+# asciidoctor checks the `:callout` sub before giving us a chance to add it.
+#
 class ElasticCompatPreprocessor < Extensions::Preprocessor
   IncludeTaggedDirectiveRx = /^include-tagged::([^\[][^\[]*)\[(#{CC_ANY}+)?\]$/
+  SourceWithSubsRx = /^\["source", ?"[^"]+", ?subs="(#{CC_ANY}+)"\]$/
 
   def process document, reader
     reader.instance_variable_set :@in_attribute_only_block, false
@@ -46,8 +76,8 @@ def reader.process_line line
         else
           line
         end
-      elsif IncludeTaggedDirectiveRx =~ line then
-        if preprocess_include_directive "elastic-include-tagged:#{$1}", $2 then
+      elsif IncludeTaggedDirectiveRx =~ line
+        if preprocess_include_directive "elastic-include-tagged:#{$1}", $2
           nil
         else
           # the line was not a valid include line and we've logged a warning
@@ -61,12 +91,18 @@ def reader.process_line line
         lines.shift
         while Asciidoctor::AttributeEntryRx =~ (check_line = lines.shift)
         end
-        if check_line == '--' then
+        if check_line == '--'
           @in_attribute_only_block = true
           line.clear
         else
           line
         end
+      elsif SourceWithSubsRx =~ line
+        line = super
+        unless $1.include?('callouts')
+          line.sub! "subs=\"#{$1}\"", "subs=\"#{$1},callouts\""
+        end
+        line
       else
         line = super
         line&.gsub!(/(added)\[([^\]]*)\]/, '\1::[\2]')

resources/asciidoctor/spec/elastic_compat_preprocessor_spec.rb

@@ -165,4 +165,40 @@
     expect(actual).to eq(expected.strip)
   end
 
+  it "adds callouts to substitutions for source blocks if there aren't any" do
+    actual = convert <<~ASCIIDOC
+      == Example
+      ["source","sh",subs="attributes"]
+      --------------------------------------------
+      wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}.zip
+      wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}.zip.sha512
+      shasum -a 512 -c elasticsearch-{version}.zip.sha512 <1>
+      unzip elasticsearch-{version}.zip
+      cd elasticsearch-{version}/ <2>
+      --------------------------------------------
+      <1> Compares the SHA of the downloaded `.zip` archive and the published checksum, which should output
+          `elasticsearch-{version}.zip: OK`.
+      <2> This directory is known as `$ES_HOME`.
+    ASCIIDOC
+    expected = <<~DOCBOOK
+      <chapter id="_example">
+      <title>Example</title>
+      <programlisting language="sh" linenumbering="unnumbered">wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}.zip
+      wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}.zip.sha512
+      shasum -a 512 -c elasticsearch-{version}.zip.sha512 <1>
+      unzip elasticsearch-{version}.zip
+      cd elasticsearch-{version}/ <2></programlisting>
+      <calloutlist>
+      <callout arearefs="CO1-1">
+      <para>Compares the SHA of the downloaded <literal>.zip</literal> archive and the published checksum, which should output
+      <literal>elasticsearch-{version}.zip: OK</literal>.</para>
+      </callout>
+      <callout arearefs="CO1-2">
+      <para>This directory is known as <literal>$ES_HOME</literal>.</para>
+      </callout>
+      </calloutlist>
+      </chapter>
+    DOCBOOK
+    expect(actual).to eq(expected.strip)
+  end
 end