HTML
Haskell
TeX
Markdown
Pandoc

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


追記(14.02.07)

Pandoc User’s Guideを日本語に全訳しました。

よろしければご参照ください。


はじめに

今回は、ドキュメント作成Tips Advent Calendar 2012の1日目

マインドマップから全てを紡ぎ出す - XMind+Pandocのドキュメント作成術 -

で少し紹介したPandocというツールについて、もう少し深く掘り下げて紹介したいと思います。


MarkdownとかreStructuredTextとか、流行ってますよね

いわゆる軽量マークアップ言語が最近流行しています。特にMarkdownは猫も杓子もMarkdownな状態ですね。

一方で、Word文書、LaTeX、PDFなどの形式が提出文書として指定される場合も多々あります。

MarkdownやreSTで書いた文書を色々なフォーマットに変換できたら嬉しいですよね。


電子書籍(EPUB)も流行ってますよね

Kindleの上陸により、電子書籍を作成する需要が高まっています。

一方で、HTMLで書いた文書がしこたま溜まっていたり、

(特に学術系の方は)LaTeXで作成した本や論文がいっぱいあったりして、

それらを電子書籍化したい、という方も多いと思います。

HTMLやLaTeXがEPUBに変換できたら嬉しいですよね。


それらを実現するのがPandocです

PandocはMarkdown, HTML, LaTeX, reStructuredTextなどを

様々な形式(Markdown, reST, HTML, LaTeX, Word, PDFなどなど)に変換出来る強力なツールです。

Pandocが日本であまり知られていないのは、非常に残念に思います。

ここでは、ドキュメント作成の強い味方となるPandocについて、入門編として紹介します。


Pandocとは

Pandocは、Haskell製のドキュメント変換ツールです。

この手のツールとしては、reStructuredTextを用いるSphinxが有名で、

他にも特定のマークアップ言語用のツールが多数存在します。

しかしながら、Pandocはこのようなツールとは大きく違う点があります。

それは、対応フォーマットが恐ろしく豊富な点と、開発が活発な点です


長所


とにかく対応フォーマットが豊富

まずは、対応フォーマットを見て下さい。


入力

入力フォーマットは、以下に対応しています:


  • Markdown

  • Textile

  • reStructuredText

  • HTML

  • LaTeX

  • DocBook XML

  • OPML (追記 14.05.09)

  • Emacs Org-mode (追記 14.05.09)

  • Literate Haskell (Markdown,reST,LaTeX)


出力

出力フォーマットは以下の通りです(一部省略しています):


  • Plain Text

  • Markdown

  • reStructuredText

  • HTML


    • XHTML

    • HTML 5

    • HTMLスライドショー (Slidy, Slideous, DZSlides or S5)



  • DocBook XML

  • LaTeX


    • プレゼン用スタイルファイル beamer も出力可



  • RTF

  • ODT

  • Word docx

  • MediaWiki markup

  • EPUB

  • Emacs Org-Mode

  • OPML (追記 14.05.09)

  • Adobe InDesign ICML (追記 14.05.09)

  • PDF (LaTeXをインストールしている場合のみ)

詳細はこちらをご覧ください。


開発が活発

Pandocは2012年12月現在、開発が比較的活発です。

その証拠に、Pandocの開発用グループである pandoc-discuss - Google グループ で、2012年12月1日〜12月22日に更新されたトピック(スレッド)は33件ありました。


開発が比較的容易

(以下、推測ですが)開発が活発な要因としては、開発が比較的容易であることが考えられます。


機能ごとにモジュール化されている

Pandocは書き出しモジュール (Writer)、読み込みモジュール (Reader)などのように、

うまくモジュール化されています。

そのため、部分ごとの拡張が比較的容易になっています。


HaskellのパーサコンビネータParsecをうまく利用している

また、PandocはHaskellで書かれています。

Haskellには、構文解析を行うためのパーサコンビネータParsecがあり、Pandocはこれを有効活用しています。

Parsecは正規表現よりも強力(LL(n)文法が解析可)なため、HTMLなどタグを囲むような文法を容易に解析できます。

