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.
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
```
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!
Locked
Jan 11, 2014; 10:53am
