Asciidoctor: Implement beta and experimental (#662)

Implements the `beta[]` and `experimental[]` macros for asciidoctor. It
adds integration tests that make sure that we copy the required image
even if that is the only admonition in the book. This is an especially
good idea here because the code that copies the images for the
admonitions is a little sneaky.

README.asciidoc

@@ -1,6 +1,15 @@
 = Docs HOWTO
 :ref:  http://www.elastic.co/guide/elasticsearch/reference/current
 
+////
+This file contains the sequence `_` to escape from around Elastic's
+Asciidoctor plugin that provides Asciidoc compatibility. It automatically
+translates things like `beta[]` into their Asciidoctor compatible form
+which looks like `beta::[]`. We use `beta_]` inside of asciidoc
+examples so we can output `beta[]`. Once we no longer support Asciidoc
+we can drop these sequences.
+////
+
 == Conditions of use
 
 This documentation build process is provided to the public purely for the
@@ -1233,9 +1242,9 @@ the addition or deprecation of individual parameters.
 [source,asciidoc]
 ----------------------------------
 [horizontal]
-`foo.bar`::   Does XYZ. added[0.90.4]
-`foo.bar`::   Does XYZ. coming[0.90.4]
-`foo.baz`::   Does XYZ. deprecated[0.90.4]
+`foo.bar`::   Does XYZ. added_0.90.4]
+`foo.bar`::   Does XYZ. coming_0.90.4]
+`foo.baz`::   Does XYZ. deprecated_0.90.4]
 ----------------------------------
 
 [horizontal]
@@ -1250,9 +1259,9 @@ user hovers over it:
 [source,asciidoc]
 ----------------------------------
 [horizontal]
-`foo.bar`::   Does XYZ. added[0.90.4,Replaces `foo.baz`]
-`foo.bar`::   Does XYZ. coming[0.90.4,Replaces `foo.baz`]
-`foo.baz`::   Does XYZ. deprecated[0.90.4,Replaced by `foo.bar`]
+`foo.bar`::   Does XYZ. added_0.90.4,Replaces `foo.baz`]
+`foo.bar`::   Does XYZ. coming_0.90.4,Replaces `foo.baz`]
+`foo.baz`::   Does XYZ. deprecated_0.90.4,Replaced by `foo.bar`]
 ----------------------------------
 
 [horizontal]
@@ -1270,19 +1279,19 @@ to the version in which the change was made:
 ----------------------------------
 ==== New section
 
-added[0.90.4]
+added_0.90.4]
 
 Text about new functionality...
 
 ==== New section not yet released
 
-coming[0.90.9]
+coming_0.90.9]
 
 Text about new functionality...
 
 ==== Old section
 
-deprecated[0.90.4]
+deprecated_0.90.4]
 
 Text about old functionality...
 ----------------------------------
@@ -1305,6 +1314,7 @@ deprecated[0.90.4]
 
 Text about old functionality...
 
+[[with_details]]
 ==== With details...
 
 Or they can include extra text, including more
@@ -1315,21 +1325,21 @@ Asciidoc markup:
 [[new-section]]
 ==== New section
 
-added[0.90.4,Replaces `foo.bar`. See <<old-section>>]
+added&#x5f;0.90.4,Replaces `foo.bar`. See <<old-section>>]
 
 Text about new functionality...
 
 [[coming-section]]
 ==== New section not yet released
 
-coming[0.90.9,Replaces `foo.bar`. See <<old-section>>]
+coming&#x5f;0.90.9,Replaces `foo.bar`. See <<old-section>>]
 
 Text about new functionality...
 
 [[old-section]]
 ==== Old section
 
-deprecated[0.90.4,Replace by `foo.baz`. See <<new-section>>]
+deprecated&#x5f;0.90.4,Replace by `foo.baz`. See <<new-section>>]
 
 Text about old functionality...
 ----------------------------------
@@ -1359,9 +1369,9 @@ markup similar to that used in <<changes>>.  For instance:
 [[new-feature]]
 === New experimental feature
 
-experimental[]
+experimental&#x5f;]
 
-experimental[Custom text goes here]
+experimental&#x5f;Custom text goes here]
 
 Text about new feature...
 
@@ -1373,8 +1383,8 @@ a new experimental parameter:
 
 [horizontal]
 `established_param`::  This param has been around for ages and won't change.
-`experimental_param`:: experimental[] This param is experimental and may change in the future.
-`experimental_param`:: experimental[Custom text goes here] This param is experimental and may change in the future.
+`experimental_param`:: experimental&#x5f;] This param is experimental and may change in the future.
+`experimental_param`:: experimental&#x5f;Custom text goes here] This param is experimental and may change in the future.
 
 ----------------------------------
 
@@ -1403,9 +1413,9 @@ a new experimental parameter:
 [[new-beta-feature]]
 === New beta feature
 
-beta[]
+beta&#x5f;]
 
-beta[Custom text goes here]
+beta&#x5f;Custom text goes here]
 
 Text about new feature...
 
@@ -1417,8 +1427,8 @@ a new beta parameter:
 
 [horizontal]
 `established_param`::  This param has been around for ages and won't change.
-`beta_param`:: beta[] This param is beta and may change in the future.
-`beta_param`:: beta[Custom text goes here] This param is beta and may change in the future.
+`beta_param`:: beta&#x5f;] This param is beta and may change in the future.
+`beta_param`:: beta&#x5f;Custom text goes here] This param is beta and may change in the future.
 
 ----------------------------------
 

integtest/Makefile

@@ -12,6 +12,8 @@ check: \
 	style \
 	minimal_expected_files minimal_same_files \
 	includes_expected_files includes_same_files \
