북마크와 메타데이터

hyperref를 불러오는 LaTeX 문서를 보조 파일까지 지운 상태에서 딱 한 번만 컴파일해 보세요. 만들어진 PDF에는 책갈피(아웃라인)가 하나도 없습니다. 두 번째 실행에서야 전부 갖춰집니다. 이유는 책갈피가 만들어지는 방식에 있습니다. hyperref는 제목들을 jobname.out이라는 별도 파일에 써 두고, 다음 실행이 시작될 때 그것을 다시 읽어 PDF에 넣기 때문입니다. 이 페이지에서는 그 구조와, .out 파일을 아예 버리고 한 번에 끝내는 bookmark 패키지, \hypersetup으로 넣는 PDF 메타데이터, 새로운 \DocumentMetadata 진입점, 그리고 일본어 책갈피가 깨지는 문제와 해결을 실제 pdfinfo 출력으로 확인하며 살펴봅니다.

책갈피는 hyperref가 제목에서 자동 생성합니다

\usepackage{hyperref}라고 쓰기만 하면 \chapter, \section, \subsection이 PDF 아웃라인이 됩니다. 설정은 패키지 옵션이나 \hypersetup{}으로 하며, 자주 쓰는 것은 넷입니다. bookmarks(기본 켜짐), bookmarksnumbered(절 번호도 책갈피에 넣기), bookmarksopen(펼친 상태로 시작), bookmarksopenlevel=N(어느 깊이까지 펼칠지). 중간 파일 jobname.out을 열어 보면 LaTeX 매크로 호출의 나열인데, 문자열이 평문이 아니라 UTF-16BE로 쓰여 있어서 영어 제목조차 \376\377\000C\000o\000v\000e\000r처럼 글자마다 \000이 끼어 있습니다. 앞머리의 \376\377는 UTF-16의 바이트 순서 표시이며, PDF의 문자열이 그렇게 정의되어 있기 때문입니다.

\usepackage[bookmarksnumbered,bookmarksopen,bookmarksopenlevel=1]{hyperref}
% or set the same keys later
\hypersetup{bookmarksopenlevel=1}

% report.out after three passes — hyperref stores the outline here
\BOOKMARK [0][]{cover.0}{\376\377\000C\000o\000v\000e\000r}{}% 1
\BOOKMARK [0][]{chapter.1}{...1 Foundations...}{}% 2
\BOOKMARK [1][-]{section.1.1}{...1.1 First section...}{chapter.1}% 3
\BOOKMARK [2][-]{subsection.1.1.1}{...1.1.1 A subsection...}{section.1.1}% 4

깊이의 기본값은 책갈피 쪽이 아니라 목차 쪽에서 옵니다. report 클래스의 tocdepth는 2(subsection까지)이므로 \subsubsection을 써도 아웃라인에 나오지 않습니다. 목차와 책갈피의 입자를 맞추려는 의도된 동작입니다. 책갈피만 더 깊게 하고 싶다면 bookmarksdepth를 씁니다. 실측으로 bookmarksdepth=4를 더하자 목차에는 없는 \subsubsection이 책갈피에만 나타났습니다. 반대로 bookmarksdepth=1로 하면 절까지만 남습니다.

제목이 없는 자리에 책갈피 달기: \pdfbookmark

표지, 목차, 번호 없는 머리말처럼 절 명령을 거치지 않는 자리에는 \pdfbookmark[level]{보일 문자}{앵커 이름}을 직접 놓습니다. 첫 인자의 레벨은 숫자로 \chapter가 0, \section이 1이며, 셋째 인자의 앵커 이름은 문서 안에서 유일해야 합니다. 겹치면 목적지가 충돌합니다. 현재 레벨에 그대로 더하려면 \currentpdfbookmark{문자}{앵커}, 한 단계 깊게 더하려면 \belowpdfbookmark{문자}{앵커}가 있습니다. 실무에서 가장 흔한 쓰임은 목차 자체에 책갈피를 다는 것으로, \tableofcontents 바로 앞에 한 줄이면 됩니다. 이것이 없으면 어디로든 갈 수 있는데 목차로만 돌아갈 수 없는 이상한 PDF가 됩니다.

\begin{document}
\pdfbookmark[0]{Cover}{cover}      % level 0, same rank as \chapter
\maketitle
\clearpage
\pdfbookmark[1]{Contents}{toc}     % the classic missing bookmark
\tableofcontents
\chapter{Foundations}

bookmark 패키지: .out 파일을 버리고 한 번에 끝내기

