Zenn
🦔

[初心者向け] LaTeX文書をいい感じに運用する方法

2021/12/29に公開
Docker
GitHub Actions
初心者向け
textlint
LaTeX
idea

はじめに

僕が普段\LaTeXでレポートを書くとき，どう運用しているかの記事です．参考になれば幸いです．テンプレートとして，t4t5u0/latex2e-textlint-sample[1] というリポジトリを作成したので，ぜひ利用してください．また，欲しい機能や不具合があれば，お気軽に Issue までおねがいします．

この記事のモチベーションとしては，レポートを楽に書きたい．というものです．
https://twitter.com/shimakid/status/1475353805047099392?s=20

こういう[2]のは，僕は楽ではないと思います(ちょうど Twitter に流れてきた)．みなさんも GitHub や Docker などに乗っかって楽をしていきましょう．

環境構築

  • Git/GitHub
  • Docker
  • VSCode
    が前提としてでてきます．まずはこれらの環境構築をします．

Git

Windows ユーザー

Git for Windows[3] を参照してください．

Git のインストールは，Powershell を用いて以下のようにもできます[4]．

winget install -e --id Git.Git

Mac ユーザー [5] 

brew install git

Linux(Ubuntu)ユーザー [6] 

sudo apt install git

GitHub

Git のインストールが終わったら，GitHub のアカウントを作成[7]してください．
アカウントを作成したら，GitHub アカウントへの新しい SSH キーの追加 - GitHub Docs[8]を参照して，SSH キーを追加してください．GitHub からリポジトリをクローン(コピー)する際に必要になります．

Docker

使用している OS に合わせて以下を参照してください．

Windows ユーザー

まずは WSL2 を導入してください

Docker のインストールは，Powershell を用いて以下のようにもできます[11]．

winget install -e --id Docker.DockerDesktop

Mac ユーザー

Linux ユーザー

VSCode

VSCode のインストールは以下のリンクから行ってください．コマンドラインからでも構いません．
Download Visual Studio Code - Mac, Linux, Windows[14]

VSCode を起動します．VSCode 左側の四角形が並んでいる場所で，以下の拡張機能を検索してください．

fig1

[オプション]vscode-textlint をインストールし，無効にします．手元で TextLint を使用したい場合は，ワークスペース単位で有効化するのがいいでしょう．

fig2

Dockefile の設定

Docker の説明

いきなり Docker というものがでてきて，Docker とは？？という人もいると思うので軽く説明します．公式の説明は以下のとおりです．

Docker とは開発者やシステム管理者が、コンテナでアプリケーションを 構築（build）、実行（run）、共有（share）するためのプラットフォームです。

Docker は環境をコンテナという単位で扱います．

Part 1：概要説明とセットアップ — Docker-docs-ja 20.10 ドキュメント[18] より

今回は，LaTeX の環境を整えるのに時間がかかる(ビルドに数時間)ので採用します．

docker composeは，docker コンテナを簡単に起動するためのサブコマンドと思ってもらえれば大丈夫です．

書き換える場所

今回は，LuaLaTeX[19] を使用しますが，ご自身の環境によって，upLaTeX[20] や pLaTeX [20:1]を使用したいこともあると思います．そのときは，2 つ操作が必要です．

以下の行を user_name/image_name:version の順番で書き換えてください．(後ほどブランチによって切り替えられるようにしておきます)．
例えば，aruneko/texlive:latest [21] などとするといいでしょう．

https://github.com/t4t5u0/latex2e-textlint-sample/blob/04905703468b0eb849cfaff1f68f66189f493c3e/docker-compose.yml#L14

latex2e-textlint-sample/.latexmkrc at main · t4t5u0/latex2e-textlint-sample というファイルを

#!/usr/bin/perl

@default_files  = 'main.tex';
$out_dir        = ('output/');

$pdf_mode         = 3;
$latex            = 'uplatex -halt-on-error';
$latex_silent     = 'uplatex -halt-on-error -interaction=batchmode';
$bibtex           = 'upbibtex';
$dvipdf           = 'dvipdfmx %O -o %D %S';
$makeindex        = 'mendex %O -o %D %S';

$ENV{TZ} = 'Asia/Tokyo';
$ENV{OPENTYPEFONTS} = '/usr/share/fonts//:';
$ENV{TTFONTS} = '/usr/share/fonts//:';

[22]

などと書き換えてください．

この 2 箇所を書き換えると，大体の TeX ファイルをコンパイルできるはずです．

機能

t4t5u0/latex2e-textlint-sampleで実装した機能の話をします．手元で試したい場合は，Use this template というボタンをクリックしてください．

  • docker compose up pdf としたら，PDF が作成される
  • docker compose up linter としたら，日本語のミスをチェックしてくれる
  • Pull Request を出したら，Web 上でレビューをしてくれる
  • タグを付与すると，Release にそのバージョンの PDF を配置してくれる．

docker compose up pdf としたら，PDF が作成される

docker compose up pdf

とすると， /writing_space/output/main.pdf という pdf が生成されているはずです．中身は，夏目漱石氏の吾輩は猫であるの冒頭です．
/writing_space 以下に配置した，main.texというファイルがコンパイルされるようになっています．ここにレポートや論文を書き込んでいきましょう．

docker compose up clean 

docker compose up clean

とすると，/writing_space/output 以下の中間ファイル(.aux)などを削除します．まれに中間ファイルが残っているとコンパイルに失敗することがあります．
TeXファイルに問題がないのにコンパイルに失敗した場合は試してみてください．

docker compose up linter としたら，日本語のミスをチェックしてくれる

linter という言葉を初めて聞いた人もいるかも知れません．これは，ソースコードを解析し，問題点を自動で見つけてくれるものです．今回使用する TextLint[23] というものは，これを日本語に対して，行ってくれるものです．僕はよく単純なミスをするので，とてもありがたいです．くわしい設定方法は調べるとたくさん出てくるので，そちらにお譲りします．

動作例

Pull Request を出したら，Web 上でレビューをしてくれる

reviewdog という仕組みを使用します．

zenn-cli + reviewdog + textlint + GitHub Actions で執筆体験を最高にする[24] がわかりやすいです．

動作例

上記画像にはないですが，Commit Suggestion というボタンがあるときは，Bot からの更新をコミットとして取り込めます．基本的には，ローカルで変更を加え，再びプッシュするのがいいと思います．

例えば画像，既存のルールに加え，表記揺れを解決したい場合は，prh.yml というファイルにパターンを書き込むことで，ルールを追加できます．

タグを付与すると，Release にそのバージョンの PDF を配置してくれる．

Git/GitHub にはタグという機能があります．

Git - タグ[25]

最も簡単にタグを付けるには，以下のようにします．

git tag v0.1.0

以下のどちらかのコマンドで，タグをリモートに送ることができます．後者は，複数のタグを同時に送るコマンドです．

git push origin v0.1.0
git push origin --tags

このタグという機能を用いて，vから始まるタグが送られたとき，Release という場所に PDF を配置するというワークフローが組まれています．

GitHub の左下にあります．Release をクリックすると，以下のような画面に飛びます．

タグ付きの PDF を GitHub 上からダウンロードできることがわかります．

この機能はGitHub Actions で TeX をコンパイルして PDF を Releases にアップロードする[26]を参考にしました．大きな差異は Makefile やシェルスクリプトをdocker composeで代替していることです．

運用

機能の紹介と簡単な解説が長くなりましたが，本題の運用です．僕が実際に使用する場合は，リポジトリ構成は，ざっくり以下のようになっています．

