Pandocで参考文献リストを処理する扱う方法 (PandocとZoteroで参考文献:後編)
この記事は前編・後編で構成されています(注:余談編が追加されました)。
- 前編:Zoteroから参考文献リストを自動エクスポートする
- Zotero → BibTeX形式
- 後編:Pandocで参考文献リストを処理する扱う方法
- Pandoc's Markdown + BibTeX形式 → HTMLやLaTeXなど出力ファイル
- いまここ
- 余談編:Pandocで参考文献が辛い話
- 結論:既存のBibTeX用参考文献スタイル(bstファイル)を使いたいなら、Pandocの参考文献機能を諦めよう
(余談編にさらっと絶望的な結論が書いていますね……)
後編で説明するのは、Pandocで参考文献を処理する方法です。特に次の前提で説明します。
- BibTeX形式の参考文献リストを用いる(前編参照)
- Pandoc's Markdownで原稿を書き、文献を引用する
- 参考文献スタイルはCSLファイルを用いる
- Citation Style Languageの略で、参考文献スタイルを定義するために用いられるXMLファイルの一種
ただし「Pandocで簡単!」となる条件があります。それは「参考文献スタイルにあまりこだわりがない」ことです。
たとえば場合によっては次の要件もあります。
論文誌で参考文献スタイル(bstファイル)が指定されているので、これを絶対使いたい
この要件だとPandocを使う選択肢はだいぶ限られます。少なくとも「Pandoc側の参考文献機能(citeproc)を使う」という選択肢はなくなります(詳細は余談編にて)。
Pandocで参考文献リストを生成する流れ
Pandocで参考文献リストを生成するための大枠を説明します。
入力ファイルはPandoc's Markdown (-f markdown
/.md
ファイル)とします。
- 次のファイルを用意する
- 参考文献ファイル:BibTeX形式 (.bib)
- 今回はZoteroからエクスポートする(前編)
- 参考文献リスト用のスタイルファイル:CSLファイル (.csl)
- 参考文献ファイル:BibTeX形式 (.bib)
- Pandoc's Markdown上で文献を引用する
- PandocでPandoc's Markdownを変換する
- 末尾に参考文献リストが生成される
必要なファイルの用意
まず、次のファイルを用意します。
- 参考文献ファイル:BibTeX形式 (.bib)
- 今回はZoteroからエクスポートする(前編)
- 参考文献リスト用のスタイルファイル:CSLファイル (.csl)
参考文献ファイル:BibTeX形式 (.bib)
BibTeX形式のファイルを用意します(book.bib
とします)。これを適当なフォルダ(以下、プロジェクトフォルダ)に入れておきます。
@misc{shirasaki2020,
title = {{電子書籍(EPUB)作成ツール、個人的にTypora+Pandocが最適解の予感|白崎矢宵(やよい)|note}},
author = {白崎, 矢宵},
url = {https://note.com/yayoi_shirasaki/n/n1b742449599f},
urldate = {2020-11-26},
journal = {note(ノート)},
language = {ja}
}
参考文献リスト用のスタイルファイル:CSLファイル (.csl)
次にCSLファイルも調達してきます。次のサイトで検索ができます。
- Zotero Style Repository
-
citation-style-language/styles
-
t
キーを打つとファイル名を検索できる
-
欧文における有名な参考文献スタイル(シカゴスタイル、APAなど)はだいたい揃っていると思います。しかし和文向けのスタイルの数は少ないです[1]。
和文(横書き)で無難に使える参考文献スタイルとして、個人的にはSIST02をお勧めします。SIST02は科学技術情報流通技術基準(SIST)の成果物で、次のような目的・内容を持っています。
技術論文の末尾に参照文献を記述する際に,記述する個々の文献について,書誌的情報として,何を選定すべきか,選定したものの表記法,記載順序,句読点使用法等についての原則と指針を示したもの(電子文献を含む)。
SIST02には、sist02.csl
というCSLファイルがあります[2]。これをそのままダウンロードして、プロジェクトフォルダに入れておけばOKです。
- CSLファイルのダウンロード: Zotero Style Repository
- 詳細: Style Info
Pandoc's Markdown上で文献を引用する
いよいよPandoc's Markdownの原稿を書いていきます。
- あらかじめZotero側で文献に引用キー(citation key)を設定しておく
- 前編を参照
- たとえば
foo
という引用キーを設定したとします
- Pandoc's Markdownで文献を引用する
- たとえば
[@foo]
と書けば、出力ファイルでは(1)
のように番号が自動的に振られます
- たとえば
2に関しては、前編でQuickCopyの設定をしていれば、Zoteroで文献を選択してCommand-C / Ctrl-Cで [@foo]
の形式をコピーできます。
さらに必要なら、入力ファイルの最後[3]に # 参考文献
のように、参考文献リスト用の見出しを書いておきます。
... (何かしらの文章の終わり)
# 参考文献
末尾に参考文献リストが生成されてほしくない場合もあります。任意の場所で次のように書けば、書いた場所に参考文献リストが生成されます。
::: {#refs}
:::
例として、Pandoc's Markdownで書かれた次の入力ファイルをinput.md
とします。
---
title: サンプル
---
> 「このツールを知るだけで世界が変わる人がいるはず」
この言葉は、Pandocで電子書籍を制作された白崎矢宵さんによるものです[@shirasaki2020]。
PandocでPandoc's Markdownを変換する
最後に、Pandocで各ファイルを読み込み、文献リストを生成します。
注意:参考文献処理エンジンの変更 [Pandoc 2.11+]
Pandoc 2.11以前で参考文献リストを生成するには、Pandoc本体に加えてpandoc-citeproc
というバイナリが必要でした。オプションとしては --filter pandoc-citeproc
を渡していました。
しかしPandoc 2.11以降から、Pandoc内部で参考文献の処理を行うように変更されました[4]。コマンドラインオプションとしては --citeproc
(-C
) を渡します。
整理すると次のとおりです。
- Pandoc 2.11以降の場合
- コマンドラインオプション:
--citeproc
(-C
) - フィルタ
pandoc-citeproc
は不要
- コマンドラインオプション:
- Pandoc 2.11以前の場合
- コマンドラインオプション:
-F pandoc-citeproc
(フィルタを指定する) - フィルタ
pandoc-citeproc
のインストールが必要- 公式のGitHub Releasesにあるインストーラやzipを使えば、Pandoc本体と同時に
pandoc-citeproc
も同時にインストールできます - Homebrewなどのパッケージマネージャを使っている場合は、
pandoc-citeproc
を別途インストールします
- 公式のGitHub Releasesにあるインストーラやzipを使えば、Pandoc本体と同時に
- コマンドラインオプション:
コマンド例
順に「HTML」「LaTeXソース」「LuaLaTeXで生成したPDF」を出力するPandocコマンドを挙げます。
# Pandoc 2.11以降
pandoc input.md -s -o output.html --citeproc --bibliography=book.bib --csl=sist02
pandoc input.md -s -o output.tex --citeproc --bibliography=book.bib --csl=sist02
pandoc input.md -o output.pdf --citeproc --bibliography=book.bib --csl=sist02 --pdf-engine=lualatex -V documentclass=ltjsarticle
# Pandoc 2.11以前(要・pandoc-citeproc)
pandoc input.md -s -o output.html --filter=pandoc-citeproc --bibliography=book.bib --csl=sist02
pandoc input.md -s -o output.tex --filter=pandoc-citeproc --bibliography=book.bib --csl=sist02
pandoc input.md -o output.pdf --filter=pandoc-citeproc --bibliography=book.bib --csl=sist02 --pdf-engine=lualatex -V documentclass=ltjsarticle
なお、このコマンド例でPDF出力するにはTeX Liveが必要です(この記事では割愛します)。
--pdf-engine=lualatex
や-V documentclass=ltjsarticle
については下記を参照してください。
サンプルファイルはGitHubの sky-y/pandoc-advent-2020-zotero に上げています。
(図:HTML出力の例)
]
(例:LuaLaTeXで生成したPDF出力の例)
おわりに
前編・後編にわたって、Pandocで参考文献リストをつくる方法について説明しました。軽くおさらいしましょう。
- 前編:Zoteroから参考文献リストを自動エクスポートする
- Zotero → BibTeX形式
- 後編:Pandocで参考文献リストを処理する扱う方法
- Pandoc's Markdown + BibTeX形式 → HTMLやLaTeXなど出力ファイル
ところで記事の最初には
- 余談編:Pandocで参考文献が辛い話
- 結論:既存のBibTeX用参考文献スタイル(bstファイル)を使いたいなら、Pandocの参考文献機能を諦めよう
という項目がありました。これを次回にまわします。
-
Zotero Style Repositoryで「japan」と検索した結果は16件でした。 ↩︎
-
sist02.csl
のライセンスはCreative Commons Attribution-ShareAlike 3.0 (CC-BY-SA 3.0)です。このファイルを編集・改変する際はこのライセンスを継承してください。CSLの編集については余談編で軽く触れます。 ↩︎ -
入力ファイルが複数ある場合は、最後のファイルの末尾に参考文献リスト用の見出しを書きます。 ↩︎
-
citeproc
というHaskellライブラリ(パッケージ)が、Pandoc本体の内部で用いられます。 ↩︎
Discussion
こんにちは。大変貴重な情報と思って拝読しております。質問させてください。
--pdf-engine=lualatex -V documentclass=ltjsarticle
を指定するとこんな感じのエラーが出てきて困っています。本文中に [@hoge] があるときにだけこのエラーが出ます。無いときには正常に日本語のPDFが出力されます。逆に、
--pdf-engine=lualatex -V documentclass=ltjsarticle
を指定せず、日本語を使わない場合は、正常に参考文献が生成されます。なにか思い当たる修正点はございますでしょうか?公式のDockerfileを使ったらエラーメッセージがでなくなりました。