About the PDF-Generator Prawn
Asciidoctor PDF is made possible by an amazing Ruby gem named Prawn. And what a gem it is! Prawn is a nimble PDF writer for Ruby. More important, it’s a hackable platform that offers both high level APIs for the most common needs and low level APIs for bending the document model to accommodate special circumstances.
|Asciidoctor PDF is currently alpha software. While the converter handles most AsciiDoc content, there’s still work needed to fill in gaps where conversion is incomplete, incorrect or not implemented. See the milestone v1.5.0 in the Issue tracker for details.|
With Prawn, you can write text, draw lines and shapes and place images anywhere on the page and add as much color as you like. In addition, it brings a fluent API and aggressive code re-use to the printable document space.
Here’s an example that demonstrates how to use Prawn to create a basic PDF document.
require 'prawn' Prawn::Document.generate 'output.pdf' do text 'Hello, PDF creation!' end
It’s that easy. And that’s just the beginning.
Prawn is the killer library for PDF generation we’ve needed to close this critical gap in Asciidoctor. It absolutely takes the pain out of creating printable documents. Picking up from there, Asciidoctor PDF takes the pain out of creating PDF documents from AsciiDoc.
Direct AsciiDoc to PDF conversion
PDF document outline (i.e., bookmarks)
Table of contents page(s)
Document metadata (title, authors, subject, keywords, etc)
Internal cross reference links
Syntax highlighting with Rouge, Pygments, or CodeRay
Customizable running content (header and footer)
“Keep together” blocks (i.e., page breaks avoided in certain block content)
Orphaned section titles avoided
Autofit verbatim blocks (as permitted by base_font_size_min setting)
Table border settings honored
Custom (TTF) fonts
Double-sided printing mode (margins alternate on recto and verso pages)
All that’s needed is Ruby (1.9.3 or above; 2.3.x recommended) and a few Ruby gems, which we explain how to install in the next section.
To check if you have Ruby available, use the
ruby command to query the version installed:
$ ruby --version
By default, Asciidoctor PDF automatically installs the latest version of Prawn if you don’t already have Prawn installed. This will fail on older versions of Ruby. To workaround, you need to install certain dependencies first.
Starting with Prawn 2.0.0, Prawn requires Ruby >= 2.0.0 during installation. Therefore, to use Asciidoctor PDF with Ruby 1.9.3, you must first explicitly install the following dependencies to lock the versions:
$ gem install prawn --version 1.3.0 gem install addressable --version 2.4.0 gem install prawn-svg --version 0.21.0 gem install prawn-templates --version 0.0.3
You can then proceed with installation of Asciidoctor PDF on Ruby 1.9.3.
Starting with Prawn 2.2.0, Prawn requires Ruby >= 2.1.0 during installation. Therefore, to use Asciidoctor PDF with Ruby 2.0.0, you must first explicitly install the following dependencies to lock the versions:
$ gem install prawn --version 2.1.0 gem install prawn-svg --version 0.26.0 gem install prawn-templates --version 0.0.4
For all other versions of Ruby, you can simply install the Asciidoctor PDF gem. It will transitively install the required dependencies.
Asciidoctor assumes you’re using UTF-8 encoding. To minimize encoding problems, make sure the default encoding of your system is set to UTF-8.
If you’re using a non-English Windows environment, the default encoding of your system may not be UTF-8. As a result, you may get an
Encoding::UndefinedConversionError or other encoding issues when invoking Asciidoctor. To solve these problems, we recommend at least changing the active code page in your console to UTF-8.
Once you make this change, all your Unicode headaches will be behind you.
You can get Asciidoctor PDF by installing the published gem or running th code from source.
Install the Published Gem
Asciidoctor PDF is published as a pre-release on RubyGems.org. First, make sure you have satisfied the prerequisites. Then, you can install the published gem using the following command:
$ gem install asciidoctor-pdf --pre
If you want to syntax highlight source listings, you’ll also want to install Rouge, Pygments, or CodeRay. Choose one (or more) of the following:
$ gem install rouge
$ gem install pygments.rb
$ gem install coderay
You then activate syntax highlighting for a given document by adding the
source-highlighter attribute to the document header (Rouge shown):
Assuming all the required gems install properly, verify you can run the
$ asciidoctor-pdf -v
If you see the version of Asciidoctor PDF printed, you’re ready to use Asciidoctor PDF.
Let’s grab an AsciiDoc document to distill and start putting Asciidoctor PDF to use!
An Example AsciiDoc Document
If you don’t already have an AsciiDoc document, you can use the basic_example.adoc file found in the examples directory of this project.
= Document Title Doc Writer <firstname.lastname@example.org> :doctype: book :reproducible: :source-highlighter: rouge :listing-caption: Listing A simple http://asciidoc.org[AsciiDoc] document. == Introduction A paragraph followed by a simple list with square bullets. [square] * item 1 * item 2 Here's how you say "`Hello, World!`" in Prawn: .Create a basic PDF document using Prawn [source,ruby] ---- require 'prawn' Prawn::Document.generate 'example.pdf' do text 'Hello, World!' end ----
It’s time to convert the AsciiDoc document directly to PDF.
Convert AsciiDoc to PDF
| You’ll need the |
Converting to PDF is a simple as running the
asciidoctor-pdf script using Ruby and passing our AsciiDoc document as the first argument.
$ asciidoctor-pdf 000_basic_example.adoc
This command is just a shorthand way of running:
$ asciidoctor -r asciidoctor-pdf -b pdf 000_basic_example.adoc
asciidoctor-pdf command just saves you from having to remember all those flags. That’s why we created it.
When the script completes, you should see the file 000_basic_example.pdf in the same directory. Open the 000_basic_example.pdf file with a PDF viewer to see the result.
You’re also encouraged to try converting the documents in the examples directory to see more of what Asciidoctor PDF can do.
The pain of the DocBook toolchain should be melting away about now.
The layout and styling of the PDF is driven by a YAML configuration file. To learn how the theming system works and how to create and apply custom themes, refer to the Asciidoctor PDF Theme Guide. You can use the built-in theme files, which you can find in the data/themes directory, as examples.
Support for Non-Latin Languages
Asciidoctor can process the full range of characters in the UTF-8 character set. That means you can write your document in any language, save the file with UTF-8 encoding, and expect Asciidoctor to convert the text properly. However, you may notice that certain characters for certain languages, such as Chinese, are missing in the PDF. Read on to find out why and how to address it.
If you’re writing in a non-Latin language, you need to use a dedicated theme that provides the necessary fonts. For example, to produce a PDF from a document written in a CJK language such as Chinese, you need to use a CJK theme. You can get such a theme by installing the
asciidoctor-pdf-cjk-kai_gen_gothic gem. See the asciidoctor-pdf-cjk-kai_gen_gothic project for detailed instructions.
Using a dedicated theme is necessary because PDF is a “bring your own font” kind of system. In other words, the font you provide must provide glyphs for all the characters. There’s no one font that supports all the worlds languages (though some, like Noto Serif, certainly come close). Even if there were such a font, bundling that font with the main gem would make the package enormous. It would also severely limit the style choices in the default theme, which targets Latin-based languages.
Therefore, we’re taking the strategy of creating separate dedicated theme gems that target each language family, such as CJK. The base theme for CJK languages is provided by the asciidoctro-pdf-cjk project and a concrete implementation provided by the asciidoctor-pdf-cjk-kai_gen_gothic project that’s based on the kai_gen_gothic font. Of course, you’re free to follow this model and create your own theme gem that uses fonts of your choice.