しかもParsecは単なるHaskellのライブラリなので、Haskellの文法知識だけで理解できます。

そのため、特別な文法を覚える必要があるyaccなどのパーサジェネレータに比べて、

Parsecの方が分かりやすく簡潔に書けます。

以上の理由から、Pandocは開発が容易であることが考えられます。


最近、Org-mode用読み込みモジュールの開発がスタート

(以下、Emacs Org-modeユーザ向けになりますが)

これまで書き出ししか対応していなかったOrg-mode文書に対して、

読み込みモジュール(Reader)の開発が始まっているそうです。

これが完成すれば、さらにPandocの世界が広がること間違い無しです。

楽しみにしましょう。

Emacs Org-modeの読み込みモジュールが完成しました!(14.05.09現在)


短所

一方で、Pandocにも短所があります。


独自の読み込み・書き込みエンジンにより処理するため、文書の仕様をカバーできていない場合がある

Pandocは独自の読み込み・書き込みエンジンにより処理を行っています。

そのため、文書の仕様に沿っていない部分もあります。

また、内部的にはHTMLで表現できる形式で処理されているため、その表現能力を超えるようなことはできません。

この欠点は、特にLaTeX(使った事無いですが、おそらくreSTも)に影響します。


Pandocのインストール

下記リンクをご覧ください。

Pandocの比較的簡単なインストール方法 - Qiita


基本的な使い方

ここでは例としてMarkdownを入力形式とし、HTMLを出力してみます。

もちろんHTML, LaTeX, reStructuredTextなどを入力としてもOKです。


MarkdownからHTMLに変換


手順


1. Mac, Linuxの方はターミナル(端末)を、Windowsの方はコマンドプロンプトを開きます


2. 公式サイトのREADME(Markdown形式)を適当な場所にダウンロードします

# Mac, Linuxの方はwgetやcurl -OでもOK

$ wget http://pandoc.org/demo/MANUAL.txt


3. READMEのある場所に移動(cd)し、READMEをinput.mdに名前変更します

# Mac, Linux 

$ cd ~/hoge
$ mv README input.md


4. 以下のコマンドを入力:

$ pandoc input.md -s -o output.html


  • input.md: 入力するMarkdown文書の名前

  • -o output.html : 出力するHTMLファイル名

  • -s: standalone(完結したフォーマットで出力)


    • HTML文書、LaTeX文書を出力する場合は、基本的に -s (standalone) オプションを付けましょう

    • .bashrc/.zshrc のaliasに指定しておいてもいいかも:


      • alias pandoc="pandoc -s"






そのままブラウザでプレビューするとき


Mac

$ pandoc input.md -s -o output.html && open output.html


Linux

$ pandoc input.md -s -o output.html && gnome-open output.html

$ pandoc input.md -s -o output.html && firefox output.html


  • Linux使いならニュアンスは分かると思うので、適当にいじってください


形式を明示的に指定することもできます

$ pandoc -f markdown -t html input.md -s -o output.html


  • -f 入力形式

  • -t 出力形式

形式の明示は、ファイルを指定せずにパイプで処理する際に必要です。


  • 出力ファイル(-o)を指定しない場合は、-tオプションで指定した形式で標準出力に出してくれます(一部形式を除く)


おすすめ使い方ベスト5

ここからは、おすすめの使い方を紹介します。


ベスト5まとめ


  1. MarkdownをEmacs Org-mode文書、reStructuredTextに変換する

  2. Markdownをdocx/odt文書に変換する

  3. MarkdownをLaTeX文書に変換する

  4. Markdownをプレゼン文書に変換する

  5. LaTeX文書をEPUBに変換する


1. MarkdownをEmacs Org-mode文書、reStructuredTextに変換する

出力ファイル(-o)の拡張子を変えるだけです。


Org-mode文書

pandoc input.md -o output.org


  • ファイル形式を指定する場合は -t org


reStructuredText

pandoc input.md -o output.rst


  • ファイル形式を指定する場合は -t rst

簡単ですね。


2. Markdownをdocx/odt文書に変換する


Word文書(docx)

