ビルドツール（latexmk / llmk / arara）

「LaTeX をインストールした」と言うとき、実際にディスクへ置かれるのは一本のプログラムではなく、コマンドラインツールが詰まったディレクトリです。手元の TeX Live 2024 では、その bin ディレクトリに 490 個近いコマンドが並んでいます。ふだん原稿を書いているあいだに打つのは、そのうち一つか二つ。残りの四百数十本は、文書が言うことを聞かなくなった日のためにディストリビューションが抱えている予備です——パッケージが実際にどこにあるのかを訊く kpsewhich、その説明書を開く texdoc、足りないものを入れる tlmgr、図版の余白を落とす pdfcrop。このページは、その予備を「どんな疑問に答えてくれるか」で並べ直した地図です。上に乗るビルドドライバ（latexmk・llmk・arara）には別のページがあるので、ここではその一段下の層を扱います。

「自分の環境では通るのに」——そのとき最初に打つのが kpsewhich

同じ .tex が自分の機械では通り、共著者の機械では止まる。この症状のほぼすべてはファイルの在りかの問題で、それを一行で確かめられるのが kpsewhich です。このコマンドが偉いのは、独自に探しているのではないところにあります。TeX Live 2024 のエンジンはどれも kpathsea（この版では kpathsea 6.4.0）というファイル検索ライブラリにリンクされていて、kpsewhich はそのライブラリをそのまま単体コマンドにしたもの。つまり返ってくるパスは「エンジンが実際に開くファイル」そのもので、推測ではありません。kpsewhich amsmath.sty が何も表示せずに終わったら、そのパッケージはこの環境に存在せず、コンパイルすれば ! LaTeX Error: File amsmath.sty not found. が出ます。逆に何かを表示したなら、問題は「無い」ことではなく「別のものが見えている」ことです。

kpsewhich amsmath.sty
# /usr/local/texlive/2024/texmf-dist/tex/latex/amsmath/amsmath.sty

kpsewhich article.cls          # classes are found the same way
kpsewhich --all texmf.cnf      # every match, in search order
kpsewhich --progname=xelatex --format=tfm cmr10.tfm

--all を付けると、最初の一致だけでなく 見つかったすべて が探索順に並びます。ここが「無い」より厄介な事故の見つけどころです。TeX は最初に見つけたものを使うので、原稿フォルダに何年か前にコピーした古い .sty が転がっていると、それが配布物の新しい版を覆い隠します。ログには何の異常も出ず、ただ挙動だけが機械ごとに変わる。kpsewhich --all を一度打てば、同じ名前が二つ出てくる形で目に見えます。なお kpsewhich は .sty 専用ではなく、クラス（article.cls）、フォントメトリック、設定ファイルまで同じ仕組みで探します。エンジンごとに探索先が違う場合は --progname=xelatex のように名乗りを変えて訊けますし、--format=tfm のようにファイル種別を明示すると絞り込めます（種別の一覧は kpsewhich --help-formats）。

--var-value と --show-path — エンジンが信じている設定を読み出す

kpsewhich --var-value=TEXMFHOME は設定変数を一つだけ、kpsewhich --show-path=tex は .tex を探すディレクトリの並びを丸ごと印字します。前者が「どこ」、後者が「どの順で」に答えるわけです。この二つを覚えると、ドキュメントに載っている一般論ではなく、いま目の前の環境が実際に採用している値を確かめられます。とりわけ有用なのが下の四つで、TeX の探索木は個人用・サイト用・配布物・生成物という役割で分かれています。順序も意味を持ち、個人の木が配布物より先に来るからこそ、自作の .sty で標準のものを上書きできます。

kpsewhich --var-value=TEXMFHOME
# /Users/you/Library/texmf

kpsewhich --show-path=tex      # the whole ordered search list
kpsewhich --expand-var='$TEXMFDIST/tex/latex'

自作の .sty はどこに置くのか——個人用 texmf ツリー

自分で書いた .sty や .cls、CTAN から手で落としたパッケージは TEXMFHOME に置きます。場所を推測せず kpsewhich --var-value=TEXMFHOME に訊いてください——macOS の MacTeX では ~/Library/texmf が返り、Linux の TeX Live では ~/texmf が返るのが通例で、環境ごとに違います。ここで一つ落とし穴があります。このディレクトリは、たいてい最初は存在しません。 kpsewhich は「設定された場所」を答えるのであって「実在する場所」を答えるわけではないからです。返ってきたパスを自分で作るところから始めます。中の構造は TDS（TeX Directory Structure）に従い、LaTeX パッケージなら TEXMFHOME/tex/latex/<名前>/<名前>.sty に置きます。

mkdir -p "$(kpsewhich --var-value=TEXMFHOME)/tex/latex/mystyle"
cp mystyle.sty "$(kpsewhich --var-value=TEXMFHOME)/tex/latex/mystyle/"
kpsewhich mystyle.sty          # found immediately, no texhash needed

texhash と mktexlsr — 名前が二つある同じプログラム

texhash と mktexlsr は同じことをします——というより、同じファイルです。TeX Live 2024 の bin ディレクトリを覗くと、texhash は mktexlsr への symlink になっています。どちらも ls-R という「ファイル名データベース」を作り直すコマンドです。配布物の木は巨大で、この環境の texmf-dist/ls-R はそれだけで 5 MB 以上あります。毎回ディスクを歩き回っていては遅すぎるので、システム側の木では ls-R を引くだけで済ませ、代わりに ファイルを足したらデータベースを作り直す という約束になっています。だから TEXMFLOCAL に何かを置いたのに見つからないときの答えは sudo mktexlsr です。逆に前節の TEXMFHOME は毎回ディスクを見に行くので、置いた .sty はコマンドを打たなくてもその場で見つかります——実際に作って kpsewhich に訊けば、texhash を一度も走らせずに答えが返ります。個人用の木を勧める理由の一つがこれです。

