diff --git a/docs/modules/guides/nav.adoc b/docs/modules/guides/nav.adoc index 78bfd71e..20c3eda8 100644 --- a/docs/modules/guides/nav.adoc +++ b/docs/modules/guides/nav.adoc @@ -1,6 +1,6 @@ * Help & Guides ** Updating to New Releases -***xref:api-migration-guide-v25x-to-v30.adoc[] +*** 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 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 ad34e5bf..d0c62f52 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 @@ -59,3 +59,7 @@ Map attributesMap = attributes.map(); ---- include::partial$removal-of-deprecated-methods-in-asciidoctor.adoc[] + +include::partial$update-preprocessor-api.adoc[] + +include::partial$update-macro-api.adoc[] diff --git a/docs/modules/guides/partials/update-macro-api.adoc b/docs/modules/guides/partials/update-macro-api.adoc new file mode 100644 index 00000000..c45a0e66 --- /dev/null +++ b/docs/modules/guides/partials/update-macro-api.adoc @@ -0,0 +1,75 @@ +== Update Macro Processors + +In the earlier version of AsciidoctorJ (2.5.x), the signature of Macro Processors required the implementation to return an unrestricted Object. +However, the specific type that a Macro Processor had to return was unclear, making it difficult to understand the necessary implementation steps. + +To address this issue, AsciidoctorJ 3.x.x has introduced the following changes: + +`InlineMacroProcessor::process`:: +The implementation of this method now needs to return a `PhraseNode`. +Please update your code accordingly to ensure that the returned value is of type `PhraseNode`. +`BlockMacroProcessor::process`:: +The implementation of this method now needs to return a `StructuralNode`. +Make sure to modify your implementation to return a `StructuralNode` as required. + +Moreover, there was a problem with the first parameter of the process method in InlineMacroProcessors. +Previously, it incorrectly expected a `PhraseNode` as the first parameter. + +To resolve this issue, AsciidoctorJ 3.x.x has rectified the first parameter of `InlineMacroProcessor::process` to be a `StructuralNode`. +Please ensure that you update your code accordingly to reflect this change. + +If you have any further questions or concerns, please refer to the updated documentation. + +=== Update Inline Macro Processors + +If your existing InlineMacroProcessor looks like this for AsciidoctorJ 2.5.x: + +[,java] +---- + public class TestInlineMacro extends InlineMacroProcessor { + @Override + public Object process(ContentNode parent, String target, Map attributes) { + return createPhraseNode(parent, "quoted", "This is from an Inline Macro"); + } + } +---- + +then you have to change it to this for AsciidoctorJ 3.x.x: + +[,java] +---- + public class TestInlineMacro extends InlineMacroProcessor { + @Override + public PhraseNode process(StructuralNode parent, String target, Map attributes) { + return createPhraseNode(parent, "quoted", "This is from an Inline Macro"); + } + } +---- + +In the above example you can see that the return type and the type of the first parameter of the process method have changed. + +=== Update Block Macro Processors + +If your existing BlockMacroProcessor looks like this for AsciidoctorJ 2.5.x: + +[,java] +---- + public class TestBlockMacro extends BlockMacroProcessor { + @Override + public Object process(StructuralNode parent, String target, Map attributes) { + return createBlock(parent, "paragraph", "This is from a Block Macro"); + } + } +---- + +then you have to change it to this for AsciidoctorJ 3.x.x: + +[,java] +---- + public class TestBlockMacro extends BlockMacroProcessor { + @Override + public StructuralNode process(StructuralNode parent, String target, Map attributes) { + return createBlock(parent, "paragraph", "This is from a Block Macro"); + } + } +---- diff --git a/docs/modules/guides/partials/update-preprocessor-api.adoc b/docs/modules/guides/partials/update-preprocessor-api.adoc new file mode 100644 index 00000000..2eade484 --- /dev/null +++ b/docs/modules/guides/partials/update-preprocessor-api.adoc @@ -0,0 +1,43 @@ +== Update Preprocessors + +In earlier versions of AsciidoctorJ (up to 2.5.x), Preprocessors were provided with a `Reader` object that they had to modify directly. +Unlike the Ruby implementation, the Java implementation of Asciidoctor did not support Preprocessors to return a new `Reader`. + +To address this limitation, AsciidoctorJ 3.0.0 has introduced a fix, enabling Preprocessors to create and return a new `Reader`. +This enhancement allows Preprocessors to have more flexibility and enables a cleaner implementation. + +If you have existing Preprocessors, it is essential to update the signature of their process method to return a Reader object, even if the implementation does not create a new Reader object and returns null. + +The following example shows how to update a Preprocessor to return a new `Reader`: + +.Preprocessor for AsciidoctorJ 2.5.x +[,java] +---- + public static class MyPreprocessor extends Preprocessor { + + @Override + public void process(Document document, PreprocessorReader reader) { + // Do something with the reader + } + } +---- + +To ensure compatibility with AsciidoctorJ 3.0.0, the process method of the Preprocessor needs to be modified to return a `Reader`. +However, if you wish to maintain the same behavior as before, the method can simply return `null`. + +.Preprocessor for AsciidoctorJ 3.x.x +[,java] +---- + public static class MyPreprocessor extends Preprocessor { + + @Override + public Reader process(Document document, PreprocessorReader reader) { + // Do something with the reader + return null; + } + } +---- + +You may find it helpful to review the methods `Processor::newReader` and `PreprocessorReader::read` to simplify your code when creating a new `Reader` and reading the content of the existing `Reader`. + +However, please note that following the steps mentioned above will be sufficient to migrate your existing processor.