diff --git a/README.asciidoc b/README.asciidoc index 68fb78a222861..cfe420091b13b 100644 --- a/README.asciidoc +++ b/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 <>] +added_0.90.4,Replaces `foo.bar`. See <>] Text about new functionality... [[coming-section]] ==== New section not yet released -coming[0.90.9,Replaces `foo.bar`. See <>] +coming_0.90.9,Replaces `foo.bar`. See <>] Text about new functionality... [[old-section]] ==== Old section -deprecated[0.90.4,Replace by `foo.baz`. See <>] +deprecated_0.90.4,Replace by `foo.baz`. See <>] Text about old functionality... ---------------------------------- @@ -1359,9 +1369,9 @@ markup similar to that used in <>. For instance: [[new-feature]] === New experimental feature -experimental[] +experimental_] -experimental[Custom text goes here] +experimental_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_] 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. ---------------------------------- @@ -1403,9 +1413,9 @@ a new experimental parameter: [[new-beta-feature]] === New beta feature -beta[] +beta_] -beta[Custom text goes here] +beta_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_] 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. ---------------------------------- diff --git a/integtest/Makefile b/integtest/Makefile index 760dc59401dc6..6a86b88d2c730 100644 --- a/integtest/Makefile +++ b/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. diff --git a/integtest/beta.asciidoc b/integtest/beta.asciidoc new file mode 100644 index 0000000000000..cccd528e01e3a --- /dev/null +++ b/integtest/beta.asciidoc @@ -0,0 +1,7 @@ += Title + +== Chapter + +beta[] + +Words diff --git a/integtest/experimental.asciidoc b/integtest/experimental.asciidoc new file mode 100644 index 0000000000000..65b7da6d64c34 --- /dev/null +++ b/integtest/experimental.asciidoc @@ -0,0 +1,7 @@ += Title + +== Chapter + +experimental[] + +Words diff --git a/lib/ES/Template.pm b/lib/ES/Template.pm index 5343b860b5f59..98e40b363d89a 100644 --- a/lib/ES/Template.pm +++ b/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 { diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb new file mode 100644 index 0000000000000..7c0516592aacf --- /dev/null +++ b/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 + + #{attrs[:text]} + + DOCBOOK + else + <<~DOCBOOK + + DOCBOOK + end + end + end +end diff --git a/resources/asciidoctor/lib/elastic_compat_preprocessor/extension.rb b/resources/asciidoctor/lib/elastic_compat_preprocessor/extension.rb index 41a30fc5149b4..c859a694fe9f8 100644 --- a/resources/asciidoctor/lib/elastic_compat_preprocessor/extension.rb +++ b/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]') diff --git a/resources/asciidoctor/lib/extensions.rb b/resources/asciidoctor/lib/extensions.rb index 14535ada322de..d175aa3feb83b 100644 --- a/resources/asciidoctor/lib/extensions.rb +++ b/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 diff --git a/resources/asciidoctor/spec/care_admonition_spec.rb b/resources/asciidoctor/spec/care_admonition_spec.rb new file mode 100644 index 0000000000000..d08644fb8b19b --- /dev/null +++ b/resources/asciidoctor/spec/care_admonition_spec.rb @@ -0,0 +1,113 @@ +# frozen_string_literal: true + +require 'care_admonition/extension' + +RSpec.describe CareAdmonition do + before(:each) do + Asciidoctor::Extensions.register CareAdmonition + end + + after(:each) do + Asciidoctor::Extensions.unregister_all + end + + %w[beta experimental].each do |(name)| + it "#{name}'s block version creates a warning" do + actual = convert <<~ASCIIDOC + == Example + #{name}::[] + ASCIIDOC + expected = <<~DOCBOOK + + Example + + + + + DOCBOOK + expect(actual).to eq(expected.strip) + end + + it "#{name}'s block version supports asciidoc in the passtext" do + actual = convert <<~ASCIIDOC + == Example + #{name}::[See <>] + [[some-reference]] + === Some Reference + ASCIIDOC + expected = <<~DOCBOOK + + Example + + See + +
+ Some Reference + +
+ + DOCBOOK + expect(actual).to eq(expected.strip) + end + + it "#{name}'s block version is not invoked without the ::" do + actual = convert <<~ASCIIDOC + == Example + #{name}[] + ASCIIDOC + expected = <<~DOCBOOK + + Example + #{name}[] + + DOCBOOK + expect(actual).to eq(expected.strip) + end + + it "#{name}'s inline version creates a phrase" do + actual = convert <<~ASCIIDOC + == Example + words #{name}:[] + ASCIIDOC + expected = <<~DOCBOOK + + Example + words + + + DOCBOOK + expect(actual).to eq(expected.strip) + end + + it "#{name}'s inline version creates a phrase with extra text if provided" do + actual = convert <<~ASCIIDOC + == Example + words #{name}:[more words] + ASCIIDOC + expected = <<~DOCBOOK + + Example + words + more words + + + + DOCBOOK + expect(actual).to eq(expected.strip) + end + + it "#{name}'s inline version is not invoked without the :" do + actual = convert <<~ASCIIDOC + == Example + words #{name}[] + ASCIIDOC + expected = <<~DOCBOOK + + Example + words #{name}[] + + DOCBOOK + expect(actual).to eq(expected.strip) + end + end +end diff --git a/resources/asciidoctor/spec/copy_images_spec.rb b/resources/asciidoctor/spec/copy_images_spec.rb index 75473957b0270..cfb7b07da3d62 100644 --- a/resources/asciidoctor/spec/copy_images_spec.rb +++ b/resources/asciidoctor/spec/copy_images_spec.rb @@ -1,5 +1,6 @@ # frozen_string_literal: true +require 'care_admonition/extension' require 'change_admonition/extension' require 'copy_images/extension' require 'fileutils' @@ -9,6 +10,7 @@ RSpec::Matchers.define_negated_matcher :not_match, :match before(:each) do + Asciidoctor::Extensions.register CareAdmonition Asciidoctor::Extensions.register ChangeAdmonition Asciidoctor::Extensions.register do tree_processor CopyImages::CopyImages @@ -419,6 +421,26 @@ def copy_attributes(copied) end end + %w[beta experimental].each do |(name)| + it "copies images for the block formatted #{name} care admonition when requested" do + copied = [] + attributes = copy_attributes copied + attributes['copy-admonition-images'] = 'png' + input = <<~ASCIIDOC + #{name}::[] + ASCIIDOC + # We can't get the location of the blocks because asciidoctor doesn't + # make it available to us here! + expected_warnings = <<~WARNINGS + INFO: : line 1: copying #{spec_dir}/resources/copy_images/images/icons/warning.png + WARNINGS + convert input, attributes, eq(expected_warnings.strip) + expect(copied).to eq([ + ["images/icons/warning.png", "#{spec_dir}/resources/copy_images/images/icons/warning.png"], + ]) + end + end + [ %w[added note], %w[coming note], diff --git a/resources/asciidoctor/spec/elastic_compat_preprocessor_spec.rb b/resources/asciidoctor/spec/elastic_compat_preprocessor_spec.rb index ac6ff47f11184..8fc2f3c5a5c72 100644 --- a/resources/asciidoctor/spec/elastic_compat_preprocessor_spec.rb +++ b/resources/asciidoctor/spec/elastic_compat_preprocessor_spec.rb @@ -1,5 +1,6 @@ # frozen_string_literal: true +require 'care_admonition/extension' require 'change_admonition/extension' require 'elastic_compat_preprocessor/extension' require 'elastic_include_tagged/extension' @@ -7,6 +8,7 @@ RSpec.describe ElasticCompatPreprocessor do before(:each) do + Asciidoctor::Extensions.register CareAdmonition Asciidoctor::Extensions.register ChangeAdmonition Asciidoctor::Extensions.register do preprocessor ElasticCompatPreprocessor @@ -57,21 +59,71 @@ end it "doesn't mind skipped #{name} block macros" do - actual = convert <<~ASCIIDOC - == Example + actual = convert <<~ASCIIDOC + == Example - ifeval::["true" == "false"] - #{name}[some_version] - #endif::[] - ASCIIDOC - expected = <<~DOCBOOK - - Example + ifeval::["true" == "false"] + #{name}[some_version] + #endif::[] + ASCIIDOC + expected = <<~DOCBOOK + + Example - - DOCBOOK - expect(actual).to eq(expected.strip) + + DOCBOOK + expect(actual).to eq(expected.strip) + end end + + %w[beta experimental].each do |name| + it "invokes the #{name} block macro when #{name}[] starts a line" do + actual = convert <<~ASCIIDOC + == Example + #{name}[] + ASCIIDOC + expected = <<~DOCBOOK + + Example + + + + + DOCBOOK + expect(actual).to eq(expected.strip) + end + + it "invokes the #{name} inline macro when #{name}[version] is otherwise on the line" do + actual = convert <<~ASCIIDOC + == Example + words #{name}[] + ASCIIDOC + expected = <<~DOCBOOK + + Example + words + + + DOCBOOK + expect(actual).to eq(expected.strip) + end + + it "doesn't mind skipped #{name} block macros" do + actual = convert <<~ASCIIDOC + == Example + + ifeval::["true" == "false"] + #{name}[] + #endif::[] + ASCIIDOC + expected = <<~DOCBOOK + + Example + + + DOCBOOK + expect(actual).to eq(expected.strip) + end end it "invokes include-tagged::" do