Reaching Asciidoctor 1.5.0 and beyond

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Reaching Asciidoctor 1.5.0 and beyond

mojavelinux
Administrator
As many of you are well aware, its been a long road to Asciidoctor 1.5.0. Asciidoctor began as a minimum viable implementation to replace AsciiDoc Python on GitHub. It has become a serious documentation toolchain and the driver of the AsciiDoc syntax.

I've always seen the 1.5.0 release as a reflection of that evolution. I fallen a bit into the trap of wanting to fit all the improvements we've planned into this release. It's come time to wrap up this development cycle and trust that future versions will bring the deferred improvements. Releasing Asciidoctor 1.5.0 will open the door to the AsciidoctorJ and Asciidoctor.js 1.5.0 releases as well as initial releases of Asciidoctor PDF and Asciidoctor EPUB 3.

With that said, there are still changes and improvements remaining that I want to make part of this release. These changes are as follows:

* Ensure the default stylesheet delivers a consistent appearance by switching the font family to Noto and retrieve the fonts from Google Web Fonts (#879)
  - This change has the added benefit of aligning with Asciidoctor core values by relying only on Open Source fonts
* Upgrade Font Awesome to 4.1 (#752)
* Add source map information to blocks (critical for writing plugins) (#861)
* Add option or attribute to swap role of backtick and plus characters for inline literals (#714 and 718)
* Add option to control use of single quote as a formatting character, disable by default (#717)
* Enable embedding of remote images when data-uri and allow-uri-read is set (#612)
* Move parsing of document subtitle to main parser, expose via Document API
* Ensure compatibility with Asciidoctor.js (mostly done) and AsciidoctorJ
* Update the changelog
* Write a blog entry to announce the release and highlights key improvements and changes

Here's a complete list of what's currently assigned to 1.5.0, some of which may be moved off to a later release:


There are some other unreported (but noted) issues I may want to add to this list, so I'll update it after I review my notes.

I've also worked really hard to improve the performance of Asciidoctor 1.5.0. I've always been very particular about Asciidoctor's performance because the faster the parser, the more pleasant it is to use and the more doors it opens. There are a few features I've pushed off to later versions because they may affect performance and I don't want to sacrifice where we are right now until we get out the 1.5.0 release. We'll have plenty of time to evaluate these trade-offs in later releases.

Last month, I set a goal to have the Asciidoctor 1.5.0 out by mid June. Unfortunately, I ran into housing problems and it significantly disrupted my productivity. I expect to be moved into my new place by the end of the weekend and I can work without interruption.

How about we plan to push the Asciidoctor 1.5.0 release on July 1?

If you want to help achieve this goal, I ask that you keep a close eye on the issue tracker for the next couple of weeks and provide feedback and test the changes as we try to wrap up decisions necessary to finish the issues above.

Thank you all for your participation. I'm confident Asciidoctor 1.5.0 is going to put us on a great path towards making documentation rock!

Reply | Threaded
Open this post in threaded view
|

Re: Reaching Asciidoctor 1.5.0 and beyond

asotobu
Good news. In case of AsciidoctorJ it is almost integrated as well.

It will only require some work on extensions API if there are some changes between latest preview and the final release.

Also I will add a new package called experimental where users will be able to use asciidoctor.js instead of JRuby to render documents. In this case there is only some work in my sandbox, so I will only need to incorporate to the project and clean some dirty hacks (Viktor is helping in this task).

And of course a lot of improvements and deprecations as well.

Probably for version 1.6.0 we will need to talk about how to deal with RubySymbols in Java part and of course if it has a good acceptance the javascript integration in AsciidoctorJ add a way to write extensions in Javascript and execute them within JVM.

The release of AsciidoctorJ 1.5.0.Final it won't be 1st of July for sure, but I will try to be the next week.

Alex.
Reply | Threaded
Open this post in threaded view
|

Re: Reaching Asciidoctor 1.5.0 and beyond

mojavelinux
Administrator

On Sun, Jun 22, 2014 at 3:21 AM, asotobu [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Also I will add a new package called experimental where users will be able to use asciidoctor.js instead of JRuby to render documents. In this case there is only some work in my sandbox, so I will only need to incorporate to the project and clean some dirty hacks (Viktor is helping in this task).

Alex, this is really exciting!

One small word of advise. Let's ensure we don't get into a situation where the experimental package morphs into a public API like what happened in JUnit. I imagine long term the switch between Ruby and JavaScript implementation can be controlled via a switch in the main public API. Is that your plan?

Reply | Threaded
Open this post in threaded view
|

Re: Reaching Asciidoctor 1.5.0 and beyond

asotobu
My idea is releasing for 1.5.0 two artefacts, one without js integration and compiled with JDK6. And another one with js integrated and in experimental package and compiled with Java8 (because we are using Nashorn). Of course this may change if the same code works for Rhino as well but I am not sure it would be possible, let's see. About experimental my idea is that in 3 months make a release of AsciidoctorJ (and if it is with an Asciidoctor release too then better), to move the classes from final package instead of experimental. I want this first release to be at experimental because I am not an expert on Nashorn, so I prefer that users are aware that it may be some pieces that can not work correctly.

About Asciidoctor Js integration I am having one problem which it can be a bug on Nashorn. I have contacted people from Oracle but they said me that they need a trivial example and I am not pretty sure how to do it.

Look I have isolated the error in a unit test:

https://github.com/lordofthejars/asciidoctorjs/blob/master/src/test/java/rhino/RenderDocumentWithRhino.java

If I render document from eval calling:

System.out.println(engine.eval("Opal.Asciidoctor.$render(content, hash2);", simpleScriptContext));

it works perfectly, but if instead of using eval I use the getInstance approach:

AsciidoctorJs asciidoctorJs = invocable.getInterface(AsciidoctorJs.class);
System.out.println(asciidoctorJs.render(content, eval));

then this exception is thrown:

<eval>:12234 TypeError: Cannot call undefined
        at jdk.nashorn.internal.runtime.ECMAErrors.error(ECMAErrors.java:56)
        at jdk.nashorn.internal.runtime.ECMAErrors.typeError(ECMAErrors.java:212)
        at jdk.nashorn.internal.runtime.ECMAErrors.typeError(ECMAErrors.java:184)
        at jdk.nashorn.internal.runtime.ECMAErrors.typeError(ECMAErrors.java:171)

Basically it says that in file asciidoctor.js at line 12234 (timing.$start) cannot be called. I am not sure why it works with one approach and not with the other one. I will find a way to debug javascript from java but if you have any idea it will be welcome :)

Reading I see that Invocable's invokeFunction, invokeMethod and getInterface methods look for backing scripting functions in ENGINE_SCOPE of script engine's own Script Context (you can get/set that by ScriptEngine.getContext, ScriptEngine.setContext methods).

But Oracle guys told me that my code it seems ok, but they will review my code if I can simplify the javascript code.

As a workaround if I can't find a solution, I will release with eval approach, but of course I would prefer to release using getInterface approach.

Reply | Threaded
Open this post in threaded view
|

Re: Reaching Asciidoctor 1.5.0 and beyond

mojavelinux
Administrator

Great assessment. With that detail, hopefully we can get to the bottom of things. I'll see what I can do to help.

Cheers!

-Dan

On Jul 28, 2014 3:18 PM, "asotobu [via Asciidoctor :: Discussion]" <[hidden email]> wrote:
My idea is releasing for 1.5.0 two artefacts, one without js integration and compiled with JDK6. And another one with js integrated and in experimental package and compiled with Java8 (because we are using Nashorn). Of course this may change if the same code works for Rhino as well but I am not sure it would be possible, let's see. About experimental my idea is that in 3 months make a release of AsciidoctorJ (and if it is with an Asciidoctor release too then better), to move the classes from final package instead of experimental. I want this first release to be at experimental because I am not an expert on Nashorn, so I prefer that users are aware that it may be some pieces that can not work correctly.

About Asciidoctor Js integration I am having one problem which it can be a bug on Nashorn. I have contacted people from Oracle but they said me that they need a trivial example and I am not pretty sure how to do it.

Look I have isolated the error in a unit test:

https://github.com/lordofthejars/asciidoctorjs/blob/master/src/test/java/rhino/RenderDocumentWithRhino.java

If I render document from eval calling:

System.out.println(engine.eval("Opal.Asciidoctor.$render(content, hash2);", simpleScriptContext));

it works perfectly, but if instead of using eval I use the getInstance approach:

AsciidoctorJs asciidoctorJs = invocable.getInterface(AsciidoctorJs.class);
System.out.println(asciidoctorJs.render(content, eval));

then this exception is thrown:

<eval>:12234 TypeError: Cannot call undefined
        at jdk.nashorn.internal.runtime.ECMAErrors.error(ECMAErrors.java:56)
        at jdk.nashorn.internal.runtime.ECMAErrors.typeError(ECMAErrors.java:212)
        at jdk.nashorn.internal.runtime.ECMAErrors.typeError(ECMAErrors.java:184)
        at jdk.nashorn.internal.runtime.ECMAErrors.typeError(ECMAErrors.java:171)

Basically it says that in file asciidoctor.js at line 12234 (timing.$start) cannot be called. I am not sure why it works with one approach and not with the other one. I will find a way to debug javascript from java but if you have any idea it will be welcome :)

Reading I see that Invocable's invokeFunction, invokeMethod and getInterface methods look for backing scripting functions in ENGINE_SCOPE of script engine's own Script Context (you can get/set that by ScriptEngine.getContext, ScriptEngine.setContext methods).

But Oracle guys told me that my code it seems ok, but they will review my code if I can simplify the javascript code.

As a workaround if I can't find a solution, I will release with eval approach, but of course I would prefer to release using getInterface approach.




If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Reaching-Asciidoctor-1-5-0-and-beyond-tp1847p1930.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML