論文のdraftをmarkdownを使って書いて、ほどよい感じで.docxに出力する方法

markdownはいろいろなところで活用されていますが、論文や書籍の原稿に使う試みもなされています。体裁を整える手技もlatex->pdfの書式を中心に紹介があります。

一方、論文の下書き程度ですと共著者に回して修正やコメントをもらうのにはword (.docx)が多いと思います。今後先々はmarkdownでそのまま回覧できる日が来るかも知れませんが、当面docxの優位は変わらないでしょう (医学保健学系)。

今回想定している使い方は

1. windowsで
2. タイトルページをそれなりの形にする(yamlに記載)
3. markdownとpandocを使って
   • ページ区切りを挿入
   • セクション番号を追加
   • 文献の引用 + 引用文献リストの作成
4. docxのスタイルをそれっぽく見せるためのpandocのオプション

を記録に残すためのものです。完成形までは行けませんが、概ね用は足せる状況になりました。

.docxとは?

一応ですが、wordの通常のファイルの意味です。拡張子が.docxなのでそのように記述してます。以下同様にwordファイルではないですが、.csl (文献引用のスタイルシートのファイル)とか.bib (文献引用情報のファイル)とか.lua (pandocの拡張機能のファイル)とか.md (markdownのファイル)とか出てきます。

他のツールは何が足りなかった?

車輪の再発明は面倒なのでいろいろググりましたが、自分のニーズにフィットする方法は見つかりませんでした。
.docxに変換すると概ね著者情報が飛んでおり、そこが主なハードルになっています。

1. Rstudio-Rmarkdown-rticlesの利用

   pdf (latex経由)の書式は概ね目的を達成できました。試しにFrontiersとか使ってみましたが、Rmarkdownのテンプレートも用意されていて、いい感じです。αとかβみたいなギリシャ文字のフォントが当たらずトウフになるのが改善できませんでしたが。あとdocxだと著者の欄がすっぽりなくなるので結局不採用。

2. typademic

   サイトにあるテンプレートをダウンロードして、内容を書き換えた後、サイトにアップロードするとpdfとかdocxに変換してくれるすぐれもの。

   ただ著者を複数並べて、施設(institute, affiliation)を複数並べてFirst Author^1^みたいにする方法がわからなかった。

   .docxは著者情報がやはり残らない。

3. Science.md

   上のtypademicに近いけれどもテンプレートがセクション毎に異なるファイルを指定。サイトを見るとpdfは著者情報を含めタイトルページが整形されているけれども、やはり.docxの著者情報は落ちてるみたい。

   あと変換の処理がlinuxがベースぽい。dockerが使えるとwindowsでも簡単なのだろうけれども、その辺の知識がないので断念。

4. pandoc-scholar

   サイトの説明には出てくるがpdf、docxともに住所などは表記されていない。makeファイルを使っていてlinuxが必要そう。サイトでもdockerの説明あり。docker初心者にはハードル高し。ちゃんと理解できればこれが目標に一番近い印象。

やりたかったことをもう少し具体的に

1. タイトルページの著者情報をいい感じに

タイトルページはこんな感じ

---
# YAML front matter
title: "Some title"
# runtitle: "Short Title" #通常使わない
author:
  - First Author:
      email: [e-mail]
      institute: [hoge_univ, fuga_univ] # 施設が複数ある時は鍵括弧
      address: Street X, City Y, 1111111, Japan # 今のところ使えない
      correspondence: true
  - Last Author:
      institute: fuga_univ
institute:
  - hoge_univ : Department of X, School of Y, Z University, City Y, Japan
  - fuga_univ: Department of A, Faculty of B, C University, City D, Japan
# date: "07 September 2021" # 使わない
# reference style: 原稿の.mdに"csl"のフォルダを作って、その中にfrontiers.cslを入れている場合
csl: ./csl/frontiers.csl
# reference: 原稿の.mdに"ref"のフォルダを作って、その中にreferences.bibを入れている場合
bibliography: ./ref/references.bib
---

この中身をいじって後に示すpandocのオプションをつけると、以下のようなタイトルページができます。

2. pandocのオプション

pandocのインストールが済んでいるのは前提です。

素でmarkdown -> docxに変換するのは以下の通りです。powershellあたりにコピペしましょう。

pandoc input.md -o output.docx

input.mdが原稿を書き込んだmarkdown。output.docxは出力後の.docxです。

input.mdがないとNo such file or directory的なエラーが返ってきます。

output.docxがなければ生成されるし、ファイルがあれば警告なしに上書きされます。

例に挙げたオプションなしでの変換だと、タイトルページはこんな感じになります。

タイトルだけで、著者情報が全部飛んでいます。

