卒論が終わったので、自分流の卒論の書き方をまとめた
みなさんこんにちは、 @km_conner です。
今回は卒業論文を書いた時に使った方法を紹介します。 これから卒論を書く人の参考になれば幸いです。
卒論とは？
多くの大学の理系学部では学部 4 年になると研究室に配属され、そこで研究をします。そこで研究をした成果として、卒業するためにそれまでの研究をまとめて、論文の形で大学に提出することが求められることがあります。これは卒業論文と呼ばれ、時に理系大学生の頭を悩ませるものです。 (文系学部でも卒論があるところも多いですが、ここでは割愛します。)
ちなみに、自分の所属していた京都大学工学部情報学科計算機科学コースでは A4 サイズで 25 ページ (参考文献リストを除く、 1 割以内の増減可、図表は全体の 4 割まで) の用紙指定があり、普段書くことのないような分量の文章を書くことになります。これだけの長さの文章を書くにはかなりの手間と時間がかかるため、データのバックアップやバージョン管理、自動ビルドなどの機能があるととても幸せになれると考えています。
通常の書き方
情報系の学部・学科では卒論を LaTeX と呼ばれる組版ソフトを使って書くよう推奨していることが多く、自分の所属する学科でも専用の LaTeX テンプレートが配布されています。このテンプレートでは指定されたフォーマット (1 枚あたりの行数、 1 行あたりの文字数など) を使って LaTeX のドキュメントを作成できるドキュメントクラスが格納されています。
このドキュメントクラスを使って platex や bibtex 、 dvipdfmx などを使って PDF を出力します。この際、 platex を何回か実行して次に bibtex を実行して… などとコマンドの実行順が煩雑なのでそれらをいい感じにやってくれる latexmk を使う人が、自分の周りでは多いように思います。
論文データの保存方法
論文データには、 LaTeX のソースコードや論文中で使用される画像などが含まれます。それらは一般に単一の PC だけではなくどこかの場所にバックアップされるべきです。時々ツイッターを眺めていると、締め切り直前に USB メモリが壊れた、とか PC の調子が悪い… などの投稿を見かけます。しかしながらこれは適切なデータのバックアップによりほぼ回避できます。
データをバックアップする手段としては Git を使用する方法や、研究室のファイルサーバー、オンラインストレージを使用する方法辺りが一般的だと思います。論文は日々更新されるため手動でバックアップするのは大変なので Git の使用をお勧めします。このほかに、 Overleaf などのすべてがオンライン上で完結するサービスを使用することも考えられます。
このような様々なデータの保存方法がありますが、
- テキストの編集には使い慣れたエディターを使いたい
- 手動でのバージョン管理は避けたい
という理由から、ソースコードなどのデータは Git を使用して管理することにしました。
Markdown で書きたい！
自分は普段のレポートなどは markdown で書き、 pandoc + lualatex で PDF を生成したものを提出していました。そのため、あまり LaTeX に慣れていません。また、 markdown で簡単に箇条書きやセクションタイトルなども、 \begin{itemize}...\end{itemize} や、 \subsection{...} などと書く必要があり、やや面倒に感じていました。しかし、 markdown の仕様の中でも多く用いられている CommonMark
や GitHub Flavored Markdown
の機能だけでは機能が不十分です。例えば、参考文献からの引用を示すコマンドである \cite{...} や、文書内部の図表を参照するコマンドである \ref{../} に相当する機能はありません。
Markdown の仕様には先述したもの以外にも様々なものがあります。その中でも Pandoc’s Markdown はかなり多くの機能をサポートしており、標準で用意されている拡張を使うことで必要な機能の ほぼ 全ての機能をカバーできます。しかしながら、完全に全ての機能がカバーできているわけではありません。例えば、複数の画像を横に並べる際には両方の画像に対してそれぞれキャプションをつけることはできません。そのような問題点を解決するために、 Pandoc のコードを一部改造して専用の変換ソフトを作りました。
Pandoc の改造
Pandoc とは、様々なフォーマットのドキュメントを相互に変換することのできるソフトウェアで、 Haskell で書かれています。このソフトウェアの内部的な処理の流れとしては以下のようなステップになっています。
- 入力するドキュメントを Reader が読み込み、 AST (abstract syntax tree) に変換する
- 入力された AST を Filter と呼ばれるプログラムによって操作する
- AST を Writer が指定された出力形式に変換する。
上の 2 は、 pandoc のコマンドラインオプションなどで filter を指定しないと何も操作は行われません。
今回作成したのは主に 3 において重要になってくる Writer です。Writer とは、 AST を指定されたフォーマットに変換して出力するプログラムです。つまり、今回は AST を元に大学で指定されたフォーマットの LaTeX コードに変換する機能を実装しました。
Writer の作成方法には 2 つの方法があり、 Haskell のコードを書き換える他にも Lua のコードを作成する方法があります。今回はこれらの方法のうち、既に存在する LaTeX 用の Writer のコードを一部変更し、大学で指定されたフォーマットの LaTeX コードを出力できるようにしました。
改造した pandoc のコードは こちらのリポジトリ
にて (master ブランチではなく modify-for-thesis ブランチに変更されたコードがあることに注意してください。) 公開しています。また、ビルド用のスクリプトなどを含めたコードを このリポジトリ
にて公開しています。また、このソースコードをビルドしたものを docker コンテナにして Docker Hub
に置いています。
GitLab + CI による自動化
うちの研究室では研究室内のサーバーにて GitLab をホスティングしており、卒論のソースコードもそこにアップしていました。GitLab には GitHub にもあるような CI の機能があります。その機能を利用してソースコードを push した際に毎回最新のビルドが走るようにしました。
ちなみに。 GitLab の CI はホストされているサーバーで動くのではなく GitLab Runner と呼ばれるプログラムをインストールしたマシンを GitLab の CI 設定から追加することにより Runner の動作している端末の上で実行されます。 (おそらく GitHub Actions の Self Hosted Runner のような感じだと思います。) CI では、 docker コマンドを実行してビルドして、成果物である卒論の PDF ファイルを保存できるようにしています。
この機構を採用してよかった点
この方法を採用したことにより、自分の書きやすいフォーマットである markdown で卒論を執筆できるようになりました。他にもメリットがありました。
それは、先生とのやり取りが楽になったことです。 従来は先生に卒論のレビューをお願いする際には出来上がった PDF をメールか Slack などで送る必要がありましたが、 GitLab のリポジトリに最新のビルドをダウンロードできるリンクを張った README を設置することでファイルを送信する必要がなくなりました。 また、先生に確認をお願いするときも Web GUI 上でソースの Diff を確認できるので、先生にもどこを修正したかを簡単に伝えられるようになりました。
まとめ・今後の課題
このシステムは卒論を締め切りまでに書くことを最優先し、その合間に開発したものであるため、卒論を書くのに最低限必要な機能しか備わっていません。例えば、コードブロックなど Markdown の機能の一部は、使用すると LaTeX でのビルド時にエラーとなります。また、卒論専用のドキュメントクラスでのみ動作するようになっているので、学会などで実際に使用されるドキュメントクラス (例えば IEEETran など) でも動くようにしたいです。
LaTeX に苦手のある学生の皆さん、 markdown を愛してやまないエンジニアの皆さん、ぜひ Markdown を使った論文執筆に挑戦してみてはいかがでしょうか？