ドキュメント変換ツールPandoc:ユーザーズガイドを熟読して分かったマニアックな使い方

  • 110
    いいね
  • 1
    コメント

この度、Pandoc ユーザーズガイド 日本語版を全訳致しました。その宣伝を兼ねて、Pandocのマニアックな機能を紹介していきます。

翻訳という作業には、必然的に翻訳元文書を読み込むという作業が入ってきます。Pandocユーザーズガイドの翻訳でもそれは当てはまり、色々と勉強になりました。

今回は、それらの中から、マニアックながら面白そうな機能を紹介していきます。

その前に

Pandocって何?っていう感じの初心者の方は以下を先にご覧ください。

OPMLの入力

いきなり玄人向けですが、PandocはOPMLの入力に対応しています。
OPMLはOutline Processor Markup Languageの略で、XMLの一種です。アウトラインプロセッサ向けのマークアップ言語らしいです。

OPMLの便利なところは、OmniOutlinerなどのアウトラインプロセッサからエクスポートできる点です。よって、例えば最初にこのようなソフトである程度構造を作って、その後でMarkdownに変換して本格的に文書を執筆する、といった使い方ができます。

入力にURLを直接指定

ユーザーズガイドにも書いてありますが、Pandocでは入力ファイルの代わりにURLを指定することもできます。 この場合、PandocはHTTPを用いてコンテンツを取得します。

pandoc -f html -t markdown http://www.fsf.org

タイポグラフィ的に正しい表示

-Sまたは--smartオプションを指定すると、タイポグラフィ的に正しく出力します。 具体的には、直線状の'引用符'を曲がった‘引用符’に、---をemダッシュ「—」に、--をenダッシュ「–」に、 ...を3点リーダー「…」に変換します。また、“Mr.”のようなある種の略記・略称に対しては、自動的な改行のないスペース(non-breaking space)がその後に挿入されます。

フィルタ

Pandocの入力処理と出力処理の間に挟んで変換処理を行うフィルタというものがあります。
https://github.com/jgm/pandocfilters/tree/master/examples にいくつか例がありますが、例えば英字を全て大文字にするcaps.pyというフィルタなどがあります。これを使う場合、

pandoc --filter ./caps.py -t latex

は以下と等価です:

pandoc -t json | ./caps.py latex | pandoc -f json -t latex

詳細はユーザーズガイドに譲ります。
色々できそうで想像がつきませんが、高い可能性を秘めていそうです。

ODT/docxの参照用スタイルファイル

これはLibreOffice ODTやWord docx形式を扱う際には重要かもしれません。
標準のスタイルではなく自分でスタイルをカスタマイズするには、次の手順を行います。
(以下、docxの手順を説明しますが、ODTの場合も似ています。)

1. 以下を実行し、スタイル参照用ファイルを手に入れる。

pandoc --print-default-data-file reference.docx > reference.docx

2. Wordでreference.docxを開き、スタイルをいじる。

使用できるスタイルは以下の通り:【段落】 標準(Normal), Compact, 表題(Title), Authors, 日付(Date), Heading 1, Heading 2, Heading 3, Heading 4, Heading 5, Block Quote, Definition Term, Definition, 本文(Body Text), Table Caption, Image Caption; 【文字】 Default Paragraph Font, Body Text Char, Verbatim Char, Footnote Ref, Link.

3. reference.docxをユーザデータディレクトリに入れる。

ユーザデータディレクトリは標準で$HOME/.pandoc(Mac), C:\Users\USERNAME\AppData\Roaming\pandoc(Windows)です。なければディレクトリを作ってください。

(2017-05-03 加筆)

または、コマンド引数で直接指定できます。

注意:従来のバージョンでは --reference-docx (docx) / --reference-odt (odt)でしたが、最近のバージョン(現時点で2.0)では --reference-doc に統一されたようです。

