「オープンソース」を使ってみよう
（第47回 Pandoc）

07/05

OSPN Press編集部Use it ! OSS No Comments
このエントリーをはてなブックマークに追加

目次

はじめに

日本Pandocユーザ会の藤原(@sky_y)と申します。

この記事では、ドキュメント変換ツールPandocについて紹介します。

Pandocを使うことで、様々なマークアップ言語で書かれたドキュメント（Markdown, reST, LaTeX, HTMLなど）を、
別のマークアップ言語やPDF/LibreOffice Writer/Word形式を含む多くのドキュメントに変換できます。

また、PandocはHaskell製のOSSです（GitHub: jgm/pandoc）。他の言語では複雑になりがちな構文解析などがシンプルに設計・実装されており、Haskellコードリーディングの題材としても最適です。

Pandocとは

Pandocは、あるフォーマットで書かれた文書（ドキュメント）を、別のフォーマットに変換するツールです。（図1）


図1：Pandocの基本的な処理フロー

Pandocの最大の特徴は、対応書式（フォーマット）が非常に多いことです。例を挙げてみましょう。

  • 入力
    • Markdown (Pandoc, CommonMark, PHP Markdown Extra, GitHub-Flavored Markdown, MultiMarkdown)
    • Textile, reStructuredText, HTML, LaTeX, MediaWiki markup, Emacs Org mode
    • OPML, DocBook, EPUB, ODT(LibreOffice Writer), Word docx
  • 出力
    • 入力フォーマットのほとんど（ODT/Word含む）
    • Markdown
    • man page, AsciiDoc, InDesign ICML
    • プレゼンテーション： LaTeX Beamer, HTML5(reveal.jsなど）
    • PDF (wkhtmltopdfまたはLaTeXエンジンが必要）

例えば、下記の図2はPandoc公式サイトのトップに掲載されているもので、左側の丸が入力書式を、右側の丸が出力書式を表します。
このように、あらゆる書式から別の書式への文書変換を、Pandocは実現してくれます。


図2：Pandoc公式サイト・トップの図

Pandocが役に立つ場面

Pandocは多機能ながら、そのインタフェースはシンプルに設計されています。それゆえ、多様な使い方ができるツールです。

その1：
1つのドキュメント（HTMLページに相当するもの）を変換する

例えば、下記のような場面ではPandocが役に立つでしょう。

  • 大量にあるMarkdown文書を別の書式に一括変換したい
  • 大量にあるHTMLが編集しづらいので、Markdownなどに変換してコンパクトにしたい
  • Emacs org-mode、reST、LaTeXなどで書き溜めたテキストをMarkdownに一括変換したい
  • Wikipediaに加筆したいけど、記法を忘れるのでMarkdownで書きたい
  • Markdownなどでスライドショーを作りたい
  • Writer/Wordが重く、diffやGitHub管理が面倒なのでテキストファイルで下書きしたい
  • Writer/Word文書をHTMLやMarkdownに変換したい

ただし、Pandocは原則として単一ドキュメント（1ファイルのHTMLに相当）しか処理できません。例えば複数ページからなるWebサイト一式をPandoc単体で生成することはできません。そのような用途のために、次の方法が用いられます。

その2：
スクリプトやソフトウェアに組み込んだり、
外部プログラムによるフィルタを中間処理に入れる

Pandocそのものはコマンドラインツールです。つまり、シェルスクリプトの中に組み込むことができます。

また、Pandocはシェルの標準入力と標準出力に対応しています。入力または出力ファイル名を省略すると、Pandocは暗黙に標準入力・出力を使用します。これを利用し、シェル上で他のプログラムからデータをパイプで受けたり、逆にPandocから他のプログラムにデータを引き渡すことも可能です（図3）。


図3

この性質を利用したのがPandocのフィルタ(filter)という機能です。パイプによるデータ引き渡しの際は、多くのプログラミング言語で利用しやすいJSON形式を指定することができます。このJSONファイルをPythonやJavaScriptなどのスクリプト言語（バイナリでも可）に引き渡すことで、文書変換処理を比較的簡単に拡張することができます（図4）。

具体的には「外部ファイルをインポートする」フィルタなどが実現できます（参考：pandocでMarkdownを拡張しコードをインポート出来るfilterを書く | Web Scratch）。


図4

一方、Pandocを主要プログラミング言語にてライブラリとして呼ぶことも可能です。
これにより、Sphinxなどの他のサイトジェネレータやCMS、AtomやVimなどのエディタ・外部ツールなどからPandocを呼ぶことができ、高度なドキュメント生成・変換が可能になります。

例：SphinxでPandoc's Markdown（後述）を使える拡張 pashango2/sphinxcontrib-pandoc-markdown

以上のように、Pandocはドキュメントに関するあらゆる場面において、強力な「アーミーナイフ」として使用できるでしょう。

インストール：Pandoc本体

以下、ターミナル（またはコマンドプロンプト）が使えることを前提とします。

Windows, macOSであれば、インストーラによりダウンロード・インストールできます。

ダウンロードページの

  • pandoc-1.19.2.1-windows.msi (Windows)
  • pandoc-1.19.2.1-osx.pkg (macOS)

を使用してください（ファイル名中の番号が異なる場合があります）。

一方、パッケージマネージャを利用したインストールも可能です：

  • Windows(Chocolatey): cinst -y pandoc
  • macOS(Homebrew): brew install pandoc
  • Debian/Ubuntu(apt): sudo apt-get install pandoc

ただしLinuxのパッケージマネージャでインストールすると、バージョンが古い場合があります。新しいバージョンが必要な場合は、リポジトリを別の場所に指定するか、Stack（Haskellのビルドツール）などを用いてソースコードからビルドする必要があります。その場合は、Pandoc – Installing pandocの「Quick stack method」を参考にするとよいでしょう。

インストール：PDF出力のためのパッケージ

Pandoc単体はPDFを出力できません。「wkhtmltopdf」または「LaTeX」に頼る必要があります。今回は使用が簡単なwkhtmltopdfをインストールしましょう。

wkhtmltopdfのインストールも、下記の通りにインストールできます：

  • インストーラ： ダウンロードページからダウンロード・インストール
  • Windows (Chocolatey): cinst -y wkhtmltopdf
  • macOS (Homebrew): brew install wkhtmltopdf
  • Debian/Ubuntu(apt): sudo apt-get install wkhtmltopdf

LaTeXを用いる場合は、今回は割愛します。

  • 注意1：pLaTeXは直接Pandocから使用できないので、少し工夫が必要です。
  • 注意2：Pandoc標準のLaTeX処理系はpdfLaTeXですが、これは日本語文書の処理に適さないので、同じくPandocが対応するXeLaTeXやLuaLaTeXをインストールし利用する（–latex-engineとして指定する）ことをおすすめします。

チュートリアル1：標準入力・出力で遊ぼう

まず先に、以上のインストールが完了したことを確認しましょう。

$ pandoc --version
$ wkhtmltopdf --version

バージョン番号が確認できればOKです。

次に、標準入力からパイプでPandocに繋いでみましょう。Markdown記法の見出し（「#」がh1に相当）をHTML5形式として出力してみます。入力書式は「-f」オプションで、出力書式は「-t」オプションで指定します。

$ echo "# Hello"
# Hello
$ echo "# Hello" | pandoc -f markdown -t html5
<h1 id="hello">Hello</h1>

標準入力のMarkdownが、HTMLのh1タグとして標準出力に出力されました。

この出力は標準出力なので、そのままリダイレクトによってファイルに保存できます。

$ echo "# Hello" | pandoc -f markdown -t html5 > hello.html
$ cat hello.html
<h1 id="hello">Hello</h1>

同様に、「-o」オプションでファイルに保存することができます。

$ echo "# Hello" | pandoc -f markdown -t html5 -o hello2.html
$ cat hello2.html
<h1 id="hello">Hello</h1>

「-f」「-t」に指定できる書式の名前は Pandoc – Pandoc User’s Guideの「General Options」を参照してください。

チュートリアル2：まとまったMarkdown文書をあらゆる形式に変換しよう

ここではサンプルとして、青空文庫にある『あたらしい憲法のはなし』のMarkdown版（nogajunさん編）を利用しましょう。（パブリックドメインなので安心して利用してください）

Git(SourceTreeなどでも可)をインストールしている人は、下記のようにcloneしましょう。

$ git clone https://github.com/nogajun/story_of_the_new_constitution.git

その中の「atarashii_kenpo.md」が、今回使うMarkdownファイルです。

または、Markdownソースを直接ダウンロードしてもかまいません： atarashii_kenpo.md

（ただしソースのみだと画像が表示されないので、git cloneをおすすめします）

まずは、このMarkdownファイルをHTMLに変換してみます：

$ pandoc atarashii_kenpo.md -t html5 -o output.html
$ less output.html

一応HTMLらしきものが出力されているはずです。しかし、ヘッダがありません！

Pandocのデフォルトでは、HTMLのタグ内部に相当するものしか出力してくれないので、注意が必要です。完全な文書（ヘッダ・フッタ付きの文書）を出力するには、「-s」を付ける必要があります。

$ pandoc -s atarashii_kenpo.md -t html5 -o output2.html
$ less output2.html

これで完全なHTMLが得られました。

同様に、Markdownを色々な書式に変換してみましょう。（「-t」オプションを省略すると、「-o」オプションの拡張子から自動的に推測してくれます）

# LaTeX
# 注意: -s を付けるとpdfLaTeX前提のヘッダとなるため、あえて省略しています
$ pandoc atarashii_kenpo.md -o output.tex

# EPUB（EPUB3を推奨。WindowsのEdgeだと綺麗に読めます）
$ pandoc atarashii_kenpo.md -t epub3 -o output.epub

# PDF（wkhtmltopdfを利用する場合：オプションに注意）
$ pandoc atarashii_kenpo.md -t html5 -o output.pdf

# LibreOffice Writer / MS Word
$ pandoc atarashii_kenpo.md -o output.odt
$ pandoc atarashii_kenpo.md -o output.docx

チュートリアル3：Markdown以外の文書からMarkdownに変換しよう

最後に、逆方向の変換を試して終わりましょう。ここではHTMLからMarkdownに変換します。

Pandocでは、入力ファイルの代わりにURLを指定すると、それを自動的にダウンロードして入力文書として解釈します。その機能を利用して、Pandoc公式サイトのPandoc User's GuideをMarkdownに変換してみましょう。

$ pandoc https://pandoc.org/MANUAL.html -t markdown -o manual.md
$ less manual.md

紹介が遅れましたが、Pandocがデフォルトで使っているMarkdownは、Pandoc独自で定められた文法（Pandoc's Markdown）です。その詳細は同じくUser's Guideの「Pandoc's Markdown」セクションで説明されています。

他のMarkdown方言として、

  • GitHub Flavored Markdown (-t markdown_github)
  • PHP Markdown Extra (-t markdown_phpextra)
  • MultiMarkdown (-t markdown_mmd)
  • CommonMark (-t commonmark)

も利用できます。（もちろん、各方言で相互変換も可能です）

チュートリアルは以上です。

最後に

これまで紹介した機能はほんの一部です。Pandocの大きな可能性を感じていただければ幸いです。

もしPandocそのものや活用方法、あるいはドキュメンテーションという分野に興味のある方は、ぜひ日本Pandocユーザ会のSlackにご参加ください。あらゆるジャンルで活躍されている方が、Pandocという枠を越えてドキュメンテーション全体についてゆるくディスカッションをしています。

登録は Slack登録フォーム から可能です。初心者でもお気軽にご参加ください。よろしくお願いいたします。

参考リンク

Comments are closed.