From 1d78b5e0694419c150f60c88ddf56e1723cd4bec Mon Sep 17 00:00:00 2001 From: Abel Salgado Romero Date: Mon, 22 May 2023 23:01:35 +0200 Subject: [PATCH] v3 migration guide for 'Document' removed methods Fixes #1202 --- .../api-migration-guide-v25x-to-v30.adoc | 58 ++----------------- ...val-of-deprecated-asMap-from-builders.adoc | 49 ++++++++++++++++ ...val-of-deprecated-methods-in-document.adoc | 19 ++++++ 3 files changed, 74 insertions(+), 52 deletions(-) create mode 100644 docs/modules/guides/partials/removal-of-deprecated-asMap-from-builders.adoc create mode 100644 docs/modules/guides/partials/removal-of-deprecated-methods-in-document.adoc diff --git a/docs/modules/guides/pages/api-migration-guide-v25x-to-v30.adoc b/docs/modules/guides/pages/api-migration-guide-v25x-to-v30.adoc index d0c62f52..3ecc4160 100644 --- a/docs/modules/guides/pages/api-migration-guide-v25x-to-v30.adoc +++ b/docs/modules/guides/pages/api-migration-guide-v25x-to-v30.adoc @@ -4,62 +4,16 @@ AsciidoctorJ v3.0.0 introduces breaking changes. This guide will provide the steps required to update a project currently using 2.5.x version. -include::partial$removal-of-deprecated-methods-in-options.adoc[] - -include::partial$removal-of-deprecated-methods-in-attributes.adoc[] - -== Removal of `asMap` from OptionsBuilder and AttributesBuilder - -In v2.5.x it is possible to obtain the backing `Map` for both options and attributes. - -[,java] -.Obtaining backing Map for OptionsBuilder ----- -Map optionsMap = Options.builder() - .backend("html5") - .mkDirs(true) - .safe(SafeMode.UNSAFE) - .asMap(); ----- - -[,java] -.Obtaining backing Map for AttributesBuilder ----- -Map attributesMap = Attributes.builder() - .icons("font") - .sectionNumbers(true) - .asMap(); ----- - -To remove feature duplication and avoid confusion between values in the actual `org.asciidoctor.Attributes` and `org.asciidoctor.Options` and their respective builders, `asMap` it's no longer available in both builders. +include::partial$update-preprocessor-api.adoc[] -To obtain the backing up, use the `map()` method from the actual `org.asciidoctor.Attributes` and `org.asciidoctor.Options` instances. +include::partial$update-macro-api.adoc[] -IMPORTANT: `Options::map()` and `Attributes::map()` are marked as deprecated and subject to change at some point, but are still maintained and safe to use in v3.0.x. +include::partial$removal-of-deprecated-methods-in-options.adoc[] -[,java] -.Obtaining backing Map for Options ----- -Options options = Options.builder() - .backend("html5") - .mkDirs(true) - .safe(SafeMode.UNSAFE) - .build(); -Map optionsMap = options.map(); ----- +include::partial$removal-of-deprecated-methods-in-attributes.adoc[] -[,java] -.Obtaining backing Map for Attributes ----- -Attributes attributes = Attributes.builder() - .icons("font") - .sectionNumbers(true) - .build(); -Map attributesMap = attributes.map(); ----- +include::partial$removal-of-deprecated-asMap-from-builders.adoc[] include::partial$removal-of-deprecated-methods-in-asciidoctor.adoc[] -include::partial$update-preprocessor-api.adoc[] - -include::partial$update-macro-api.adoc[] +include::partial$removal-of-deprecated-methods-in-document.adoc[] diff --git a/docs/modules/guides/partials/removal-of-deprecated-asMap-from-builders.adoc b/docs/modules/guides/partials/removal-of-deprecated-asMap-from-builders.adoc new file mode 100644 index 00000000..034f5873 --- /dev/null +++ b/docs/modules/guides/partials/removal-of-deprecated-asMap-from-builders.adoc @@ -0,0 +1,49 @@ +== Removal of `asMap` from OptionsBuilder and AttributesBuilder + +In v2.5.x it is possible to obtain the backing `Map` for both options and attributes. + +[,java] +.Obtaining backing Map for OptionsBuilder +---- +Map optionsMap = Options.builder() + .backend("html5") + .mkDirs(true) + .safe(SafeMode.UNSAFE) + .asMap(); +---- + +[,java] +.Obtaining backing Map for AttributesBuilder +---- +Map attributesMap = Attributes.builder() + .icons("font") + .sectionNumbers(true) + .asMap(); +---- + +To remove feature duplication and avoid confusion between values in the actual `org.asciidoctor.Attributes` and `org.asciidoctor.Options` and their respective builders, `asMap` it's no longer available in both builders. + +To obtain the backing up, use the `map()` method from the actual `org.asciidoctor.Attributes` and `org.asciidoctor.Options` instances. + +IMPORTANT: `Options::map()` and `Attributes::map()` are marked as deprecated and subject to change at some point, but are still maintained and safe to use in v3.0.x. + +[,java] +.Obtaining backing Map for Options +---- +Options options = Options.builder() + .backend("html5") + .mkDirs(true) + .safe(SafeMode.UNSAFE) + .build(); +Map optionsMap = options.map(); +---- + +[,java] +.Obtaining backing Map for Attributes +---- +Attributes attributes = Attributes.builder() + .icons("font") + .sectionNumbers(true) + .build(); +Map attributesMap = attributes.map(); +---- diff --git a/docs/modules/guides/partials/removal-of-deprecated-methods-in-document.adoc b/docs/modules/guides/partials/removal-of-deprecated-methods-in-document.adoc new file mode 100644 index 00000000..a1b8548c --- /dev/null +++ b/docs/modules/guides/partials/removal-of-deprecated-methods-in-document.adoc @@ -0,0 +1,19 @@ +== Removal of deprecated methods in `org.asciidoctor.ast.Document` + +Several methods in `org.asciidoctor.ast.Document` that were marked as `@Deprecated` have been removed. + +For each of the removed methods, the equivalent can be found below. + +[,java] +.Removed deprecated methods +---- +String doctitle() +boolean basebackend(String backend) +---- + +[,java] +.Final methods +---- +String getDoctitle() +boolean isBasebackend(String backend) +----