PandocとMarkdownによるアカデミックライティング

この記事は，[Pandoc Advent Calendar 2019](https://adventar.org/calendars/4338) の18日目の穴埋め記事です．

17日目の記事は，[mitixx](https://qiita.com/mitixx)さんによる[markdownで技術書を書いてpandocでpdfやicml(indesign)に変換する](https://qiita.com/mitixx/items/715fccf57a3527102532)でした．
19日目の記事は，[sky_y](https://qiita.com/sky_y)さんによる[Pandocの比較的簡単なインストール方法](https://qiita.com/sky_y/items/3c5c46ebd319490907e8)の大幅改訂版です．

**本記事では，Pandocユーザーを増やすことを目的に，MarkdownやPandocなどに親しみのない研究者層に対して，MarkdownとPandocで論文を執筆する利点について紹介します．
また，[論文でよく使う書式やフォーマットに関して，具体例を紹介](https://qiita.com/TomosurebaOrange/items/1ee83f56cd853a9ba5cd#%E8%A8%98%E6%B3%95%E4%BE%8B%E3%81%A8pandoc%E3%81%AB%E3%82%88%E3%82%8B%E8%AB%96%E6%96%87%E3%83%86%E3%83%B3%E3%83%97%E3%83%AC%E3%83%BC%E3%83%88)します．**
本記事を読むことで，PandocとMarkdownで論文を書こうかな，と思ってくれる研究者が周りに増えれば嬉しいです．

# 研究者にとってアカデミックライティングは必須の仕事である
<!-- {{{ -->

職業研究者として生きていく上で，論文執筆は不可欠の仕事である．
ただ研究をして結果を蓄積するだけでは，真の意味での"研究活動"とはいえない．
その研究結果を適切なロジックで整理し，そこから新しい価値を議論すること，そしてそれを論文として世界に発表することまでが"研究活動"である．
また，ただ発表するだけならば，個人ブログなどで文章を公表するだけでもよいが，それでは"研究活動"とは認められない．
一般に"ちゃんとした"研究論文とは，国際的な標準言語である英語で記載され，査読(同分野の研究者による論文内容の評価)を通った論文である必要がある．
これらの論文は，投稿する学術誌が規定するフォーマットや，研究分野の慣例に従った書式で執筆されなければいけない．

<!-- }}} -->

# MS Wordによる論文執筆の不便性
<!-- {{{ -->

これらの書式に従って論文を執筆するため，ほとんどの場合，(筆者の所属するような生物系領域では)MS wordによって論文が執筆されている[^1]．
しかし，読者の多くがご存知のように，MS wordは，非常に高額であり，またその起動速度の遅さやWindows OS以外との相性の悪さなど，コストのかかるワードプロセッサソフトである．
また，[kaityo256](https://qiita.com/kaityo256)さんの[投稿](https://qiita.com/kaityo256/items/c15889dbb7acb2632c6e)のように，代々継承されたWordファイルは断片化が進み，保存すら時間がかかるようになり，フラストレーションが溜まる．
その一方で，画面上に見たままのフォーマットで執筆できる(WYSIWYG)ため，学習コストは低い(と言われがちだが，実際の検証はあるのか?)．
また，論文を最後にチェックするラボヘッドは，ほぼ必ずと言っていいほどMS Wordしか使えない．
MS Wordは論文執筆にはイマイチ使いにくいにもかかわらず，上述した条件が，MS Wordから論文執筆を切り離せない原因となっている．

<!-- }}} -->

# 論文執筆に必要十分な機能
<!-- {{{ -->

一旦，MS Wordにまつわる問題を離れ，どのような書式があれば論文執筆が可能になるか考えてみる．
(生物系の)英語論文を執筆する上で，必要不可欠な書式は案外少ない;

- 図表の挿入
- 斜体 (遺伝子名や種名の記載)
- 数式 (定量化手法や数理モデルの記載)
- 上付き文字 (対立遺伝子名や同位体の記載)
- 下付き文字 (分子式の記載)

また，次の機能も，ほとんど必須に近いほど重要である;

- 引用文献の自動挿入
- 編集履歴とコメントの挿入
- 見出し

Word書式以外で，これらの書式を利用可能な軽量フォーマットが存在し，かつ，それがWordファイルと両方向に変換可能ならば，MS Wordに頼らない論文執筆環境を構築できるだろう．

<!-- }}} -->

# MarkdownとPandocを利用した軽量で快適な論文執筆環境
<!-- {{{ -->

上述した機能を持ち，軽量な(ソフトウェアで執筆できる)フォーマットがMarkdownである．
Markdownは，マークアップ言語であるため，メモ帳のようなデフォルトアプリでも編集でき，また[MarkText](https://marktext.app/)のようなMarkdown専用エディタを用いると，簡単にMS WordのようにWYSIWYGな文章に変換できる[^2]．
これだけでも十分に便利だが，プレーンテキストで記載できるため，MS Wordではできなかった，論文執筆に便利な以下のような機能を利用することが可能となる．

- 書式をつけた文章も(正規表現などを利用して)検索・置換の対象にできるという利点が存在する
    - 斜体にしたテキストのみ検索
    - 斜体になっていない種名をすべて斜体に置換
    - 上付き文字の一括置換
- Gitを利用したバージョン管理
    - Wordの編集履歴より軽量
    - ブランチを利用した分岐

Markdownは，生物系研究者が解析に用いているRmarkdownやJupyter Notebookでも記法として採用されており，普段の解析で記述した文章からシームレスに転用可能である点も重要だろう．

しかし，Markdownの形式では，MS Wordに慣れきったボスはチェックをしてくれず，また，学術誌も受け取ってくれない．
そこで，Markdownをdocx形式に変換する必要が出てくる．
Markdownからdocx形式への変換(，およびその逆)は，Pandocを用いることで可能になる．
Pandocそのものについては，[sky_y](https://qiita.com/sky_y)さんをはじめとする先達の皆様の解説に任せる．
重要なことは，Pandocを用いることで，

- 図表の挿入
- 斜体 (遺伝子名や種名の記載)
- 数式 (定量化手法や数理モデルの記載)
- 上付き文字 (対立遺伝子名や同位体の記載)
- 下付き文字 (分子式の記載)
- 引用文献の自動挿入
- 編集履歴とコメントの挿入
- 見出し

が適切になされたdocxファイルが出力可能であるという点である．

<!-- }}} -->

# 記法例とPandocによる論文テンプレート
<!-- {{{ -->

ここまでは，MarkdownとPandocによる抽象的な利点について記載してきた．
この節では，具体的な記法と利用法について簡単に紹介する．
ただし本節は，"MarkdownとPandocによる執筆はこのくらい簡単で便利だ"ということを知っていただき，利用へのハードルを下げることを目的としている．
そのため，MarkdownやPandocの使用法については専門の記事に任せ，事前の説明なくPandoc filterを利用した論文執筆法を紹介する．

## 図表の挿入
<!-- {{{ -->

論文執筆においては，図表の挿入は必須である．
すでに図や表がJPGやTIFFなどの形式になっているときは，

```
![Figure 1. The hogehoge model is important.](./figs/fig1.jpg){#fig:model-scheme}
\(A) Schematic of the hogehoge model is shown.
...
```

とすれば良い．
ちなみに，この記法を採用することで，MS Wordを超える利点が生まれる．
MS Wordでは，ファイル内に直接図が埋め込まれるため，図を更新した際は，MS Word内の図をいちいち変更する必要がある．
しかし，Markdownでは，更新された図が同じファイル名(パス)である限り，最新の図を常に参照するので，docxに挿入した図を更新する必要がない．

後半の`{#fig:xxxxx}`という部分は，[pandoc-crossref](https://github.com/lierdakil/pandoc-crossref)を用いた記法である．
crossrefを利用すると，まず当該図に自動で"Figure 1"など図番号が付され，また，論文中で`[@fig:xxxxx]`などと引用することで，自動で図番号に置換される．
詳しい使い方は，[pandoc-crossrefマニュアル](http://lierdakil.github.io/pandoc-crossref/)を参照されたい．

また，表を挿入する際は，

```
|             | Preveous Method | Novel Method |
|------------:|:---------------:|:------------:|
| Parameter 1 |        1        |       2      |
| Parameter 2 |        3        |       4      |
|       Score |       100       |    100000    |

:Comparison of two methods. {#tbl:table-comparison}
```

とすれば，Word形式の表に変換される．
図の挿入と同様に，`{#tbl:xxxxx}`とタグ付けすることで，crossrefによる"Table 1"などの表番号挿入や`[@tbl:xxxxx]`という記載による表引用が可能となる．

これだけでなく，既存のCSVが存在しているときは，[pandoc-csv2table](https://hackage.haskell.org/package/pandoc-csv2table)などのフィルターを用いることで，CSVファイルを直接読み込んで表にすることも可能である．

<!-- }}} -->

## 斜体 (遺伝子名や種名の記載)
<!-- {{{ -->

Markdown記法では，斜体したい文字列をアスタリスク(`*`)もしくはアンダーバー(`_`)で囲むことで斜体にすることができる;

```
*hoge* gene is involved in the embryonic development during hoge in *Drosophila*.
```

<!-- }}} -->

## 数式 (定量化手法や数理モデルの記載)
<!-- {{{ -->

PandocではLaTeX記法の数式入力が可能である．
`$`記号で囲んだ領域は，数式として認識される;

```
The equation $1 + 1 \neq 3$ was used to calculate hoge index.
```

これ以外のLaTeX記法(やLaTeXパッケージ)も利用可能なので，すでにLaTeXで論文を執筆している方にとっても使いやすいだろう．
詳しくは，[Pandocマニュアル: 数式](http://sky-y.github.io/site-pandoc-jp/users-guide/#math)を参照されたい．

<!-- }}} -->

## 上付き文字 (対立遺伝子名や同位体の記載)
<!-- {{{ -->

上付き文字は，ハット(`^`)で囲む．

```
The protein encoded by *hoge^fuga^* was labeled with ^13^C.
```

<!-- }}} -->

## 下付き文字 (分子式の記載)
<!-- {{{ -->

下付き文字は，チルダ(`~`)で囲む．

```
We found that H~2~O was tasty.
```

<!-- }}} -->

## 引用文献の自動挿入
<!-- {{{ -->

準備が少し必要なため，詳しい使い方は[Pandocマニュアル: 文献の引用](http://sky-y.github.io/site-pandoc-jp/users-guide/#citations)を参照されたい．

まず，引用文献を参照するリストとして`bib`ファイルを用意する．
これは，Mendeleyなどの文献管理ソフトによって出力可能である．
同時に，引用スタイルを指定する`csl`ファイルもダウンロードする．
Mendeleyなどのソフトウェア上では，論文ごとに，`Yamada2019`などの形式で"citation key"というものが発行される．
このcitation keyを以下のように引用すればよい．

```
It has been proposed that hoge is fuga [@Yamada2019].
```

引用は，自動でファイル末尾に挿入されるが，特別に引用文献の章を設けたい場合も，特別に記載すれば可能である．
筆者の場合，

```
# References

<div id="refs"></div>
```

という章を用意している．
これにより，`<div id="refs></div>`の部分に引用文献が挿入される．

<!-- }}} -->

## 編集履歴とコメントの挿入
<!-- {{{ -->

MS Wordの校正機能を用いた編集履歴などは，Pandoc上で`--track-changes=all`オプションを利用することで，Markdownへと変換もしくはMarkdownから変換できる．
詳しくは[Pandoc Manual: Option Track-changes](https://pandoc.org/MANUAL.html#option--track-changes)を参照のこと．

Markdown上では，

```
Here, we showed that hoge is important, [which]{.insertion author="TomosurebaOrange" date="2019-12-18:00:00Z"}[and it]{.deletion author="TomosurebaOrange" date="2019-12-18:00:00Z"} suggested that fuga is also important.
```

というように記述される．

また，HTMLコメントも利用できるため，日本語で下書きをしたいときなどは

```
<!-- ここでhogeとfugaの関係性を議論 -->
```

などとすることで，docxファイルには反映されないメモを挿入することができる．

<!-- }}} -->

## 見出し
<!-- {{{ -->

Markdown記法では，見出しは行頭のハッシュ(`#`)から始める．

```
# Abstract

# Introduction

# Experimental Procedures

# Reulsts

# Discussion

# Acknowledgements

# References

# Funding
```

<!-- }}} -->

## 論文のテンプレート
<!-- {{{ -->

筆者の論文テンプレートを紹介しておく．

[Github: ishibaki/paper-template](https://github.com/ishibaki/paper-template)

<!-- }}} -->

<!-- }}} -->

# 結語
<!-- {{{ -->

本記事では，(最後が駆け足になったが，)PandocとMarkdownを用いた論文執筆環境について紹介した．

そもそも，Pandocは，大学教員によって作成されたソフトウェアであり，その製作目的は，当初からアカデミックライティングを気軽に行うことだったであろうことがわかる．
筆者のような実験系生物学者などは，CUIソフトウェアと馴染みがなく，はじめはPandocに取っ付きにくさを感じるかもしれない．
しかし上述のとおり，Pandocは，アカデミアの人間がアカデミアの為に作ったソフトウェアである．
[Pandoc Manual](https://pandoc.org/MANUAL.html)や[日本Pandocユーザ会のマニュアル](http://sky-y.github.io/site-pandoc-jp/users-guide/)をよく読み，Qiitaなどの記事を読んでいけば，大抵の研究者はすぐに使いこなせるようになるだろう．

全く無関係な話だが，日本Pandocユーザ会を運営していらっしゃる[sky_y](https://qiita.com/sky_y)さんは，全く面識もコミュニケーションもないが，同じ時期に同じ大学に在籍していたため，一方的に親近感を持っている．
本記事の投稿を機会に，筆者も日本Pandocユーザ会へ参加を考えている．

<!-- }}} -->

<!-- Notes {{{ -->

[^1]: LaTeXによる執筆がメジャーな領域もあるだろうが，本稿ではそれ以外の領域を対象とする
[^2]: 同様のソフトウェアとしてTyporaがあるが，MarkTextのほうがOSSなため，個人的にはこちらを応援したい

<!-- }}} -->

<!-- vim: set foldmethod=marker : -->