Next steps for AsciidoctorJ

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

Next steps for AsciidoctorJ

mojavelinux
Administrator
Alex et al,

There are two important changes we are currently scheduling in AsciidoctorJ:

* Distributing AsciidoctorJ PDF and AsciidoctorJ EPUB3 jars
* Pluggable Asciidoctor implementation (JRuby and Nashorn)

I know we really want to get the pluggable Asciidoctor implementation integrated and released, but I think that the request from the community to produce jars for AsciidoctorJ PDF and AsciidoctorJ EPUB3 is more urgent. I've given some thought about how to proceed and I've come up with a proposal.

My proposal is to perform the work of reorganizing the AsciidoctorJ repository in two discrete phases.

Phase #1::
  Convert the current single-module build to a multi-module build that is capable of building & distributing jars for asciidoctorj, asciidoctorj-pdf and asciidoctor-epub3 (maybe asciidoctorj-diagram too).
  To avoid sinking more time & effort into the Maven build, I think we should also switch to Gradle at this point.
  Switching to Gradle also allows us to leverage the JRuby Gradle plugin, which is much more capable of doing what we need to do than the Maven support.

Phase #2::
  Split the core module into an API and multiple implementations (asciidoctorj-api, asciidoctorj-jruby, asciidoctorj-nashorn).

NOTE: After phase #2 is complete, we can still produce an asciidoctorj jar that combines the asciidoctorj-api and asciidoctorj-jruby for backward compatibility and convenience.

I think we should complete Phase #1 for the AsciidoctorJ 1.5.2 release.

I thought about whether we should keep the PDF and EPUB3 modules inside the AsciidoctorJ repository or split them out as individual repositories. What I concluded is that splitting them out would be too much administrative overhead for right now. Instead, we can release these components when we release AsciidoctorJ, using the gem versions available at the time. If we need to make an interim release of a component (e.g., asciidoctorj-pdf), we can create a dedicated tag for that upgrade and release only that component out of the repository. Gradle affords us this flexibility, which is one of the key reasons I want to switch to it now.

To summarize, I consider it imperative to get a jar for Asciidoctor PDF released as part of the AsciidoctorJ 1.5.2 release. I believe that my proposal gives us a way to make that happen. I'm thinking Phase #2 would then be most appropriate for the AsciidoctorJ 1.6.0 release.

I'm interested to hear your feedback about this plan.

Cheers,

-Dan

p.s. Another reason to be more patient about the Nashorn support is that it can't be used until JDK 8u40 is released anyway (due to bugs we found in Nashorn, which are now fixed in the EA builds).

--
Reply | Threaded
Open this post in threaded view
|

Re: Next steps for AsciidoctorJ

glaforge
Amen :-)

On Thu, Nov 27, 2014 at 9:17 AM, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Alex et al,

There are two important changes we are currently scheduling in AsciidoctorJ:

* Distributing AsciidoctorJ PDF and AsciidoctorJ EPUB3 jars
* Pluggable Asciidoctor implementation (JRuby and Nashorn)

I know we really want to get the pluggable Asciidoctor implementation integrated and released, but I think that the request from the community to produce jars for AsciidoctorJ PDF and AsciidoctorJ EPUB3 is more urgent. I've given some thought about how to proceed and I've come up with a proposal.

My proposal is to perform the work of reorganizing the AsciidoctorJ repository in two discrete phases.

Phase #1::
  Convert the current single-module build to a multi-module build that is capable of building & distributing jars for asciidoctorj, asciidoctorj-pdf and asciidoctor-epub3 (maybe asciidoctorj-diagram too).
  To avoid sinking more time & effort into the Maven build, I think we should also switch to Gradle at this point.
  Switching to Gradle also allows us to leverage the JRuby Gradle plugin, which is much more capable of doing what we need to do than the Maven support.

Phase #2::
  Split the core module into an API and multiple implementations (asciidoctorj-api, asciidoctorj-jruby, asciidoctorj-nashorn).

NOTE: After phase #2 is complete, we can still produce an asciidoctorj jar that combines the asciidoctorj-api and asciidoctorj-jruby for backward compatibility and convenience.

