LuaTeX(LuaLaTeX)/XeTeX(XeLaTeX) + BXjscls/LuaLaTeX-ja + Latexmk/ClutTeX + BibLaTeX + LaTeX Workshop + Git + pre-commit + GitHub

LuaTeX/LuaLaTeX/XeTeX/XeLaTeX + BXjscls/LuaTeX-ja + Latexmk/ClutTeX + BibLaTeX + LaTeX Workshop + Git + pre-commit + GitHub

1. LuaTeX/LuaLaTeX/XeTeX/XeLaTeXはぴーでぃーえふのコンパイルに使うエンジンだにょ。
2. BXjscls/LuaTeX-jaは日本語を表示するための文章クラスだにょ。
3. Latexmk/ClutTeXはコンパイルのためのコマンドを必要なだけ呼び出すためのツールだにょ。
4. BibLaTeXは参考文献を管理するためのパッケージだにょ。
5. LaTeX WorkshopはVS CodeでLaTeXをべんりに使えるVS Code拡張機能だにょ。
6. Gitは編集履歴をよさげに管理してくれるソフトウェアだにょ。
7. pre-commitはGitで履歴を付ける前にフォーマットしてくれるソフトだにょ。
8. GitHubはいろいろべんりなGitのリモートだにょ！

エンジンはどれを使うにょ？

LuaTeX vs XeTeX vs upLaTeX vs pLaTeX vs pdfTeX ?

• ”XeTeX か LuaTeX の二択”¹という説があるにょ。

詳細

• upLaTeXとpLaTeX以外では、日本語文章用のパッケージを別途使うようです。LuaTeX-jaはLuaTeX使用時によく用いられ、ltjs~等の文章クラスも提供している。BXjsclsはこのような日本語文章用のパッケージを自動的に読み込む文章クラスのパッケージであり、上で挙げた5つに全て対応している。²
• upLaTeXとpLaTeXはGitHubで管理されているようだが、最終コミット日時はそれぞれ2022/7/14, 2023/2/15であった。一方で、LuaTeX-jaパッケージの最終更新時は2023/10/10であったが、GitHubで管理されていない。BXjsclsはGitHubで管理されており、最終コミット日時は2023/8/6であった。
• TeX処理系御伽話 #LaTeX - Qiita
• XeLaTeXで日本語文章を書く例
• 日本語 LaTeX の新常識 2021 #LaTeX - Qiita
• システム情報科学コース 実験と演習

すでに優れたテンプレートはあるのかにょ？

LaTeXに"テンプレート"という概念があるので、検索するのがとても難しいにょ。

詳細

但し、"latex+latexmk+pre-commit"などで検索するとほとんど結果が出ないため、上記の要求を満たし、かつ絶対的に優れているテンプレートがあるとは言えないと思われます。 ノートを全てLaTeXで取ったLaTeX and Vimは英語圏で有名だと思います。shenapse/template-texlive-docker-vscode、eed6d80434107db92f2276b9c4e5a799ce064cdeも見つけました。

ビルドツールはどれを使うにょ？

Latexmk vs llmk vs ClutTeX vs arara vs ptex2pdf

中間ファイルを別の場所に置いてくれるClutTeXを使うにょ！特に設定はいらないにょ。これでファイルがすっきりするにょ。

ClutTeXに乗り換えるにあたって中間ファイルを消すにはどうするにょ？

git cleanを使うにょ。 まず

git clean -x -n

でなくなったらこまるファイルが消されないか確かめるにょ。大丈夫なら

git clean -x -f

で消すにょ。

詳細

ptex2pdfは3年ほど更新がないようです。 LaTeX Workshopを使ってしまうと、エディターに対する依存性が高まってしまうと思います。

Latexmkをどうしても使いたいにょ……？

.latexmkrcの設定

./.latexmkrc

