Added descriptions for migrating extensions from 1.6.x to 2.0.x
MODIFY
asciidoctorj-documentation/src/main/asciidoc/extension-migration-guide.adoc
asciidoctorj-documentation/src/main/asciidoc/extension-migration-guide.adoc
@@ -39,12 +39,82 @@ ifdef::awestruct,env-browser[]
toc::[]
endif::[]
+This document explains the necessary steps to lift an extension from an older version of AsciidoctorJ to a newer version.
+If you want to migrate from 1.5.x to the latest version, i.e. 2.0.x, please follow all individual sections, i.e. first <<Migrate15x-16x>> and then <<Migrate16x-20x>>.
+
+[[Migrate16x-20x]]
+== Migrating from AsciidoctorJ 1.6.x to 2.0.x
+
+Between 1.6.x and 2.0.x there are only very few API changes that affect an extension writer.
+
+You might have implemented the `org.asciidoctor.extension.spi.ExtensionRegistry` Service Interface to automatically register extensions as explained in the <<integrator-guide.adoc#ExtensionSPI,Integrator Guide>>.
+To achieve this you might have added these two artifacts:
+
+First the implementation:
+
+[source,java]
+.MyExtension.java for AsciidoctorJ 1.5.x or 1.6.x
+----
+package com.example;
+
+import org.asciidoctor.extension.spi.ExtensionRegistry;
+
+public class MyExtension implements ExtensionRegistry {
+ @Override
+ public void register(Asciidoctor asciidoctor) {
+ JavaExtensionRegistry javaExtensionRegistry = asciidoctor.javaExtensionRegistry();
+ javaExtensionRegistry.treeprocessor(MyTreeprocessor.class);
+ }
+}
+----
+
+Additionally you have added a file in `META-INF/services/` that declares your extensions and allows it to be discovered:
+
+./META-INF/services/org.asciidoctor.extension.spi.ExtensionRegistry for AsciidoctorJ 1.5.x or 1.6.x
+----
+com.example.MyExtension
+----
+
+Now the interface `org.asciidoctor.extension.spi.ExtensionRegistry` moved to `org.asciidoctor.jruby.extension.spi.ExtensionRegistry`.
+That means that you have to update the name of the interface and rename the file in `/META-INF/services/`.
+In particular the last step is easily overseen as the compiler will not warn you.
+
+Therefore the implementation has to look like this:
+
+[source,java]
+.MyExtension.java for AsciidoctorJ 2.0.x
+----
+package com.example;
+
+import org.asciidoctor.jruby.extension.spi.ExtensionRegistry; // <1>
+
+public class MyExtension implements ExtensionRegistry {
+ @Override
+ public void register(Asciidoctor asciidoctor) {
+ JavaExtensionRegistry javaExtensionRegistry = asciidoctor.javaExtensionRegistry();
+ javaExtensionRegistry.treeprocessor(MyTreeprocessor.class);
+ }
+}
+----
+<1> Import ExtensionRegistry from the new package
+
+Additionally the file `/META-INF/services/org.asciidoctor.extension.spi.ExtensionRegistry` has to be renamed to `/META-INF/services/org.asciidoctor.jruby.extension.spi.ExtensionRegistry`.
+
+./META-INF/services/org.asciidoctor.jruby.extension.spi.ExtensionRegistry for AsciidoctorJ 2.0.x
+----
+com.example.MyExtension
+----
+
+
+[[Migrate15x-16x]]
+== Migrating from AsciidoctorJ 1.5.x to 1.6.x
+
AsciidoctorJ 1.6.0 fixed many issues with extensions, but also brought some incompatible changes in comparison to 1.5.x.
In fact these incompatible changes were necessary to fix some of these bugs.
This guide explains how to migrate an existing extension for AsciidoctorJ 1.5.x to 1.6.0.
We will take an existing extension from the 1.5.x test cases and migrate it step by step to 1.5.x.
-== The original extension
+=== The original extension
As an example we are taking the `YellStaticBlock` extension.
This is a BlockProcessor that transforms the contents of the corresponding block to upper case.
@@ -112,7 +182,7 @@ import org.asciidoctor.ast.AbstractBlock;
This is because the AST interfaces were renamed to better represent their purpose.
The next section shows how these have to be updated.
-== Update to new AST class names
+=== Update to new AST class names
The following table shows the new AST class names with their counterparts in AsciidoctorJ 1.5.x.
See the <<integrator-guide#,Integrator Guide>> for details about the purpose of the classes.
@@ -216,7 +286,7 @@ Finally it is rather ugly that the constructor has to take a parameter `config`,
The next section shows how this can be done in a more concise way.
-== Instantiating and configuring extensions
+=== Instantiating and configuring extensions
The configuration of an extension has to be known at the time of registration.
With AsciidoctorJ 1.5.x the way to define the configuration was to pass it to the super constructor and every extension type had to implement one certain constructor.

MODIFY
asciidoctorj-documentation/src/main/asciidoc/integrator-guide.adoc
asciidoctorj-documentation/src/main/asciidoc/integrator-guide.adoc
@@ -1025,6 +1025,7 @@ include::src/test/java/org/asciidoctor/integrationguide/extension/RobotsDocinfoP
<3> Docinfo Processors will only be called by Asciidoctor if the safe mode is at least `SECURE`.
<4> Test via the Jsoup HTML parsing library that our meta tag was correctly added to the resulting document.
+[[ExtensionSPI]]
=== Extension SPI
In previous examples, the extensions were registered manually.

