TeX 文書の Magic Comment

この記事では、 TeX 文書におけるマジックコメントの種類と構文についてまとめてみた。

マジックコメントとは

プログラムのソースコードというのは、プログラミング言語の処理系（実行環境）向けに書かれているものである。しかし、テキストエディターなどの周辺ツールは、そのソースコードについて、処理系が必要とする以上の情報が欲しいことがある。そういう場合に、追加の情報をソースコードのコメントとして記述してやって、周辺ツールに与えてやるということがよく行われる。このようなコメントは、俗に、マジックコメントと呼ばれる。

「追加の情報」の中で典型的なものが、文字コードである。Emacs で編集されるソースコードに -*- coding: utf-8 -*- と書かれたコメントがあるのを見たことがある方も多いだろう。

（ちなみに、 Python や Ruby などの一部のスクリプト言語処理系は、マジックコメントによってファイルの文字コードを判定する場合がある。つまり、コメントとして書かれたものが処理系にとってい意味を持つ。）

TeX 文書におけるマジックコメントの用途

TeX 文書の場合、マジックコメントの用途はいくつか考えられる。

用途その1：処理系やコマンドの指定

現在使われている TeX エンジンには、 pdfTeX, XeTeX, LuaTeX, および日本語用の (u)pTeX など、いくつかの種類が存在し、しかも、機能や特性がそれぞれ異なっている。選択肢は多いが、ユーザーが通常使うのは文書ごとに1種類だろう。

コマンドラインからタイプセットするユーザーなら、使いたい処理系に応じて実行するコマンド名を変えるだけだ。しかし、統合環境で「ボタン一発でタイプセット」する場合は、なんらかの方法で統合環境が処理系を判断する必要がある。「なんらかの方法」は、具体的には、ソースコードを見て使う処理系を判断するとか、統合環境の環境設定で指定されたデフォルト値を使うとか、そういうのだ。前者の場合、 LaTeX には、処理系を指定する専用の文法はないので、統合環境ごとに独自のマジックコメントを使うことになる。

（普通にプログラミングをする際はプロジェクトを作ってそこでコンパイル方法等を設定するので、こういう問題は起こらない）

ちなみに、日本語の文書ならドキュメントクラスやプリアンブルの記述によって処理系（pTeX vs. upTeX vs. LuaTeX-ja vs. XeTeX）がほぼ確定するが、実際にそれをやっている統合環境というのは筆者は聞いたことがない。（この話については別の記事で書くことにする）

用途その2：ファイルを分割した際のメインファイル

「ボタン一発でタイプセット」する際に問題になるのは処理系だけではない。

文書のソースコードを複数のファイルに分割する際、サブファイルは単体でタイプセットできないことが多い。サブファイルに対して「タイプセット」ボタンを押した際は、サブファイルではなくメインファイルの方を処理して欲しい。

（ちなみに、 LaTeX/Modular Documents – Wikibooks, open books for an open world には、サブファイルを単体でタイプセットできるようにする方法が書かれている）

用途その3：文字コード

ぶっちゃけ今は2016年だし、全部 UTF-8 でいいじゃんという気はするが…。

文字コードの情報は、例えば Emacs だと -*- coding: utf-8 -*- みたいな感じで指定する。Emacs を使う場合はもちろんこのような文字コード指定が使える。

しかし、エディターが違えばマジックコメントも違うのが一般的なので、TeX 専用の統合環境についてはそれぞれマジックコメントの構文を調べなくてはならない。

ちなみに、LaTeX には inputenc パッケージというものがあって、オプションとして欧文の8ビット文字コードや utf8 などの文字コードを指定できる（欧文用である）。TeX 向け統合環境の一つである TeXstudio は、 \usepackage[utf8]{inputenc} というような記述を考慮してくれるようである。

TeXShop 系 (TeXworks 含む) の場合

TeXShop, TeXworks, TeXstudio などでは、ある程度共通したマジックコメントが使える。 % !TEX で始まるものが多い。

これらのマジックコメントについては、この Stack Exchange に色々まとまっている：

compiling – When and why should I use % !TEX TS-program and % !TEX encoding? – TeX – LaTeX Stack Exchange

さて、マジックコメントの正確な文法を知りたければ、ソースファイルを参照するのが一番早い：

TeXShop: TSDocument.m, TSDocument-Jobs.m, TSDocument-RootFile.m 他
TeXworks: TeXDocument.cpp
TeXstudio: latexdocument.cpp

というわけで TeXShop のソースコードを読んでみた。TeXShop では、以下のような文字列の完全一致で探している。それぞれ、最初にマッチしたものが拾われる。

処理系の指定
- “% !TEX TS-program =“
- “%!TEX TS-program =“
- “% !TEX program =“
- “%!TEX program =“
処理系の指定（BibTeX?）
- “% !BIB TS-program =“
- “%!BIB TS-program =“
- “% !BIB program =“
- “%!BIB program =“
メインファイルの指定
- “%!TEX root =“
- “% !TEX root =“
文字コード
- “%!TEX encoding =“
- “% !TEX encoding =“
スペルチェック（？）
- “%!TEX spellcheck =“
- “% !TEX spellcheck =“

イコール = の後は行末まで読んで、前後の空白を削ぎ落としている。

一方、 TeXworks や TeXstudio は正規表現を使っていて、空白の個数の違いや大文字・小文字の違いにもう少し寛容である。

ちなみに、 TS-program には、統合環境に登録された「名前」を指定する。実行するコマンドを直接書くのではない。TeXShop の場合は、以下の名前が組み込みで認識されるようだ：

pdftex, pdflatex, tex, latex, personaltex, personallatex, bibtex, makeindex, metapost, context

Emacs/AUCTeX の場合

Emacs のファイルローカル変数として変数を指定できる。詳しくはマニュアルを見て欲しいが、この記事として興味があるのは次の2つだ：

TeX-engine: 処理系の「名前」を指定する。default, xetex, luatex, omega が組み込みで認識される。
TeX-master: メインファイルを指定する。

Emacs のファイルローカル変数の指定の仕方については、 Emacs 本体のマニュアルを参照されたい。

Emacs/YaTeX の場合

%# 記法というのが用意されている。具体的には、 %#! と %#BEGIN〜%#END, %#LPR の3種類だ。

%#! : タイプセット時に起動するコマンドを指定する。この記号列のチョイスは、いわゆる shebang を意識したものだろうか。
%#BEGIN 〜 %#END : タイプセットする領域を指定する。
%#LPR : プリントアウトに使うコマンドを指定する。

ファイル分割時のメインファイルを指定する専用の構文はないが、 %#! にファイル名まで書くことによって同等のことができるようだ。

マジックコメント以外の方法

処理系の選択

ソースファイルと同じディレクトリに latexmkrc または .latexmkrc というファイルが存在すれば、そのディレクトリのファイルは latexmk を使って処理することを意図されている可能性が高い。その latexmkrc ファイルの中には実行すべきコマンドが書かれているので、統合環境が深いことを考える必要はない。

一方、ホームディレクトリに .latexmkrc が存在するがカレントディレクトリに存在しない場合はどうするべきか。そのユーザーは latexmk を常用していると考えて良いだろうか。それとも、もう少し慎重に判断するべきか。

メインファイルの選択

Vim-LaTeX でメインファイルを指定する場合は main.tex.latexmain という名前のファイルを置いておくらしい。当然、メインファイルはディレクトリごとに1つしか存在できない。

Latex-Suite Reference — 9 Multiple file LaTeX projects

雑記帳

人生やっていき