texdoc — パッケージの説明書はすでに手元にある

texdoc geometry と打つと、geometry パッケージの PDF マニュアルがビューアで開きます。ネットワークは要りません——CTAN からパッケージが届いたとき、説明書も一緒に入っているからです。検索エンジンでたどり着く古い解説より、いま入っている版そのものの説明書のほうが正確、というのがこのコマンドの値打ちです。同じ名前の文書が複数あることもあるので、迷ったら texdoc -l geometry で候補を一覧にします。この環境では英語版 geometry.pdf のほかにドイツ語版 geometry-de.pdf も出てきます。-s（showall）を付けると関連の薄いものまで含めて拾い、-M を付けると機械可読な一覧になります。TeX Live 2024 に入っているのは Texdoc 4.1（2024-03-10）で、著作権表示には Manuel Pégourié-Gonnard、Takuto Asakura、TeX Live Team の名が並びます。

texdoc geometry            # open the manual
texdoc -l geometry         # list every candidate first
texdoc texdoc              # the manual for texdoc itself

tlmgr install / update / info と「TeX Live 2024 is frozen」の意味

tlmgr は TeX Live のパッケージマネージャで、日常的に使うのは三つです。tlmgr info NAME でそのパッケージについて訊き、tlmgr install NAME で入れ、tlmgr update --self --all で全体を最新にします。info の出力がとりわけ実用的で、installed: Yes で導入済みかどうか、revision: でどの版か、collection: でどのまとまりに属するかが一望できます。ここで一つ、知らないと時間を溶かす事実があります。コマンド名と TeX Live のパッケージ名は一致しないことがある。 たとえば tlmgr info llmk は tlmgr: cannot find package llmk と返しますが、そのまま説明文とファイル名を検索し直して light-latex-make を提示してくれます。llmk というコマンドは、その名前のパッケージに入っているわけではないのです。

tlmgr info amsmath             # installed? which revision? which collection?
sudo tlmgr install siunitx     # a system-wide tree needs root
sudo tlmgr update --self --all
tlmgr --version                # also prints which installation is in use

もう一つ、初見でぎょっとするのが凍結の通知です。TeX Live 2024 上で tlmgr を叩くと、多くのコマンドがまず TeX Live 2024 is frozen と and will no longer be routinely updated. を表示します。これは エラーではなく告知 です。新しい年度版が出たあと、前の年度のリポジトリは定常的な更新を止める——という TeX Live の運用そのものを伝えているだけで、コマンド自体はその下で普通に走ります（tlmgr info amsmath は banner のあとにきちんと情報を返します）。したがって対処は「再実行する」ではなく「新しい年度版を入れる」です。加えて MacTeX などの標準的な導入では /usr/local/texlive/2024/texmf-dist の所有者が root なので、tlmgr install や tlmgr update には sudo が要ります。管理者権限が無い機械では、この節ではなく前節の TEXMFHOME に手で置くほうが早いこともあります。

pdfcrop — 図版 PDF の白い余白を落とす

pdfcrop figure.pdf を実行すると、ページごとに余白を計算して切り落とした figure-crop.pdf が出力されます。使いどころは、TikZ の図を別ファイルで作ったときや、他のソフトから「A4 の真ん中に小さな図」という形で PDF が出てきたときです。そのまま \includegraphics すると、図ではなく紙を貼り込むことになります。余白をあえて少し残したいときは --margins "5 5 5 5" のように四辺を指定でき、単位は bp（big point）です。落とし穴は依存関係で、pdfcrop は自分では切りません——既定で Ghostscript（gs、--gscmd で変更可）と TeX エンジンを呼び出します。pdfcrop は入っているのに動かない、という報告のほとんどは Ghostscript が無いことが原因です。TeX Live 2024 同梱版は pdfcrop 1.42（2023/04/15、Heiko Oberdiek 作）です。

pdfcrop figure.pdf                       # -> figure-crop.pdf
pdfcrop --margins "5 5 5 5" figure.pdf   # keep 5bp on every side
pdfcrop --luatex figure.pdf              # drive lualatex instead of pdftex

完成した PDF の中身を見る——pdftotext は TeX のコマンドではない

出来上がった PDF からテキストを抜き出したいとき、多くの解説が pdftotext を挙げます。ただし pdftotext は TeX Live の一部ではありません。 TeX Live 2024 の bin ディレクトリを端から端まで見ても入っておらず、この Mac にあるものは Homebrew の poppler が置いたものです。同じことは pdfinfo にも当てはまります。使うのは構いませんが、「TeX が入っているのに pdftotext: command not found になる」のは故障ではなく、そもそも別のソフトウェアだからです。TeX Live 側にあるのは pdftosrc で、pdftosrc <PDF-file> [<stream-object-number>] という書式どおり、PDF の中のストリームオブジェクトを取り出す道具です。日常の点検では、まず PDF の見た目より .log を読むほうが早く、ログを要約する texfot や PDF を扱う Ghostscript、dvisvgm といった周辺ツールは別ページに整理してあります。

症状からコマンドを引く

身につけておく価値があるのは、順序の習慣です。何かがおかしいと思ったら、誰かに訊く前に kpsewhich で在りかを、texdoc で仕様を確かめる——この二つはネットワークも管理者権限も要らず、数秒で答えます。そこで足りないと分かってはじめて tlmgr に手を伸ばし、置き場所に迷ったら TEXMFHOME を選ぶ。ビルドの回数やタイミングを自動化する層（latexmk など）と、この「探す・読む・入れる」の層は別物で、後者が固まっていない限り、前者をいくら整えても環境ごとの食い違いは消えません。