#!/usr/bin/env perl
$lualatex    = 'lualatex -shell-escape -synctex=1 -interaction=nonstopmode';
$pdflualatex = $lualatex;
$biber       = 'biber %O --bblencoding=utf8 -u -U --output_safechars %B';
$bibtex      = 'bibtex %O %B';
$makeindex   = 'mendex %O -o %D %S';
$pdf_mode    = 4;
$max_repeat  = 5;
$pvc_view_file_via_temporary = 0;

# use default previewer
if ( $^O eq 'MSWin32' ) {
    $pdf_previewer = 'start';
}
elsif ( $^O eq 'darwin' ) {
    $pdf_previewer = 'open';
}
else {
    $pdf_previewer = 'evince';
}

使うTeXの種類によって$pdf_mode等を変更する必要があります。ここではLuaTeX+Biber+makeindexにおける例を挙げます。BibLaTeXのバックエンドにはBiber, BibTeX, bibtex8があるようですが、普通はBiberを使うようです。 参考

• 続くといいな日記 – upLaTeX から LuaTeX に移行する
• latexmkrcメモ #LaTeX - Qiita

サブディレクトリにある.texファイルをコンパイルする場合、LaTeX Workshopはそのディレクトリからコマンドを呼び出すため、.latexmkrcもそのディレクトリに置くか、または引数に.latexmkrcのファイルパスを指定する必要があります。

{
  "latex-workshop.latex.recipes": [
    {
      "name": "latexmk",
      "tools": ["latexmk"]
    }
  ],
  "latex-workshop.latex.tools": [
    {
      "name": "latexmk",
      "command": "latexmk",
      "args": [
        "-r",
        "%WORKSPACE_FOLDER%/.latexmkrc",
        "-outdir=%OUTDIR%",
        "%DOC%"
      ],
      "env": {}
    }
  ],
  "editor.wordWrap": "on",
  "latex-workshop.latex.autoBuild.cleanAndRetry.enabled": false
}

.latexmkrcが適切に読み込まれていない場合、LaTex Compilerの出力を見ると、-interaction=nonstopmodeが指定されていないために途中で止まっているかもしれません。その場合は、LaTeX WorkshopのウィンドウからTerminate current compilationを押します。

ClutTeXやLatexmkをLaTeX Workshopと一緒に使うために.vscode/settings.jsonを作るにょ！

{
  "latex-workshop.latex.recipes": [
    {
      "name": "cluttex",
      "tools": ["cluttex"]
    },
    {
      "name": "latexmk",
      "tools": ["latexmk"]
    }
  ],
  "$comment": "LaTeX Workshop calls commands from the directory of the main tex file, not the root of the project. See https://github.com/James-Yu/LaTeX-Workshop/wiki/Compile#placeholders for more info.",
  "latex-workshop.latex.tools": [
    {
      "name": "cluttex",
      "command": "cluttex",
      "args": ["--engine=xelatex", "--biber", "%DOC%"],
      "env": {}
    },
    {
      "name": "latexmk",
      "command": "latexmk",
      "args": [
        "-r",
        "%WORKSPACE_FOLDER%/.latexmkrc",
        "-outdir=%OUTDIR%",
        "%DOC%"
      ],
      "env": {}
    }
  ],
  "editor.wordWrap": "on",
  "latex-workshop.latex.autoBuild.cleanAndRetry.enabled": false,
  "latex-workshop.latex.autoBuild.run": "onSave"
}

pre-commitはどのフックを使うにょ？

• .texのフォーマットには、まずlatexindentをつかうにょ！LaTeX Workshopのデフォにょ。
• .texのフォーマットにpre-commit-latex-hooksも使うにょ。
• .texのリントにはchktexとlacheckをつかうらしいにょ。³
• .bibのフォーマットにはbibtex-tidyをつかうにょ！

latexindentと.latexindent.yamlの設定

素直にコピペするにょ！（view rawからまず開くにょ！）

詳細