MODIFY
docs/extension-migration-guide.adoc
docs/extension-migration-guide.adoc
@@ -39,12 +39,82 @@ ifdef::awestruct,env-browser[]
toc::[]
endif::[]
+This document explains the necessary steps to lift an extension from an older version of AsciidoctorJ to a newer version.
+If you want to migrate from 1.5.x to the latest version, i.e. 2.0.x, please follow all individual sections, i.e. first <<Migrate15x-16x>> and then <<Migrate16x-20x>>.
+
+[[Migrate16x-20x]]
+== Migrating from AsciidoctorJ 1.6.x to 2.0.x
+
+Between 1.6.x and 2.0.x there are only very few API changes that affect an extension writer.
+
+You might have implemented the `org.asciidoctor.extension.spi.ExtensionRegistry` Service Interface to automatically register extensions as explained in the <<integrator-guide.adoc#ExtensionSPI,Integrator Guide>>.
+To achieve this you might have added these two artifacts:
+
+First the implementation:
+
+[source,java]
+.MyExtension.java for AsciidoctorJ 1.5.x or 1.6.x
+----
+package com.example;
+
+import org.asciidoctor.extension.spi.ExtensionRegistry;
+
+public class MyExtension implements ExtensionRegistry {
+ @Override
+ public void register(Asciidoctor asciidoctor) {
+ JavaExtensionRegistry javaExtensionRegistry = asciidoctor.javaExtensionRegistry();
+ javaExtensionRegistry.treeprocessor(MyTreeprocessor.class);
+ }
+}
+----
+
+Additionally you have added a file in `META-INF/services/` that declares your extensions and allows it to be discovered:
+
+./META-INF/services/org.asciidoctor.extension.spi.ExtensionRegistry for AsciidoctorJ 1.5.x or 1.6.x
+----
+com.example.MyExtension
+----
+
+Now the interface `org.asciidoctor.extension.spi.ExtensionRegistry` moved to `org.asciidoctor.jruby.extension.spi.ExtensionRegistry`.
+That means that you have to update the name of the interface and rename the file in `/META-INF/services/`.
+In particular the last step is easily overseen as the compiler will not warn you.
+
+Therefore the implementation has to look like this:
+
+[source,java]
+.MyExtension.java for AsciidoctorJ 2.0.x
+----
+package com.example;
+
+import org.asciidoctor.jruby.extension.spi.ExtensionRegistry; // <1>
+
+public class MyExtension implements ExtensionRegistry {
+ @Override
+ public void register(Asciidoctor asciidoctor) {
+ JavaExtensionRegistry javaExtensionRegistry = asciidoctor.javaExtensionRegistry();
+ javaExtensionRegistry.treeprocessor(MyTreeprocessor.class);
+ }
+}
+----
+<1> Import ExtensionRegistry from the new package
+
+Additionally the file `/META-INF/services/org.asciidoctor.extension.spi.ExtensionRegistry` has to be renamed to `/META-INF/services/org.asciidoctor.jruby.extension.spi.ExtensionRegistry`.
+
+./META-INF/services/org.asciidoctor.jruby.extension.spi.ExtensionRegistry for AsciidoctorJ 2.0.x
+----
+com.example.MyExtension
+----
+
+
+[[Migrate15x-16x]]
+== Migrating from AsciidoctorJ 1.5.x to 1.6.x
+
AsciidoctorJ 1.6.0 fixed many issues with extensions, but also brought some incompatible changes in comparison to 1.5.x.
In fact these incompatible changes were necessary to fix some of these bugs.
This guide explains how to migrate an existing extension for AsciidoctorJ 1.5.x to 1.6.0.
We will take an existing extension from the 1.5.x test cases and migrate it step by step to 1.5.x.
-== The original extension
+=== The original extension
As an example we are taking the `YellStaticBlock` extension.
This is a BlockProcessor that transforms the contents of the corresponding block to upper case.
@@ -112,7 +182,7 @@ import org.asciidoctor.ast.AbstractBlock;
This is because the AST interfaces were renamed to better represent their purpose.
The next section shows how these have to be updated.
-== Update to new AST class names
+=== Update to new AST class names
The following table shows the new AST class names with their counterparts in AsciidoctorJ 1.5.x.
See the <<integrator-guide#,Integrator Guide>> for details about the purpose of the classes.
@@ -216,7 +286,7 @@ Finally it is rather ugly that the constructor has to take a parameter `config`,
The next section shows how this can be done in a more concise way.
-== Instantiating and configuring extensions
+=== Instantiating and configuring extensions
The configuration of an extension has to be known at the time of registration.
With AsciidoctorJ 1.5.x the way to define the configuration was to pass it to the super constructor and every extension type had to implement one certain constructor.

MODIFY
docs/integrator-guide.adoc
docs/integrator-guide.adoc
@@ -1538,6 +1538,7 @@ To make AsciidoctorJ use our processor it also has to be registered at the `Java
<3> Docinfo Processors will only be called by Asciidoctor if the safe mode is at least `SECURE`.
<4> Test via the Jsoup HTML parsing library that our meta tag was correctly added to the resulting document.
+[[ExtensionSPI]]
=== Extension SPI
In previous examples, the extensions were registered manually.

Added descriptions for migrating extensions from 1.6.x to 2.0.x