Asciidoctor :: Discussion

Re: Reaching Asciidoctor 1.5.0 and beyond

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

2 messages Options

mojavelinux

Re: Reaching Asciidoctor 1.5.0 and beyond

Administrator

At last, we have a release candidate! If all goes well, I'll release the final version this week.

http://rubygems.org/gems/asciidoctor/versions/1.5.0.rc.1

Please give it a try, experiment with it, abuse it, whatever you need to do. We want to put our best foot forward for 1.5.0.

For the Groovy folks, the release candidate will have the relative leveloffset feature for you to try. Once Alex releases the AsciidoctorJ 1.5.0.rc.1, you can try it...or you can try a local snapshot.

NOTE: I'm aware of a parse error when attempting to compile Asciidoctor.js. I'll likely push an rc.2 once we get that resolved. If we notice any other problems, I'll try to include fixes for them in rc.2 as well.

There are now 6 open issues remaining, several of which are documentation or infrastructure issues.

Here's where we stand with the original list I posted (using the Asciidoctor task list syntax, [*] means done)

* [*] Ensure the default stylesheet delivers a consistent appearance by switching the font family to Noto and retrieve the fonts from Google Web Fonts (#879)

* [*] 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 (and README)

* [ ] Write a blog entry to announce the release and highlights key improvements and changes

The really hard stuff is done. We just need to put the final touches on it and run it through QA!

It's important for me to emphasize that this release candidate includes two changes to the AsciiDoc syntax. When you upgrade to Asciidoctor 1.5.0, the first thing you should do is add the following attribute entry to the top (or header) of existing documents:

```

:compat-mode: legacy

```

Then, you should verify that you have updated to the new syntax for italic and monospaced text. For italic text, you should replace single quotes with underscores.

```asciidoc

Use _italic_ instead of 'italic'.

```

For monospaced text, follow the recommendations in the following comment:

https://github.com/asciidoctor/asciidoctor/issues/718#issuecomment-50289412

Once you've switched to the new syntax (or the transitional syntax), then remove the compat-mode attribute entry from your document.

For new documents, I strongly urge you to use the new (or transitional) syntax.

If you have any questions or concerns, please feel free to chime in!

-Dan

On Fri, Jun 20, 2014 at 6:13 PM, Dan Allen <[hidden email]> wrote:

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:

https://github.com/asciidoctor/asciidoctor/issues?direction=desc&milestone=8&sort=updated&state=open

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!

-Dan

--
Dan Allen | http://google.com/profiles/dan.j.allen

Dan Allen | http://google.com/profiles/dan.j.allen

asotobu

Re: Reaching Asciidoctor 1.5.0 and beyond

From AsciidoctorJ I need to integrate some changes on extension API (IncludeProcessor), I will try to do it during this week, but if I can't this weekend I will spend one night in finishing the integration for sure.