Heiko Oberdiek의 bookmark 패키지(TeX Live 2024 동봉판은 v1.31, 2023-12-10)를 hyperref 뒤에 불러오면 책갈피 생성 기구가 통째로 교체됩니다. 재 보면 효과가 바로 드러납니다. 순수 hyperref에서는 깨끗한 디렉터리에서의 첫 실행이 만든 PDF에 /Outlines 객체가 아예 없고, 두 번째 실행에서야 일곱 항목이 들어갔습니다. bookmark를 더하면 첫 실행부터 일곱 항목이 모두 있습니다. 비결은 단순합니다. bookmark는 .out 파일을 쓰지 않습니다(디렉터리에 생기지 않는 것으로 확인할 수 있습니다). 아웃라인 정보를 .aux로 돌리기 때문에 낡은 별도 파일을 다시 읽는 단계가 사라집니다. hyperref 쪽 책갈피는 자동으로 꺼지므로 충돌 걱정도 없습니다.

두 번째 이점은 꾸밈입니다. \bookmarksetup{}은 numbered(절 번호 포함), open과 openlevel, 그리고 항목별 모양—color=blue, bold, italic—을 받습니다. 생성된 PDF를 들여다보면 아웃라인 항목마다 /C [ … ]라는 색 항목이 실제로 기록되어 있습니다. 한 항목만 바꾸려면 바로 앞에 \bookmarksetupnext{color=red}를 둡니다. 긴 보고서에서 부록과 색인만 색을 달리해 두면 사이드바가 한눈에 훨씬 잘 읽힙니다.

\usepackage{hyperref}
\usepackage{bookmark}      % must come after hyperref
\bookmarksetup{numbered, open, openlevel=1, color=blue}

% one entry only
\bookmarksetupnext{color=red, bold}
\chapter{Appendix}

PDF 메타데이터: \hypersetup으로 제목과 저자 밝히기

뷰어의 “문서 속성”에 나오는 정보는 \hypersetup{}의 네 키가 결정합니다. pdftitle, pdfauthor, pdfsubject, pdfkeywords입니다. \title이나 \author에서 자동으로 옮겨지지 않으므로 양쪽 모두에 써야 합니다. hyperref가 \maketitle보다 먼저 값을 알아야 하기 때문입니다. 제대로 들어갔는지는 pdfinfo 한 번이면 바로 보입니다. pdfcreator와 pdfproducer는 생성 소프트웨어를 나타내는 칸으로 보통 자동으로 채워집니다. hyperref를 불러온 pdfLaTeX 출력이라면 Creator: LaTeX with hyperref, Producer: pdfTeX-1.40.26입니다. 이 둘은 덮어쓸 수 있지만, 그러면 “무엇으로 만들었는지” 추적할 유일한 단서가 사라지므로 건드리지 않는 편이 안전합니다.

\usepackage{hyperref}
\hypersetup{
  pdftitle={Measured Bookmarks},
  pdfauthor={Ada Lovelace},
  pdfsubject={PDF navigation},
  pdfkeywords={LaTeX, hyperref, bookmarks}
}

$ pdfinfo report.pdf
Title:           Measured Bookmarks
Subject:         PDF navigation
Keywords:        LaTeX, hyperref, bookmarks
Author:          Ada Lovelace
Creator:         LaTeX with hyperref
Producer:        pdfTeX-1.40.26
Pages:           5
Page size:       595.276 x 841.89 pts (A4)
PDF version:     1.5

악센트가 붙은 문자도 이제 그대로 쓸 수 있습니다. TeX Live 2024에 동봉된 hyperref 7.01h는 내부적으로 \Hy@unicodetrue를 기본으로 두므로, pdftitle={Théorie des catégories — Übersicht}는 pdfLaTeX에서도 그대로 pdfinfo에 나옵니다. 예전에 필요했던 unicode 옵션을 굳이 붙일 필요가 없습니다. 여전히 문제가 되는 것은 \hypersetup의 값이 PDF 문자열로 그대로 기록된다는 점이라, 실무의 철칙은 매크로를 넣지 않는 것입니다. pdftitle={\LaTeX{} 사용법}처럼 쓰면 전개가 실패하기 쉽고, 그냥 pdftitle={LaTeX 사용법}이라고 쓰는 편이 확실합니다.

\DocumentMetadata: 메타데이터와 태깅의 새 진입점

\DocumentMetadata{…}는 \documentclass보다 앞에 두는 LaTeX 커널의 새 선언입니다. TeX Live 2024에서 실제로 동작하며 lang=en-GB(문서 언어), pdfversion=2.0, pdfstandard=A-2B(PDF/A 수준. A-1B부터 A-4까지), uncompress(압축을 모두 끄기) 같은 키를 받습니다. 한 줄만 더해도 효과가 눈에 보입니다. pdfinfo의 Metadata Stream이 no에서 yes로 바뀌고, PDF에 XMP 메타데이터 스트림이 들어갑니다. 기존의 \hypersetup 키들은 그대로 함께 쓸 수 있고, 양쪽 값이 모두 PDF에 제대로 들어가는 것을 실측으로 확인할 수 있습니다.

