ドキュメントクラスとプリアンブル

1994 年 6 月 1 日、LaTeX は一つの命令を二つに割りました。それ以来、どの LaTeX 文書も同じ形で始まります——\documentclass の一行、そしてそこから続く \usepackage の並ぶ プリアンブル。それまでは \documentstyle[12pt,twoside]{article} と書き、オプションも追加スタイルも同じ角括弧に詰め込んでいました。ドキュメントクラス とパッケージを分けたのは、整理整頓の話ではありません。クラスは 文書が何であるか（論文か、報告書か、書籍か、スライドか）を決め、プリアンブルは 文書に何ができるか を決めます。この線引きが正しければ、投稿先は一行を書き換えるだけで原稿全体を組み直せます。間違えれば、本文を書くはずだった一晩が Option clash for package geometry の追跡で終わります。

\documentclass が本当に決めているもの

\documentclass[options]{class} は文書の 最初 に置かなければならない唯一の命令で、これより前に書けるのは % で始まるコメントだけです。波括弧の中がクラス名、角括弧の中がオプション。そしてその波括弧の名前は、実体のあるファイルを指しています。article と書けば article.cls という数百行の定義集が読み込まれ、そこに入っているのは規則だけです。たとえば \section の見出しは \Large\bfseries、上に 3.5ex、下に 2.3ex——この三つの数字が article.cls に literal で書かれています。本文には一文字も入っていません。

この分業は偶然の産物ではありません。1980 年代の初め、レスリー・ランポートは自分の本を書き始めたところで当時のマクロパッケージが力不足だと気づき、自分用のマクロを書くついでに、もう少し手を加えれば他人にも使えるものになると考えました。DMV-Mitteilungen 2000 年 1 月号のインタビューで、本人がそれを LaTeX の始まりだと語っています。つまりクラスとは、構造と体裁の分離 をそのままファイルの形にしたものです。本文には \section{Introduction} と意味だけを書き、それを大きな太字にして番号を振り、上に空きを取るのはクラスの仕事。学会や出版社が独自のクラスを配るのはこのためで、amsart・IEEEtran・elsarticle・revtex4-2・acmart はどれも実在し、投稿規定として指定されます。ランポート自身、1980 年代後半に ACM へ、電子投稿を速く回すために TeX/LaTeX・troff・Scribe それぞれの標準文書スタイルを作ってはどうかと提案しました——担当の編集者には断られましたが。

% Only the first line changes; the body stays as it is.
\documentclass[11pt,a4paper]{article}  % top level heading is \section
% \documentclass[11pt,a4paper]{book}   % \chapter becomes available

\begin{document}
\section{Introduction}
The source carries the structure; the class supplies the appearance.
\end{document}

article・report・book は何が違うのか

違いは実質的に二つ、章があるかどうか と 両面を前提にするかどうか です。article.cls に \chapter の定義はなく、最上位の見出しは \section。report.cls と book.cls には \chapter があります。既定値はクラスファイルの \ExecuteOptions の行にそのまま並んでいて、article は letterpaper,10pt,oneside,onecolumn,final、report はそれに openany が付き、book だけが twoside と openright です。ここで見落とされがちなのが用紙で、三つとも既定は letterpaper——A4 が欲しければ a4paper を自分で書く必要があります。タイトルの扱いも分かれ、article は本文と同じページに続き、report と book は独立したタイトルページになります。

book にはもう一段の仕掛けがあります。\frontmatter / \mainmatter / \backmatter の三つで、これらは本の慣習をほぼ一行ずつで実装しています。\frontmatter は \pagenumbering{roman} を呼んで序文や目次を小文字ローマ数字（i, ii, iii…）にし、章番号を止めます。\mainmatter は \pagenumbering{arabic} でページ番号を 1 に振り直し、章番号を再開します。\backmatter はアラビア数字のまま章番号だけを外すので、付録や索引が「第 12 章 索引」にならずに済みます。序文だけが i, ii, iii で本文が 1 から始まる本を見たことがあるはずです——あれはこの三行の帰結です。