pandoc input.md -o output.docx


  • ファイル形式を指定する場合は -t docx


LibreOffice Writer文書(odt)

pandoc input.md -o output.odt


  • ファイル形式を指定する場合は -t odt


3. MarkdownをLaTeX文書に変換する

pandoc input.md -s -o output.tex


注意

Macの場合、Emacsで開くと濁点が分離します。

(MacのUnicodeが、NFDという形式を標準としているためです。NFC形式に変換する必要があります。)


Emacs上で直す方法

こちらを参照して下さい:


端末上で直す

iconvコマンド(後述)を使うと、以下で直ります:

iconv -f UTF-8-MAC -t UTF-8 output.tex


  • 標準出力に出るので、パイプで適当に処理して下さい


4. Markdownをプレゼン文書に変換する


準備

公式サイトのSLIDESをダウンロードします。


  • SLIDES

  • または wget http://johnmacfarlane.net/pandoc/demo/SLIDES


LaTeX Beamer

pandoc -t beamer SLIDES -o output_beamer.pdf


HTMLスライド (Slidy)

pandoc -t slidy SLIDES -s -o output_slidy.html


  • -sオプションの付け忘れに注意!


5. LaTeX文書をEPUBに変換する

Pandocを使うと(少しの手間はありますが)LaTeX文書をいとも簡単にEPUB形式の電子書籍を作れます。


準備

公式サイトのexample4.texをダウンロード


  • example4.tex

  • または wget http://johnmacfarlane.net/pandoc/demo/example4.tex


コマンド

pandoc example4.tex -o output.epub


EPUBのプレビュー


Mac

Murasakiがおすすめです: Murasaki


Linux, Windows

Calibreが良いそうです: Calibre


注意



  • LaTeXで \input を使っている場合は、

    参照先ファイルをすべて元のTeXファイルに埋め込んでください。


    • Pandocが \input に対応していないためです。




  • 画像ファイルは全てpng形式にしてください。


    • EPS画像しか無い場合、ImageMagickのmogrifyコマンドで変換するのが一番楽ちんです。




日本語文書をPDFで出力する方法

Pandocには、LaTeXを使ってPDFを出力する機能があります。

これを使えると便利ですが、日本語文書(特にMacの場合)ちょっとややこしいです。

というのも、Pandoc標準の設定では、日本語の通らないpdfTeXを使用するためです。

そこで、日本語に対応し、PandocがサポートしているLuaLaTeXを使用します。


準備


LuaLaTeX

単体でインストールするのは難しいので、TeX Live 2012というパッケージをインストールします。

(これ以外のインストール方法は知らないです・・・。)

TeX環境が古くなっている方は、これを機にTeX環境を一新するとよいと思います。

(ただし、卒論や原稿提出前の方は、やめておいたほうがよいと思われます・・・(汗))


iconv (Mac)

Macの場合は、iconvという文字コードを変換するツールをインストールしておきます。

HomebrewかMacportsでインストールできると思います。


コマンド


Mac以外のOSの場合

pandoc input.md -o output.pdf -V documentclass=ltjarticle --latex-engine=lualatex


Macの場合

iconv -f UTF-8-MAC -t UTF-8 input.md | pandoc -f markdown -o output.pdf -V documentclass=ltjarticle --latex-engine=lualatex

長いので、よく使う場合はaliasかシェルスクリプトにしておくことをおすすめします


  • 以下を.bashrc/.zshrcに追加

alias pandocpdf="pandoc -V documentclass=ltjarticle --latex-engine=lualatex -t pdf"


その他のデモ

こちらにいっぱいあります:


まとめ

PandocはMarkdown, HTML, LaTeX, reStructuredTextなどを様々な形式に変換出来る強力なツールです。

パイプ処理などをうまく使ったりすると、さらに便利に使えるかもしれません。

また、開発も進んでいるため、今後新たな可能性が広がるかもしれません。

しかし、まだ日本であまり知られておらず、非常にもったいなく思います。

まずはPandocを試してみて下さい。

そして感銘を受けた方は、ぜひ友人にどんどん布教してください!