+	beta_expected_files beta_same_files \
+	experimental_expected_files experimental_same_files \
 	readme_expected_files readme_same_files \
 	small_all_expected_files
 
@@ -41,6 +43,16 @@ readme_expected_files: /tmp/readme_asciidoc
 	[ -s $^/images/icons/callouts/2.png ]
 	[ -s $^/snippets/blocks/1.json ]
 
+.PHONY: experimental_expected_files
+beta_expected_files: /tmp/beta_asciidoc
+	$(STANDARD_EXPECTED_FILES)
+	[ -s $^/images/icons/warning.png ]
+
+.PHONY: experimental_expected_files
+experimental_expected_files: /tmp/experimental_asciidoc
+	$(STANDARD_EXPECTED_FILES)
+	[ -s $^/images/icons/warning.png ]
+
 .PHONY: %_expected_files
 %_expected_files: /tmp/%_asciidoc
 	$(STANDARD_EXPECTED_FILES)
@@ -54,7 +66,7 @@ readme_expected_files: /tmp/readme_asciidoc
 		<(cd /tmp/$*_asciidoctor && find * -type f | sort)
 	# The grep -v below are for known issues with asciidoctor
 	for file in $$(cd /tmp/$*_asciidoc && find * -type f -name '*.html' \
-			| grep -v 'blocks\|changes\|experimental'); do \
+			| grep -v 'blocks'); do \
 		./html_diff /tmp/$*_asciidoc/$$file /tmp/$*_asciidoctor/$$file; \
 	done
 
@@ -67,6 +79,11 @@ endef
 
 /tmp/readme_asciidoctor: /docs_build/README.asciidoc
 	$(BD) --asciidoctor --doc /docs_build/README.asciidoc
+	# These are different when rendered by asciidoctor but they are
+	# correct for asciidoctor. So we're ok with it. It isn't perfect, but
+	# perfect is quite hard for this.
+	# sed -i -E 's/beta::?\[/beta\[/' /tmp/readme_asciidoctor/experimental.html
+	# sed -i -E 's/experimental::?\[/experimental\[/' /tmp/readme_asciidoctor/experimental.html
 
 # These don't declare dependencies because we don't know in general which files
 # are needed to build which asciidoc files.

integtest/beta.asciidoc

@@ -0,0 +1,7 @@
+= Title
+
+== Chapter
+
+beta[]
+
+Words

integtest/experimental.asciidoc

@@ -0,0 +1,7 @@
+= Title
+
+== Chapter
+
+experimental[]
+
+Words

lib/ES/Template.pm

@@ -154,7 +154,7 @@ sub _init {
     }
 
     my $created = $1 || 0;
-    if ( not $force and time - $latest < 20 * 60 ) {
+    if ( not $force and time - $latest < 20 * 60) {
         $new = $old[-1];
     }
     else {

resources/asciidoctor/lib/care_admonition/extension.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'asciidoctor/extensions'
+
+##
+# Extensions for marking when something as `beta` or `experimental`.
+#
+# Usage
+#
+#   beta::[]
+#   experimental::[]
+#   Foo beta:[]
+#   Foo experimental:[]
+#
+class CareAdmonition < Asciidoctor::Extensions::Group
+  def activate(registry)
+    [
+        [:beta, 'beta'],
+        [:experimental, 'experimental'],
+    ].each do |(name, role)|
+      registry.block_macro ChangeAdmonitionBlock.new(role), name
+      registry.inline_macro ChangeAdmonitionInline.new(role), name
+    end
+  end
+
+  ##
+  # Block care admonition.
+  class ChangeAdmonitionBlock < Asciidoctor::Extensions::BlockMacroProcessor
+    use_dsl
+    name_positional_attributes :passtext
+
+    def initialize(role)
+      super(nil)
+      @role = role
+    end
+
+    def process(parent, _target, attrs)
+      Asciidoctor::Block.new(parent, :admonition,
+          :source => attrs[:passtext],
+          :attributes => {
+            'role' => @role,
+            'name' => 'warning',
+            'style' => 'warning',
+          })
+    end
+  end
+
+  ##
+  # Inline care admonition.
+  class ChangeAdmonitionInline < Asciidoctor::Extensions::InlineMacroProcessor
+    use_dsl
+    name_positional_attributes :text
+    with_format :short
+
+    def initialize(role)
+      super(nil)
+      @role = role
+    end
+
+    def process(_parent, _target, attrs)
+      if attrs[:text]
+        <<~DOCBOOK
+          <phrase role="#{@role}">
+            #{attrs[:text]}
+          </phrase>
+        DOCBOOK
+      else
+        <<~DOCBOOK
+          <phrase role="#{@role}"/>
+        DOCBOOK
+      end
+    end
+  end
+end

resources/asciidoctor/lib/elastic_compat_preprocessor/extension.rb

@@ -142,7 +142,7 @@ def reader.process_line(line)
             @code_block_start = line
           end
         end
-        supported = 'added|coming|deprecated'
+        supported = 'added|beta|coming|deprecated|experimental'
         # First convert the "block" version of these macros. We convert them
         # to block macros because they are at the start of the line....
         line&.gsub!(/^(#{supported})\[([^\]]*)\]/, '\1::[\2]')

resources/asciidoctor/lib/extensions.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'care_admonition/extension'
 require_relative 'change_admonition/extension'
 require_relative 'copy_images/extension'
 require_relative 'cramped_include/extension'
@@ -8,6 +9,7 @@
 require_relative 'elastic_compat_preprocessor/extension'
 require_relative 'elastic_include_tagged/extension'
 
+Asciidoctor::Extensions.register CareAdmonition
 Asciidoctor::Extensions.register ChangeAdmonition
 Asciidoctor::Extensions.register do
   # Enable storing the source locations so we can look at them. This is required