A native PDF renderer for AsciiDoc!

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

A native PDF renderer for AsciiDoc!

mojavelinux
Administrator
Hey everyone!

I return with exciting news! Our first gig as OpenDevise, Inc. was to create a custom PDF document for NFJS, the Magazine from articles written in AsciiDoc. We were excited about this project since it would give us the opportunity to invest time in better solutions for PDF rendering in Asciidoctor.

Since we only had 2 weeks to complete the project, I quickly ruled out trying to customize the DocBook XSL stylesheets (for sanity!) and decided instead to explore using a Ruby-based PDF writer named Prawn. I was pleasantly surprised by its capabilities and managed to complete the project on time with some bonus features. You can see the result of it if you have access to the December Issue of NFJS, the Magazine at http://nofluffjuststuff.com/home/magazine_subscribe (a great magazine, btw).

Since completing the project, I've been heads down working to refactor the code into a general purpose PDF renderer for the Asciidoctor community and get it pushed to GitHub. Low and behold, I present Asciidoctor PDF, a native PDF renderer for AsciiDoc!!

No more DocBook toolchain.
No more middleman.
It's AsciiDoc direct to PDF.


Check out the README for more details, instructions on how to use it and some examples: https://github.com/opendevise/asciidoctor-pdf/blob/master/README.adoc

Asciidoctor PDF is currently alpha software, so use accordingly. Though it renders the bulk of AsciiDoc content, there’s still work needed to fill in gaps where rendering is incomplete, incorrect or not implemented. Once it’s ready, and we are happy with the name, we'll move the project into the Asciidoctor organization on GitHub to indicate it has the community seal of approval.

At the moment, Asciidoctor PDF works by loading the AsciiDoc source into the Asciidoctor AST and then walks the tree to build the PDF document. Ideally, we want to plug this in as a custom renderer in Asciidoctor. However, Asciidoctor doesn't currently expose the renderer as an extension point. I'm going to try to get that enhancement in for Asciidoctor 1.5.0 so that I can hook in Asciidoctor PDF as a first-class citizen.

I'm truly excited about Prawn. Finally, a decent solution for creating PDFs. Honestly, it's one of the best APIs I've come across in Ruby. With it, you can create a PDF document in only 4 lines of code:

```ruby

require 'prawn'
Prawn::Document.generate 'example.pdf' do
  text 'Hello, PDF creation!'
end

```

That's it! From there, the sky is the limit. You can format text, draw lines and shapes, add images, use custom fonts and much more.

Prawn also recognizes HTML-like inline formatting in text strings.

```ruby

text '<a href="http://asciidoctor.org">Asciidoctor</a> is a <em>fast</em>, Ruby-based AsciiDoc processor.', inline_format: true

```

I took the liberty of writing our own formatted text parser to extend the markup it recognizes and to give us the control we need as we grow. I built the parser using Treetop, which was quite a fun and challenging exercise. 

You can also extend Prawn's DSL to wrap up common code and make it more descriptive. For instance, here's the callback for rendering a paragraph block in Asciidoctor PDF:

```ruby

def render_paragraph_node node
  prose node.content
end

```

Remembering how painful it is to customize the formatting and style of a PDF using the DocBook toolchain, I implemented a simple theme mechanism in Asciidoctor PDF that's driven by a YAML configuration file with support for basic math operations. You can see how the default theme is defined here: https://github.com/opendevise/asciidoctor-pdf/blob/master/data/themes/default-theme.yml.

The configuration structure and default theme are inspired by Bootstrap 3. It's a pretty good start, but of course, we can build in additional controls as needed.

It's good to be back. I'm so glad we're already starting off 2014 with ground-breaking work! Let's keep the documentation revolution going!

Cheers and Happy New Year!
Jmm
Reply | Threaded
Open this post in threaded view
|

Re: A native PDF renderer for AsciiDoc!

Jmm
I am wordless ...

I browsed over your mail this morning and was impressed. I re-read it now and am even more impressed and look forward to try it out.

Well done, Dan !


I now have a (priority) problem: do I invest my time in learning and eventually adapting this important feature or do I complete my maven asciidoc archetype that implements a complete PDF production pipeline with Docbook and sample customization.

I think that I will choose the later: I am too near to finish my "industrialized" docbook based pipeline and want to use it to present it (and make the promotion of it) for the company.

Jmm


2014/1/11 mojavelinux [via Asciidoctor :: Discussion] <[hidden email]>
Hey everyone!

