Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
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
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!
|
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
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]>
... [show rest of quote] |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
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. |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
Administrator
|
On Mon, Jan 13, 2014 at 3:28 AM, daveb [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Thanks! And now, a present brought on by autumn leaves, a release!
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 |
Free forum by Nabble | Edit this page |