これは本当に難しいようなので、素直に専門家に頼る。 但し、ファイルはprettierにyamlとして認識されないため、コメントを除去する必要がある。そこまでして使う価値があるかは、筆者には判断しかねる。 オプションは以下を参照した。

• latexindentの実践的な使い方&設定例
• 5. defaultSettings.yaml — latexindent.pl 3.23.4 documentation

.bibのフォーマットはLaTeX Workshopに直接実装されているため、pre-commitと同時に使いにくいし、こちらもあまり特定のエディターに依存したくない。 あまりメンテナンスされているフォーマッタは無いが、bibtex-tidyが一番まともだと思われる。但し、v1.9.0より後ではpre-commitのargsが正常に動作しないという不具合が現時点で解決されていない。

.latexmkrcはPerlファイルであるため、やり過ぎ感はあるが、一応フォーマットする。Perlのインストールが必要。Strawberry PerlとActivePerlがあるが、段々と前者が主流になっている模様。⁴

winget install -e --id StrawberryPerl.StrawberryPerl

- repo: https://github.com/henryykt/pre-commit-perl
  rev: v0.0.5
  hooks:
    - id: perltidy
      files: ".latexmkrc"

pre-commit-latex-hooksは"pre-commit latex"等で検索すると最も上に出てくる。Rustのインストールが必要。

Rustをインストールしておくにょ。

winget install -e --id Rustlang.Rustup

pre-commit-config.yaml

# See https://pre-commit.com for more information
# See https://pre-commit.com/hooks.html for more hooks
exclude: "CHANGELOG.md|.copier-answers.yml"
default_stages: [commit]

ci:
  autofix_commit_msg: "chore(pre-commit.ci): auto fixes"
  autoupdate_commit_msg: "chore(pre-commit.ci): pre-commit autoupdate"

repos:
  - repo: https://github.com/commitizen-tools/commitizen
    rev: v3.2.2
    hooks:
      - id: commitizen
        stages: [commit-msg]
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: check-added-large-files
      - id: check-builtin-literals
      - id: check-case-conflict
      - id: check-docstring-first
      - id: check-merge-conflict
      - id: check-json
      - id: check-toml
      - id: check-xml
      - id: check-yaml
      - id: detect-private-key
      # - id: end-of-file-fixer
      # - id: trailing-whitespace
  - repo: https://github.com/pre-commit/mirrors-prettier
    rev: v2.7.1
    hooks:
      - id: prettier
        args: ["--tab-width", "2"]
  - repo: https://github.com/jonasbb/pre-commit-latex-hooks
    rev: v1.4.0
    hooks:
      - id: american-eg-ie
      - id: cleveref-capitalization
      - id: csquotes
      - id: ensure-labels-for-sections
      - id: no-space-in-cite
      - id: tilde-cite
        # args:
        #     [
        #       # If present only check that there is a \label{} but not the value
        #       "--ignore-label-content",
        #     ]
      - id: cleveref-instead-of-autoref
  - repo: https://github.com/cmhughes/latexindent.pl.git
    rev: V3.23.4
    hooks:
      # - id: latexindent
      # - id: latexindent-conda
      - id: latexindent-docker
        args:
          - --overwriteIfDifferent
          - --replacement
          - --local
          - --modifylinebreaks
          - --silent
  - repo: https://github.com/FlamingTempura/bibtex-tidy
    rev: v1.9.0
    hooks:
      - id: bibtex-tidy
        args: [--no-align]

GitHub Actionsでコンパイルするにょ！

コンパイルにもcluttexを使うにょ！Dockerの起動に2分ぐらいかかるからprivateリポジトリの場合残り時間に気をつけるにょ。1日60分ぐらい使えるから、10回/日ぐらいが無難にょ。

.github\workflows\build.yaml

name: Build LaTeX document
on:
  push:
    branches:
      - main
  pull_request:
  workflow_dispatch:
