Asciidoctor: Implement beta and experimental

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