❯ exa -T --git-ignore -L 3
.
├── Docker
│  └── node
│     └── dockerfile
├── docker-compose.yml
├── LICENSE
├── package-lock.json
├── package.json
├── prh.yml
├── README.md
└── writing_space
   ├── main.tex
   ├── output
   │  └── main.pdf
   ├── parts
   │  ├── 01overall
   │  │  ├── 01background.tex
   │  │  ├── 02conclusion.tex
   │  │  ├── reference.bib
   │  │  └── images
   │  │      └── sample_image.png
   │  ├── 00abst.tex
   │  └── 01overall.tex
   └── styles
      └── sample.sty

writing_space/

執筆作業はすべてwriting_spaceの中で行います．main.texでは，parts や chapters(今回は 01overall に相当)を参照する程度にしておきます．ソースコードをパッケージ化するのと同じように，文書を分割することで，管理がしやすくなります．01overall.tex は 01overallディレクトリを参照するようにします．これは，Rust という言語のパッケージ管理と似た構造になっています．ファイルの先頭に数字を付けている理由ですが，エディターで見たときに，ソートされて見やすくなるようにです．章番号や節番号とリンクさせるとさらにわかりやすくなります．

main.tex
% lualatex を使用する
\documentclass[openany,11pt,report]{ltjsbook}

% 画像を使用する場合
\usepackage{graphicx}

% biblatexを使用して参考文献を管理する場合
% sorting=none は引用順に参考文献を並べる
% refsegment=part は章ごとに参考文献を管理する．章ごとなら=chapter
\usepackage[sorting=none,refsegment=part]{biblatex}
\addbibresource{parts/01overall/reference.bib}

\begin{document}
\maketitle

%前付け
\frontmatter

% 概要はタイトルの後，目次の前に挿入
\input{parts/00abst.tex}

\tableofcontents% 目次

%======================================================================
\mainmatter% 本文のはじまり

%各章の.texファイルをここに並べる
\input{parts/01overall.tex}

% ======================================================================
% 奥付け
\backmatter

\end{document}
01overall.tex
\part{活動の概要}

% writing_space からの相対パスを記述します．
\input{parts/01overall/01background.tex}
\input{parts/01overall/02conclusion.tex}

% 参考文献というタイトルで章ごとに参考文献を表示

\printbibliography[title=参考文献,segment=\therefsegment]
01background.tex
\chapter{背景}

これは背景です．

このように，ツリー状に文書を管理します．ファイルを細分化することで，GitHub で複数人が編集するときも，コンフリクトが少なくなったり，担当箇所が明瞭になってわかりやすくなります．

その他のディレクトリやファイルについて解説します．

writing_space/output/

コンパイルしたPDFや中間生成物が配置される場所です．

コンパイルした PDF や中間生成物が配置される場所です．

PDF を作成したあと，.texファイルを VSCode で開き，右上のタブのようなマークを押すと，右側で PDF のプレビューが行なえます．

writing_space/styles/

学校や学会で指定のスタイルファイルがあればここに配置します．main.tex冒頭で以下のように呼び出します．

学校や学会で指定のスタイルファイルがあればここに配置します．main.tex冒頭（プリアンブル）で以下のように呼び出します．

main.tex
\usepackage{styles/sample}

\begin{document}
...

参考文献の管理

今回はBibLaTeXを用います．main.texのプリアンブルのうち，以下の部分に着目します．

% biblatexを使用して参考文献を管理する場合
% sorting=none は引用順に参考文献を並べる
% refsegment=part は章ごとに参考文献を管理する．章ごとなら=chapter
\usepackage[sorting=none,refsegment=part]{biblatex}
\addbibresource{parts/01overall/reference.bib}

Google Scholor から論文を引用する場合は，目的の論文を検索し，引用 -> BibTeX をクリックし，中身をコピーします．

