Markdownで卒業論文を書きたい

当記事について

この記事は 学生LT Advent Calendar2018 5日目の記事です。

学生LTとは、技術を学ぶいろんな学生同士がLT会を通して交流しようという趣旨で始まった学生組織です。

私は来年からエンジニアとして会社員になるので、どちらかというとこの組織をどこかしらでサポートする形になりますが、もし興味を持った学生の方がいましたら、ぜひ公式HPからDiscordにご参加ください。中学生から大学生まで、学生であれば小学生もウェルカムです。

• 学生LT公式HP: https://student-lt.tech/

また、イベント会場を提供していただける企業様も同時に募集しておりますので、ぜひぜひ宜しくおねがいします。

卒業論文をTeXで書きたくない！

さて、本題です。そろそろ卒論や修論で忙しい時期ですね。私もついに5年目にしてやっと今年度で卒論を書けば学部卒業です。

しかし、私の大学の卒業論文には書き方に厳しい規定があり、TeXの卒論スタイルファイルが配布されています。.docxで書いてもいいそうで、docx形式のサンプルファイルも配布されていますが、左右余白何mmとかタイトル位置が上から・・・下から・・・mm単位で指定されており、ここまで厳格だとwordで書いたほうが消耗するな・・・と感じたので、TeXを使おうと思います。

今はTeX以外にも、モダンなマークアップ言語があるし、wordでも数式エディタが優秀になってきてますし、研究職に進まず学部で卒業しようとしてる自分としてはわざわざ卒業論文を書くためだけにTeXの学習コストを研究時間から割かなきゃいけないのは嫌だな、そんな時間があったら開発を進めたいなとは思うのですが、しかたありません。TeXを「ベース」にして、如何にエンジニア学生が楽してTeXを出力するかを書いていきます。

TeXで書こうとしても問題がある

私の大学では、卒論のテンプレートとしてwordファイルとstyファイルを含むtexのアセット一式がサンプルとして提供されているので、それに則って書くのが一番らく　(TeXの学習コストを除けば)レイアウトを気にせず論文書けて一番ラクなんですが、問題は、このstyファイルがなんとTeX時代のものなので、cloudLaTeXなんかでやろうとしたり、後述するpandocでPDFまで変換しようとしてもそのままでは動かないんですよね(てか今の環境で動かないファイルをよこすなという話なんですが)

そんなわけで、レガシーなスタイルシートにも対応可能なmarkdownで論文を書く方法を書いていきます。

Markdownについて

GithubのReadmeやここ、Qiitaなどで使われるMarkdown。多分この記事を見ている殆どの人は書いたことはなくともその存在は知っていると思います。

例えば、

サンプル

吾輩は猫である

吾輩は猫である。
名前はまだ無い。

という文章をHTMLとmarkdownとTeXでかき比べてみる。

sample.html

<h1>サンプル</h1>
<h2>吾輩は猫である</h2>
吾輩は<b>猫</b>である。<br>
名前はまだ無い。

sample.md

# サンプル
## 吾輩は猫である

吾輩は**猫**である。

名前はまだ無い。

sample.tex

\section{サンプル}
\subsection{吾輩は猫である}
吾輩は\textbf{猫}である。\\
名前はまだ無い。

markdownの場合、改行の数は多くなりますが、よくあるマークアップ言語と違い、文字や文の先頭に記号を置けば、それだけで文字の装飾や見出しが指定できます。

TeXもまあこう見てみると言うほど難解なマークアップ言語でも無いと思いますが、Qiitaに記事を上げるようなエンジニアならMarkdownで書きてぇになると思うので、長文を書いた時の労力を考慮し、ぜひMarkdownで論文を書きましょう。

論文PDFができるまでの過程と手順

今回採る手法

Markdownで書いた物は、一度HTMLやTeXなどのマークアップ言語に変換されてから、PDF
になります。今回ですと、最終的にPDFにしたいので、TeXファイルがプログラム内部で中間生成され、PDFになります。

ここで用いられるのが、Pandocというドキュメント変換ツールです。

これを用いるとmarkdown以外にもHTMLやdocx、odtや電子書籍フォーマットのepubなどからの相互変換も可能です。

Markdown→(Pandoc)→TeX→(LuaTeX)→PDF

ですが、今回はあえてpandocで作業するのは最終出力ファイルのPDFでは無く、TeXまでにしておきます。何故かと言うと、私の大学のように卒業論文フォーマットスタイルファイルが今主流のLaTeXでは無くTeXのままになって更新されていない、独自パッケージが使われている等互換性の問題でpandocで最後のPDFまでやろうとすると面倒が発生することがあるからです。

今回の私のやり方では、