I think we should complete Phase #1 for the AsciidoctorJ 1.5.2 release.

I thought about whether we should keep the PDF and EPUB3 modules inside the AsciidoctorJ repository or split them out as individual repositories. What I concluded is that splitting them out would be too much administrative overhead for right now. Instead, we can release these components when we release AsciidoctorJ, using the gem versions available at the time. If we need to make an interim release of a component (e.g., asciidoctorj-pdf), we can create a dedicated tag for that upgrade and release only that component out of the repository. Gradle affords us this flexibility, which is one of the key reasons I want to switch to it now.

To summarize, I consider it imperative to get a jar for Asciidoctor PDF released as part of the AsciidoctorJ 1.5.2 release. I believe that my proposal gives us a way to make that happen. I'm thinking Phase #2 would then be most appropriate for the AsciidoctorJ 1.6.0 release.

I'm interested to hear your feedback about this plan.

Cheers,

-Dan

p.s. Another reason to be more patient about the Nashorn support is that it can't be used until JDK 8u40 is released anyway (due to bugs we found in Nashorn, which are now fixed in the EA builds).

--



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Next-steps-for-AsciidoctorJ-tp2488.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Guillaume Laforge
Groovy Project Manager
Pivotal, Inc.

Reply | Threaded
Open this post in threaded view
|

Re: Next steps for AsciidoctorJ

asotobu
In reply to this post by mojavelinux
Dan in my repo I have a layout which perfectly fits the phase1 and phase 2 https://github.com/lordofthejars/asciidoctorj/tree/feature_189, then can you take look and if you agree let's send a PR to the origin repo and let's start working with issues but based on this new layout.

WDYT?

BTW it really helps me you set the milestone to the issues. It helps me on focusing on what to develop.
Reply | Threaded
Open this post in threaded view
|

Re: Next steps for AsciidoctorJ

Victor Romero
So glad to read this.
Reply | Threaded
Open this post in threaded view
|

Re: Next steps for AsciidoctorJ

bodiam
In reply to this post by mojavelinux
Hi Dan,

I see your note about Nashorn, but what about Rhino? My current Rhino tests outperform Nashorn by at least 30%, while functionally they are the same. Is this also something to consider?

Erik
Reply | Threaded
Open this post in threaded view
|

Re: Next steps for AsciidoctorJ

domgold
In reply to this post by mojavelinux
+1 for this roadmap.

Though I don't see the urge to switch to a gradle build too quickly. (I admit that I feel pretty comfortable with Maven :-) )
 What feature exactly do you have in mine when you mention the ruby gradle plugin?

Dominik

Reply | Threaded
Open this post in threaded view
|

Re: Next steps for AsciidoctorJ

mojavelinux
Administrator
You can find the completed pull request here.


I'll merge after a few more minor cleanups.

> What feature exactly do you have in mine when you mention the ruby gradle plugin?

Most notably, one of the maintainers of the plugin is an Asciidoctor community member (Schalk). As for the JRuby Maven plugins, they seem to live in a vacuum and it frustrates me tremendously that there's absolutely 0 documentation about how to use them and no roadmap. So, Gradle wins here big time.

We also need more control about how to package the gems inside the jar and Gradle gives us that power. We're able to reduce the size of the AsciidoctorJ jar file from 27MB down to 650K. I'd say that's pretty good motivation to use Gradle.

Plus, Gradle, even with its kinks, is a much better build tool. It's smarter about incremental building and testing and the Gradle daemon runs the build lighting fast. I've been working with the Gradle build in AsciidoctorJ for almost a week now and I can say for sure that it's boosting productivity.

-Dan

On Thu, Nov 27, 2014 at 8:34 AM, domgold [via Asciidoctor :: Discussion] <[hidden email]> wrote:
+1 for this roadmap.

Though I don't see the urge to switch to a gradle build too quickly. (I admit that I feel pretty comfortable with Maven :-) )
 What feature exactly do you have in mine when you mention the ruby gradle plugin?

Dominik




If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Next-steps-for-AsciidoctorJ-tp2488p2493.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--