그다음에 있는 것이 태그 PDF입니다. testphase={phase-III}를 더하고 pdflatex을 두 번 돌리면 pdfinfo의 Tagged가 yes로 바뀝니다. LaTeX이 문단과 제목의 구조를 PDF의 구조 트리로 쓰기 시작했다는 뜻입니다. 이름 그대로 아직 시험 단계 기능이므로 투고용 최종본에서 무조건 켤 것은 아니지만, 동작하는 판이 표준 TeX Live에 들어 있다는 사실은 알아 둘 만합니다. 또 \DocumentMetadata에는 용지 크기에 대한 부작용이 있으므로 기존 문서에 더할 때는 PDF 치수를 확인하세요(자세한 내용은 “PDF의 생성과 제어”를 참조).

\DocumentMetadata{pdfversion=2.0, lang=en-GB, testphase={phase-III}}
\documentclass{article}
\usepackage{hyperref}
\hypersetup{pdftitle={Tagged Test}, pdfauthor={Ada Lovelace}}
% pdfinfo then reports: Tagged: yes / Metadata Stream: yes / PDF version: 2.0

일본어 책갈피가 깨질 때: pxjahyper와 dvipdfmx 옵션

upLaTeX + dvipdfmx에서 일본어 책갈피를 제대로 내려면 두 가지 손질이 필요합니다. 첫째는 hyperref의 드라이버 지정입니다. \usepackage{hyperref}라고만 쓰면 로그에 Package hyperref Info: Driver (default): hdvips.가 나옵니다. DVI를 만들고 있는데도 hyperref는 dvips용 \special을 쓰는 것입니다. 그 DVI를 dvipdfmx에 넣으면 dvipdfmx:warning: Unknown token "SDict"와 Interpreting special command ps: (ps:) failed.가 줄줄이 나오고, 책갈피도 링크도 통째로 사라진 PDF가 만들어집니다. \usepackage[dvipdfmx]{hyperref}라고 쓰면 로그가 Driver: hdvipdfm.으로 바뀌고 경고는 0이 됩니다.

둘째는 문자 인코딩입니다. 드라이버를 고치면 책갈피는 나오지만, 일본어 제목은 æ鞥æ鲬èꪞã膮èꚋå螺ã膗 같은 문자열로 깨집니다. .out 파일을 보면 이유가 드러납니다. 원래 日은 UTF-16BE에서 \145\345 두 바이트가 되어야 하는데, UTF-8의 세 바이트가 각각 별개의 문자로 취급되어 \000\346\000\227\000\245처럼 부풀려집니다. 여기에 \usepackage{pxjahyper}(八登崇之 작, TeX Live 2024 동봉판 v1.3)를 더하면 .out이 올바른 UTF-16BE, 곧 \376\377\145\345\147\054\212\236…가 되고 pdfinfo의 Title도 日本語のタイトル로 읽힙니다. 책갈피뿐 아니라 pdftitle・pdfauthor까지 함께 고쳐진다는 점이 중요합니다.

% upLaTeX -> dvipdfmx: both lines are needed
\documentclass{ujarticle}
\usepackage[dvipdfmx]{hyperref}   % without this: dvipdfmx warning, no outline
\usepackage{pxjahyper}            % without this: mojibake in the outline
\hypersetup{pdftitle={...}, pdfauthor={...}}

이 두 단계는 (u)pLaTeX의 DVI 경로에서만 필요합니다. LuaLaTeX + LuaTeX-ja라면 평범한 \usepackage{hyperref}만으로 정답에 이릅니다. 로그에 Driver (autodetected): hluatex.가 나오고 .out은 처음부터 올바른 UTF-16BE입니다. XeLaTeX + xeCJK도 마찬가지로 추가 패키지 없이 책갈피가 읽힙니다. 일본어 문서에서 책갈피 깨짐에 계속 시달린다면 엔진을 갈아타는 것이 가장 빠른 해결책일 수 있습니다. 순서에 관한 한마디: hyperref는 되도록 뒤에서 불러오는 것이 정석이지만, cleveref는 반드시 hyperref 뒤여야 하며 순서를 어기면 ! Package cleveref Error: cleveref must be loaded after hyperref!.로 멈춥니다. varioref까지 쓴다면 hyperref → varioref → cleveref 순입니다.