I return with exciting news! Our first gig as OpenDevise, Inc. was to create a custom PDF document for NFJS, the Magazine from articles written in AsciiDoc. We were excited about this project since it would give us the opportunity to invest time in better solutions for PDF rendering in Asciidoctor.

Since we only had 2 weeks to complete the project, I quickly ruled out trying to customize the DocBook XSL stylesheets (for sanity!) and decided instead to explore using a Ruby-based PDF writer named Prawn. I was pleasantly surprised by its capabilities and managed to complete the project on time with some bonus features. You can see the result of it if you have access to the December Issue of NFJS, the Magazine at http://nofluffjuststuff.com/home/magazine_subscribe (a great magazine, btw).

Since completing the project, I've been heads down working to refactor the code into a general purpose PDF renderer for the Asciidoctor community and get it pushed to GitHub. Low and behold, I present Asciidoctor PDF, a native PDF renderer for AsciiDoc!!

No more DocBook toolchain.
No more middleman.
It's AsciiDoc direct to PDF.


Check out the README for more details, instructions on how to use it and some examples: https://github.com/opendevise/asciidoctor-pdf/blob/master/README.adoc

Asciidoctor PDF is currently alpha software, so use accordingly. Though it renders the bulk of AsciiDoc content, there’s still work needed to fill in gaps where rendering is incomplete, incorrect or not implemented. Once it’s ready, and we are happy with the name, we'll move the project into the Asciidoctor organization on GitHub to indicate it has the community seal of approval.

At the moment, Asciidoctor PDF works by loading the AsciiDoc source into the Asciidoctor AST and then walks the tree to build the PDF document. Ideally, we want to plug this in as a custom renderer in Asciidoctor. However, Asciidoctor doesn't currently expose the renderer as an extension point. I'm going to try to get that enhancement in for Asciidoctor 1.5.0 so that I can hook in Asciidoctor PDF as a first-class citizen.

I'm truly excited about Prawn. Finally, a decent solution for creating PDFs. Honestly, it's one of the best APIs I've come across in Ruby. With it, you can create a PDF document in only 4 lines of code:

```ruby

require 'prawn'
Prawn::Document.generate 'example.pdf' do
  text 'Hello, PDF creation!'
end

```

That's it! From there, the sky is the limit. You can format text, draw lines and shapes, add images, use custom fonts and much more.

Prawn also recognizes HTML-like inline formatting in text strings.

```ruby

text '<a href="http://asciidoctor.org">Asciidoctor</a> is a <em>fast</em>, Ruby-based AsciiDoc processor.', inline_format: true

```

I took the liberty of writing our own formatted text parser to extend the markup it recognizes and to give us the control we need as we grow. I built the parser using Treetop, which was quite a fun and challenging exercise. 

You can also extend Prawn's DSL to wrap up common code and make it more descriptive. For instance, here's the callback for rendering a paragraph block in Asciidoctor PDF:

```ruby

def render_paragraph_node node
  prose node.content
end

```

Remembering how painful it is to customize the formatting and style of a PDF using the DocBook toolchain, I implemented a simple theme mechanism in Asciidoctor PDF that's driven by a YAML configuration file with support for basic math operations. You can see how the default theme is defined here: https://github.com/opendevise/asciidoctor-pdf/blob/master/data/themes/default-theme.yml.

The configuration structure and default theme are inspired by Bootstrap 3. It's a pretty good start, but of course, we can build in additional controls as needed.

It's good to be back. I'm so glad we're already starting off 2014 with ground-breaking work! Let's keep the documentation revolution going!

Cheers and Happy New Year!



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

Reply | Threaded
Open this post in threaded view
|

Re: A native PDF renderer for AsciiDoc!

daveb
In reply to this post by mojavelinux
Wow! What a Christmas present for us all.  Truly amazing work Dan.

Presumably this doesn't play nicely with the math support you have added to 0.1.4?

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

Re: A native PDF renderer for AsciiDoc!

mojavelinux
Administrator

On Mon, Jan 13, 2014 at 3:28 AM, daveb [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Wow! What a Christmas present for us all.  Truly amazing work Dan.

Thanks! And now, a present brought on by autumn leaves, a release!

 

Presumably this doesn't play nicely with the math support you have added to 0.1.4?

It's coming {1}. There is a way to make it work using the Mathoid extension {2}, but it's not the easiest to setup atm.

-Dan