reference.bib
@article{oord2016wavenet,
  title={Wavenet: A generative model for raw audio},
  author={Oord, Aaron van den and Dieleman, Sander and Zen, Heiga and Simonyan, Karen and Vinyals, Oriol and Graves, Alex and Kalchbrenner, Nal and Senior, Andrew and Kavukcuoglu, Koray},
  journal={arXiv preprint arXiv:1609.03499},
  year={2016}
}

BibLaTeXを論文投稿サイトarXivは連携があるので，そちらを使います．
arXiv内の論文のページに飛び，右カラムの一番下にある Export Bibtex Citation をクリックし，中身をコピーします．自動でarXivへリンクしてくれるなどの機能があります．

reference.bib
@misc{oord2016wavenet,
      title={WaveNet: A Generative Model for Raw Audio}, 
      author={Aaron van den Oord and Sander Dieleman and Heiga Zen and Karen Simonyan and Oriol Vinyals and Alex Graves and Nal Kalchbrenner and Andrew Senior and Koray Kavukcuoglu},
      year={2016},
      eprint={1609.03499},
      archivePrefix={arXiv},
      primaryClass={cs.SD}
}

Webページを引用する場合は，BibTeX entry from URL - Chrome ウェブストア[27]というChrome拡張を使用すると便利です．
ただし，urldataの属性を書き換えないといけないことがあります(MM/DD/YYYY -> YYYY-MM-DD)．

