용어집과 기호표

어느 투고 규정에나 같은 한 줄이 있습니다. 약어는 처음 나올 때만 풀어 쓰고 그 뒤로는 줄여 쓴다는 것입니다. 사람 손으로는 좀처럼 지킬 수 없는 규칙입니다. 절 하나를 옮기면 “처음”의 자리도 따라 움직이고, 정작 중요한 한 곳을 놓치면 심사자가 찾아냅니다. LaTeX의 glossaries 패키지와 그 후속인 glossaries-extra는 이 규칙을 기계에 맡깁니다. 용어나 약어를 프리앰블에서 한 번 정의하고 본문에서는 \gls{key}라고만 쓰면, 첫 사용이 알아서 펼쳐지고 덤으로 실제로 쓴 항목만 정렬되어 책 끝의 용어집에 나타납니다. 이 페이지는 항목 정의부터 \newacronym, makeglossaries 실행, \printglossary까지 전 과정을 따라가면서, 용어집이 새하얗게 나오는 네 가지 원인——그중 셋은 경고조차 나오지 않습니다——을 먼저 없애 둡니다.

한 번 정의하고 어디서든 부르기 — newglossaryentry와 gls

프리앰블에 \newglossaryentry{key}{name=..., description=...}을 쓰고, 본문에서는 \gls{key}로 부릅니다. 첫 인수 key는 직접 정하는 이름표이고, 인쇄되는 것은 name, 용어집에 실릴 설명이 description입니다. 여기서 붙잡아 둘 점은 \gls가 두 가지 일을 동시에 한다는 것입니다. name을 그 자리에 넣는 동시에, 이 용어를 용어집에 실으라는 기록을 보조 파일에 씁니다. 그래서 정의만 하고 한 번도 \gls로 부르지 않은 용어는 용어집에 나타나지 않습니다. 쓴 용어만 실리는 것은 설계이지 결함이 아닙니다.

호출 변형은 명령 앞부분 글자만 다릅니다. 문장 처음에는 \Gls{key}, 복수형은 \glspl{key}, 둘 다면 \Glspl{key}입니다. 자동으로 만들어지는 복수형은 name 끝에 “s”를 붙인 것뿐이라 matrices 같은 불규칙형은 plural key로 명시해야 합니다. 본문에서 쓰는 표기를 표시명과 다르게 하려면 text를 지정하고, 대응하는 기호는 symbol key에 넣어 \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는 용어를 기록할 뿐 정렬하거나 서식을 만들지는 않습니다. 첫 실행에서 \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를 끼우는 이유입니다. 이 스크립트는 Perl로 쓰였으므로 Perl이 없는 환경(Windows에서 흔합니다)에서는 makeglossaries-lite를 부릅니다. 같은 일을 하는 makeglossaries-lite.lua이며 texlua가 실행합니다.

용어집이 새하얀 때 — 원인 넷, 그중 셋은 말이 없습니다

가장 흔한 원인은 makeglossaries 실행을 잊는 것이며, 이 실패는 단서를 거의 남기지 않습니다. .gls가 없으니 용어집은 제목까지 통째로 나오지 않습니다. 빈 틀이 남는 것이 아니라 그 자리에 아무것도 조판되지 않습니다. 오류도 경고도 없이 로그 깊숙한 곳에 No file mydoc.gls. 한 줄만 남습니다. 색인에서 makeindex를 잊었을 때와 똑같은 함정이며, 위장도 훌륭합니다. \gls 자체는 첫 실행부터 제대로 펼쳐지므로 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(기본)는 description 환경을 바탕으로 하고, 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로 되돌려 씁니다. 이런 설계 덕분에 첫 실행에서는 아직 아무것도 정의되어 있지 않은 것이 정상입니다. 그래서 glossaries-extra는 정의되지 않은 항목을 오류가 아니라 경고로 낮춥니다. 첫 회차에 Package glossaries-extra Warning: Glossary entry ... has not been defined가 줄줄이 나오는 것은 예상된 일입니다. 순수 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를 쓰면 됩니다. 기호는 수식이므로 $...$로 감쌉니다. 빌드는 다시 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를 다시 돌립니다. 잊어도 아무도 나무라지 않습니다.