用語集・記号表

どの投稿規定にも同じ一行があります——略語は初出のときだけフルスペルで書き、以降は略記でよい。人間の手ではまず守れない規則です。節をひとつ入れ替えれば「初出」の位置は動き、その一箇所を直し忘れれば査読者に見つかります。LaTeX の glossaries パッケージ（と後継の glossaries-extra）は、この規則を機械に守らせる道具です。用語や略語をプリアンブルで一度定義し、本文では \gls{key} と呼ぶだけ。初出だけが自動的に展開され、ついでに実際に使った語だけが巻末の用語集に整列して現れます。このページでは、定義から \newacronym、makeglossaries の実行、\printglossary までを追い、用語集が真っ白になる四つの原因——うち三つは警告すら出ません——を先に潰しておきます。

一度定義して何度でも呼ぶ — newglossaryentry と gls

プリアンブルに \newglossaryentry{key}{name=..., description=...} を書き、本文では \gls{key} と呼びます。第 1 引数の key は自分で決める名札で、印刷されるのは name、用語集に並ぶ説明が description です。ここで大事なのは、\gls が二つの仕事を同時にしていること——name をその場に差し込み、同時に「この語を用語集に載せる」という記録を補助ファイルへ書き出します。だから、定義しただけで一度も \gls で呼ばなかった語は、用語集に現れません。使った語だけが並ぶのは仕様であって、不具合ではありません。

呼び出しの変種は、命令の頭文字を変えるだけで使い分けられます。文頭なら \Gls{key}、複数形なら \glspl{key}、その両方なら \Glspl{key}。自動生成される複数形は name の末尾に s を足しただけなので、matrices のような不規則形は plural キーで明示します。表示名と本文中の表記を変えたいときは text、対応する記号は symbol キーに入れて \glssymbol{key} で呼び、説明だけを差し込みたいときは \glsdesc{key} です。説明が段落をまたぐほど長ければ \longnewglossaryentry を使います。なお存在しない key を呼ぶと ! Package glossaries Error: Glossary entry ... has not been defined. で止まります——綴りを間違えても黙って無視されないのは、ここでは良い性質です。

\usepackage{glossaries}
\makeglossaries              % opens the glossary files -- required

\newglossaryentry{set}{%
  name={set},
  description={a collection of distinct objects}%
}
\newglossaryentry{matrix}{%
  name={matrix},
  plural={matrices},      % irregular plural, spelled out
  description={a rectangular array of numbers}%
}

\begin{document}
\Gls{set} theory studies a \gls{set}; linear algebra studies \glspl{matrix}.
\printglossaries
\end{document}

略語を機械に任せる — newacronym と初出展開

\newacronym{key}{short}{long} で定義し、あとは \gls{key} と書くだけです。short が略記（たとえば SVM）、long が正式名称（support vector machine）。同じ \gls{svm} を二度書いても、出力は一度目が “support vector machine (SVM)”、二度目以降が “SVM” になります。ここが手作業では守れない規則を機械が引き受けるところです——初出フラグは項目ごとに、しかも処理される順序で管理されるので、節を入れ替えれば展開される場所も一緒に動きます。原稿を並べ替えても矛盾が生じません。

章ごとに読み切りにしたい場合など、「ここから先はもう一度フルスペルで」と戻したいときは \glsreset{key}、全項目まとめてなら \glsresetall を使います。略語だけを別の一覧にまとめるなら、パッケージを \usepackage[acronym]{glossaries} と読み込みます。これで用語集と略語表が二つの独立したリストになり、補助ファイルもそれぞれに一組ずつ用意されます。なお glossaries-extra を併用している場合、\newacronym は category=acronym を付けた \newabbreviation の別名になります——新しく書き始めるなら \newabbreviation を直接使うほうが、豊富な略語スタイルにそのまま乗れます。

\usepackage[acronym]{glossaries}   % a second, separate list
\makeglossaries

\newacronym{svm}{SVM}{support vector machine}

\begin{document}
\gls{svm} is a classifier.   % -> support vector machine (SVM)
Another \gls{svm} follows.   % -> SVM

\glsreset{svm}               % start a chapter that must stand alone
\gls{svm} again in full.     % -> support vector machine (SVM)

\printglossary[type=main,title={Glossary}]
\printglossary[type=\acronymtype,title={Acronyms}]
\end{document}

ビルド — makeglossaries が .glo を .gls に変える

LaTeX は語を記録するだけで、整列も整形もしません。1 回目の実行で \makeglossaries が .ist（整列規則を書いたスタイルファイル）を吐き、\gls が呼ばれた語は .glo に溜まります。ここで外部プログラム makeglossaries を挟むと、その正体が見えます——実行するとこう表示されます: makeindex -s mydoc.ist -t mydoc.glg -o mydoc.gls mydoc.glo。索引を作るのとまったく同じ makeindex です。整列済みの .gls ができたら、もう一度 LaTeX を回して読み込ませます。