標準の四つで足りないときは、CTAN に目的別のクラスが揃っています。発表資料なら beamer が定番で、frame 環境ひとつが一枚のスライドになり、段階的な表示（オーバーレイ）とテーマが付いてきます。標準クラスの既定タイポグラフィが古く感じるなら KOMA-Script の scrartcl / scrreprt / scrbook が article / report / book に対応し、細かな調整のためのインタフェースがはるかに充実しています。日本語組版では、pLaTeX / upLaTeX なら奥村晴彦氏らが保守する jsarticle / jsbook（jsclasses）、LuaLaTeX ならその LuaTeX-ja 版の ltjsarticle / ltjsbook、そして「日本語組版処理の要件（JLReq）」に基づく jlreq が選択肢です。jlreq はエンジンを自動判別し、report / book オプションで report 相当・book 相当に切り替わります。いずれの場合も、エンジンとクラスが噛み合っているか が最初の分岐点です。

\documentclass のオプションは何を意味するのか

オプションは角括弧の中にカンマ区切りで並べる、文書全体のスイッチです。\documentclass[11pt,a4paper,twoside]{article} のように書きます。順序は問われず、同じ系統のオプション（oneside と twoside など）を両方書けば後勝ちになります。実務でよく使うのは次の表のものですが、注意すべきは既定値のほうです——本文サイズは 10pt、用紙は letterpaper、段組は onecolumn。日本や欧州で A4 に印刷するつもりなら、a4paper は毎回自分で書く必要があります。

ここで一つ、知らないと必ず一度は踏む仕組みがあります。\documentclass に書いたオプションはクラスだけのものではなく、その後に読み込まれるすべてのパッケージへ グローバルオプション として渡ります。clsguide の説明では、\usepackage[...] に直接書いたものが「ローカルオプション」、\documentclass[...] に書いたものが「グローバルオプション」で、パッケージは自分が知っているオプション名を両方から拾います。だから \documentclass[twocolumn]{article} と書けば、2 段組を理解するパッケージは黙って 2 段組向けに振る舞います。そしてこの仕組みは、! LaTeX Error: Option clash for package geometry. の解決策でもあります。同じパッケージが（多くはクラスやテンプレート経由で）別のオプション付きで二度読まれると、この一行で止まります。LaTeX 自身がログに出す助言は「そのオプションを \documentclass の宣言に移してみなさい」——グローバルオプションなら二重読み込みの衝突を起こしません。

プリアンブルに書くもの、本文に書くもの

プリアンブルは \documentclass の次の行から \begin{document} の直前までで、置けるのは 宣言だけ、本文の文字は一字も置けません。ここに普通の文を一行書くと ! LaTeX Error: Missing \begin{document}. で止まります。エラー名は紛らわしいのですが、意味は「本文が始まっていないのに組版すべき文字が来た」です。プリアンブルの % コメントの閉じ忘れや、日本語の全角スペースが紛れ込んだときにも同じ一行が出ます。逆に本文の中で \usepackage を呼ぶと ! LaTeX Error: Can be used only in preamble. になります——パッケージはページを組み始める前にすべて出そろっていなければならないからです。

• パッケージの読み込み — \usepackage[options]{package}。\usepackage{amsmath,amssymb} のようにまとめて書けますが、その書き方ではオプションを付けられません。
• タイトル情報 — \title{...} \author{...} \date{...}。実際に組版されるのは本文の \maketitle で、慣習としてこの三つはプリアンブルに置きます。
• 自作の命令と環境 — \newcommand \renewcommand \newenvironment。文書全体で使うものだけを置きます。
• 寸法とカウンタ — \setlength{\parindent}{0pt}、\setcounter{tocdepth}{2} など、文書全体に効く値。
• ページ書式とパッケージ設定 — \pagestyle{headings}、\hypersetup{...}、\graphicspath{{figures/}} のような、読み込み後の調整。
• 入れてはいけないもの — 見出し・段落・図・表、つまり出力に現れるものはすべて \begin{document} の後です。

パッケージはどの順番で読み込むべきか