著者名だけ、とかいうのは可能のようですが、施設名とかもないとあまり使い勝手がよくないので、pandocの拡張機能を使います。

2-1. 著者(施設)情報の追加

pandocのオプションに--lua-filter なんとか、みたいなのをつけます。この辺からよくわかっていません。

lua filtersのサイトにautho-info-blocks.luaとscholarly-metadata.luaの2つがあって、これらが必要そうです。

.luaをダウンロードして、.mdと同じとこに"lua"とかディレクトリを作って、そこに入れておきましょう。

適当なディレクトリ
├─ input.md (原稿)
├─ lua/ <- このディレクトリを作成
│ ├─ author-info-blocks.lua <- これを追加
│ └─ scholarly-metadata.lua <- これを追加

pandoc input.md -o output.docx

は以下のように変化します。

pandoc input.md -o output.docx --lua-filter ./lua/scholarly-metadata.lua --lua-filter ./lua/author-info-blocks.lua

結果タイトルはこうなります。

タイトルが青字になってたりするのはスタイルの問題なので2-5で改めて説明します。

2-2. ページ区切りの挿入

.mdに\newpageと入っているところでページ区切りが入ります。前後に空の行が必要かも知れません。要確認。

ページ区切りが不要な場合はここで追加するオプションをつけずに2-3に進みましょう

2-1で出てきた--lua-filterを再度使います。pagebreak.luaはここからダウンロードできます。最初.luaをダウンロードしたつもりがhtmlをダウンロードしてました。がっかり。

2-1と同様に "lua" ディレクトリに "pagebreak.lua" ファイルを保存しておきましょう。

適当なディレクトリ
├─ input.md (原稿)
├─ lua/
│ ├─ author-info-blocks.lua
│ ├─ scholarly-metadata.lua
│ └─ pagebreak.lua <- これを追加

pandocは以下のようにオプションが増えます。

pandoc input.md -o output.docx --lua-filter ./lua/scholarly-metadata.lua --lua-filter ./lua/author-info-blocks.lua --lua-filter ./lua/pagebreak.lua

最後に--lua-filter ./lua/pagebreak.luaが追加されています。テンプレートではabstract, introduction, references, figure legendのところで改ページしています。

2-3. セクションに番号を付加

セクション番号は普通に直打ちで構いませんが、たまに段落入れ替えたりして妙な番号になったままうっかり放置したりしませんか?
pandocのオプションを以下のように追加します。

pandoc input.md -o output.docx --lua-filter ./lua/scholarly-metadata.lua --lua-filter ./lua/author-info-blocks.lua --lua-filter ./lua/pagebreak.lua --number-sections

になります。最後に--number-sectionsが付加されています。これでセクション番号(1. Introductionみたいなの)が付加されます。
セクション番号が不要な時はこのオプションを入れずに2-4に進むとよいです。またabstractはセクション番号不要、みたいな時は

# Abstract {.unnumbered}

みたいに{.unnumbered}を入れとくとセクション番号が付かなくなります。

2-4. 原稿中の引用 + Referencesの生成

この辺は他でもよく書いてあります。Zettlrを使うと作業しやすいです。

短く書くと、文献情報をまとめた.bibファイルを用意して、原稿のmarkdown中に[@author2000]みたいな形式で挿入する、

ということになります。あとはpandocでオプションをつけるといい感じに引用文献リストが生成されます。

前提: .bibがあること。
ここでは例としてreferences.bibとします。ref.bibでもreference.bibでも何でもよいですが、保存した時のファイル名に合わせます。.bibの取り方はこの辺から

.cslとは?・・・

ディレクトリはこんな感じになります。

適当なディレクトリ
├ input.md (原稿)
├ lua/
│ ├─ author-info-blocks.lua
│ ├─ scholarly-metadata.lua
│ └─ pagebreak.lua
├ ref/ <- このディレクトリを作成
│ └─ references.bib <- これを追加
├ csl/ <- このディレクトリを作成
│ └─ frontiers.csl <- これを追加

• 引用の仕方

  markdownを開いて[@hoge2000]みたいな形で引用。@hoge2000は.bibの・・・

• 引用文献リストの作成

markdownのヘッダ部分にこっそり必要な設定が記述されています。関係するところだけ抜き出しています。

# reference style: 原稿の.mdのあるディレクトリに"csl"のフォルダを作って、その中にfrontiers.cslを入れている場合
csl: ./csl/frontiers.csl
# reference: 原稿の.mdのあるディレクトリに"ref"のフォルダを作って、その中にreferences.bibを入れている場合
bibliography: ./ref/references.bib
---

pandocのオプションを追加することでReferenceに引用文献リストが作成されます。

pandoc input.md -o output.docx --lua-filter ./lua/scholarly-metadata.lua --lua-filter ./lua/author-info-blocks.lua --lua-filter ./lua/pagebreak.lua --number-sections --citeproc