pdflatex mydoc       # writes mydoc.glo (and mydoc.ist)
makeglossaries mydoc # sorts it: no file extension here
pdflatex mydoc       # reads mydoc.gls, prints the glossary

# what makeglossaries actually runs, once per glossary type:
#   makeindex -s mydoc.ist -t mydoc.glg -o mydoc.gls mydoc.glo
#   makeindex -s mydoc.ist -t mydoc.alg -o mydoc.acr mydoc.acn

用語集が二つあれば、ファイルも二組になります。既定の用語集は .glo → .gls（記録は .glg）、acronym オプションを足すと略語表が .acn → .acr（.alg）を使い、makeglossaries は makeindex を二回呼びます。この「いくつリストがあるかを知っていて必要なだけ回す」役目こそ、素の makeindex を手で叩くのではなく makeglossaries を挟む理由です。makeglossaries 自体は Perl スクリプトなので、Perl の無い環境（Windows でよくあります）では、同じ役目を果たす Lua 実装の makeglossaries-lite を呼びます——中身は texlua で動く makeglossaries-lite.lua です。

用語集が真っ白なとき — 四つの原因、三つは無言

いちばん多いのは makeglossaries の実行忘れです。しかもこの場合、失敗の兆候がほとんどありません。.gls が無いので用語集は見出しごと出ません——空の枠が残るのではなく、そこには何も組まれないのです。エラーも警告も出ず、ログの奥に No file mydoc.gls. という一行が残るだけ。ここは索引で makeindex を忘れたときとまったく同じ落とし穴で、\gls 自体は 1 回目から正しく展開されるため、PDF を眺めているかぎり「動いている」ように見えてしまいます。

• makeglossaries を走らせていない。 .gls が無く、用語集は見出しごと出ない。警告なし、ログに No file mydoc.gls. のみ。
• プリアンブルに \makeglossaries が無い。 書き出し先のファイル自体が開かれないので .glo すら作られず、やはり何も印刷されない。警告なし。
• 語を定義しただけで \gls で呼んでいない。 未使用の項目は記録されないので載らない。これは仕様。載せたい語は本文で一度は呼ぶこと。
• 唯一まともに教えてくれるのが逆の間違い。 \makeglossaries はあるのに \printglossary を書き忘れると Package glossaries Warning: No \printglossary or \printglossaries found. (Remove \makeglossaries if you dont want any glossaries.) This document will not have a glossary. が出る。

もう一つ、無言で壊れる組み合わせがあります。hyperref を使う場合、glossaries は hyperref より後に読み込みます。「hyperref は最後」という定番の助言の、数少ない例外です。パッケージの入門ガイドがはっきりそう書いており、順序を間違えても警告は出ません——用語集の中のリンクとページ番号が静かに壊れるだけです。次のように並べてください。

\usepackage[colorlinks]{hyperref}
\usepackage{glossaries}   % after hyperref, not before
\makeglossaries

% put the glossary into the table of contents as well:
% \usepackage[toc]{glossaries}

出力する — printglossary の題・種類・目次入り

\printglossaries は用意されているリストをすべて出力し、\printglossary は一つだけを出します。使い分けは選択肢の必要性で決まります——題やスタイルをリストごとに変えたいなら \printglossary[type=main, title={用語集}] のようにオプションを渡し、そうでなければ \printglossaries の一行で足ります。見出しの語そのものは \glossaryname に入っており、\renewcommand で差し替えられます。

これらの見出しは番号なしで組まれるため、既定では目次に出ません。パッケージを \usepackage[toc]{glossaries} と読み込めば自動で目次に載ります——用語集ごとに \addcontentsline を書き並べるより確実です。見た目そのものは \setglossarystyle{...} で切り替えます。list（既定）は説明環境ベース、altlist は語を独立した行に置いて説明を下げ、long 系は表組みで組みます。説明が長い文書ほど altlist や long 系が読みやすくなります。

現代の構成 — glossaries-extra と bib2gls

glossaries の初版は 2007 年 5 月 16 日、Nicola Talbot が旧 glossary パッケージの後継として公開したものです。同じ作者はその後 2015 年に glossaries-extra を、2017 年に bib2gls を出しました。組み合わせの発想は文献管理そのままで、用語を .bib ファイルに書きためておき、bib2gls が本文で実際に使われた語だけを選び、整列して取り込みます——biber が引用された文献だけを拾ってくるのと同じ役回りです。makeindex／xindy が担っていた「選別と整列」を、一つのプログラムが引き受けます。

