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

追記（2020.4.19）
--------------

[Pandoc User’s Guide](http://johnmacfarlane.net/pandoc/README.html)を日本語に全訳しました。
よろしければご参照ください。

* **新しい翻訳をプレリリースしました！**（翻訳途中の部分もあります）
    * [Pandocユーザーズガイド 日本語版 \[2\.7\.2\] — 日本Pandocユーザ会 2019\.02\.21 ドキュメント](https://pandoc-doc-ja.readthedocs.io/ja/latest/users-guide.html)
* 旧日本語版：~~[Pandoc ユーザーズガイド 日本語版](http://sky-y.github.io/site-pandoc-jp/users-guide/)~~ 


はじめに
--------

今回は、ドキュメント作成Tips Advent Calendar 2012の1日目
（[マインドマップから全てを紡ぎ出す - XMind+Pandocのドキュメント作成術 -](http://qiita.com/items/b92e9ce4b941545c8af5)）
で少し紹介した**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](http://sphinx-users.jp/)が有名で、
他にも特定のマークアップ言語用のツールが多数存在します。

しかしながら、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 User's Guide](http://johnmacfarlane.net/pandoc/README.html)


#### 開発が活発

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

その証拠に、Pandocの開発用グループである [pandoc-discuss - Google グループ](https://groups.google.com/forum/?fromgroups#!forum/pandoc-discuss) で、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)の開発が始まっているそうです。~~

* [Org-Mode Reader · Issue \#476 · jgm/pandoc](https://github.com/jgm/pandoc/issues/476)

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

Emacs Org-modeの読み込みモジュールが完成しました！（14.05.09現在）

### 短所

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

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

Pandocは独自の読み込み・書き込みエンジンにより処理を行っています。
そのため、文書の仕様に沿っていない部分もあります。

また、内部的にはHTMLで表現できる形式で処理されているため、その表現能力を超えるようなことはできません。
この欠点は、特にLaTeX（使った事無いですが、おそらくreSTも）に影響します。



Pandocのインストール
--------------------

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

[Pandocの比較的簡単なインストール方法 - Qiita](https://qiita.com/sky_y/items/3c5c46ebd319490907e8)

基本的な使い方
--------------

ここでは例としてMarkdownを入力形式とし、HTMLを出力してみます。
もちろんHTML, LaTeX, reStructuredTextなどを入力としてもOKです。

### MarkdownからHTMLに変換

#### 手順

##### 1. Mac, Linuxの方はターミナル（端末）を、Windowsの方はコマンドプロンプトを開きます
##### 2. 公式サイトの[README](http://johnmacfarlane.net/pandoc/demo/README)(Markdown形式)を適当な場所にダウンロードします

```bash
# Mac, Linuxの方はwgetやcurl -OでもOK
$ wget http://pandoc.org/demo/MANUAL.txt
```	

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

```bash
# Mac, Linux 
$ cd ~/hoge
$ mv README input.md
```

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

```bash
$ 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
```bash
$ pandoc input.md -s -o output.html && open output.html
```

##### Linux
```bash
$ pandoc input.md -s -o output.html && gnome-open output.html
$ pandoc input.md -s -o output.html && firefox output.html
```

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

#### 形式を明示的に指定することもできます
```bash
$ 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文書
```bash
pandoc input.md -o output.org
```

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

#### reStructuredText
```bash
pandoc input.md -o output.rst
```

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

簡単ですね。

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

#### Word文書(docx)
```bash
pandoc input.md -o output.docx
```

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

#### LibreOffice Writer文書(odt)
```bash
pandoc input.md -o output.odt
```

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

### 3. MarkdownをLaTeX文書に変換する
```bash
pandoc input.md -s -o output.tex
```

#### 注意

Macの場合、Emacsで開くと濁点が分離します。
(MacのUnicodeが、NFDという形式を標準としているためです。NFC形式に変換する必要があります。)

##### Emacs上で直す方法
こちらを参照して下さい：

-   [Emacs小ネタ:MacでPDFからコピーすると濁点が分離する問題を直す](http://d.hatena.ne.jp/sky-y/20120805/1344169124)

##### 端末上で直す
iconvコマンド（後述）を使うと、以下で直ります：

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

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


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

#### 準備

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

* [SLIDES](http://johnmacfarlane.net/pandoc/demo/SLIDES)
* または `wget http://johnmacfarlane.net/pandoc/demo/SLIDES`

#### LaTeX Beamer
```bash
pandoc -t beamer SLIDES -o output_beamer.pdf
```

#### HTMLスライド (Slidy)
```bash
pandoc -t slidy SLIDES -s -o output_slidy.html
```

* -sオプションの付け忘れに注意！


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

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

#### 準備

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

* [example4.tex](http://johnmacfarlane.net/pandoc/demo/example4.tex)
* または `wget http://johnmacfarlane.net/pandoc/demo/example4.tex`

#### コマンド
```bash
pandoc example4.tex -o output.epub
```

#### EPUBのプレビュー

##### Mac
Murasakiがおすすめです： [Murasaki](http://genjiapp.com/mac/murasaki/index.html)

##### Linux, Windows
Calibreが良いそうです： [Calibre](http://calibre-ebook.com/)

#### 注意
* LaTeXで `\input` を使っている場合は、
参照先ファイルをすべて元のTeXファイルに埋め込んでください。
  * Pandocが `\input` に対応していないためです。

* 画像ファイルは全てpng形式にしてください。
  * EPS画像しか無い場合、ImageMagickのmogrifyコマンドで変換するのが一番楽ちんです。


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

Pandocには、LaTeXを使ってPDFを出力する機能があります。
これを使えると便利ですが、日本語文書（特にMacの場合）ちょっとややこしいです。
というのも、Pandoc標準の設定では、日本語の通らないpdfTeXを使用するためです。

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

### 準備

#### LuaLaTeX

単体でインストールするのは難しいので、TeX Live 2012というパッケージをインストールします。
（これ以外のインストール方法は知らないです・・・。）

* [TeX Live - TeX Wiki](http://oku.edu.mie-u.ac.jp/~okumura/texwiki/?TeX%20Live)

TeX環境が古くなっている方は、これを機にTeX環境を一新するとよいと思います。
（ただし、卒論や原稿提出前の方は、やめておいたほうがよいと思われます・・・（汗））

#### iconv (Mac)

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

### コマンド

#### Mac以外のOSの場合
```bash
pandoc input.md -o output.pdf -V documentclass=ltjarticle --latex-engine=lualatex
```

#### Macの場合
```bash
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に追加

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

その他のデモ
------------

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

* [Pandoc - Demos](http://johnmacfarlane.net/pandoc/demos.html)

まとめ
------

PandocはMarkdown, HTML, LaTeX, reStructuredTextなどを様々な形式に変換出来る強力なツールです。
パイプ処理などをうまく使ったりすると、さらに便利に使えるかもしれません。
また、開発も進んでいるため、今後新たな可能性が広がるかもしれません。

しかし、まだ日本であまり知られておらず、非常にもったいなく思います。
まずはPandocを試してみて下さい。
そして感銘を受けた方は、ぜひ友人にどんどん布教してください！