になります。最後に--citeprocが追加されています。これによりReferencesの欄に引用文献リストが作られます。

書式はここではfrontiers.cslで定義されたものになりますので、他の雑誌に合わせたい場合はzotero style repositoryで検索すると概ね雑誌名でヒットするので、.cslをダウンロードして置き換えると適用されると思います。

2-5. テンプレート.docxの適用

タイトルの青字を黒にしてフォントも変えたりするのに"スタイル"を参照するための.docxを用意しておきます。

ディレクトリは以下のようになります。

適当なディレクトリ
├ input.md (原稿)
├ lua/
│ ├ author-info-blocks.lua
│ ├ scholarly-metadata.lua
│ └ pagebreak.lua
├ ref/
│ └ references.bib
├ csl/
│ └ frontiers.csl
├ docx_template/ <- このディレクトリを作成
│ └ Template.docx <- これを追加

2-6. 実際に走らせた結果

こうなります

結論

1. を利用

文献引用はZettlrあたりを使ってすると作業が楽になります。下記の.bibが必要となります。

2. .bib、.cslを用意する: 引用文献情報とそのスタイル

例として今回はcsl, ref, template_docxというフォルダを作って、それぞれに.csl、.bib、.docxファイルを入れました。同じディレクトリにあってもよいですが、それに合わせて設定ファイル等変更するようになります。

2-1. markdownのヘッダ(yaml)の情報を確認

繰り返しですが、以下の行

bibliography: ./ref/references.bib

の箇所は原稿の.mdファイルと同じとこに"ref"というディレクトリがあって、"references.bib"という.bibファイルをそこ置いています。それを参照します、ということになります。

csl: ./csl/frontiers.csl

同様に上記は原稿の.mdファイルと同じとこに"csl"というディレクトリがあって、"frontiers.csl"という.cslファイルを置いています。それを参照します、という意味になります。

それぞれ実際のファイル名、配置に合致しているか、確認しましょう。

合致していなければpandocを走らせたときにno such file or directory的なエラーが返ってきます。

3. .luaファイルを用意する

原稿の.mdファイルと同じディレクトリに"lua"というディレクトリを作って、そこに3つファイル(scholarly-metadata.lua, author-info-blocks.lua, pagebreak.lua)を入れる状態を想定しています。

pandoc 云々 --lua-filter ./lua/scholarly-metadata.lua --lua-filter ./lua/author-info-blocks.lua --lua-filter ./lua/pagebreak.lua 云々

が相当するpandocのオプションです。

4. テンプレート.docxを用意する

原稿の.mdファイルと同じディレクトリに"docx_template"というディレクトリを作って、そこに"Template.docx"というファイルを置いている状態にします。pandocのオプションで

pandoc 云々 --reference-doc ./docx_template/Template.docx 云々

という箇所がありますが、これに合致していればよいです。

たとえばテンプレート.docxが.mdと同じディレクトリに"Frontiers_Template.docx"というファイル名で置いてあれば

--reference-doc Frontiers_Template.docx

というオプションに変わります。

5. pandocをオプション付きで走らせる

ひどく長いので怯みますが、基本powershellあたりにコピペで大丈夫です。メモ帳などに置いて、必要箇所を書き換えて使いまわすとよいでしょう。

pandoc input.md -o output.docx --lua-filter ./lua/scholarly-metadata.lua --lua-filter ./lua/author-info-blocks.lua --lua-filter ./lua/pagebreak.lua --number-sections --citeproc  --reference-doc ./docx_template/Template.docx

主に変わるのは"input.md"(原稿のmarkdownのファイル名)、"output.docx"(変換後の.docxのファイル名)でしょう。output.docxはinput.mdと同じディレクトリになければ生成され、ファイルがあれば警告なしで上書きされます。

あと.docxの行間を変えたい、などあれば、Template.docxの行間を広げると反映しますが、この辺も多少tipsはあり、うまく行かないかも知れません。頑張ってググりましょう。

4. 出力した.docxを確認

うまく行くと以下のような.docxが得られます。

まだできてないこと

1. corresponding authorに住所、電話番号を追記

2. タイトルのyamlにkeywordは追記できるようだけれども.docxに反映する方法がわからない。

   現在はただのテキストとして記述。

3. running titleに対応できない (Rstudioのrticlesでpdfを出すときは対応するようですが)

最後に

今回はFrontiersのtemplateを使いましたが、この行間を変えて、--number-sectionsのオプションをつける/外す、くらいで他の雑誌でも対応できるのではないかと思います。

意外と説明が長くなりました。まだ面倒が多いですね。

これで論文がはかどるといいけど、そうは行きません・・・