$ pandoc -s input.md -o output.docx --reference-doc reference.docx (新しいバージョン)
$ pandoc -s input.md -o output.docx --reference-docx reference.docx (古いバージョン)

以上の手順で、docxやODTのスタイルをカスタマイズした状態で出力できます。

テンプレート

-s/--standaloneオプションを指定すると、スタンドアローンモードになります。このときPandocは完全で独立した文書を生成するために、ヘッダとフッタをつけ加えるためのテンプレートを使用します。

テンプレートには、各種変数が使えます。
例えば、以下のような$title$

<title>$title$</title>

その文書のタイトルに置き換えられます。

詳細はやはりユーザーズガイドをご覧ください。
未だに把握できないほど、細かいカスタマイズが可能です。

Pandoc拡張Markdown

Pandocで標準で用いられるMarkdownは、他のMarkdown文法を参考に作られたPandoc独自の文法です。
知っておくと便利な文法もあるので、いくつか紹介します。

囲まれた(fenced)コードブロック

3つ以上のチルダ(~)またはバックスラッシュ(`)の行で囲まれた部分はコードブロックになります。

~~~~~~~
if (a > 3) {
  moveShip(5 * gravity, DOWN);
}
~~~~~~~

オプションとして、各種属性(クラス、ID)を付けることができます。

~~~~ {#mycode .haskell .numberLines startFrom="100"}
qsort []     = []
qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
               qsort (filter (>= x) xs)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

特にシンタックスハイライト用クラスは重要で、haskellなど多種多様な言語に対してシンタックスハイライトが使用できます。一覧を示します。

actionscript, ada, apache, asn1, asp, awk, bash, bibtex, boo, c, changelog,
clojure, cmake, coffee, coldfusion, commonlisp, cpp, cs, css, curry, d,
diff, djangotemplate, doxygen, doxygenlua, dtd, eiffel, email, erlang,
fortran, fsharp, gnuassembler, go, haskell, haxe, html, ini, java, javadoc,
javascript, json, jsp, julia, latex, lex, literatecurry, literatehaskell,
lua, makefile, mandoc, markdown, matlab, maxima, metafont, mips, modelines,
modula2, modula3, monobasic, nasm, noweb, objectivec, objectivecpp, ocaml,
octave, pascal, perl, php, pike, postscript, prolog, python, r,
relaxngcompact, rhtml, roff, ruby, rust, scala, scheme, sci, sed, sgml, sql,
sqlmysql, sqlpostgresql, tcl, texinfo, verilog, vhdl, xml, xorg, xslt, xul,
yacc, yaml

コンパクトなリストとルーズなリスト

コンパクトなリストはまとめて1つの段落となります:

* ひとつめ
* ふたつめ
* みっつめ

ルーズなリストは各項目がそれぞれ1つの段落です:

* ひとつめ

* ふたつめ

* みっつめ

定義リスト

PandocのMarkdownではPHP Markdown Extraと同様の定義リストが使用できます。

用語1

:   定義1

PandocのMarkdownでは4種類の表(テーブル)が使用できますが、日本語でも使いやすいのはグリッドテーブルとパイプテーブルでしょう。

グリッドテーブル

: グリッドテーブルのサンプル。

+---------------+---------------+--------------------+
| 果物           | 値段          | 利点                |
+===============+===============+====================+
| バナナ         | $1.34         | - むきやすい        |
|               |               | - 明るい色          |
+---------------+---------------+--------------------+
| オレンジ       | $2.10         | - ビタミンCが豊富    |
|               |               | - おいしい          |
+---------------+---------------+--------------------+

パイプテーブル

|右寄せ | 左寄せ|デフォルト|中央寄せ|
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

  : パイプテーブルのデモ

終わりに

以上でマニアックな機能の紹介を終わりますが、Pandocはまだまだ機能が隠れています。繰り返しになりますが、興味を持った方はぜひユーザーズガイドを一読してみてください!