大半のパッケージは順序を気にしませんが、例外は必ず覚えておく価値があります。もっとも有名なのが hyperref で、マニュアルは「読み込むパッケージの 最後 に置くこと」と明言しています。理由は身も蓋もなく、hyperref の仕事が LaTeX の多くの命令を再定義することだからです。先に読み込むと、後から来たパッケージがその再定義を上書きして、リンクや PDF のしおりが静かに壊れます。ちなみにマニュアルには脚注が付いていて、再定義の数を減らして順序依存を弱める作業が始まっている、とあります。つまりこれは恒久の法則ではなく、現時点での回避策です。

そして「最後」には有名な例外があります。cleveref は hyperref より後に読み込まなければなりません。 cleveref は hyperref の定義を検出してから自分の参照命令を組み立てるので、順序が逆だと機能しません。varioref も使うなら、cleveref のマニュアルが指定する順序は varioref → hyperref → cleveref です。この落とし穴が厄介なのは、失敗が静かなことです——マニュアル自身が警告しているとおり、順序を誤ると相互参照がまったく別の対象を指し、出力にもログにも警告が出ません。参照番号がなぜか一つずれている、という症状に心当たりがあるなら、まずプリアンブルのこの三行の順番を見てください。

\documentclass[11pt,a4paper]{article}

% 1. encoding and fonts
\usepackage[T1]{fontenc}
% 2. language
\usepackage[english]{babel}
% 3. page geometry
\usepackage[margin=25mm]{geometry}
% 4. mathematics
\usepackage{amsmath,amssymb}
% 5. graphics and colour
\usepackage{graphicx}
\usepackage{xcolor}
% 6. hyperref near the end: it redefines many commands
\usepackage{hyperref}
% 7. cleveref is the exception, it must come after hyperref
\usepackage{cleveref}

% document-wide settings and definitions
\newcommand{\R}{\mathbb{R}}
\setlength{\parindent}{0pt}
\title{A Short Note}
\author{Ada Lovelace}
\date{\today}

\begin{document}
\maketitle

\section{Setup}\label{sec:setup}
For all $x \in \R$ we have $x^2 \ge 0$.

\section{Result}
The argument of \cref{sec:setup} applies unchanged.
\end{document}

プリアンブルを本文より大きくしない

先ほどのインタビューで、ランポートは「LaTeX 利用者がやめるべき三つの間違いは？」と訊かれています。彼の答えは三つとも同じでした——体裁を気にしすぎて、中身を気にしなさすぎること。三度繰り返すという形式そのものが答えだったわけです。プリアンブルはまさにこの罠が仕掛けられている場所で、一度きりの見た目調整、試しただけで外し忘れたパッケージ、二度と使わない短縮命令が溜まっていきます。困るのは見た目ではなく、後日エラーが出たときに、犯人がその何十行のどこかに隠れることです。クラス、言語とフォント、数式、図表、リンク——文書全体に効くもの だけを置き、\newcommand は本文を書いていて実際に繰り返した構造にだけ与えます。投稿テンプレートを使うときは、テンプレートのプリアンブルをまず尊重してください。クラスが前提にしているパッケージを勝手に差し替えると、たいてい Option clash か、もっと分かりにくい形で返ってきます。

• 新しい報告書 — article から始めます。ページ設計に手を入れるのは、本文がひととおり書けてからで十分です。
• 学位論文 — 大学が配るクラスをそのまま使い、余白や見出しの調整は最後にまとめて。テンプレートのプリアンブルには触らないのが最短距離です。
• 投稿論文 — 投稿先のクラス（elsarticle、IEEEtran、revtex4-2 など）を先に入れ、自分のプリアンブルはその上に必要最小限だけ足します。
• A4 で刷りたい — 標準クラスの既定は letterpaper なので、\documentclass[a4paper]{...} と明示します。geometry を使うならそちらでも指定できます。
• エラーが出たとき — 直前に足した \usepackage や \newcommand をまず疑い、それでも分からなければプリアンブルを半分に切って二分探索します。