reference.bib
@online{Google26:online,
author = {},
title = {Google},
url = {https://www.google.com/webhp?hl=ja&sa=X&ved=0ahUKEwiYjJLj6K_1AhXRad4KHSStCH8QPAgI},
month = {},
year = {},
urldate = {2022-01-14}
}

[28][29][30]

画像を挿入

画像を挿入したい場合は，プリアンブルでgraphicxパッケージを読み込む必要があります．
現代においては，PNG画像を使用すれば問題ないでしょう．

main.tex
\usepackage{graphicx}

もっとも一般的であろう使用方法は以下の通りです．

01overall/02conclusion.tex
\begin{figure}
    \centering
    \includegraphics[scale=0.4]{image/cat_1.png}
    \caption{猫の画像}
    \label{fig:cat}
\end{figure}

figure環境の中でincludegraphics命令を呼び出します．オプションのscaleで画像の比率を保ったまま大きさを変更します．centeringは画像の中央揃えです．正しくラベルを貼るために，caption -> label の順番で命令を呼び出してください[31]．

執筆フロー

執筆フローについて簡単に解説します．

初回に行うこと

  1. Docker 等の環境構築
  2. リポジトリ作成(テンプレート使用)
  3. リポジトリをクローン

執筆開始時に行うこと

  1. VSCode でリポジトリを開く
  2. main から別のブランチを切る (chapter ごとが望ましい)
git switch -c draft/abstract

執筆時に行うこと

  1. VSCode でリポジトリを開く
  2. 執筆する
  3. 適度にコミットする
  4. 手元で TextLint を使用する(できれば)
docker compose up linter
  1. レビューできる状態になったら，手元で PDF を作成する
docker compose up pdf
  1. GitHub 上に送信する．(プッシュ)
  2. Pull Request を作成する
  3. レビューを受ける
  4. レビューされたものを更新する
  5. main ブランチにマージする

たまにやること

  1. Tag をうち，GitHub 上に送信する

レビュー

執筆フローでレビューについて出てきましたが，少し細かく紹介します．
レビューをする/されるときに大切なのが，レビュー項目を事前に共有しておくことです．感覚のズレを少なくできます．今回は，Textlint を導入していますが，軽微な日本語の誤りなどは，事前にセルフレビューを行い，レビュアーの負担を減らしましょう．また，レビューで大幅な修正があったとしても，否定されてるなどとは思わずに真摯に受け止めましょう．レビューは成果物をより良くするための作業です．

レビューをお願いするとき

Pull Requests という画面に移動し，画面右側のReviewersのところに，レビューしてほしい人の名前を入力します．複数人指定することができます．指定することを assign といいます．

assign されると以下のようになります．

レビューをするとき

Pull Request の画面に移動します．次に，Files changed をクリックします．そうするとその Pull Request で更新されたファイルが見れます．以下のように，+が増えた分で，-が減った分です．

+ aaa
- bbb

特に問題がなく，Okという場合は，チェックボックスのComment を Approve にしてコメントを書き込み，Submit review を押します．

修正する必要がある場合は，Comment を Reqeust changes とします．コメントには，修正するべき問題を書き込みます．これは，タブを Files changed から Conversation にすると見ることができます．レビュアーは，他に修正する箇所がない場合は，もう一度Review changes を押し， Reqeust changes を Approve にしましょう．

軽微な修正箇所に対しては，以下のようにするのが楽です[32]．

  1. 修正したい箇所をドラッグ・アンド・ドロップする
  2. 左にある青い+を押す

  1. 提案する修正内容を書き込みます

Preview

  1. Start a review を押す

  1. 内容に問題がなければ，執筆者がCommit suggestion を押し，変更をコミットする

おわりに

ほとんど身内向けの資料ですが，誰かの役に立てば幸いです．
みなさんも，もっと楽をして LaTeX を書いてみませんか．

脚注

  1. t4t5u0/latex2e-textlint-sample ↩︎

  2. しましまＰ=͟͟͞͞( ╹ω╹)🌲 さんは Twitter を使っています 「自分の修論を発掘してたらバージョン管理が雑すぎて笑ってしまった https://t.co/yil7weEkOo」 / Twitter ↩︎

  3. Git for Windows ↩︎

  4. Download and install Git with winget ↩︎

  5. Git - Downloading Package ↩︎

  6. Git Guides - install git ↩︎

  7. GitHub ↩︎

  8. GitHub アカウントへの新しい SSH キーの追加 - GitHub Docs ↩︎

  9. WSL のインストール | Microsoft Docs ↩︎

  10. Windows に Docker Desktop をインストール — Docker-docs-ja 19.03 ドキュメント ↩︎

  11. Download and install Docker Desktop with winget ↩︎

  12. Mac に Docker Desktop をインストール — Docker-docs-ja 19.03 ドキュメント ↩︎

  13. Docker のインストール — Docker-docs-ja 1.12.RC ドキュメント ↩︎

  14. Download Visual Studio Code - Mac, Linux, Windows ↩︎

  15. Japanese Language Pack for Visual Studio Code ↩︎

  16. LaTeX Workshop ↩︎

  17. vscode-textlint ↩︎

  18. Part 1：概要説明とセットアップ — Docker-docs-ja 20.10 ドキュメント ↩︎

  19. LuaTeX - TeX Wiki ↩︎

  20. upTeX,upLaTeX - TeX Wiki ↩︎ ↩︎

  21. aruneko/texlive - Docker Image | Docker Hub ↩︎

  22. LaTex のコンパイルを Latexmk に統一する - Qiita ↩︎

  23. textlint/textlint: The pluggable natural language linter for text and markdown. ↩︎

  24. zenn-cli + reviewdog + textlint + GitHub Actions で執筆体験を最高にする ↩︎

  25. Git - タグ ↩︎

  26. GitHub Actions で TeX をコンパイルして PDF を Releases にアップロードする ↩︎

  27. BibTeX entry from URL - Chrome ウェブストア ↩︎

  28. BibTeXからBibLaTeXへ乗り換える(物理屋編) - fock’s blog ↩︎

  29. BibLaTeXで節や章ごとの参考文献 - Qiita ↩︎

  30. BibLaTeX+Biberの始め方 | tm23forest.com ↩︎

  31. リンク: \labelと\refが対応しない！ - 学習する機械、学習しない人間 Next Generation ↩︎

  32. [GitHub] Multi-line code suggestions でコード提案機能が便利になりました | DevelopersIO ↩︎

Discussion