From 5b20ad4062b600192165fc1f63cde575b5fb05ee Mon Sep 17 00:00:00 2001
From: Abel Salgado Romero <abelromero@gmail.com>
Date: Sun, 21 May 2023 21:36:02 +0200
Subject: [PATCH] v3 migration guide for 'Asciidoctor' removed methods

Fixes #1201
---
 .../api-migration-guide-v25x-to-v30.adoc      |  2 +
 ...-of-deprecated-methods-in-asciidoctor.adoc | 73 +++++++++++++++++++
 2 files changed, 75 insertions(+)
 create mode 100644 docs/modules/guides/partials/removal-of-deprecated-methods-in-asciidoctor.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 2bec16df..ad34e5bf 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
@@ -57,3 +57,5 @@ Attributes attributes = Attributes.builder()
     .build();
 Map<String, Object> attributesMap = attributes.map();
 ----
+
+include::partial$removal-of-deprecated-methods-in-asciidoctor.adoc[]
diff --git a/docs/modules/guides/partials/removal-of-deprecated-methods-in-asciidoctor.adoc b/docs/modules/guides/partials/removal-of-deprecated-methods-in-asciidoctor.adoc
new file mode 100644
index 00000000..c3d061cf
--- /dev/null
+++ b/docs/modules/guides/partials/removal-of-deprecated-methods-in-asciidoctor.adoc
@@ -0,0 +1,73 @@
+== Removal of deprecated methods in `org.asciidoctor.Asciidoctor`
+
+Several methods in `org.asciidoctor.Asciidoctor` that were marked as `@Deprecated` have been removed.
+
+=== Removal of methods using `Map<String,Object>` as options input
+
+To streamline the API, only methods using `Options` instances have been left in the `org.asciidoctor.Asciidoctor`.
+That means that the following methods are no longer available.
+
+[,java]
+.Removed convert methods
+----
+String convert(String content, Map<String, Object> options);
+String convertFile(File file, Map<String, Object> options);
+
+void convert(Reader contentReader, Writer rendererWriter, Map<String, Object> options) throws IOException;
+
+<T> T convert(String content, Map<String, Object> options, Class<T> expectedResult);
+<T> T convertFile(File file, Map<String, Object> options, Class<T> expectedResult);
+
+String[] convertDirectory(Iterable<File> directoryWalker, Map<String, Object> options);
+String[] convertFiles(Collection<File> files, Map<String, Object> options);
+----
+
+[,java]
+.Removed load methods
+----
+Document load(String content, Map<String, Object> options);
+Document loadFile(File file, Map<String, Object> options);
+----
+
+For each of the methods above there's an equivalent using `org.asciidoctor.Options`.
+Use those when migrating to v3.0.0.
+
+=== Removal of methods using `OptionsBuilder` as options input
+
+Likewise to the methods seen in the previous section, the following methods are also no longer available.
+
+[,java]
+.Removed convert methods
+----
+String convert(String content, OptionsBuilder options);
+String convertFile(File file, OptionsBuilder options);
+
+void convert(Reader contentReader, Writer rendererWriter, OptionsBuilder options) throws IOException;
+
+<T> T convert(String content, OptionsBuilder options, Class<T> expectedResult);
+<T> T convertFile(File file, OptionsBuilder options, Class<T> expectedResult);
+
+String[] convertDirectory(Iterable<File> directoryWalker, OptionsBuilder options);
+String[] convertFiles(Collection<File> files, OptionsBuilder options);
+----
+
+For each of the methods above there's an equivalent using `org.asciidoctor.Options.Options`.
+Use those when migrating to v3.0.0.
+
+=== Removal of methods `readDocumentHeader`
+
+All implementations of `Asciidoctor::readDocumentHeader` have been removed because the same feature can be obtained using `load` with the `parse_header_only` option.
+
+[,java]
+.Using load to obtain Document header
+----
+Options options = Options.builder().option("parse_header_only", true).build();
+Document document = asciidoctor.loadFile(documentHeaders, options);
+
+List<Author> authors = document.getAuthors();
+RevisionInfo revisionInfo = document.getRevisionInfo();
+String doctitle = document.getDoctitle();
+Title structuredDoctitle = document.getStructuredDoctitle();
+----
+
+As a consequence, class `org.asciidoctor.ast.DocumentHeader` has been also removed.