Markdown→(Pandoc)→TeX
TeX+TeXスタイルシート→(LaTeX)→TeX

の手順でやっていきます。

また、このやり方では概要やタイトル等は大学のサンプルファイルなどのTeXファイルに直接書いて、本文をそのTeXファイルにインポートする形で説明します。こうすることで一番長い本文をmarkdownで書きつつ、論文タイトルなどのメタ情報的なとこだけ手打ちすることで各大学のフォーマット別の面倒事やレガシーの不便さ、エラー等を最大限に吸収できるという算段です。

そのままTeXで書く場合においても、本文だけ別のTeXファイルに分離しておくと、本学のように各学期末にレポートを出すような大学では本文の使い回しが聞くので便利だと思いますよ。

今回はあくまでpandocで出力したファイルを別のTeXファイルにインポートするやり方を中心にやるためLaTeXの環境整備については省略してCloudLaTeXを使う手順で紹介します。

Pandoc導入

さて、さっそく導入していきましょう。

手順自体はhttps://qiita.com/sky_y/items/3c5c46ebd319490907e8で書かれているパッケージマネージャでインストールでOKです。

WindowsでもChocolateyでインストールできるみたいですね。でも私はWindows Subsystem LinuxのUbuntuアプリの手順でやるのをおすすめします。

Macの場合(Homebrewが入っている前提)

$ brew install pandoc

Linux Debian/Ubuntu系とWindows Ubuntuアプリ(パッケージリストのアップデートコマンドも載せてます)

$ sudo apt update
$ sudo apt install pandoc

Linux Redhat/CentOS系

$ sudo yum install pandoc

pandocの本当の最新版が使いたい(パッケージマネージャに載っているものだとpandocの公式最新版よりバージョンが古いときがある)方は、Haskelのパッケージマネージャであるcabalを使うのもおすすめです。

実行

それでは試しに実行しましょう。実行したいディレクトリに移動して、入力ファイルがbody.md、出力ファイルがbody.texだとすれば

$ pandoc body.md -o body.tex --top-level-division=chapter

でbody.texにTeXファイルが出力されます。

※--top-level-division=chapterを付けないとトップレベルタイトルが別のTeXにimportされた際にセカンドレベルタイトルになってしまう為, トップレベルタイトルを章にするようオプションを設定する必要がある為, このオプションを付与します. 01/27修正しました.

既存のTeXファイルにmarkdownから生成されたTeXファイルを突っ込む

大学で既にサンプルのTeXファイルがあるのであれば、本文が書かれているところをすべて消して、そこに

\input {hoge}

のhogeの部分にmarkdownからpandocで生成したファイルの相対パスを書きます。拡張子の有無は関係無いようです。

もし、スタイルファイルを元にTeXファイルを1から自作する場合は、\begin{document}と\end{document} の間に\input{hoge}を入れればいいです。{document}の部分はもしスタイルシートで独自に定義されているものがある場合はそれを入れてください。

sample.tex

\begin{document}

\def\tightlist{\itemsep1pt\parskip0pt\parsep0pt}
\input {hoge}

\end{document}

また、環境によっては\def\tightlist{\itemsep1pt\parskip0pt\parsep0pt}が無いと、pandocから自動生成されたTeXファイルのtightlistタグがundefinedでエラーとなることがあるみたいなので、エラーが出たらこれをinputタグの手前に入れてあげてください。

コンパイル

手元の環境にLaTeX環境を入れればいいのですが、なんせセオリーどおりのやり方で導入する、例えばMacTeXだと1GB以上も容量が食われる上に、細かい設定やパッケージの導入が出てきて大変面倒です。そこで、問題が無いのであればCloudLaTeXで作業することをオススメします。

• CloudLaTeX: https://cloudlatex.io

大抵の日本語環境でよく使うパッケージは導入済みで、保存すると即時にPDFでプレビューしてくれます。

また、Dropboxに同期できるので、ローカルにDropboxの同期ソフトを導入していればローカルファイルといい感じにやり取りも出来ます。直接git管理が出来ないのが玉に瑕ですが、一度コンパイルが通るようになれば、後はmarkdown側でカキカキするだけなので、最悪markdownファイルだけをgit管理すればいいと思います。私はインポートされる側のTeXファイルを触ったときだけDropbox同期フォルダからgit管理フォルダにコピーしてます。

まとめ

結局TeXを頼ってるけど、まあこの方法だと卒論の9割はmarkdownで書いてるから実質TeXは書いてないようなもんかと(暴論)

まあそしてなんやかんやでTeXをTeXにインポートしたらpandocとLaTeXと日本語環境由来のいろいろな厄介から開放された上でmarkdownで卒論書けるよやったねたえｔ