Add v2.5.x to v3.0.0 API migration guide alongside current migration …

…guides

docs/modules/guides/nav.adoc

@@ -1,5 +1,6 @@
 * Help & Guides
 ** Updating to New Releases
+***xref:api-migration-guide-v25x-to-v30.adoc[]
 *** xref:extension-migration-guide-16-to-20.adoc[]
 *** xref:extension-migration-guide-15-to-16.adoc[]
 ** Running in Frameworks

docs/modules/guides/pages/api-migration-guide-v25x-to-v30.adoc

@@ -0,0 +1,59 @@
+= AsciidoctorJ v3.0.x migration guide
+:navtitle: v3.0.x migration guide
+
+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<String,Object>` for both options and attributes.
+
+[,java]
+.Obtaining backing Map for OptionsBuilder
+----
+Map<String, Object> optionsMap = Options.builder()
+    .backend("html5")
+    .mkDirs(true)
+    .safe(SafeMode.UNSAFE)
+    .asMap();
+----
+
+[,java]
+.Obtaining backing Map for AttributesBuilder
+----
+Map<String, Object> 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<String, Object> optionsMap = options.map();
+----
+
+[,java]
+.Obtaining backing Map for Attributes
+----
+Attributes attributes = Attributes.builder()
+    .icons("font")
+    .sectionNumbers(true)
+    .build();
+Map<String, Object> attributesMap = attributes.map();
+----

docs/modules/guides/partials/removal-of-deprecated-methods-in-attributes.adoc

@@ -0,0 +1,73 @@
+== Removal of deprecated methods in `org.asciidoctor.Attributes`
+
+Several methods in `org.asciidoctor.Attributes` class that were marked as `@Deprecated` have been removed.
+This has been done to remove duplicated features and simplify the API interaction.
+
+=== Simplification of Attributes initialization
+
+In v2.5.x the following alternatives to initialize `Attributes` where possible:
+
+[,java]
+.Using Java Constructor and setters
+----
+Attributes attributes = new Attributes();
+attributes.setIcons("font");
+attributes.setNoFooter(true);
+----
+
+[,java]
+.Using Map constructor
+----
+Map<String, Object> attributesMap = new HashMap<>();
+attributesMap.put("toclevels", 2);
+attributesMap.put("icons", "font");
+Attributes attributes = new Attributes(attributesMap);
+----
+
+[,java]
+.Using AttributesBuilder.attributes() and get() methods
+----
+Attributes attributes = AttributesBuilder.attributes()
+    .icons("dont")
+    .noFooter(true)
+    .get();
+----
+
+The new API streamlines the process with a more standard builder approach, in which
+
+* Only interaction with `org.asciidoctor.Attributes` is required.
+* Nested methods offer IDE completion and creation of immutable instances.
+* Improved code readability through indentation.
+
+From v3.0.x, use the new `builder()` and `build()` methods from `org.asciidoctor.Attributes`.
+
+[,java]
+.Using Attributes builder
+----
+Attributes attributes = Attributes.builder()
+    .icons("dont")
+    .noFooter(true)
+    .build();
+----
+
+Note that `Attributes` setter methods are still available, that means that `Attributes` instances can still be modified as in this example.
+
+[,java]
+.Using setters on an instance
+----
+Attributes attributes = Attributes.builder().build();
+attributes.setIcons("font");
+attributes.setNoFooter(true);
+----
+
+[NOTE]
+====
+Free key-value insertion is still possible using:
+
+* `AttributesBuilder::attribute(String attributeName)`
+* `AttributesBuilder::attribute(String attributeName, Object attributeValue)`
+* `Attributes::setAttribute(String attributeName, Object attributeValue)`
+* `Attributes::setAttributes(String attributes)`
+* `Attributes::setAttributes(String... attributes)`
+* `Attributes::setAttributes(Map<String, Object> attributes)`
+====

docs/modules/guides/partials/removal-of-deprecated-methods-in-options.adoc

@@ -0,0 +1,170 @@
+== Removal of deprecated methods in `org.asciidoctor.Options`
+
+Several methods in `org.asciidoctor.Options` class that were marked as `@Deprecated` have been removed.
+This has been done to remove duplicated features and simplify the API interaction.
+
+=== Simplification of Options initialization
+
+In v2.5.x the following alternatives to initialize `Options` where possible:
+
+[,java]
+.Using Java Constructor and setters
+----
+Options options = new Options();
+options.setBackend("html5");
+options.setSafe(SafeMode.UNSAFE);
+options.setMkDirs(true);
+----
+
+[,java]
+.Using Map constructor
+----
+Map<String, Object> optionsMap = new HashMap<>();
+optionsMap.put("backend", "html5");
+optionsMap.put("sage", SafeMode.UNSAFE);
+optionsMap.put("mkdirs", true);
+Options options = new Options(optionsMap);
+----
+
+[,java]
+.Using OptionsBuilder.options() and get() methods
+----
+Options options = OptionsBuilder.options()
+    .backend("html5")
+    .mkDirs(true)
+    .safe(SafeMode.UNSAFE)
+    .get();
+----
+
+The new API streamlines the process with a more standard builder approach, in which
+
+* Only interaction with `org.asciidoctor.Options` is required.
+* Nested methods offer IDE completion and creation of immutable instances.
+* Improved code readability through indentation.
+
+From v3.0.x, use the new `builder()` and `build()` methods from `org.asciidoctor.Options`.
+
+[,java]
+.Using Options builder
+----
+Options options = Options.builder()
+    .backend("html5")
+    .mkDirs(true)
+    .safe(SafeMode.UNSAFE)
+    .build();
+----
+
+Note that `Options` setter methods are still available, that means that `Options` instances can still be modified as in this example.
+
+[,java]
+.Using setters on an instance
+----
+Options options = Options.builder().build();
+options.setBackend("html5");
+options.setSafe(SafeMode.UNSAFE);
+options.setMkDirs(true)
+----
+
+[NOTE]
+====
+Free key-value insertion is still possible using:
+
+* `OptionsBuilder::option(String option, Object value)`
+* `Options::setOption(String option, Object value)`
+====
+
+=== Simplification of Attributes injection in Options
+
+The previous API offered the following ways to inject attributes to an `Options` instance.
+
+[,java]
+.Using Attributes instance setter
+----
+Attributes attributes = new Attributes();
+options.setAttributes(attributes);
+----
+
+[,java]
+.Using Map setter
+----
+Map<String, Object> attributesMap = new HashMap<>();
+attributesMap.put("toclevels", 2);
+attributesMap.put("icons", "font");
+options.setAttributes(attributesMap);
+----
+
+Also, in v2.5.x it is possible to pass attributes to an `OptionsBuilder`.
+
+[,java]
+.Using OptionsBuilder's Attributes instance setter
+----
+Attributes attributes = new Attributes();
+Options options = OptionsBuilder.options()
+    .attributes(attributes)
+    .get();
+----
+
+[,java]
+.Using OptionsBuilder's Map setter
+----
+Map<String, Object> attributesMap = new HashMap<>();
+attributesMap.put("toclevels", 2);
+attributesMap.put("icons", "font");
+Options options = OptionsBuilder.options()
+    .attributes(attributesMap)
+    .get();
+----
+
+[,java]
+.Using OptionsBuilder's AttributesBuilder setter
+----
+AttributesBuilder attributesBuilder = AttributesBuilder.attributes();
+Options options = OptionsBuilder.options()
+    .attributes(attributesBuilder)
+    .get();
+----
+
+All these alternatives have been unified in two methods for `Options` and one for `OptionsBuilder`.
+
+[,java]
+.Using Attributes setter in Options
+----
+Attributes attributes = Attributes.builder()
+    .icons("font")
+    .build();
+
+Options options = Options.builder().build();
+options.setAttributes(attributes);
+----
+
+[,java]
+.Using attributes Map setter in Options
+----
+Map<String, Object> attributesMap = new HashMap<>();
+attributesMap.put("toclevels", 2);
+attributesMap.put("icons", "font");
+
+Options options = Options.builder().build();
+options.setAttributes(attributesMap);
+----
+
+[,java]
+.Using Attributes instance setter in OptionsBuilder
+----
+Attributes attributes = Attributes.builder()
+    .icons("font")
+    .build();
+Options options = Options.builder()
+    .attributes(attributes)
+    .build();
+----
+
+[NOTE]
+====
+Free key-value or string insertion is still possible using:
+
+* `AttributesBuilder::attribute(String attributeName)`
+* `AttributesBuilder::attribute(String attributeName, Object attributeValue)`
+* `Attributes::setAttributes(String attributes)`
+* `Attributes::setAttributes(String... attributes)`
+====