jobs:
  build_latex:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Git repository
        uses: actions/checkout@v4
      # doesn't support cluttex, for latexmk
      #   - name: Compile LaTeX document
      #     uses: xu-cheng/latex-action@v3
      #     with:
      #       root_file: "**/*.tex"
      #       latexmk_use_xelatex: true
      - name: Compile LaTeX document
        uses: xu-cheng/texlive-action@v2
        with:
          scheme: full
          # runs on docker image
          # clutex: https://github.com/minoki/cluttex
          # non-paralleled version:
          # find . -name "*.tex" -exec sh -c 'cd $(dirname {}) && cluttex --no-halt-on-error --no-file-line-error -e xelatex $(basename {})' \;
          run: |
            apk add parallel
            find . -name "*.tex" | parallel "cd $(dirname {}) && cluttex --no-halt-on-error --no-file-line-error -e xelatex $(basename {})"
      - name: Upload PDF file
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: PDF
          path: "**/*.pdf"
      - name: Set up Git user
        uses: fregante/setup-git-user@v2
      - name: Create Release
        run: |
          # specifing filenames in `gh release create` didn't work
          gh release create v${{ github.run_number }} --title "Release v${{ github.run_number }}" --notes "Release v${{ github.run_number }}"
          find . -name "*.pdf" -type f -exec gh release upload v${{ github.run_number }} {} --clobber \;
        env:
          GITHUB_TOKEN: ${{ secrets.GH_PAT }}

ちなみにcluttexはデフォルトで--halt-on-error --file-line-errorとなっているから気をつけるにょ。GNU Parallelで高速化してるにょ。actions/cacheでもっと速くなると思うにょ。Latexmkを使うときはlatex-actionをそのまま使うといいにょ。

マルチカーソルを使いこなすにょ！

Ctrl+Dで次の同じワードにも同時にカーソルをおけるにょ。\begin{...}...\end{...}の...の中身を変えるのに使えるにょ。ドキュメントを読むにょ！

サジェストとスニペットを使いこなすにょ！

特にこだわりがなければとりあえずLaTeX WorkshopのWikiにあるスニペット(例:BEQ→\begin{equation}...\end{equation})とサジェスト(例:@a→α, @/→\frac{}{})の説明を読むにょ！

さらなる高みを目指すなら下のファイルも使うなり改造するなりするにょ。

.vscode/latex.code-snippets

人によってdfn,Def,defi,definitionなど定理環境の派閥の違いがあることを考えると(GitHubで調べると面白いにょ！)、自動生成するのもありにょ。

from pathlib import Path
import json


theorems = "axiom,defi,thm,prop,lemma,cor,ex,exer".split(",")
envs = "figure,proof,equation,align,alignat,gather,multiline,split,aligned,alignedat,gathered,lgathered,rgathered,multilined,cases".split(",")

def make_item(prefix: str, env: str) -> tuple[str, dict[str, list[str]]]:
    return f"begin/end {env}", {
		"prefix": [
			prefix,
		],
		"body": [
			"\\begin{" + env + "}",
            "\t$TM_SELECTED_TEXT$0",
			"\\end{" + env + "}",
		]
	}

d = dict(make_item(env, env) for env in envs + theorems)
d.update(dict([make_item("begin", "${1:env}")]))
Path("latex.code-snippets").write_text(json.dumps(d, indent=4))

複雑なスニペットで長いコマンドをすぐに書けるようにするよりも\NewDocumentCommandや\DeclareDocumentCommandでコマンドを定義したほうが良いかもしれないにょ。そーゆう意味で下のHyperSnips用のファイルはいらないかもしれないにょ。

.vscode/latex.hsnips

---

1. [TeX処理系御伽話 #LaTeX - Qiita](https://qiita.com/yyu/items/↩

2. BXjscls - TeX Wiki↩

3. shenapse/template-texlive-docker-vscode、eed6d80434107db92f2276b9c4e5a799ce064cde↩

4. (5) Strawberry vs ActiveState - Which is right for me? : perl↩