鍵は record オプションです。\usepackage[record]{glossaries-extra} と読み込むと makeindex／xindy による索引付けが止まり、代わりに .aux へ \glsxtr@record{set}{}{page}{glsnumberformat}{1} のような行が書き出されます。bib2gls はこれを読み、必要な項目だけを .glstex に書き戻します。この設計のおかげで、1 回目の実行ではまだ何も定義されていないのが正常です——だから glossaries-extra は未定義の項目をエラーではなく警告に格下げしています。Package glossaries-extra Warning: Glossary entry ... has not been defined が並んでも、1 回目なら想定内です。素の glossaries が同じ場面で実行を止めるのと対照的で、どちらも設計として筋が通っています。

@entry{set,
  name = {set},
  description = {a collection of distinct objects}
}

@abbreviation{svm,
  short = {SVM},
  long  = {support vector machine}
}

@symbol{sigma,
  name = {\ensuremath{\sigma}},
  description = {standard deviation}
}

\usepackage[record]{glossaries-extra}
\GlsXtrLoadResources[src={terms}]   % terms.bib, without the extension

\begin{document}
\gls{set} and \gls{svm} are used here.
\printunsrtglossary                 % already sorted by bib2gls
\end{document}

本文側の書きかたはほとんど変わりません。.bib は \GlsXtrLoadResources[src={terms}] で読み（src は拡張子なしのファイル名）、語の呼び出しは \gls{set} のまま。違うのは印刷命令で、並べ替えは bib2gls が済ませているため \printunsrtglossary（unsrt = unsorted、「並べ替えずそのまま出す」の意）を使います。ビルドでは makeglossaries の代わりに bib2gls を呼びます。--group を付けると頭文字ごとの小見出しが付き、pdflatex は xelatex／lualatex に置き換えて構いません。ひとつだけ導入時の注意があり、bib2gls は Java で書かれているため Java 実行環境（Java 8 以上）が必要です。TeX Live のコマンドは中身が .jar を起動するシェルスクリプトなので、Java が無い環境では実行した瞬間にそれと分かります。

pdflatex mydoc
bib2gls --group mydoc   # reads mydoc.aux, writes mydoc.glstex
pdflatex mydoc

記号だけの一覧なら nomencl

論文の冒頭に置く記号表であれば、glossaries でも書けますが、軽量な nomencl のほうが手数が少なくて済みます。プリアンブルに \usepackage{nomencl} と \makenomenclature を置き、記号が初めて出るところで \nomenclature{$g$}{gravitational acceleration} と印を付け、一覧を出したい位置に \printnomenclature を書くだけです。記号は数式なので $...$ で囲みます。ビルドは nomencl が makeindex を借りる形で、\makenomenclature が .nlo を吐き、付属スタイル nomencl.ist で整列して .nls を作り、もう一度 LaTeX を回します。

pdflatex mydoc
makeindex mydoc.nlo -s nomencl.ist -o mydoc.nls
pdflatex mydoc

整列の基準になるのは、記号の入力そのものです。$\sigma$ と書けば並べ替えのキーも $\sigma$ という文字列で、$ やバックスラッシュは文字コード上どの英字よりも前に来ます。実際に試すと、σ は g や m より先頭に並びました。そこで任意引数に並べ替えキーを与えます——\nomenclature[g-sigma]{$\sigma$}{...} の g-sigma が整列に使われ、記号そのものは印刷されます。ついでに、\nomenclature の直前の行末には % を置くのが定石です。余分な空白が入ると整列がずれます。

\usepackage{nomencl}
\makenomenclature
\renewcommand{\nomname}{List of Symbols}
% \usepackage[intoc]{nomencl}  % also list it in the contents

\begin{document}
Let $g$ be gravity.%
\nomenclature{$g$}{gravitational acceleration}%
A mass $m$ feels $F = mg$.%
\nomenclature{$m$}{mass of the object}%
\nomenclature[g-sigma]{$\sigma$}{stress}% sort key, not the symbol

\printnomenclature
\end{document}

見出しは既定で英語の “Nomenclature” で、\renewcommand{\nomname}{...} で差し替えられます。目次に載せたければ \usepackage[intoc]{nomencl}。各項目に自動で注記を付けるオプションもあり、refpage は「, page n」を、refeq は「, see equation (n)」を追加します。物理定数と変数を分けたいといった場合は、いま見た並べ替えキーの先頭文字を使って \nomgroup を再定義すると、見出し付きの小グループに割れます。

• 語と略語の用語集なら glossaries。 初出展開・複数形・大文字化まで自動で面倒を見てくれる。
• 新規に始めるなら glossaries-extra + bib2gls。 用語を .bib に書き、使った語だけを \printunsrtglossary で出す。Java が要ることだけ確認しておく。
• 数式記号の一覧だけなら nomencl。 \nomenclature で印を付け、makeindex を一度回すだけで完結する。
• どれも追加の実行が要る。 外部プログラム（makeglossaries / bib2gls / makeindex）を挟み、もう一度 LaTeX を回す。忘れても叱ってはくれない。