Asciidoctor does well in translating asciidoc documents to html5, docbook and etc. Chinese documents also looks great in html5 and docbook. But sometimes we need to use PDF to share with others. Unfortunately, this is not easy for Chinese documents. This document shares my experience converting Chinese asciidoc documents into pdfs.

Overview of approaches to convert asciidoc to PDFs

There are currently 3 ways to convert asciidoc documents to PDF:

asciidoctor-pdf

asciidoctor-pdf is an alpha-state software in ruby to convert asciidoc documents directly into pdf, without any other tools.

While asciidoctor is nimble, it does not support CJK/multilingual documents.The output of asciidoctor-pdf is quite similar to that of asciidoctor to html5 backends, with coderay or pygments code highlights and similar fonts as the html5 backends. It’s worth trying for english documents.

At the time of writing, asciidoctor-pdf does not support fontawesome icon font. So the callouts and admotions are simple charactors.

asciidoctor-latex

asciidoctor-latex is a beta-state software in ruby to add latex support for asciidoctor. It can also convert asciidoc documents directly into latex.

With asciidoctor-latex, we can translate first asciidoc documents into latex and use latex/xelatex to produce pdf output. This makes it possible to modify the contents before final production and use ctex/xeCJK for Chinese documents.

The drawback of this approach is that it does not support the beautiful asciidoctor themes.

asciidoctor-fopub

asciidoctor-fopub is an fop based approach to produce pdf output for asciidoc docuemnts. It makes use of the docbook backend of asciidoc to produce docbook and uses Apache FOP to produce final pdf documents.

Currently asciidoctor-fopub produces the best pdf outputs. It supports the original asciidoctor theme, using SVG images for callouts and admotions. Code highlights are supported through xlsthl. It produces nice looking pdfs for English documents out of the box.

For the above ways, asciidoctor-fopub is the most mature and so is choosen as my defaults. It’s worth watching asciidoctor-pdf, which produces the best results but there are still a lot to be done in it to support CJK documents.

Install the software

Install asciidoctor-fopub is easy, you can use either the gem install approach or the github download approach.

Convert asciidoc to PDF

After successfully installing asciidoctor-fopub, one can use the following commands to convert asciidoc document into PDFs:

asciidoctor -b docbook EXAMPLE.adoc (1)
fopub EXAMPLE.xml (2)

1

Convert asciidoctor documents into docbook format with asciidoctor

2

Generate PDFs using fopub command from asciidoctor-fopub

fopub downloads proper versions of fop, docbook-xls and other components for the first run and maintains its internal copy of these software. So for the first time, it needs network connections to function.

If properly configured, the above commands produces nice looking PDFs for Chinese docuemnts out of the box.

Configure asciidoctor-fopub

Basicly, there are three steps to configure asciidoctor fopub for proper Chinese PDF production. It mainly follows the FOP font generation and configuration.

Generate font metrics

The first step for asciidoctor-fopub Chinese PDF configuration is to generate font metrics for fonts to use.

FOP comes with its own format of font metrics and every font to use shall be generated metric files first and registered to FOP. To generate the metric, use the following commands:

Then put the generated metric file into a single location. I prefer ~/.local/share/fop/fonts.

Register font to asciidoctor-fopub

After above procedure, one shall create the following registeration in FOP configuration file. For the above gem installed version, the configuration file resides in ~/.gem/ruby/gems/asciidoctor-fopub-0.0.1/build/fopub/docbook-xsl/fop-config.xml. Put the following into <render mime='application/pdf'> section:

Configure asciidoctor-fopub to use registered font

Now we are almost ready. The last step is to configure fopub to use the registered fonts. Assuming we have registered font with name 'SimSun', we the change the file ~/.gem/ruby/gems/asciidoctor-fopub-0.0.1/build/fopub/docbook-xsl/fo-pdf.xsl to use it:

Appendix 2: Generate chinese section titles

The default document generated by asciidoctor docbook backend uses English for document language, which makes the section title, table title, table of contents etc. English. We can set the lang attribute to zh_CN when generating Chinese document: