PandocとLuaLaTeXを使ったPDF出力でコードブロックをきれいに表示する

ドキュメント変換ツール Pandoc の LaTeX を使った PDF 出力。

この投稿では前回の HTML 変換に引き続いて、Pandoc を使って Markdown テキストを PDF へ変換する方法を書いています。

使用環境：Windows7 64bit, pandoc 1.13.2, TeXLive 2014

LuaLaTeX

Pandoc の PDF 出力の場合、標準では pdfLaTeX が使われます。本家の Web サイトでは pdfLaTeX をサポートした MiKTeX を薦めていますが、日本語テキストを扱う場合は LuaLaTeX がお薦めです。この LuaLaTeX では日本語組版に対応した LuaTeX-ja パッケージがサポートされています。

Windows 環境への LuaLaTeX のインストールは TeX Live を使います。専用のインストーラが用意されているので簡単にインストールできます。

TeX Liveとは

TeX Live は TeX のディストリビューションのひとつで TeX 環境がこのディストリビューションパッケージにまとめられています。現在では日本語組版に必要な要素のほとんどすべてがまるっと取り込まれているので、TeX Live をインストールするだけで日本語文書を扱うことができます。

TeX Live 2014をインストール

今回は TeX Live 2014 インストール用 DVD を作成してインストールしました。 出来上がった DVD の中の install-tl-windows.bat を実行するとインストールを開始できます。インストールに要した時間は DVD インストールでは約 1 時間でした。また別件で DVD の内容全てを HDD 上にコピー後（ISO ファイルがマウントできるならコピー不要）インストールした場合では約 30 分でした。HDD 上でインストール作業が可能な場合は後者がお勧めです。

TeX Live の最新版 TeX Live 2014 の ISO イメージファイル

• Acquiring TeX Live as an ISO image - TeX Users Group

TeX Live をインストールすると TeX の総合環境 TeXworks が付いてきます。LaTeX ファイルの動作確認など便利に使えます。

参考： インストール後の TeXworks の日本語環境の設定等が分かりやすく書かれています。

• TeX Live/Windows - TeX Wiki

PDF出力を試してみる

はじめに Markdown テキストを PDF ファイルに変換してみましょう。

1. コマンドプロンプトからpandoc -o hello.pdfを入力
2. #Hello Pandocを入力
3. Crtl + Zキーを押してEOFを入力

>pandoc -o hello.pdf
#Hello Pandoc
^Z

問題が無ければカレントフォルダにhello.pdfが出力されているはずです。

このように TeX Live を使えば Pandoc から簡単に PDF 出力できるようになります。

日本語を含んだMarkdownファイルをPDFに変換する場合

日本語文章を PDF 出力する場合は、日本語に対応したLaTeX エンジンとドキュメントクラスを Pandoc に指定して変換します。

たとえば LaTeXエンジンに LuaLaTeX を指定、ドキュメントクラスに ltjarticle を指定する場合は、コマンドにこのオプションを追加します。

--latex-engine=lualatex -V documentclass=ltjarticle

Pandoc のデフォルトエンコーディングは UTF-8 になっています。そのため、コマンドプロンプトから入力した日本語テキストを標準入力から Pandoc に入力すると、内部エンコードの違いでうまくいきません。ここでは入力用の Markdown ファイルを作成して試すことにします。

はじめに任意の Markdown テキストを記述したファイルを作成して UTF-8 でファイルを保存します。 この例ではファイル名input.mdで保存します。

input.md

#こんにちはPandoc

次のコマンドを実行して PDF へ変換します。

pandoc -f markdown input.md -s -o output.pdf ^
--latex-engine=lualatex ^
-V documentclass=ltjarticle

カレントフォルダにoutput.pdfが出力されているはずです。

この例で Pandoc は、入力されたファイルを LaTeX 形式に変換後 LuaLaTeX を経由して PDF を出力しています。このとき-sオプションによって LaTeX 用のテンプレートが適用されています。

ここで、入力した Markdown 形式の内容が、どのように LaTeX 形式に変換されたのかを知るには、出力ファイルを LaTeX 形式に指定することで確認できます。

pandoc -f markdown input.md -s -o output.tex ^
--latex-engine=lualatex ^
-V documentclass=ltjarticle

出力されたファイルoutput.texを TeXworks で開き、LuaLaTeX でタイプセットすると PDF 出力と同じ内容のプレビューを TeXworks で確認することができます。

用紙サイズやマージンの指定は-V geometry:を使うと便利です。

A4用紙に設定する

-V geometry:a4paper

マージンを1cmに設定する

-V geometry:margin=1cm

文書クラス（ドキュメントクラス）

文書クラスは LaTeX の文章の体裁や論理構造を決める情報ファイルです。LaTeX でよく使われる文書クラスは article, book, report などがあります。 (ファイルの拡張子は .cls )

日本語に対応した標準的な文書クラスはjsclassesです。接頭辞のjsは（Japanese Standard）の意味を含んでいるそうです。このファイルは新しい標準的な文書クラスとして 2000 年に公開されました。

• jsarticle.cls （標準的な横書き論文・レポート）
• jsbook.cls （標準的な横書き書籍）

LuaLaTeX用の文書クラス

LuaLaTeX で使用する文書クラスは jsclasses を LuaTeX-ja 用に調整されたものがあります。 LuaLaTeX では接頭辞にltが付いた文書クラスltjsclassesなどを使用します。

インストールフォルダを調べると下記のクラスファイルが見つかりました。Pandoc での動作確認結果と合わせて一覧に示します。

デフォルトインストールではこのフォルダに入っています。
C:\texlive\2014\texmf-dist\tex\luatex\luatexja

クラスファイル名	Pandocで使用の可否
ltjarticle.cls	OK
ltjreport.cls	OK
ltjbook.cls	OK
ltjltxdoc.cls	OK
ltjsarticle.cls	OK （ただし要パッチ）
ltjsbook.cls	NG （エラー発生）
ltjskiyou.cls	NG （エラー発生）
ltjspf.cls	NG （エラー発生）

LuaLaTeX で ltjsarticle を指定するとエラーが発生しましたが、この情報を参考にパッチを当てると使えるようになりました。

• Pandoc::PDF への変換で ltjsarticle を使うとエラーが出る - TeX Wiki

PDFのコードブロックをきれいに表示する。

実際に Markdown を PDF 変換してみると分かるのですが、Pandoc で出力したコードブロックはシンプルすぎて本文とコードブロックの違いが分かり難かったり、コードブロックの行の折り返しが行われず行が長くなると右側にはみ出た部分が途切れてしまい良くありません。

この場合 Pandoc の--listingsオプションを使うと、コードブロックの表示を良い感じに設定できます。

Pandoc: --listingsオプション

--listingsオプションの有無の違いをコマンドラインで確認してみましょう。

Pandoc 標準のコードブロック

>pandoc -t latex
```
puts "Hello Pandoc"
```
^Z
\begin{verbatim}
puts "Hello Pandoc"
\end{verbatim}

標準の PDF 出力のコードブロックは LaTeX の verbatim 環境に変換されるようです。これは入力どおりの内容をそのまま出力するもので、改行以外の文字で折り返すことなくそのまま表示されます。

つぎは、Pandoc --listingsオプション付きのコードブロック

>pandoc -t latex --listings
```
puts "Hello Pandoc"
```
^Z
\begin{lstlisting}
puts "Hello Pandoc"
\end{lstlisting}

このように、--listingsオプションを付けるとコードブロックが verbatim 環境から lstlisting 環境に変わります。この例では文字が入れ替わっただけの違いしか有りませんが、lstlisting 環境では行の折り返しは勿論のこと、シンタックスハイライトや行番号表示などが可能になります。

lstlisting 環境の設定はコマンドラインで指定すると冗長になるので、あらかじめ別ファイルlistings-setup.texに設定を書いておきます。

コードの先頭 4 行は lstlisting 環境の設定とは関係ありません。ここではフォント埋め込みや用紙サイズ、数式のためのパッケージの設定等を合わせて設定しています。

listings-setup.tex

コードブロックに listings 設定ファイルを適用するには、-H xxx.texオプションで指定します。その場合次のコマンドを実行します。

pandoc -f markdown input.md ^
-V documentclass=ltjsarticle ^
--latex-engine=lualatex ^
--listings -H listings-setup.tex ^
-o output.pdf

GFM の場合

pandoc -f markdown_github+fenced_code_attributes ^
input.md ^
-V documentclass=ltjsarticle ^
--latex-engine=lualatex ^
--listings -H listings-setup.tex ^
-o output.pdf

コードブロックの書き方

LaTeX の lstlisting 属性の記述方法も可能のようです。

この例ではコードブロックの左に行番号を表示、開始番号を 10 に指定、コードブロックのキャプションを設定しています。

```{language=Ruby numbers=left startFrom=10 caption="\{This is caption of code block\}"}
require 'sinatra'
#こんにちはPandoc

get '/' do
  'Hello Pandoc!'
end
```

PDF 出力の結果

Pandoc の属性記述方法の場合

この例では言語をRuby、行番号を表示、開始番号を 1 に指定しています。

```{ .ruby .numberLines startFrom="1"}
require 'sinatra'
#こんにちはPandoc

get '/' do
  'Hello Pandoc!'
end
```

PDF 出力の結果

Pandoc の属性記述方法（言語名のみ）

```ruby
require 'sinatra'
#こんにちはPandoc

get '/' do
  'Hello Pandoc!'
end
```

PDF 出力の結果

LaTeXコマンドを使う

Markdown の PDF 化では、HTML 出力したファイルをブラウザの PDF プリンタを経由して PDF ファイルに保存することができますが、改ページの位置を PDF プリンタに委ねなければなりません。Pandoc を使って Markdown から PDF を出力する場合は、テキスト内に LaTeX コマンドを記述して改ページをコントロールすることができます。あわせて、拡張書式tex_math_dollarsを有効にしておくと、数式にインライン数式の$...$が使えるので便利です。

Markdown テキストの中に LaTeX コマンドを記述する場合、記述方法で注意することがあります。 というのも、HTML 出力で MathJax を使う場合では数式と LaTeX コマンドの両方を$...$の中に記述できます。いっぽうで、PDF 出力の場合では LaTeX を経由するため$...$は数式モードを表します。そのため数式モードで使えないコマンドを$...$の中に記述するとエラーになる場合があります。

LaTeX コマンドを使って改ページする場合は、テキスト内の改ページしたい位置にnewpageコマンドをそのまま記述します。

\newpage

コマンドラインでは、拡張書式raw_texとtex_math_dollarsを追加して実行します。 GFM の場合このようなコマンドになります

pandoc -f markdown_github-hard_line_breaks^
+raw_tex+tex_math_dollars^
+fenced_code_attributes ^
input.md ^
-V documentclass=ltjsarticle ^
--latex-engine=lualatex ^
--listings -H listings-setup.tex ^
-o output.pdf

まとめ

Markdown テキストから簡単に PDF 出力できる Pandoc の便利さを改めて感じました。また、これまでは MathJax の数式でしか LaTeX 環境に触れたことが無かったのですが、今回の TeX Live のインストールを期に、ほんの少しですが LaTeX の世界について知ることができました。もっと LaTeX コマンドを使いこなせるようになれば活用方法が広がりそうです。

参考：

Pandocの紹介記事

• HTML - 多様なフォーマットに対応！ドキュメント変換ツールPandocを知ろう - Qiita

TeX Liveの解説

• TeX Live - TeX Wiki

Pandocの--listingsオプション設定ファイルの使い方

• Pandoc: Markdown to PDF, without cutting off code block lines that are too long - TeX - LaTeX Stack Exchange
• listings.sty: LaTeX パッケージ

lstlisting 環境の詳細は The Listings Package listings.pdf に書かれています。

• CTAN: tex-archive/macros/latex/contrib/listings

Pandoc には他にも多くの機能があります、興味を持った方はユーザーズガイドを読んでみてください。

本家ユーザーズガイド

• Pandoc - Pandoc User’s Guide

日本語ユーザーズガイド

• Pandoc ユーザーズガイド 日本語版 - Japanese Pandoc User's Association