レポート執筆環境を整える

1．はじめに

こんにちは、tardigradeです。

夏休みに入り、めでたくありとあらゆる義務から解放されました（いいえ）。
このタイミングで、かねてより考えていたレポート執筆環境の再構築を行おうと思います。

本記事では備忘録も兼ねてその手順を残していきます。

環境

• Windows11
• Ubuntu 22.04
• TeX Live (https://tug.org/texlive) version 2024

Ubuntuの導入については以下の記事が参考になります。

日本語化やエディタなど色々解説されていますが、本記事の範囲では

$ sudo apt update
$ sudo apt upgrade

までできていれば大丈夫です。

TeXLiveの導入については以下リンク先の動画が参考になります。

こちらもTeXLiveをUbuntuにインストールするというところまで完了すれば大丈夫です。

2．動機

もともと自分はLaTeX環境をローカルに作り、そこでレポートを執筆していました。
LaTeX環境を作るにあたって参考にしたサイトはこちらです。

最初期はCloud LaTeXやOverleafなどのオンラインサービスを利用していたのですが、GitHub Educationの申請が通ってからは、Copilotを使いたいがためにローカルで作業を行うようになりました。¹

基本的にはこれでほぼ快適に作業ができていたのですが、とはいえ全く不満がなかったわけでもなく…。具体的は次にあげる3点が気になっていました。

2.1 レポート/記事を別の形式に変換したい

僕は「自分が勉強した内容を記事にしてまとめておくサイト」を自分で作って管理しています（といってもまだ記事はほとんどないですが…）。

そこでは

1. Markdownでベースとなる記事を書く
2. ReactMarkdownで表示
3. cssで装飾

という手順（？）で記事を表示しています。²

大学で提出するレポートなどは基本的にLaTeXを用いるので、例えば物理で勉強したことをまとめ直そうとしたときに、両者の間で内容の再利用ができないのはかなり不便に感じていました。

TeXファイルをMarkdownファイルに変換したり、あるいはその逆ができたら、もっと作業が楽になって嬉しいです。

2.2 TeX書くのちょっと面倒

Markdownの書き心地を知っていると、どうしてもTeXを書くのが少し億劫に感じてしまいます。GitHub Copilotの登場によりそのあたりのストレスも緩和されてはいるのですが、それでも面倒なことには変わりないです。

比較的最近に登場したTypstは、少し触ってみた感じだと結構書きやすくてよかったんですが、arXivなどで受け付けてもらえないという点が将来的には辛くなりそうで、今のところ完全移行しようというほどではないです。

参考：

2.3 Gitでレポートを管理したい

正直これはやれば終わる話なのですが、なぜ今までやってこなかったのかというと、「レポートを管理しているprivateリポジトリ」が乱立するのを避けたかったからです。
これは僕個人の感覚なので、人によっては全く気にならないという方もいると思います。

アカウントをもう一つ作ることも考えましたが、そもそも規約的にグレーなのと、手元でのアカウントの切り替えがごちゃごちゃしそうでやめました。また、アーカイブしたりトピックをつけたりして管理をするというのもしっくりきませんでした。

3．やりたいこと

3.1 pandocの導入

Pandoc User’s Guideより引用

Pandoc is a Haskell library for converting from one markup format to another, and a command-line tool that uses this library.

Pandoc can convert between numerous markup and word processing formats, including, but not limited to, various flavors of Markdown, HTML, LaTeX and Word docx.

要するに、「Markdown⇔LaTeX」や「Markdown⇔HTML」ができます。すごい。
これが導入できれば、Markdown以外書かなくてよくなりそう。

あんまり詳しくは調べてないけど、User’s Guide曰くinput形式としてTypstも受け付けているっぽいです。どれくらい機能するのか気になりますね。³

自分で作っているブログサイトについては、記事をPandocでHTMLに変換したあと、dangerouslySetInnerHTMLとかhtml-react-parserとかを使って埋め込む形になるんでしょうか？詳しい方がいたら教えてください🙇

Pandocについての詳しい解説やインストール方法は以下の記事が参考になります。

WSL上に環境を作るかDockerを利用するかで少し悩みましたが、今回は前者にします。⁴
Docker Desktopは結構重たいので、大学に持っていく用の比較的スペックの低いPCで動かしたくないという気持ちです。
その点が気にならないのであれば、既にいろんな人がDockerイメージを公開しているので、それをそのまま使ったり自分好みに細かい修正を入れて環境を作るのが楽だと思います。

3.2 GitHub Organizationの利用

前述の理由でレポートをどう管理するか困っていたのですが、学科の友人から「GitHub Organizationを使うとそれ解決できるよ」と教えてもらいました。

どうやら適当なOrganizationを作成し、その中でリポジトリを管理すると良いようです（まだあんまりわかってない）。

4．手順

4.1 Pandocのインストール

WSLのターミナルを立ち上げます。バージョンは適宜読み替えてください。

最新版をインストールするために、パッケージマネージャを使うのではなくReleases · jgm/pandocから直接インストールします。

$ wget https://github.com/jgm/pandoc/releases/download/3.3/pandoc-3.3-1-amd64.deb
$ sudo dpkg -i pandoc-3.3-1-amd64.deb

pandoc -vでバージョン確認ができます。

$ pandoc -v
pandoc 3.3
Features: +server +lua
Scripting engine: Lua 5.4
User data directory: /home/taichi/.local/share/pandoc
Copyright (C) 2006-2024 John MacFarlane. Web: https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.

4.2 pandoc-crossrefのインストール

相互参照ができるようにするやつらしい。バージョンは適宜(ry

$ wget https://github.com/lierdakil/pandoc-crossref/releases/download/v0.3.17.1c/pandoc-crossref-Linux.tar.xz
$ xz -dc pandoc-crossref-Linux.tar.xz | tar xfv -

展開して、pandoc-crossrefをPATHが通っているディレクトリに移すorPATHを通します。

4.3 日本語PDFを出力できるようにする

適当にmdファイルを書いてPDFに出力してみます。

$ mkdir test_pandoc
$ cd test_pandoc
$ （hoge.mdを作って適当に編集する）
$ pandoc hoge.md -o hoge.pdf

hoge.md

# TEST

## TEST2

$123 \times 456$

*Thie is a test.*

おーすごい。ちゃんと出力できました。

ところで、日本語が含まれるファイルで同じことをすると、次のようなエラーがでます。

Error producing PDF.
! LaTeX Error: Unicode character て (U+3066)
               not set up for use with LaTeX.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...

l.55 \section{てすと}

以下ようにオプションをつけるといいらしいです（詳しい意味はあまりわかっていません）。

$ pandoc hoge.md -o hoge.pdf --pdf-engine=lualatex -V documentclass=ltjarticle

4.4 オプション設定をする

先ほど、MarkdownからPDFへの変換を行う際に

--pdf-engine=lualatex -V documentclass=ltjarticle

というオプションをつけました。

変換の際にこういうオプションを毎回書いてもいいのですが、オプションにあれも加えて～これも加えて～とこだわりが増えていくと、だんだん面倒になっていきます。

その手間を省くために、Pandocではオプション設定のセットをyamlファイルに書いて渡すことができます。

Pandoc User’s Guideより引用

-d FILE, --defaults=FILE
Specify a set of default option settings. FILE is a YAML file whose fields correspond to command-line option settings. All options for document conversion, including input and output files, can be set using a defaults file. The file will be searched for first in the working directory, and then in the defaults subdirectory of the user data directory (see --data-dir). The .yaml extension may be omitted. See the section Defaults files for more information on the file format. Settings from the defaults file may be overridden or extended by subsequent options on the command line.

カスタムや再利用が楽で便利ですね。

というわけで設定を書きました。

サンプルコードとそれをpdfに変換したものも一緒にアップしているので、詳しい記法やスタイルについてはそちらをご覧ください。

$ pandoc hoge.md --defaults=path/to/report.yaml -o hoge.pdf
$ pandoc hoge.md --defaults=path/to/report.yaml -o hoge.tex

あるいは

$ pandoc hoge.md --defaults=path/to/report_lualatex.yaml -o hoge.pdf
$ pandoc hoge.md --defaults=path/to/report_lualatex.yaml -o hoge.tex

でMarkdownをPDF（TeX）に変換できます。

なお、pdflatexのほうが動作は軽いですが、日本語が入っているとうまく変換できない場合があります。⁵
また、フォントもlualatexのほうが綺麗なので、基本的にはpdflatexで変換して最後の仕上げにlualatexを使うのがいいかもしれません。

なお、今回書いた設定に関しては、偉大な友人が書いたものをパクらせて参考にさせていただきました。

なんとこちらにはDockerイメージもあります！最高！

4.5 Organizationの作成

ようやくPandocの導入が終わったので、Organizationを作成します（freeプラン）。

と言ってもこっちは書くことがあんまりないです。

Organizationは今までずっと管理される側だったので、管理する側として何ができるのか把握しきれていないのですが、個人利用の範囲だと触らなくて良いものが多そう。ひとまずは「アカウントが一個増えた」くらいの気持ちで使います。

今年の前期だけで10数個、細かい課題も合わせたらその3倍くらいレポートを書いているので、それらを趣味やバイト関係のリポジトリと分けて管理できるようになったのはめちゃめちゃ嬉しい。早くやればよかった…。

5. おわりに

そこそこ満足のいく環境が作れたーーーー！！！

記事では省きましたが、

1. Pandocが上手く動かない
2. TeXの日本語のパッケージが入ってない
3. そもそもTeX-Liveのインストールが上手くいっていない
4. 全部消して入れ直し

という過程があり、当初想定していたよりも長丁場になりました。

自分は「自宅作業用」と「大学用」の2台のPCを使っているので、もう一回この作業を繰り返す必要があるのですが、正直気が重たいです。途中にも書いたけど、やっぱりDockerを使うべきだったかも。

ブログサイトの方は、手元と公開されるもので見た目が変わっちゃうけどしばらくはそのまま運用しようかな。一部使えない記法があって不便だけど、それよりも慣れないReactを触って実装を修正する方が億劫すぎる…。

pandoc-report-markdownはこれからじっくり育てていこうと思います。

それでは、長々とお付き合いいただきありがとうございました。

1. GitHub Educationの申請が通ると無料でGitHub Copilotを利用できるようになります。学生は申請し得なのでまだの方はぜひ！ ↩

2. https://github.com/akTARDIGRADE13/study-room/blob/main/src/study-room/routes/Blog/BlogCategory/BlogArticle/BlogArticle.tsx ↩

3. https://github.com/jgm/pandoc のDiscussionsをいくつか読んだ感じだと、まだ微妙そう。 ↩

4. 普段プログラミングをするときはWSL環境で作業しているから、Windowsに直接入れる選択肢は最初に切り捨てがち。 ↩

5. 「リンク内に日本語が含まれている」「CodeBlock内に日本語が含まれている」等。そのうち直したい。 ↩