Debian Codegraph @

texmf-dist/doc/latex/hyperref/hyperref-doc.tex

raw
1 % This is the manual for the LaTeX hyperref package.
2 %
3 % Copyright (C) 1998-2003 Sebastian Rahtz.
4 % Copyright (C) 2003 Steve Peter and Karl Berry
5 % Copyright (C) 2006-2012 Heiko Oberdiek.
6 % Copyright (C) 2017-2019 David Carlisle Ulrike Fischer
7 % Copyright (C) 2019-2024 The LaTeX Project
8 %
9 % Permission is granted to copy, distribute and/or modify this document
10 % under the terms of the GNU Free Documentation License, Version 1.1 or
11 % any later version published by the Free Software Foundation; with no
12 % Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
13 % Texts. A copy of the license is included in the section entitled
14 % ``GNU Free Documentation License.''
15 %
16
17 \def\mydate{January 2020}
18
19 \RequirePackage{iftex}
20
21 \documentclass{article}
22
23
24 \usepackage{pifont}
25 \usepackage{calc}
26
27 \usepackage{hologo}
28
29 \newcommand*{\cs}[1]{%
30 \texttt{\textbackslash #1}%
31 }
32 \newcommand*{\xpackage}[1]{\textsf{#1}}
33 \newcommand*{\xoption}[1]{\textsf{#1}}
34
35 % from doc.sty
36 \makeatletter
37 \ifx\l@nohyphenation\@undefined
38 \newlanguage\l@nohyphenation
39 \fi
40 \ifx\l@nohyphenation\@undefined
41 \newlanguage\l@nohyphenation
42 \fi
43 \DeclareRobustCommand\meta[1]{%
44 \ensuremath\langle
45 \ifmmode \expandafter \nfss@text \fi
46 {%
47 \meta@font@select
48 \edef\meta@hyphen@restore
49 {\hyphenchar\the\font\the\hyphenchar\font}%
50 \hyphenchar\font\m@ne
51 \language\l@nohyphenation
52 #1\/%
53 \meta@hyphen@restore
54 }%
55 \ensuremath\rangle
56 }
57 \def\meta@font@select{\ttfamily\itshape}
58 \makeatother
59
60 % Page layout.
61 \advance\textwidth by 1.1in
62 \advance\oddsidemargin by -.55in
63 \advance\evensidemargin by -.55in
64 %
65 \advance\textheight by 1in
66 \advance\topmargin by -.5in
67 \advance\footskip by -.5in
68 %
69 \pagestyle{headings}
70 %
71 % Avoid some overfull boxes.
72 \emergencystretch=.1\hsize
73 \hbadness = 3000
74
75 % these are from lshort.sty, but lshort.sty pulls in so many other
76 % packages it seems cleaner to just include them here.
77 %
78 \newcommand{\bs}{\symbol{'134}}%Print backslash
79 \newcommand{\ci}[1]{\texttt{\bs#1}}
80
81 \makeatletter
82 \@ifpackageloaded{tex4ht}{%
83 % separate definition for HTML case to avoid
84 % nasty borders with double horizontal lines with
85 % large gaps.
86 \newsavebox{\cmdsyntaxbox}%
87 \newenvironment{cmdsyntax}{%
88 \par
89 % \small
90 \addvspace{3.2ex plus 0.8ex minus 0.2ex}%
91 \vskip -\parskip
92 \noindent
93 \begin{lrbox}{\cmdsyntaxbox}%
94 \begin{tabular}{l}%
95 \rule{0pt}{1em}%
96 \ignorespaces
97 }{%
98 \end{tabular}%
99 \end{lrbox}%
100 \fbox{\usebox{\cmdsyntaxbox}}%
101 \par
102 \nopagebreak
103 \addvspace{3.2ex plus 0.8ex minus 0.2ex}%
104 \vskip -\parskip
105 }%
106 }{%
107 \newenvironment{cmdsyntax}{%
108 \par
109 \small
110 \addvspace{3.2ex plus 0.8ex minus 0.2ex}%
111 \vskip -\parskip
112 \noindent
113 \begin{tabular}{|l|}%
114 \hline
115 \rule{0pt}{1em}%
116 \ignorespaces
117 }{%
118 \\%
119 \hline
120 \end{tabular}%
121 \par
122 \nopagebreak
123 \addvspace{3.2ex plus 0.8ex minus 0.2ex}%
124 \vskip -\parskip
125 }%
126 }
127 \makeatother
128
129 \usepackage{array,longtable}
130 \ifTUTeX%
131 \usepackage{fontspec}%
132 \renewcommand*{\ttdefault}{lmvtt}%
133 \else % not \XeTeX* nor \LuaTeX*
134 \usepackage[T1]{fontenc}%
135 \usepackage{lmodern}%
136 \renewcommand*{\ttdefault}{lmvtt}%
137 \fi
138
139 \newcommand*{\Quote}[1]{\textquotedblleft#1\textquotedblright}
140
141 \ifpdf
142 \usepackage[%
143 % pdftex,% might be luatex, just allow automatic default
144 colorlinks,%
145 hyperindex,%
146 plainpages=false,%
147 bookmarksopen,%
148 bookmarksnumbered,
149 pdfusetitle,%
150 ]{hyperref}
151 %%?? \def\pdfBorderAttrs{/Border [0 0 0] } % No border around Links
152 \else
153 \usepackage{hyperref}
154 \fi
155
156 \makeatletter
157 \@ifpackageloaded{tex4ht}{%
158 \author{Sebastian Rahtz (deceased)\and
159 Heiko Oberdiek (inactive)\and
160 The \LaTeX3 Project (\url{https://github.com/latex3/hyperref/issues})}
161 }{%
162 \usepackage{bmhydoc}%
163 \author{Sebastian Rahtz\thanks{deceased}\and
164 Heiko Oberdiek\thanks{inactive}\and
165 The \LaTeX3 Project\thanks{\url{https://github.com/latex3/hyperref/issues}}}
166 }
167 \makeatother
168 \title{Hypertext marks in \hologo{LaTeX}: a manual for \xpackage{hyperref}}
169 \date{2026-04-24 v7.01q}
170
171 \begin{document}
172
173 % comes out too close to the toc, and we know it's page one anyway.
174 \thispagestyle{empty}
175 \maketitle
176 \tableofcontents
177 \setcounter{tocdepth}{2}% for bookmark levels
178
179 \section{Preface}
180 As can be already seen in the following introduction, \xpackage{hyperref}
181 has a long history and has seen many changes over time. The introduction
182 mentions workflows, drivers and problems that are no longer (or only in edge cases) relevant.
183 The documentation reflects this varied history: changes
184 and extensions and explanations were and are spread over various papers and sources or
185 have been incorporated later and so are not always in a coherent order and in sync which each other.
186
187 This history is continuing: If you are using the new \hologo{LaTeX} PDF management
188 which is currently distributed as a testphase package \xpackage{pdfmanagement-testphase}
189 then \xpackage{hyperref} will for the PDF output use a new generic driver which
190 contains a number of changes and new features. The documentation of this driver
191 \texttt{hyperref-generic.pdf}
192 is currently a part of the \xpackage{pdfmanagement-testphase} documentation.
193 One important change of the new driver is
194 that it removed the old \xpackage{hyperref} code for book marks and uses
195 the \xpackage{bookmark} package instead. So to learn
196 about options to extend the bookmarks you should consult the \xpackage{bookmark} documentation
197 too.
198
199 \subsection{Restoring removed patches}
200
201 \xpackage{hyperref} has over time patched quite a number of packages to resolve clashes and incompabilities.
202 Many of them are either no longer needed or should be done by the original packages.
203 Those patches are now slowly removed from \xpackage{hyperref}. It should normally not lead to problems, but
204 in case that the patches should be restored they can be loaded through the package \xpackage{hyperref-patches} which
205 is a part of this bundle.
206
207
208
209 \section{Introduction}
210
211 The package derives from, and builds on, the work of the Hyper\hologo{TeX}
212 project, described at \nolinkurl{http://xxx.lanl.gov/hypertex/}\footnote{Now: \url{https://ctan.org/tex-archive/support/hypertex/hypertex}}. It extends
213 the functionality of all the \hologo{LaTeX} cross-referencing commands
214 (including the table of contents, bibliographies etc) to produce
215 \cs{special} commands which a driver can turn into hypertext links;
216 it also provides new commands to allow the user to write \emph{ad hoc}
217 hypertext links, including those to external documents and URLs.
218
219 The package is currently maintained at \url{https://github.com/latex3/hyperref/} and issues should
220 be reported there.
221
222 This manual provides a brief overview of the \xpackage{hyperref}
223 package. For more details, you should read the additional documentation
224 distributed with the package, as well as the complete documentation by
225 processing \texttt{hyperref.dtx}. You should also read the chapter on
226 \xpackage{hyperref} in \textit{The \hologo{LaTeX} Web Companion}, where you will
227 find additional examples.
228
229 The Hyper\hologo{TeX} specification\footnote{This is borrowed from an article
230 by Arthur Smith.} says that conformant viewers/translators must
231 recognize the following set of \cs{special} constructs:
232
233 \begin{description}
234 \item[href:] \verb|html:<a href = "href_string">|
235 \item[name:] \verb|html:<a name = "name_string">|
236 \item[end:] \verb|html:</a>|
237 \item[image:] \verb|html:<img src = "href_string">|
238 \item[base\_name:] \verb|html:<base href = "href_string">|
239 \end{description}
240
241 The \emph{href}, \emph{name} and \emph{end} commands are used to do the
242 basic hypertext operations of establishing links between sections of
243 documents. The \emph{image} command is intended (as with current HTML
244 viewers) to place an image of arbitrary graphical format on the page in
245 the current location. The \emph{base\_name} command is be used to
246 communicate to the DVI viewer the full (URL) location of the current
247 document so that files specified by relative URLs may be retrieved
248 correctly.
249
250 The \emph{href} and \emph{name} commands must be paired with an
251 \emph{end} command later in the \TeX\ file---the \TeX\ commands between
252 the two ends of a pair form an \emph{anchor} in the document. In the
253 case of an \emph{href} command, the \emph{anchor} is to be highlighted
254 in the \emph{DVI viewer}, and when clicked on will cause the scene to
255 shift to the destination specified by \emph{href\_string}. The
256 \emph{anchor} associated with a name command represents a possible
257 location to which other hypertext links may refer, either as local
258 references (of the form \verb|href="#name_string"| with the
259 \emph{name\_string} identical to the one in the name command) or as part
260 of a URL (of the form \emph{URL\#name\_string}). Here
261 \emph{href\_string} is a valid URL or local identifier, while
262 \emph{name\_string} could be any string at all: the only caveat is that
263 `$\verb|"|$' characters should be escaped with a backslash
264 ($\backslash$), and if it looks like a URL name it may cause problems.
265
266 However, the drivers intended to produce \emph{only} PDF use literal
267 PostScript or PDF \verb|\special| commands. The commands are defined in
268 configuration files for different drivers, selected by package options or for
269 most current engines autodetected;
270 at present, the following drivers are supported:
271
272 \begin{description}
273 \item[hypertex] DVI processors conforming to the Hyper\TeX\ guidelines (i.e.\ \textsf{xdvi}, \textsf{dvips} (with
274 the \textsf{-z} option), \textsf{\hologo{OzTeX}}, and \textsf{Textures})
275 \item[dvips] produces \verb|\special| commands tailored for \textsf{dvips}. This is the default driver if dvi mode is
276 detected.
277 \item[dvipsone] produces \verb|\special| commands tailored for \textsf{dvipsone}
278 \item[ps2pdf] a special case of output suitable for processing by earlier versions of Ghost\-script's
279 PDF writer; this is basically the same as that for \textsf{dvips}, but a few variations remained before version 5.21
280 \item[tex4ht] produces \verb|\special| commands for use with \textsf{\TeX4ht}, autodetected.
281 \item[pdftex] pdf\TeX, \hologo{HanTheThanh}'s \TeX{} variant that writes PDF directly, autodetected.
282 \item[luatex] lua\TeX, Unicode \TeX{} variant that writes PDF directly, autodetected.
283 \item[dvipdfm] produces \verb|\special| commands for Mark Wicks' DVI to PDF driver \textsf{dvipdfm}
284 \item[dvipdfmx] produces \verb|\special| commands for driver
285 \textsf{dvipdfmx}, a successor of \textsf{dvipdfm}
286 \item[dviwindo] produces \verb|\special| commands that Y\&Y's Windows previewer interprets as hypertext jumps within the previewer
287 \item[vtex] produces \verb|\special| commands that MicroPress' HTML and
288 PDF-producing \TeX\ variants interpret as hypertext jumps within the
289 previewer, autodetected.
290 \item[textures] produces \verb|\special| commands that \textsf{Textures} interprets as hypertext jumps within the previewer
291 \item[xetex] produces \verb|\special| commands for Xe\TeX{}, autodetected.
292 \item[hitex] (new 2023) for the hint format produces by the Hi\TeX{} engine, autodetected. This a quite experimental
293 engine and the driver file is not part of the \xpackage{hyperref} bundle but is provided by
294 the \xpackage{hitex} package. Problems should be reported to \url{https://github.com/ruckertm/HINT}.
295 \end{description}
296
297 Output from \textsf{dvips} or \textsf{dvipsone} must be processed using
298 Acrobat Distiller to obtain a PDF file.\footnote{Make sure you turn off
299 the partial font downloading supported by \textsf{dvips} and
300 \textsf{dvipsone} in favor of Distiller's own system.} The result is
301 generally preferable to that produced by using the \textsf{hypertex}
302 driver, and then processing with \textsf{dvips -z}, but the DVI file is
303 not portable. The main advantage of using the Hyper\TeX\ \ci{special}
304 commands is that you can also use the document in hypertext DVI viewers,
305 such as \textsf{xdvi}.
306
307 \begin{description}
308 \item[driverfallback]
309 If a driver is not given and cannot be autodetected, then use
310 the driver option, given as value to this option \textsf{driverfallback}.
311 Example:
312 \begin{quote}
313 \texttt{driverfallback=dvipdfm}
314 \end{quote}
315 Autodetected drivers (\textsf{pdftex}, \textsf{luatex}, \textsf{xetex}, \textsf{vtex},
316 \textsf{vtexpdfmark}, \textsf{hitex}) are recognized from within \TeX\ and
317 therefore cannot be given as value to option \textsf{driverfallback}.
318 However a DVI driver program is run after the \TeX\ run is finished.
319 Thus it cannot be detected at \TeX\ macro level. Then package
320 \xpackage{hyperref}
321 uses the driver, given by \textsf{driverfallback}. If the driver
322 is already specified or can be autodetected, then option
323 \textsf{driverfallback} is ignored.
324 \end{description}
325
326 \section{Implicit behavior}
327
328 This package can be used with more or less any normal \LaTeX\ document
329 by specifying in the document preamble
330
331 \begin{verbatim}
332 \usepackage{hyperref}
333 \end{verbatim}
334
335 Make sure it comes \emph{last} of your loaded packages, to give it a
336 fighting chance of not being over-written, since its job is to redefine
337 many \LaTeX\ commands.\footnote{But work has started to reduce the
338 number of redefinition and so the dependencies on the loading order.}
339
340 \emph{Do not load it in \ci{AtBeginDocument} or the \texttt{begindocument} hook!}
341 While this often worked in the past this is not officially supported.
342 As \xpackage{hyperref} and \xpackage{nameref} use this hook too to initialize commands,
343 timing of code execution is tricky and fragile if the packages are loaded there.
344 If you want to delay the loading, use the \texttt{begindocument/before} hook.
345
346 Hopefully you will find that all cross-references
347 work correctly as hypertext. For example, \ci{section} commands will
348 produce a bookmark and a link, whereas \ci{section*} commands will only
349 show links when paired with a corresponding \ci{addcontentsline}
350 command.
351
352 In addition, the \texttt{hyperindex} option (see below) attempts to make
353 items in the index by hyperlinked back to the text, and the option
354 \texttt{backref} inserts extra `back' links into the bibliography for
355 each entry. Other options control the appearance of links, and give
356 extra control over PDF output. For example, \texttt{colorlinks}, as its
357 name well implies, colors the links instead of using boxes; this is the
358 option used in this document.
359
360 \section{Interfaces for class and package authors}
361
362 hyperlink features are nowadays a common requirement. \xpackage{hyperref}
363 patches quite a number of commands from the \LaTeX{} core and from packages
364 to add such features. But this is rather fragile and it add dependencies
365 on the loading order and can break if the external packages changes.
366 It is therefore much better if packages add suitable support to their commands directly.
367 Quite a lot packages actually did this, but due to missing documentation of the interface
368 they often looked into the code and then used internal commands not meant as public command.
369
370 The following tries to describe the existing variables and commands that
371 can be viewed as public interfaces or which should or can be set by packages
372 to stay compatible with the \xpackage{hyperref} command. Documented user commands
373 are naturally interfaces too, they are not explicitly mentioned here again.
374
375 This section is work in progress. Suggestions or comments are welcome.
376
377
378 \subsection{Counters}
379 Counters play an important part in the code. They are used to create destination names and
380 to define hierarchies like the bookmarks. To work correctly often they require some additional
381 setups.
382
383 \begin{description}
384
385 \item[\cs{theH<counter>}] \xpackage{hyperref} creates destination names for
386 link anchor typically out of the name of the counter and the \cs{the<counter>} value.
387 This can fail, e.g. if \cs{the<counter>} is not unique through the document,
388 or if it is not expandable. In such cases \cs{theH<counter>} should be defined so that
389 it gives a unique, expandable value. It doesn't harm to define it even if
390 \xpackage{hyperref} is not loaded.
391
392 \item[\cs{toclevel@<counter>}] This is a variable which should contain a number.
393 It is used for the level in the bookmarks. It should be defined for all counters
394 which are used in toc like lists and \cs{addcontentsline}. Typical values are
395
396 \begin{verbatim}
397 \def\toclevel@part{-1}
398 \def\toclevel@chapter{0}
399 \def\toclevel@section{1}
400 \def\toclevel@subsection{2}
401 \def\toclevel@subsubsection{3}
402 \def\toclevel@paragraph{4}
403 \def\toclevel@subparagraph{5}
404 \def\toclevel@figure{0}
405 \end{verbatim}
406
407 \end{description}
408
409 \subsection{Values of package and \cs{hypersetup} options}
410 When\marginpar{\tiny New in version 7.00s}
411 a key is set either in the package options or with
412 \cs{hypersetup} \xpackage{hyperref} typically
413 stores the result in internal variables, or executes some
414 code or sets a internal boolean.
415 Package and class authors should here \emph{not} rely on
416 the names or the details of the key processing.
417
418 But as other packages sometimes need to know which value has been set,
419 some values can be retrieved with the expandable
420 \cs{GetDocumentProperties}. The values are given back
421 surrounded by \cs{exp\_not:n}, so can be used safely in an \cs{edef}.
422 So for example to get the pdfauthor you can do.
423
424 \begin{verbatim}
425 \edef\mypdfauthor{\GetDocumentProperties{hyperref/pdfauthor}}
426 \end{verbatim}
427
428 The values are given back as entered by the user! If they should be used in a PDF context
429 \cs{pdfstringdef} or something equivalent must still be applied.
430
431 Currently this interface can be used for the keys \texttt{pdfauthor}, \texttt{pdftitle},
432 \texttt{pdfproducer},
433 \texttt{pdfcreator}, \texttt{pdfsubject} and \texttt{pdfkeywords}.
434 If used with a unknown key an empty value is returned.
435 The interface works also if the new PDF management is loaded with \cs{DocumentMetadata}, in this
436 case more keys gives back their value.
437
438
439 \subsection{Links commands}
440 The following commands are provided by all drivers to create links.
441 They can be used by packages if the user commands are not sufficient.
442 New drivers must provide these commands with similar arguments.
443
444 \begin{verbatim}
445 \hyper@anchor {destination name}
446 \hyper@anchorstart {destination name}
447 \hyper@anchorend
448 \hyper@link {context}{destination name}{link text} %GoTo
449 \hyper@linkstart {context} {destination name} %GoTo
450 \hyper@linkend %GoTo
451 \hyper@linkfile {link text} {filename} {destname} %GoToR
452 \hyper@linkurl {link text}{url} %URI
453 \hyper@linklaunch{filename} {link text} {Parameters} %Launch, only with new generic driver
454 \hyper@linknamed {action}{link text} %Named, only with new generic driver
455 \end{verbatim}
456
457 \subsection{Creating targets}
458
459 Internal links and bookmarks need something they can jump to. In a PDF this is normally called
460 a \emph{destination} (and the primitive is therefore called \cs{pdfdest}), in HTML it is more
461 common to call this an \emph{anchor} (and the \xpackage{hyperref} uses therefore \cs{hyper@anchor}).
462 History can not be undone but future commands and descriptions will use the generic
463 \emph{target} unless the PDF specific destination is meant.
464
465 Targets are created automatically when \cs{refstepcounter} is used and in many cases this
466 does the right thing and nothing more is needed.
467 But there are exceptions:
468 \begin{itemize}
469 \item A needed target can be missing for example
470 if a sectioning command doesn't have a number as the starred version is used or due to the
471 setting of \texttt{secnumdepth}.
472 \item The target created by the \cs{refstepcounter} can be in the wrong place.
473 \item The target created by the \cs{refstepcounter} can affect spacing.
474 \item The target name created by the \cs{refstepcounter} is not usable, e.g. in
475 \cs{bibitem} where you need a target name bases on the bib-key.
476 \end{itemize}
477
478 Package authors and users can use the following commands to create and manipulate
479 targets. The commands are described in more detail in \texttt{hyperref-linktarget.pdf}.
480
481 \begin{verbatim}
482 \MakeLinkTarget
483 \LinkTargetOff
484 \LinkTargetOn
485 \NextLinkTarget
486 \SetLinkTargetFilter
487 \end{verbatim}
488
489 The first four commands will be defined also in \LaTeX{} directly as no-op and so can be
490 used even if \xpackage{hyperref} is not loaded.
491
492 Until \LaTeX{} is updated package authors can also provide these definitions directly:
493
494 \begin{verbatim}
495 \ProvideDocumentCommand\MakeLinkTarget{sO{}m}{}
496 \ProvideDocumentCommand\LinkTargetOn{}{}
497 \ProvideDocumentCommand\LinkTargetOff{}{}
498 \ProvideDocumentCommand\NextLinkTarget{m}{}
499 \end{verbatim}
500
501 \subsection{Patches and how to suppress them}
502
503 The patches to external commands made by
504 \xpackage{hyperref} can be avoided completely by loading \xpackage{hyperref}
505 with the option \texttt{implicit=false}.
506 But suppressing everything is often too drastic.
507 There is a work in progress to classify
508 the patches and to offer interfaces to suppress them in a more granular way.
509
510 \begin{description}
511 \item[sectioning commands]
512 \begin{itemize}
513 \item \xpackage{hyperref} patches \cs{@sect}, \cs{@ssect}, \cs{@chapter}, \cs{@schapter},
514 \cs{@part}, \cs{@spart}.
515
516 \item It adds to the starred commands a target for a link (with the
517 prefix \texttt{chapter*} for chapters and \texttt{section*} otherwise).
518 To the other commands it adds a target for a link
519 if the sectioning is unnumbered, e.g. because of the \texttt{secnumdepth}
520 setting or in the front matter.
521
522 \item The patch can be suppressed by defining the command \cs{hyper@nopatch@sectioning}.
523 This should normally be done only by a class or a package
524 which provides sectioning commands and adds the targets itself.
525 Targets have a location on the page and e.g. the section commands should take indents into
526 account. Targets are needed for bookmarks and the table of contents,
527 so \cs{@currentHref} should get the correct meaning before
528 \cs{addcontentsline} is used.
529
530 \item Note that the \xpackage{nameref} package patches these commands too
531 to add commands to store the title text in \cs{@currentlabelname}.
532 Check the \xpackage{nameref} documentation about a way to suppress these patches.
533 \end{itemize}
534
535 \item[footnotes] To enable (partly) the linking of footnotes \xpackage{hyperref} redefines or patches various commands, in part package dependent.
536 \begin{itemize}
537 \item \xpackage{hyperref} redefines \cs{@xfootnotenext}, \cs{@xfootnotemark}, \cs{@mpfootnotetext},
538 \cs{@footnotetext}, \cs{@footnotemark}.
539 If \xpackage{tabularx} is loaded it changes \cs{TX@endtabularx}. If \xpackage{longtable} is loaded it changes \cs{LT@p@ftntext}.
540 If \xpackage{fancyvfb} is loaded it redefines \cs{V@@footnotetext}. It also redefines \cs{footref} and \cs{maketitle}.
541
542 \item \emph{All} those redefinitions can be suppressed by defining \cs{hyper@nopatch@footnote}. Be aware that this can suppress links but also make unwanted links appear.
543 \end{itemize}
544
545 \item[amsmath tags] \xpackage{hyperref} redefines two internal commands of amsmath
546 related the \cs{tag} command to add an anchor. This code can be
547 suppressed by defining \cs{hyper@nopatch@amsmath@tag}. (This normally
548 makes no sense in packages but will probably be needed when math
549 environments are changed to allow tagging.)
550
551 \item[counters] \xpackage{hyperref} patches the kernel command \cs{@definecounter},
552 \cs{@newctr}, \cs{@addtoreset} and the amsmath command \cs{numberwithin}
553 to ensure that for every counter the correct \cs{theHcounter}
554 representation is created or reset. This code can be suppressed by
555 defining \cs{hyper@nopatch@counter}. (This normally makes no sense in
556 packages but will probably be needed when kernel commands are changed
557 to allow tagging.)
558
559 \item[math environments] \xpackage{hyperref} patches \cs{equation}/\cs{endequation}, \cs{eqnarray},
560 \cs{endeqnarray}. This code can be suppressed by
561 defining \cs{hyper@nopatch@mathenv}.
562
563 \item[table of contents] \xpackage{hyperref} redefines \cs{contentsline} to be able to add links to
564 toc entries. It redefines \cs{addcontentsline} to create the bookmarks and pass the
565 destination names to the toc entries. This code can be suppressed by defining \cs{hyper@nopatch@toc}.
566
567 \item[captions] \xpackage{hyperref} redefines \cs{caption} and \cs{@caption} to insert targets for links.
568 This code can be suppressed by defining \cs{hyper@nopatch@caption} (additional helper commands are
569 not suppressed). As various packages redefine captions too (e.g. the \xpackage{caption} package)
570 side-effects must be carefully tested!
571
572 \item[longtable] \xpackage{hyperref} redefines \cs{LT@start} and \cs{LT@array} to move the targets in a better place.
573 This code can be suppressed by defining \cs{hyper@nopatch@longtable}
574
575 \item[theorems] \xpackage{hyperref} patches \cs{@thm}. This code can be suppressed by defining \cs{hyper@nopatch@thm}
576
577 \item[citations and bibliography] If \xpackage{natbib} is not loaded \xpackage{hyperref} redefines \cs{bibcite},
578 \cs{@lbibitem} and \cs{@bibitem}. These redefinitions can be suppressed by defining \cs{hyper@nopatch@bib}.
579 \end{description}
580
581 \section{Package options}
582
583 All user-configurable aspects of \xpackage{hyperref} are set using a
584 single `key=value' scheme (using the \xpackage{keyval} package) with the
585 key \texttt{Hyp}. The options can be set either in the optional argument
586 to the \cs{usepackage} command, or using the \cs{hypersetup}
587 macro. When the package is loaded, a file \texttt{hyperref.cfg} is read
588 if it can be found, and this is a convenient place to set options on a
589 site-wide basis.
590
591 Note however that some options (for example \texttt{unicode}) can only be used as
592 package options, and not in \verb|\hypersetup| as the option settings are processed
593 as the package is read. The following tabular lists (hopefully all) these options.
594 Be aware that some of the options do nothing or have
595 changed behaviour if the new pdfmanagement and so the new generic \xpackage{hyperref} driver is used.
596
597 \begin{tabular}{>{\ttfamily}l>{\raggedright\arraybackslash}p{5cm}}
598 option & remark \\\hline
599 all driver options, e.g. \texttt{pdftex} & often not needed, as detected automatically\\
600 implicit \\
601 pdfa & no-op with new pdfmanagement, set the standard in \cs{DocumentMetadata}.\\
602 unicode & is the default now anyway\\
603 pdfversion & no-op with new pdfmanagement, set the version in \cs{DocumentMetadata}.\\
604 bookmarks & this will probably change at some time. \\
605 backref &\\
606 pagebackref & \\
607 destlabel &\\
608 pdfusetitle &\\
609 pdfpagelabels &\\
610 hyperfootnotes &\\
611 hyperfigures&\\
612 hyperindex &\\
613 encap &\\
614 CJKbookmarks & only with the new pdfmanagement, in other cases it can be used in \cs{hypersetup}\\
615 psdextra & only with the new pdfmanagement, in other cases it can be used in \cs{hypersetup}\\
616 nesting & only with the new pdfmanagement, in other cases it can be used in \cs{hypersetup} (but
617 is quite unclear if it has any use)\\
618
619 \end{tabular}
620
621 As an example, the behavior of a particular file could be controlled by:
622 \begin{itemize}
623
624 \item a site-wide \texttt{hyperref.cfg} setting up the look of links,
625 adding backreferencing, and setting a PDF display default:
626
627 \begin{verbatim}
628 \hypersetup{backref,
629 pdfpagemode=FullScreen,
630 colorlinks=true}
631 \end{verbatim}
632
633 \item A global option in the file, which is passed down to
634 \xpackage{hyperref}:
635
636 \begin{verbatim}
637 \documentclass[dvips]{article}
638 \end{verbatim}
639
640 \item File-specific options in the \cs{usepackage} commands, which
641 override the ones set in \texttt{hyperref.cfg}:
642
643 \begin{verbatim}
644 \usepackage[colorlinks=false]{hyperref}
645 \hypersetup{pdftitle={A Perfect Day}}
646 \end{verbatim}
647 \end{itemize}
648
649 As seen in the previous example, information entries
650 (pdftitle, pdfauthor, \dots) should be set after the package is loaded.
651 Otherwise \LaTeX\ expands the values of these options prematurely.
652 Also \LaTeX\ strips spaces in options. Especially option `pdfborder'
653 requires some care. Curly braces protect the value, if given
654 as package option. They are not necessary in \verb|\hypersetup|.
655
656 \begin{verbatim}
657 \usepackage[pdfborder={0 0 0}]{hyperref}
658 \hypersetup{pdfborder=0 0 0}
659 \end{verbatim}
660
661 Some options can be given at any time, but many are restricted: before
662 \verb|\begin{document}|, only in \verb|\usepackage[...]{hyperref}|,
663 before first use, etc.
664
665 In the key descriptions that follow, many options do not need a value,
666 as they default to the value true if used. These are the ones classed as
667 `boolean'. The values true and false can always be specified, however.
668
669
670 \subsection{General options}
671
672 Firstly, the options to specify general behavior and page size.
673
674 \medskip
675 \begin{longtable}{>{\ttfamily}ll>{\itshape}ll}
676 draft & boolean & false & all hypertext options are turned off \\
677 final & boolean & true & all hypertext options are turned on \\
678 debug & boolean & false & extra diagnostic messages are printed in \\
679 & & & the log file \\
680 verbose & boolean & false & same as debug \\
681 implicit & boolean & true & redefines \LaTeX\ internals \\
682 setpagesize & boolean & true & sets page size by special driver commands
683 \end{longtable}
684
685 \subsection{Options for destination names}
686
687 Destinations names (also anchor, target or link names) are internal
688 names that identify a position on a page in the document. They
689 are used in link targets for inner document links or the bookmarks,
690 for example.
691
692 Usually anchors are set, if \cs{refstepcounter} is called.
693 Thus there is a counter name and value. Both are used to
694 construct the destination name. By default the counter value
695 follows the counter name separated by a dot. Example for
696 the fourth chapter:
697 \begin{quote}
698 \verb|chapter.4|
699 \end{quote}
700 This scheme is used by:
701 \begin{description}
702 \item[\cs{autoref}] displays the description label for the
703 reference depending on the counter name.
704 \item[\cs{hyperpage}] is used by the index to get
705 page links. Page anchor setting (\verb|pageanchor|) must not
706 be turned off.
707 \end{description}
708
709 It is very important that the destination names are unique,
710 because two destinations must not share the same name.
711 The counter value \cs{the<counter>} is not always unique
712 for the counter. For example, table and figures can be numbered
713 inside the chapter without having the chapter number in their
714 number. Therefore \xpackage{hyperref} has introduced \cs{theH<counter>}
715 that allows a unique counter value without messing up with
716 the appearance of the counter number. For example, the number
717 of the second table in the third chapter might be printed
718 as \texttt{2}, the result of \cs{thetable}. But the
719 destination name \texttt{table.2.4} is unique because it
720 has used \cs{theHtable} that gives \verb|2.4| in this case.
721
722 Often the user do not need to set \cs{theH<counter>}. Defaults
723 for standard cases (chapter, \dots) are provided. And after \xpackage{hyperref}
724 is loaded, new counters with parent counters also define
725 \cs{theH<counter>} automatically, if \cs{newcounter}, \cs{@addtoreset}
726 or \cs{numberwithin} of package \xpackage{amsmath} are used.
727
728 Usually problems with duplicate destination names can be solved
729 by an appropriate definition of \cs{theH<counter>}. If option
730 \texttt{hypertexnames} is disabled, then a unique artificial
731 number is used instead of the counter value. In case of page
732 anchors the absolute page anchor is used. With option \texttt{plainpages}
733 the page anchors use the arabic form. In both latter cases \cs{hyperpage}
734 for index links is affected and might not work properly.
735
736 If an unnumbered entity gets an anchor (starred forms of
737 chapters, sections, \dots) or \cs{phantomsection} is used,
738 then the dummy counter name \texttt{section*} and an artificial
739 unique number is used.
740
741 If the final PDF file is going to be merged with another file, than
742 the destination names might clash, because both documents might
743 contain \texttt{chapter.1} or \texttt{page.1}. Also \xpackage{hyperref}
744 sets anchor with name \texttt{Doc-Start} at the begin of the document.
745 This can be resolved by redefining \cs{HyperDestNameFilter}.
746 Package \xpackage{hyperref} calls this macro each time, it uses a
747 destination name.
748 The macro must be expandable and expects the destination name
749 as only argument. As example, the macro is redefined to add
750 a prefix to all destination names:
751 \begin{quote}
752 \begin{verbatim}
753 \renewcommand*{\HyperDestNameFilter}[1]{\jobname-#1}
754 \end{verbatim}
755 \end{quote}
756 In document \texttt{docA} the destination name \texttt{chapter.2}
757 becomes \texttt{docA-chapter.2}.
758
759 Destination names can also be used from the outside in URIs, (if the
760 driver has not removed or changed them), for example:
761 \begin{quote}
762 \begin{verbatim}
763 http://somewhere/path/file.pdf#nameddest=chapter.4
764 \end{verbatim}
765 \end{quote}
766 However using a number seems unhappy. If another chapter is added
767 before, the number changes. But it is very difficult to pass
768 a new name for the destination to the anchor setting process that
769 is usually deep hidden in the internals. The first name of
770 \cs{label} after the anchor setting seems a good approximation:
771 \begin{quote}
772 \begin{verbatim}
773 \section{Introduction}
774 \label{intro}
775 \end{verbatim}
776 \end{quote}
777 Option \texttt{destlabel} checks for each \cs{label}, if there is
778 a new destination name active and replaces the destination
779 name by the label name. Because the destination name is already in use
780 because of the anchor setting, the new name is recorded in the \texttt{.aux}
781 file and used in the subsequent \hologo{LaTeX} run. The renaming is done by
782 a redefinition of \cs{HyperDestNameFilter}. That leaves the old
783 destination names intact (e.g., they are needed for \cs{autoref}).
784 This redefinition is also available as \cs{HyperDestLabelReplace},
785 thus that an own redefinition can use it.
786 The following example also adds a prefix for \emph{all} destination names:
787 \begin{quote}
788 \begin{verbatim}
789 \renewcommand*{\HyperDestNameFilter}[1]{%
790 \jobname-\HyperDestLabelReplace{#1}%
791 }
792 \end{verbatim}
793 \end{quote}
794 The other case that only files prefixed that do not have a corresponding
795 \cs{label} is more complicated, because \cs{HyperDestLabelReplace} needs
796 the unmodified destination name as argument. This is solved by an
797 expandable string test (\cs{pdfstrcmp} of \hologo{pdfTeX}
798 or \cs{strcmp} of \hologo{XeTeX}, package \xpackage{pdftexcmds} also supports
799 \hologo{LuaTeX}):
800 \begin{quote}
801 \begin{verbatim}
802 \usepackage{pdftexcmds}
803 \makeatletter
804 \renewcommand*{\HyperDestNameFilter}[1]{%
805 \ifcase\pdf@strcmp{#1}{\HyperDestLabelReplace{#1}} %
806 \jobname-#1%
807 \else
808 \HyperDestLabelReplace{#1}%
809 \fi
810 }
811 \makeatother
812 \end{verbatim}
813 \end{quote}
814
815 With option \texttt{destlabel} destinations can also be named manually,
816 if the destination is not yet renamed:
817 \begin{quote}
818 \verb|\HyperDestRename{|\meta{destination}\verb|}{|\meta{newname}\verb|}|
819 \end{quote}
820
821 Hint: Anchors can also be named and set by \cs{hypertarget}.
822
823 \medskip
824 \begin{longtable}{>{\ttfamily}ll>{\itshape}ll}
825 destlabel & boolean & false & destinations are named by first \cs{label}\\
826 & & & after anchor creation\\
827 hypertexnames & boolean & true & use guessable names for links \\
828 naturalnames & boolean & false & use \LaTeX-computed names for links \\
829 plainpages & boolean & false & Forces page anchors to be named by the Arabic form \\
830 & & & of the page number, rather than the formatted form. \\
831 \end{longtable}
832
833 \subsection{Page anchors}
834
835 In a PDF \xpackage{hyperref} adds to every page an target for links (in the upper left corner). These targets are for example used by the index to references the pages of the entries. Unlike the targets generated by other counters it is not possible to change the names of these targets by defining a \cs{theHpage} command: the name can currently not be stored in a label and so is not referenceable. Nevertheless a few options exists, they are already mentioned elsewhere in the documentation but we provide here a summary:
836
837 \begin{description}
838 \item[\texttt{pageanchor}] A boolean option that determines whether every page is given an target at the top left corner. If this is turned off, \verb|\printindex| will not contain valid hyperlinks.
839 \item[\texttt{hypertexnames}] By default the targets have names built with \cs{thepage}: \verb|page.\thepage|, so e.g., \texttt{page.4} or \texttt{page.iii}. The names require that every page as an unique number representation. A frequent problem here is with title pages which often don't show page numbers but internally use the same number as a following page. If you get messages about \texttt{destination with the same identifier (name{page.1})}, change the number representation of title pages or disable the page target.
840
841 If the boolean option \texttt{hypertexnames} is set to false, an internal page counter is stepped and used as arabic number. In most cases this should mean that you get the absolute page number (exceptions could be with documents throwing away or duplicating pages at shipout). This option avoids the problem with duplicated identifiers, but does not work with an index, as the backlinks have to be created from the representation passed to the index.
842 \item[\texttt{plainpages}] This forces page anchors to be named by the arabic form, but unlike the previous option it does not use an internal counter but the page counter. That means if you have for example roman and arabic pages you will get duplicated target names as page i and page 1 both set the anchor \texttt{page.1}.
843 \end{description}
844
845 \begin{cmdsyntax}
846 \ci{@currentHpage}
847 \end{cmdsyntax}
848 Starting with version 7.01c \xpackage{hyperref} stores the name of the page
849 target it has just set into the (global) variable \cs{@currentHpage}. The
850 fallback value is \texttt{Doc-Start}. As the target is set when the page is
851 shipout, \cs{@currentHpage} is only reliable at shipout. With a
852 \hologo{LaTeX} format from 2023-11-01 the name can be labeled like this:
853
854 \begin{verbatim}
855 %labeling in the document
856 \RecordProperties{mylabel}{pagetarget}
857 %linking to the page:
858 \hyperlink{\RefProperty{mylabel}{pagetarget}}{some text}
859 \end{verbatim}
860
861
862
863 \subsection{Configuration options}
864
865 \begin{longtable}{>{\ttfamily}ll>{\itshape}lp{9cm}}
866 raiselinks & boolean & true & In the hypertex driver, the height of links is normally calculated by the driver as
867 simply the base line of contained text; this option forces \verb|\special| commands to
868 reflect the real height of the link (which could contain a graphic) \\
869 breaklinks & boolean & both & This option is in \xpackage{hyperref} only used in the dviwindo driver, in all other cases it doesn't do anything sensible---it neither allows nor prevents links to be broken. The ocgx2 package
870 checks the state of the boolean.\\
871 pageanchor & boolean & true & Determines whether every page is given an implicit anchor at the top left corner. If this
872 is turned off, \verb|\printindex| will not contain
873 valid hyperlinks. \\
874 nesting & boolean & false & Allows links to be nested; no drivers currently support this.
875 \end{longtable}
876
877 Note for option \verb|breaklinks|:
878 The correct value is automatically set according to the driver features.
879 It can be overwritten for drivers that do not support broken links.
880 However, at any case, the link area will be wrong and displaced.
881
882 \subsection{Backend drivers}
883
884 If no driver is specified, the package tries to find a driver in
885 the following order:
886 \begin{enumerate}
887 \item Autodetection, some \TeX\ processors can be detected at \TeX\ macro
888 level (pdf\TeX, Xe\TeX, V\TeX).
889 \item Option \textsf{driverfallback}. If this option is set, its value
890 is taken as driver option.
891 \item Macro \cs{Hy@defaultdriver}. The macro takes a driver file
892 name (without file extension).
893 \item Package default is \textsf{hypertex}.
894 \end{enumerate}
895 Many distributions are using a driver file \texttt{hypertex.cfg} that
896 define \cs{Hy@defaultdriver} with \texttt{hdvips}. This is recommended
897 because driver \textsf{dvips} provides much more features than
898 \textsf{hypertex} for PDF generation.
899
900 \begin{longtable}{@{}>{\ttfamily}lp{.8\hsize}@{}}
901 driverfallback & Its value is used as driver option\\
902 & if the driver is not given or autodetected.\\
903 dvipdfm & Sets up \xpackage{hyperref} for use with the \textsf{dvipdfm} driver.\\
904 dvipdfmx & Sets up \xpackage{hyperref} for use with the \textsf{dvipdfmx} driver.\\
905 dvips & Sets up \xpackage{hyperref} for use with the \textsf{dvips} driver. \\
906 dvipsone & Sets up \xpackage{hyperref} for use with the \textsf{dvipsone} driver. \\
907 dviwindo & Sets up \xpackage{hyperref} for use with the \textsf{dviwindo} Windows previewer. \\
908 hypertex & Sets up \xpackage{hyperref} for use with the Hyper\TeX-compliant drivers. \\
909 latex2html & Redefines a few macros for compatibility with \textsf{latex2html}. \\
910 nativepdf & An alias for \textsf{dvips} \\
911 pdfmark & An alias for \textsf{dvips} \\
912 pdftex & Sets up \xpackage{hyperref} for use with the \textsf{pdftex} program.\\
913 ps2pdf & Redefines a few macros for compatibility with
914 Ghostscript's PDF writer, otherwise identical to
915 \textsf{dvips}. \\
916 tex4ht & For use with \textsf{\TeX4ht} \\
917 textures & For use with \textsf{Textures} \\
918 vtex & For use with MicroPress' \textsf{VTeX}; the PDF
919 and HTML backends are detected automatically. \\
920 vtexpdfmark & For use with \textsf{VTeX}'s PostScript backend. \\
921 xetex & For use with Xe\TeX\ (using backend for dvipdfm).
922 \end{longtable}
923 \smallskip
924
925 If you use \textsf{dviwindo}, you may need to redefine the macro
926 \ci{wwwbrowser} (the default is \verb|C:\netscape\netscape|) to tell
927 \textsf{dviwindo} what program to launch. Thus, users of Internet
928 Explorer might add something like this to hyperref.cfg:
929
930 \begin{verbatim}
931 \renewcommand{\wwwbrowser}{C:\string\Program\space
932 Files\string\Plus!\string\Microsoft\space
933 Internet\string\iexplore.exe}
934 \end{verbatim}
935
936 \subsection{Extension options}
937 \begin{longtable}{@{}>{\ttfamily}ll>{\itshape}lp{8cm}@{}}
938 extension & text & & Set the file extension (e.g.\ \textsf{dvi}) which will be appended to file links
939 created if you use the \xpackage{xr} package. \\
940 hyperfigures & boolean & & \\
941 backref & text & false & Adds `backlink' text to the end of each item in the bibliography, as a list of
942 section numbers. This can only work properly \emph{if} there is a blank line after
943 each \verb|\bibitem|. Supported values are \verb|section|, \verb|slide|, \verb|page|,
944 \verb|none|, or \verb|false|. If no value is given, \verb|section| is taken as default.\\
945 pagebackref & boolean & false & Adds `backlink' text to the end of each item in the bibliography, as a list of page
946 numbers. \\
947 hyperindex & boolean & true & Makes the page numbers of index entries into hyperlinks. Relays on unique
948 page anchors (\verb|pageanchor|, \ldots)
949 \verb|pageanchors| and \verb|plainpages=false|. \\
950 hyperfootnotes & boolean & true & Makes the footnote marks into hyperlinks to the footnote text.
951 Easily broken \ldots\\
952 encap & & & Sets encap character for hyperindex \\
953 linktoc & text & section & make text (\verb|section|), page number (\verb|page|), both (\verb|all|) or nothing (\verb|none|) be link on TOC, LOF and LOT \\
954 linktocpage & boolean & false & make page number, not text, be link on TOC, LOF and LOT \\
955 breaklinks & boolean & false & allow links to break over lines by making links over multiple lines into PDF links to
956 the same target \\
957 colorlinks & boolean & false & Colors the text of links and anchors. The colors chosen depend on the type of
958 link. At present the only types of link distinguished are citations, page references,
959 URLs, local file references, and other links.
960 Unlike colored boxes, the colored
961 text remains when printing.\\
962 linkcolor & color & red & Color for normal internal links. \\
963 anchorcolor & color & black & Color for anchor text. Ignored by most drivers. \\
964 citecolor & color & green & Color for bibliographical citations in text. \\
965 filecolor & color & cyan & Color for URLs which open local files. \\
966 menucolor & color & red & Color for Acrobat menu items. \\
967 runcolor & color & filecolor & Color for run links (launch annotations). \\
968 urlcolor & color & magenta & Color for linked URLs. \\
969 allcolors & color & & Set all color options (without border and field options).\\
970 frenchlinks & boolean & false & Use small caps instead of color for links.\\
971 hidelinks & & & Hide links (removing color and border). \\
972 \end{longtable} \smallskip
973
974 Note that all color names must be defined before use, following the
975 normal system of the standard \LaTeX\ \xpackage{color} package.
976
977 \subsection{PDF-specific display options}
978 \begin{longtable}{@{}>{\ttfamily}ll>{\itshape}lp{7.6cm}@{}}
979 bookmarks & boolean & true & A set of Acrobat bookmarks are written, in a manner similar to the
980 table of contents, requiring two passes of \LaTeX. Some postprocessing
981 of the bookmark file (file extension \texttt{.out}) may be needed to
982 translate \LaTeX\ codes, since bookmarks must be written in PDFEncoding.
983 To aid this process, the \texttt{.out} file is not rewritten by \LaTeX\
984 if it is edited to contain a line \verb|\let\WriteBookmarks\relax| \\
985 bookmarksopen & boolean & false & If Acrobat bookmarks are requested, show them with all the subtrees
986 expanded. \\
987 bookmarksopenlevel & parameter & & level (\ci{maxdimen}) to which bookmarks are open \\
988 bookmarksnumbered & boolean & false & If Acrobat bookmarks are requested, include section numbers. \\
989 bookmarkstype & text & toc & to specify which `toc' file to mimic \\
990 CJKbookmarks & boolean & false &
991 This option should be used to produce CJK bookmarks.
992 Package \verb|hyperref|
993 supports both normal and preprocessed mode of the \xpackage{CJK} package;
994 during the creation of bookmarks, it simply replaces CJK's macros
995 with special versions which expand to the corresponding character
996 codes. Note that without the `unicode' option of \xpackage{hyperref} you get
997 PDF files which actually violate the PDF specification because
998 non-Unicode character codes are used -- some PDF readers localized
999 for CJK languages (most notably Acroread itself) support this.
1000 Also note that option `CJKbookmarks' cannot be used together
1001 with option `unicode'.
1002
1003 No mechanism is provided to translate non-Unicode bookmarks to
1004 Unicode; for portable PDF documents only Unicode encoding should
1005 be used.\\
1006 pdfhighlight & name & /I & How link buttons behave when selected; /I is for inverse (the default);
1007 the other possibilities are /N (no effect), /O (outline), and /P (inset
1008 highlighting). \\
1009 citebordercolor & rgb color & 0 1 0 & The color of the box around citations \\
1010 filebordercolor & rgb color & 0 .5 .5 & The color of the box around links to files \\
1011 linkbordercolor & rgb color & 1 0 0 & The color of the box around normal links \\
1012 menubordercolor & rgb color & 1 0 0 & The color of the box around Acrobat menu links \\
1013 urlbordercolor & rgb color & 0 1 1 & The color of the box around links to URLs \\
1014 runbordercolor & rgb color & 0 .7 .7 & Color of border around `run' links \\
1015 allbordercolors & & & Set all border color options \\
1016 pdfborder & & 0 0 1 & The style of box around links; defaults to a box with lines of 1pt thickness,
1017 but the colorlinks option resets it to produce no border.
1018 \end{longtable}
1019
1020 The color of link borders used to be specified \emph{only} as 3
1021 numbers in the range 0..1, giving an rgb color. Since version 6.76a, the usual
1022 color specifications of package \xpackage{(x)color} can be used if \xpackage{xcolor}
1023 has been loaded.
1024 For further information see description of package \xpackage{hycolor}.
1025
1026 The bookmark commands are stored in a file called
1027 \textit{jobname}\texttt{.out}. The file is not processed by \LaTeX\ so
1028 any markup is passed through. You can postprocess this file as needed;
1029 as an aid for this, the \texttt{.out} file is not overwritten on the
1030 next \TeX\ run if it is edited to contain the line
1031 \begin{verbatim}
1032 \let\WriteBookmarks\relax
1033 \end{verbatim}
1034
1035 \subsection{PDF display and information options}\label{sec:pdfdata}
1036 \begin{longtable}{@{}>{\ttfamily}l>{\raggedright}p{\widthof{key value}}>{\itshape}lp{7cm}@{}}
1037 baseurl & URL & & Sets the base URL of the PDF document \\
1038 pdfpagemode & name & empty & Determines how the file is opening in Acrobat; the possibilities are
1039 \verb|UseNone|, \verb|UseThumbs| (show thumbnails), \verb|UseOutlines|
1040 (show bookmarks), \verb|FullScreen|, \verb|UseOC| (PDF 1.5),
1041 and \verb|UseAttachments| (PDF 1.6). If no mode if explicitly chosen, but the
1042 bookmarks option is set, \verb|UseOutlines| is used. \\
1043 pdftitle & text & & Sets the document information Title field \\
1044 pdfauthor & text & & Sets the document information Author field \\
1045 pdfsubject & text & & Sets the document information Subject field \\
1046 pdfcreator & text & & Sets the document information Creator field \\
1047 pdfcreationdate & date & & Sets the creation date, see below the table for more info about the format\\
1048 pdfmoddate & date & & Sets the modification date, see below the table for more info about the format\\
1049 addtopdfcreator & text & & Adds additional text to the document information Creator field \\
1050 pdfkeywords & text & & Sets the document information Keywords field \\
1051 pdftrapped & name & empty & Sets the document information Trapped entry. Possible values are \verb|True|, \verb|False| and \verb|Unknown|.
1052 An empty value means, the entry is not set.\\
1053 %
1054 pdfinfo & key value list & empty & Alternative interface for setting the
1055 document information.\\
1056 pdfview & name & XYZ & Sets the default PDF `view' for each link \\
1057 pdfstartpage & integer & 1 & Determines on which page the PDF file is opened. An empty value means, the entry is not set.\\
1058 pdfstartview & name & Fit & Set the startup page view \\
1059 pdfremotestartview & name & Fit & Set the startup page view of remote PDF files \\
1060 pdfpagescrop & n n n n & & Sets the default PDF crop box for pages. This should be a set of four numbers \\
1061 pdfcenterwindow & boolean & false & position the document window in the center of the screen \\
1062 pdfdirection & name & empty & direction setting. Possible values: \verb|L2R| (left to right) and
1063 \verb|R2L| (right to left)\\
1064 pdfdisplaydoctitle & boolean & false & display document title instead of file name in title bar\\
1065 pdfduplex & name & empty & paper handling option for print dialog. Possible vatues are:
1066 \verb|Simplex| (print single-sided),
1067 \verb|DuplexFlipShortEdge| (duplex and flip on the short edge of the sheet),
1068 \verb|DuplexFlipLongEdge| (duplex and flip on the long edge of the sheet)\\
1069
1070 pdffitwindow & boolean & false & resize document window to fit document size \\
1071 pdflang & name & relax & PDF language identifier (RFC 3066)\\
1072 pdfmenubar & boolean & true & make PDF viewer's menu bar visible \\
1073 pdfnewwindow & boolean & false & make links that open another PDF file start a new window \\
1074 pdfnonfullscreenpagemode
1075 & name & empty & page mode setting on exiting full-screen mode. Possible values are
1076 \verb|UseNone|, \verb|UseOutlines|, \verb|UseThumbs|, and \verb|UseOC|\\
1077 pdfnumcopies & integer & empty & number of printed copies \\
1078 pdfpagelayout & name & empty & set layout of PDF pages. Possible values:
1079 \verb|SinglePage|, \verb|OneColumn|,
1080 \verb|TwoColumnLeft|, \verb|TwoColumnRight|,
1081 \verb|TwoPageLeft|, and \verb|TwoPageRight| \\
1082 pdfpagelabels & boolean & true & set PDF page labels \\
1083 pdfpagetransition & name & empty & set PDF page transition style. Possible values are
1084 \verb|Split|, \verb|Blinds|, \verb|Box|, \verb|Wipe|,
1085 \verb|Dissolve|, \verb|Glitter|, \verb|R|,
1086 \verb|Fly|, \verb|Push|,
1087 \verb|Cover|, \verb|Uncover|,
1088 \verb|Fade|.
1089 The default according to the PDF~Reference is \verb|R|,
1090 which simply replaces the old page with the new one. \\
1091 pdfpicktraybypdfsize
1092 & boolean & false & specify whether PDF page size is used to select input paper tray in print dialog \\
1093 pdfprintarea & name & empty & set /PrintArea of viewer preferences. Possible values are
1094 \verb|MediaBox|, \verb|CropBox|,
1095 \verb|BleedBox|, \verb|TrimBox|, and \verb|ArtBox|.
1096 The default according to the PDF~Reference is \verb|CropBox| \\
1097 pdfprintclip & name & empty & set /PrintClip of viewer preferences. Possible values are
1098 \verb|MediaBox|, \verb|CropBox|,
1099 \verb|BleedBox|, \verb|TrimBox|, and \verb|ArtBox|.
1100 The default according to the PDF~Reference is \verb|CropBox| \\
1101 pdfprintpagerange & n n (n n)*
1102 & empty & set /PrintPageRange of viewer preferences\\
1103 pdfprintscaling & name & empty & page scaling option for print dialog
1104 (option /PrintScaling of viewer
1105 preferences, PDF 1.6);
1106 valid values are \verb|None| and
1107 \verb|AppDefault| \\
1108 pdftoolbar & boolean & true & make PDF toolbar visible \\
1109 pdfviewarea & name & empty & set /ViewArea of viewer preferences. Possible values are
1110 \verb|MediaBox|, \verb|CropBox|,
1111 \verb|BleedBox|, \verb|TrimBox|, and \verb|ArtBox|.
1112 The default according to the PDF~Reference is \verb|CropBox| \\
1113 pdfviewclip & name & empty & set /ViewClip of viewer preferences Possible values are
1114 \verb|MediaBox|, \verb|CropBox|,
1115 \verb|BleedBox|, \verb|TrimBox|, and \verb|ArtBox|.
1116 The default according to the PDF~Reference is \verb|CropBox| \\
1117 pdfwindowui & boolean & true & make PDF user interface elements visible \\
1118 unicode & boolean & true & Unicode encoded PDF strings
1119 \end{longtable}
1120
1121 The dates \verb|CreationDate| and \verb|ModDate|
1122 are normally set automatically to the current date/time when the compilation
1123 started. If they should be changed
1124 (e.g. for regression tests to produce reproducible documents) they can
1125 be set with \verb|\hypersetup| with the keys
1126 \verb|pdfcreationdate|, \verb|pdfmoddate| or externally by setting the \verb|SOURCE_DATE_EPOCH| environment variable.
1127
1128 \begin{verbatim}
1129 \hypersetup{pdfcreationdate=D:20010101205959-00'00'}
1130 \end{verbatim}
1131
1132 The format should be a full date/time in PDF format, so one of these (naturally
1133 the numbers can change):
1134 \begin{verbatim}
1135 D:20010101205959-00'00'
1136 D:20010101205959+00'00'
1137 D:20010101205959Z
1138 \end{verbatim}
1139
1140 Each link in Acrobat carries its own magnification level, which is set
1141 using PDF coordinate space, which is not the same as \TeX's. The unit
1142 is bp and the origin is in the lower left corner. See also
1143 \verb|\hypercalcbp| that is explained on page \pageref{hypercalcbp}.
1144 pdf\TeX\
1145 works by supplying default values for \texttt{XYZ} (horizontal $\times$
1146 vertical $\times$ zoom) and \texttt{FitBH}. However, drivers using
1147 \texttt{pdfmark} do not supply defaults, so \xpackage{hyperref} passes in
1148 a value of -32768, which causes Acrobat to set (usually) sensible
1149 defaults. The following are possible values for the \texttt{pdfview},
1150 \texttt{pdfstartview} and \texttt{pdfremotestartview} parameters.
1151
1152 \begin{longtable}{@{}>{\ttfamily}l>{\itshape}lp{7cm}@{}}
1153 XYZ & left top zoom & Sets a coordinate and a zoom factor. If any one is null, the source link value is used.
1154 \textit{null null null} will give the same values as the current page. \\
1155 Fit & & Fits the page to the window. \\
1156 FitH & top & Fits the width of the page to the window. \\
1157 FitV & left & Fits the height of the page to the window. \\
1158 FitR & left bottom right top & Fits the rectangle specified by the four coordinates to the window. \\
1159 FitB & & Fits the page bounding box to the window. \\
1160 FitBH & top & Fits the width of the page bounding box to the window. \\
1161 FitBV & left & Fits the height of the page bounding box to the window. \\
1162 \end{longtable}
1163
1164 The \texttt{pdfpagelayout} can be one of the following values.
1165
1166 \begin{longtable}{@{}>{\ttfamily}lp{10cm}@{}}
1167 SinglePage & Displays a single page; advancing flips the page \\
1168 OneColumn & Displays the document in one column; continuous scrolling. \\
1169 TwoColumnLeft & Displays the document in two columns, odd-numbered pages to the left. \\
1170 TwoColumnRight & Displays the document in two columns, odd-numbered pages to the right.\\
1171 TwoPageLeft & Displays two pages, odd-numbered pages to the left (since PDF 1.5).\\
1172 TwoPageRight & Displays two pages, odd-numbered pages to the right (since PDF 1.5).
1173 \end{longtable}
1174
1175 Finally, the \texttt{pdfpagetransition} can be one of the following values,
1176 where \textit{/Di} stands for direction of motion in degrees, generally in 90
1177 degree steps, \textit{/Dm} is a horizontal (\texttt{/H}) or vertical
1178 (\texttt{/V}) dimension (e.g.\ \texttt{Blinds /Dm /V}), and \textit{/M} is
1179 for motion, either in (\texttt{/I}) or out (\texttt{/O}).
1180
1181 \begin{longtable}{@{}>{\ttfamily}llp{8.5cm}@{}}
1182 Blinds & /Dm & Multiple lines distributed evenly across the screen sweep in the same direction to reveal the new
1183 page. \\
1184 Box & /M & A box sweeps in or out. \\
1185 Dissolve & & The page image dissolves in a piecemeal fashion to reveal the new page. \\
1186 Glitter & /Di & Similar to Dissolve, except the effect sweeps across the screen. \\
1187 Split & /Dm /M & Two lines sweep across the screen to reveal the new page. \\
1188 Wipe & /Di & A single line sweeps across the screen to reveal the new page. \\
1189 R & & Simply replaces the old page with the new one. \\
1190 Fly & /Di /M & Changes are flown out or in (as specified by /M), in the direction
1191 specified by /Di, to or from a location that is
1192 offscreen except when /Di is None. \\
1193 Push & /Di & The old page slides off the screen while the new page slides in,
1194 pushing the old page out in the direction
1195 specified by /Di. \\
1196 Cover & /Di & The new page slides on to the screen in the direction specified
1197 by /Di, covering the old page. \\
1198 Uncover & /Di & The old page slides off the screen in the direction specified by
1199 /Di, uncovering the new page in the direction
1200 specified by /Di. \\
1201 Fade & & The new page gradually becomes visible through the old one.
1202
1203 \end{longtable}
1204
1205 \subsection{Option \texttt{pdfinfo}}
1206
1207 The information entries can be set using \texttt{pdftitle},
1208 \texttt{pdfsubject}, \dots. Option \texttt{pdfinfo} provides an alternative
1209 interface. It takes a key value list. The key names are the names that
1210 appear in the PDF information dictionary directly. Known keys such as
1211 \texttt{Title}, \texttt{Subject}, \texttt{Trapped} and other are mapped to
1212 options \texttt{pdftitle}, \texttt{subject}, \texttt{trapped}, \dots
1213 Unknown keys are added to the information dictionary. Their values are text
1214 strings (see PDF specification).
1215 Example:
1216 \begin{quote}
1217 \begin{verbatim}
1218 \hypersetup{
1219 pdfinfo={
1220 Title={My Title},
1221 Subject={My Subject},
1222 NewKey={Foobar},
1223 % ...
1224 }
1225 }
1226 \end{verbatim}
1227 \end{quote}
1228
1229 \subsection{Big alphabetical list}
1230
1231 The following is a complete listing of available options for
1232 \xpackage{hyperref}, arranged alphabetically.
1233
1234 \begin{longtable}{@{}>{\ttfamily}llp{7cm}@{}}
1235 allbordercolors & & Set all border color options\\
1236 allcolors & & Set all color options (without border and field options)\\
1237 anchorcolor & \textit{black} & set color of anchors, ignored by most drivers. \\
1238 backref & \textit{false} & do bibliographical back references \\
1239 baseurl & \textit{empty} & set base URL for document \\
1240 bookmarks & \textit{true} & make bookmarks \\
1241 bookmarksnumbered & \textit{false} & put section numbers in bookmarks \\
1242 bookmarksopen & \textit{false} & open up bookmark tree \\
1243 bookmarksopenlevel & \ttfamily\ci{maxdimen} & level to which bookmarks are open \\
1244 bookmarkstype & \textit{toc} & to specify which `toc' file to mimic \\
1245 breaklinks & \textit{false} & allow links to break over lines \\
1246 CJKbookmarks & \textit{false} & to produce CJK bookmarks\\
1247 citebordercolor & \textit{0 1 0} & color of border around cites \\
1248 citecolor & \textit{green} & color of citation links \\
1249 colorlinks & \textit{false} & color links \\
1250 & \textit{true} & (\textsf{tex4ht}, \textsf{dviwindo}) \\
1251 debug & \textit{false} & provide details of anchors defined; same as verbose \\
1252 destlabel & \textit{false} & destinations are named by the first \verb|\label| after the anchor creation \\
1253 draft & \textit{false} & do not do any hyperlinking \\
1254 driverfallback & & default if no driver specified or detected\\
1255 dvipdfm & & use \textsf{dvipdfm} backend \\
1256 dvipdfmx & & use \textsf{dvipdfmx} backend \\
1257 dvips & & use \textsf{dvips} backend \\
1258 dvipsone & & use \textsf{dvipsone} backend \\
1259 dviwindo & & use \textsf{dviwindo} backend \\
1260 encap & & to set encap character for hyperindex \\
1261 extension & \textit{dvi} & suffix of linked files \\
1262 filebordercolor & \textit{0 .5 .5} & color of border around file links \\
1263 filecolor & \textit{cyan} & color of file links \\
1264 final & \textit{true} & opposite of option draft \\
1265 frenchlinks & \textit{false} & use small caps instead of color for links \\
1266 hidelinks & & Hide links (removing color and border) \\
1267 hyperfigures & \textit{false} & make figures hyper links \\
1268 hyperfootnotes & \textit{true} & set up hyperlinked footnotes \\
1269 hyperindex & \textit{true} & set up hyperlinked indices \\
1270 hypertex & & use \textsf{Hyper\TeX} backend \\
1271 hypertexnames & \textit{true} & use guessable names for links \\
1272 implicit & \textit{true} & redefine \LaTeX\ internals \\
1273 latex2html & & use \textsf{\LaTeX2HTML} backend \\
1274 linkbordercolor & \textit{1 0 0} & color of border around links \\
1275 linkcolor & \textit{red} & color of links \\
1276 linktoc & \textit{section} & make text be link on TOC, LOF and LOT \\
1277 linktocpage & \textit{false} & make page number, not text, be link on TOC, LOF and LOT \\
1278 menubordercolor & \textit{1 0 0} & color of border around menu links \\
1279 menucolor & \textit{red} & color for menu links \\
1280 nativepdf & \textit{false} & an alias for \textsf{dvips} \\
1281 naturalnames & \textit{false} & use \LaTeX-computed names for links \\
1282 nesting & \textit{false} & allow nesting of links \\
1283 next-anchor & & allow to set the name of the next anchor\\
1284 pageanchor & \textit{true} & put an anchor on every page \\
1285 pagebackref & \textit{false} & backreference by page number \\
1286 pdfauthor & \textit{empty} & text for PDF Author field \\
1287 pdfborder & \textit{0 0 1} & width of PDF link border \\
1288 & \textit{0 0 0} & (\texttt{colorlinks)} \\
1289 pdfborderstyle & & border style for links \\
1290 pdfcenterwindow & \textit{false} & position the document window in the center of the screen \\
1291 pdfcreator & \textit{LaTeX with} & text for PDF Creator field \\
1292 & \textit{hyperref} & \\
1293 pdfcreationdate & & Sets the creation date, see below the table in section~\ref{sec:pdfdata} for more info about the format\\
1294 pdfdirection & \textit{empty} & direction setting \\
1295 pdfdisplaydoctitle & \textit{false} & display document title instead
1296 of file name in title bar\\
1297 pdfduplex & \textit{empty} & paper handling option for
1298 print dialog\\
1299 pdffitwindow & \textit{false} & resize document window to fit document size \\
1300 pdfhighlight & \textit{/I} & set highlighting of PDF links \\
1301 pdfinfo & \textit{empty} & alternative interface for setting document information\\
1302 pdfkeywords & \textit{empty} & text for PDF Keywords field \\
1303 pdflang & \textit{relax} & PDF language identifier (RFC 3066) \\
1304 pdfmark & \textit{false} & an alias for \textsf{dvips} \\
1305 pdfmenubar & \textit{true} & make PDF viewer's menu bar visible \\
1306 pdfmoddate & & Sets the modification date, see below the table in section~\ref{sec:pdfdata} for more info about the format\\
1307 pdfnewwindow & \textit{false} & make links that open another PDF \\
1308 & & file start a new window \\
1309 pdfnonfullscreenpagemode
1310 & \textit{empty} & page mode setting on exiting
1311 full-screen mode\\
1312 pdfnumcopies & \textit{empty} & number of printed copies\\
1313 pdfpagelabels & \textit{true} & set PDF page labels \\
1314 pdfpagelayout & \textit{empty} & set layout of PDF pages \\
1315 pdfpagemode & \textit{empty} & set default mode of PDF display \\
1316 pdfpagescrop & \textit{empty} & set crop size of PDF document \\
1317 pdfpagetransition & \textit{empty} & set PDF page transition style \\
1318 pdfpicktraybypdfsize
1319 & \textit{empty} & set option for print dialog \\
1320 pdfprintarea & \textit{empty} & set /PrintArea of viewer preferences \\
1321 pdfprintclip & \textit{empty} & set /PrintClip of viewer preferences \\
1322 pdfprintpagerange & \textit{empty} & set /PrintPageRange of viewer preferences \\
1323 pdfprintscaling & \textit{empty} & page scaling option for print dialog \\
1324 pdfproducer & \textit{empty} & text for PDF Producer field \\
1325 pdfremotestartview & \textit{Fit} & starting view of remote PDF documents \\
1326 pdfstartpage & \textit{1} & page at which PDF document opens \\
1327 pdfstartview & \textit{Fit} & starting view of PDF document \\
1328 pdfsubject & \textit{empty} & text for PDF Subject field \\
1329 pdftex & & use \textsf{pdf\TeX} backend \\
1330 pdftitle & \textit{empty} & text for PDF Title field \\
1331 pdftoolbar & \textit{true} & make PDF toolbar visible \\
1332 pdftrapped & \textit{empty} & Sets the document information Trapped entry.
1333 Possible values are \texttt{True}, \texttt{False} and \texttt{Unknown}.
1334 An empty value means, the entry is not set.\\
1335 pdfview & \textit{XYZ} & PDF `view' when on link traversal \\
1336 pdfviewarea & \textit{empty} & set /ViewArea of viewer preferences \\
1337 pdfviewclip & \textit{empty} & set /ViewClip of viewer preferences \\
1338 pdfwindowui & \textit{true} & make PDF user interface elements visible \\
1339 plainpages & \textit{false} & do page number anchors as plain Arabic \\
1340 ps2pdf & & use \textsf{ps2pdf} backend \\
1341 psdextra & \textit{false} & define more short names for PDF string commands \\
1342 raiselinks & \textit{false} & raise up links (for \textsf{Hyper\TeX} backend) \\
1343 runbordercolor & \textit{0 .7 .7} & color of border around `run' links \\
1344 runcolor & \textit{filecolor} & color of `run' links\\
1345 setpagesize & \textit{true} & set page size by special driver commands \\
1346 tex4ht & & use \textsf{\TeX4ht} backend \\
1347 textures & & use \textsf{Textures} backend \\
1348 unicode & \textit{true} & Unicode encoded pdf strings, starting with version v7.00g set by default to true for all engines. It will load a number of definitions in puenc.def. It can be set to false for pdflatex, but this is not recommended.\\
1349 urlbordercolor & \textit{0 1 1} & color of border around URL links \\
1350 urlcolor & \textit{magenta} & color of URL links \\
1351 verbose & \textit{false} & be chatty \\
1352 vtex & & use \textsf{VTeX} backend\\
1353 xetex & & use \textsf{Xe\TeX} backend\\
1354 \end{longtable}
1355
1356 \section{Additional user macros}
1357
1358 If you need to make references to URLs, or write explicit links, the
1359 following low-level user macros are provided:
1360
1361 \begin{cmdsyntax}
1362 \ci{href}\verb|[|\emph{options}\verb|]|\verb|{|\emph{URL}\verb|}{|\emph{text}\verb|}|
1363 \end{cmdsyntax}
1364
1365 \noindent The \emph{text} is made into a hyperlink to the \emph{URL}; this
1366 must be a full URL (relative to the base URL, if that is defined). The
1367 special characters \# and \%{} do \emph{not} need to be escaped in any
1368 way (unless the command is used in the argument of another command).
1369
1370 The optional argument \emph{options} recognizes the \xpackage{hyperref} options
1371 \texttt{pdfremotestartview}, \texttt{pdfnewwindow} and the following
1372 key value options:
1373 \begin{description}
1374 \item[\texttt{page}:] Specifies the start page number of remote
1375 PDF documents. First page is \verb|1|.
1376 \item[\texttt{ismap}:] Boolean key, if set to \verb|true|, the
1377 URL should be appended by the coordinates as query parameters by
1378 the PDF viewer.
1379 \item[\texttt{nextactionraw}:] The value of key \verb|/Next| of
1380 action dictionaries, see PDF specification.
1381 \end{description}
1382
1383 \begin{cmdsyntax}
1384 \ci{url}\verb|{|\emph{URL}\verb|}|
1385 \end{cmdsyntax}
1386
1387 \noindent Similar to
1388 \ci{href}\verb|{|\emph{URL}\verb|}{|\ci{nolinkurl}\verb|{|\emph{URL}\verb|}}|.
1389 Depending on the driver \verb|\href| also tries to detect the link type. Thus
1390 the result can be a url link, file link, \dots. The implementation makes use
1391 of the \xpackage{url} package and its commands can be used to format and fine
1392 tune the url, but the behaviour of \ci{url} is different to the behaviour in
1393 the \xpackage{url} package: Most importantly the hyperref \cs{url} expands
1394 commands. If the behaviour or the original \cs{url} is needed, the url
1395 package should be loaded first and the command should be copied into some
1396 alias command.
1397
1398 \begin{cmdsyntax}
1399 \ci{nolinkurl}\verb|{|\emph{URL}\verb|}|
1400 \end{cmdsyntax}
1401
1402 \noindent Write \emph{URL} in the same way as \verb|\url| described above,
1403 without creating a hyperlink.
1404
1405 \begin{cmdsyntax}
1406 \ci{hyperbaseurl}\verb|{|\emph{URL}\verb|}|
1407 \end{cmdsyntax}
1408
1409 \noindent A base \emph{URL} is established, which is prepended to other
1410 specified URLs, to make it easier to write portable documents. When creating a PDF
1411 the command can be used only once as the \emph{URL} is written into the catalog.
1412
1413 \begin{cmdsyntax}
1414 \ci{hyperimage}\verb|{|\emph{imageURL}\verb|}{|\emph{text}\verb|}|
1415 \end{cmdsyntax}
1416
1417 \noindent The link to the image referenced by the URL is inserted, using
1418 \emph{text} as the anchor.
1419
1420 For drivers that produce HTML, the image itself is inserted by the
1421 browser, with the \emph{text} being ignored completely.
1422
1423 \begin{cmdsyntax}
1424 \ci{hyperdef}\verb|{|\emph{category}\verb|}{|\emph{name}\verb|}{|\emph{text}\verb|}|
1425 \end{cmdsyntax}
1426
1427 \noindent A target area of the document (the \emph{text}) is marked, and
1428 given the name \emph{category.name}
1429
1430 \begin{cmdsyntax}
1431 \ci{hyperref}\verb|{|\emph{URL}\verb|}{|\emph{category}\verb|}{|\emph{name}\verb|}{|\emph{text}\verb|}|
1432 \end{cmdsyntax}
1433
1434 \noindent \emph{text} is made into a link to \emph{URL\#category.name}
1435
1436 \begin{cmdsyntax}
1437 \ci{hyperref}\verb|[|\emph{label}\verb|]{|\emph{text}\verb|}|
1438 \end{cmdsyntax}
1439
1440 \noindent
1441 \emph{text} is made into a link to the same place as
1442 \verb|\ref{|\emph{label}\verb|}| would be linked.
1443
1444 \begin{cmdsyntax}
1445 \ci{hyperlink}\verb|{|\emph{name}\verb|}{|\emph{text}\verb|}|
1446 \end{cmdsyntax}
1447 \begin{cmdsyntax}
1448 \ci{hypertarget}\verb|{|\emph{name}\verb|}{|\emph{text}\verb|}|
1449 \end{cmdsyntax}
1450
1451 \noindent A simple internal link is created with \verb|\hypertarget|,
1452 with two parameters of an anchor \emph{name}, and anchor
1453 \emph{text}. \verb|\hyperlink| has two arguments, the name of a
1454 hypertext object defined somewhere by \verb|\hypertarget|, and the
1455 \emph{text} which is used as the link on the page.
1456
1457 Note that in HTML parlance, the \verb|\hyperlink| command inserts a
1458 notional \# in front of each link, making it relative to the current
1459 testdocument; \verb|\href| expects a full URL.
1460
1461 \begin{cmdsyntax}
1462 \ci{phantomsection}
1463 \end{cmdsyntax}
1464
1465 \noindent
1466 This sets an anchor at this location. It works similar to
1467 \verb|\hypertarget{}{}| with an automatically chosen anchor name.
1468 Often it is used in conjunction
1469 with \verb|\addcontentsline| for sectionlike things (index, bibliography,
1470 preface). \verb|\addcontentsline| refers to the latest previous location
1471 where an anchor is set. Example:
1472 \begin{quote}
1473 \begin{verbatim}
1474 \cleardoublepage
1475 \phantomsection
1476 \addcontentsline{toc}{chapter}{\indexname}
1477 \printindex
1478 \end{verbatim}
1479 \end{quote}
1480 Now the entry in the table of contents (and bookmarks) for the
1481 index points to the start of the index page, not to a location
1482 before this page.
1483
1484 \begin{cmdsyntax}
1485 \ci{hyperget}\verb|{anchor}{|\emph{label}\verb|}|
1486 \ci{hyperget}\verb|{pageanchor}{|\emph{label}\verb|}|
1487 \end{cmdsyntax}
1488
1489 This retrieves the anchor or the page anchor from a label in an expandable way.
1490 It takes \verb|\HyperDestNameFilter| into account. It can e.g. be used with the
1491 \verb|\bookmark| from the bookmark package to set a destination to a label:
1492
1493 \begin{verbatim}
1494 \bookmark[dest=\hyperget{anchor}{sec}]{section}
1495 \end{verbatim}
1496
1497 As \emph{pageanchor} retrieves the page number from the label it can't be used together with
1498 the option \texttt{plainpages}.
1499
1500 \begin{cmdsyntax}
1501 \ci{hyperget}\verb|{currentanchor}{}|
1502 \end{cmdsyntax}
1503
1504 This retrieves the last anchor that has been set. It too takes \verb|\HyperDestNameFilter| into account.
1505
1506
1507
1508 \begin{cmdsyntax}
1509 \ci{autoref}\verb|{|\emph{label}\verb|}|
1510 \end{cmdsyntax}
1511
1512 \noindent
1513 This is a replacement for the usual \verb|\ref| command that places a
1514 contextual label in front of the reference. This gives your users a
1515 bigger target to click for hyperlinks (e.g.\ `section 2' instead of
1516 merely the number `2').
1517
1518 The label is worked out from the context of the original \verb|\label|
1519 command by \xpackage{hyperref} by using the macros listed below (shown
1520 with their default values). The macros can be (re)defined in documents
1521 using \verb|\(re)newcommand|; note that some of these macros are already
1522 defined in the standard document classes. The mixture of lowercase and
1523 uppercase initial letters is deliberate and corresponds to the author's
1524 practice.
1525
1526 For each macro below, \xpackage{hyperref} checks \ci{*autorefname} before
1527 \ci{*name}. For instance, it looks for \ci{figureautorefname} before
1528 \ci{figurename}.
1529
1530 \begin{longtable}{@{}lp{10cm}@{}}
1531 \textit{Macro} & \textit{Default} \\
1532 \ci{figurename} & Figure \\
1533 \ci{tablename} & Table \\
1534 \ci{partname} & Part \\
1535 \ci{appendixname} & Appendix \\
1536 \ci{equationname} & Equation \\
1537 \ci{Itemname} & item \\
1538 \ci{chaptername} & chapter \\
1539 \ci{sectionname} & section \\
1540 \ci{subsectionname} & subsection \\
1541 \ci{subsubsectionname} & subsubsection \\
1542 \ci{paragraphname} & paragraph \\
1543 \ci{Hfootnotename} & footnote \\
1544 \ci{AMSname} & Equation \\
1545 \ci{theoremname} & Theorem\\
1546 \ci{page} & page\\
1547 \end{longtable}
1548
1549 Example for a redefinition if \textsf{babel} is used:
1550 \begin{quote}
1551 \begin{verbatim}
1552 \usepackage[ngerman]{babel}
1553 \addto\extrasngerman{%
1554 \def\subsectionautorefname{Unterkapitel}%
1555 }
1556 \end{verbatim}
1557 \end{quote}
1558
1559 Hint: \cs{autoref} works via the counter name that the reference
1560 is based on. Sometimes \cs{autoref} chooses the wrong name, if
1561 the counter is used for different things. For example, it happens
1562 with \cs{newtheorem} if a lemma shares a counter with theorems.
1563 Then package \xpackage{aliascnt} provides a method to generate a
1564 simulated second counter that allows the differentiation between
1565 theorems and lemmas:
1566 \begin{quote}
1567 \begin{verbatim}
1568 \documentclass{article}
1569
1570 \usepackage{aliascnt}
1571 \usepackage{hyperref}
1572
1573 \newtheorem{theorem}{Theorem}
1574
1575 \newaliascnt{lemma}{theorem}
1576 \newtheorem{lemma}[lemma]{Lemma}
1577 \aliascntresetthe{lemma}
1578
1579 \providecommand*{\lemmaautorefname}{Lemma}
1580
1581 \begin{document}
1582
1583 We will use \autoref{a} to prove \autoref{b}.
1584
1585 \begin{lemma}\label{a}
1586 Nobody knows.
1587 \end{lemma}
1588
1589 \begin{theorem}\label{b}
1590 Nobody is right.
1591 \end{theorem}.
1592
1593 \end{document}
1594 \end{verbatim}
1595 \end{quote}
1596
1597 \begin{cmdsyntax}
1598 \ci{autopageref}\verb|{|\emph{label}\verb|}|
1599 \end{cmdsyntax}
1600
1601 \noindent
1602 It replaces \verb|\pageref| and adds the name for page in front of
1603 the page reference. First \ci{pageautorefname} is checked before
1604 \ci{pagename}.
1605
1606 For instances where you want a reference to use the correct counter, but
1607 not to create a link, there are starred forms (these starred forms exist even if
1608 hyperref has been loaded with \verb|implicit=false|):
1609
1610 \begin{cmdsyntax}
1611 \ci{ref*}\verb|{|\emph{label}\verb|}|
1612 \end{cmdsyntax}
1613
1614 \begin{cmdsyntax}
1615 \ci{pageref*}\verb|{|\emph{label}\verb|}|
1616 \end{cmdsyntax}
1617
1618 \begin{cmdsyntax}
1619 \ci{autoref*}\verb|{|\emph{label}\verb|}|
1620 \end{cmdsyntax}
1621
1622 \begin{cmdsyntax}
1623 \ci{autopageref*}\verb|{|\emph{label}\verb|}|
1624 \end{cmdsyntax}
1625
1626 A typical use would be to write
1627 \begin{verbatim}
1628 \hyperref[other]{that nice section (\ref*{other}) we read before}
1629 \end{verbatim}
1630
1631 We want \verb|\ref*{other}| to generate the correct number, but not to
1632 form a link, since we do this ourselves with \ci{hyperref}.
1633
1634 \begin{cmdsyntax}
1635 \ci{pdfstringdef}\verb|{|\emph{macroname}\verb|}{|\emph{\TeX string}\verb|}|
1636 \end{cmdsyntax}
1637
1638 \ci{pdfstringdef} returns a macro containing the PDF string. (Currently
1639 this is done globally, but do not rely on it.) All the following tasks,
1640 definitions and redefinitions are made in a group to keep them local:
1641
1642 \begin{itemize}
1643 \item Switching to PD1 or PU encoding
1644 \item Defining the \Quote{octal sequence commands} (\verb|\345|): \verb|\edef\3{\string\3}|
1645 \item Special glyphs of \TeX: \verb|\{|, \verb|\%|, \verb|\&|, \verb|\space|, \verb|\dots|, etc.
1646 \item National glyphs (\textsf{german.sty}, \textsf{french.sty}, etc.)
1647 \item Logos: \verb|\TeX|, \verb|\eTeX|, \verb|\MF|, etc.
1648 \item Disabling commands that do not provide useful functionality in bookmarks:
1649 \verb|\label|, \verb|\index|, \verb|\glossary|, \verb|\discretionary|, \verb|\def|, \verb|\let|, etc.
1650 \item \LaTeX's font commands like \verb|\textbf|, etc.
1651 \item Support for \verb|\xspace| provided by the \xpackage{xspace} package
1652 \end{itemize}
1653
1654 In addition, parentheses are protected to avoid the danger of unsafe
1655 unbalanced parentheses in the PDF string. For further details, see Heiko
1656 Oberdiek's Euro\TeX\ paper distributed with \xpackage{hyperref}.
1657
1658 \begin{cmdsyntax}
1659 \ci{begin}\verb|{NoHyper}|\ldots\ci{end}\verb|{NoHyper}|
1660 \end{cmdsyntax}
1661 Sometimes we just don't want the wretched package interfering
1662 with us. Define an environment we can put in manually, or include
1663 in a style file, which stops the hypertext functions doing anything.
1664 This is used, for instance, in the Elsevier classes, to stop
1665 \verb|hyperref| playing havoc in the front matter.
1666
1667 \subsection{Bookmark macros}
1668
1669 \subsubsection{Setting bookmarks}
1670
1671 Usually \xpackage{hyperref} automatically adds bookmarks for
1672 \verb|\section| and similar macros. But they can also set manually.
1673
1674 \begin{cmdsyntax}
1675 \ci{pdfbookmark}\verb|[|\emph{level}\verb|]{|text\verb|}{|\emph{name}\verb|}|
1676 \end{cmdsyntax}
1677 creates a bookmark with the specified text and at the given level (default is
1678 0). As name for the internal anchor name is used (in conjunction with
1679 level). Therefore the name must be unique (similar to \verb|\label|).
1680
1681 \begin{cmdsyntax}
1682 \ci{currentpdfbookmark}\verb|{|\emph{text}\verb|}{|\emph{name}\verb|}|
1683 \end{cmdsyntax}
1684 creates a bookmark at the current level.
1685
1686 \begin{cmdsyntax}
1687 \ci{subpdfbookmark}\verb|{|\emph{text}\verb|}{|\emph{name}\verb|}|
1688 \end{cmdsyntax}
1689 creates a bookmark one step down in the bookmark hierarchy.
1690 Internally the current level is increased by one.
1691
1692 \begin{cmdsyntax}
1693 \ci{belowpdfbookmark}\verb|{|\emph{text}\verb|}{|\emph{name}\verb|}|
1694 \end{cmdsyntax}
1695 creates a bookmark below the current bookmark level. However after the
1696 command the current bookmark level has not changed.
1697
1698 \noindent \textbf{Hint:} Package \textsf{bookmark} replaces
1699 \xpackage{hyperref}'s bookmark organization by a new algorithm:
1700 \begin{itemize}
1701 \item Usually only one \LaTeX\ run is needed.
1702 \item More control over the bookmark appearance (color, font).
1703 \item Different bookmark actions are supported (external file links,
1704 URLs, \dots).
1705 \end{itemize}
1706 Therefore I recommend using this package.
1707
1708 \subsubsection{Replacement macros}\label{sec:texorpdfstring}
1709
1710 \xpackage{hyperref} takes the text for bookmarks from the arguments of
1711 commands like \ci{section}, which can contain things like math, colors,
1712 or font changes, none of which will display in bookmarks as is.
1713
1714 \begin{cmdsyntax}
1715 \ci{texorpdfstring}\verb|{|\emph{\TeX string}\verb|}{|\emph{PDFstring}\verb|}|
1716 \end{cmdsyntax}
1717
1718 For example,
1719 \begin{verbatim}
1720 \section{Pythagoras:
1721 \texorpdfstring{$ a^2 + b^2 = c^2 $}{%
1722 a\texttwosuperior\ + b\texttwosuperior\ =
1723 c\texttwosuperior
1724 }%
1725 }
1726 \section{\texorpdfstring{\textcolor{red}}{}{Red} Mars}
1727 \end{verbatim}
1728
1729 \ci{pdfstringdef} executes the hook \pdfstringdefPreHook before it
1730 expands the string. Therefore, you can use this hook to perform
1731 additional tasks or to disable additional commands.
1732
1733 \begin{verbatim}
1734 \expandafter\def\expandafter\pdfstringdefPreHook
1735 \expandafter{%
1736 \pdfstringdefPreHook
1737 \renewcommand{\mycommand}[1]{}%
1738 }
1739 \end{verbatim}
1740
1741 However, for disabling commands, an easier way is via
1742 \ci{pdfstringdefDisableCommands}, which adds its argument to the
1743 definition of \ci{pdfstringdefPreHook} (`@' can here be used as letter in
1744 command names):
1745
1746 \begin{verbatim}
1747 \pdfstringdefDisableCommands{%
1748 \let~\textasciitilde
1749 \def\url{\pdfstringdefWarn\url}%
1750 \let\textcolor\@gobble
1751 }
1752 \end{verbatim}
1753
1754 \subsection{Pagelabels}
1755 \begin{cmdsyntax}
1756 \ci{thispdfpagelabel}\verb|{|\emph{page number format}\verb|}|
1757 \end{cmdsyntax}
1758
1759 This allows to change format of the page number shown in the tool bar of
1760 a PDF viewer for a specific page, for example
1761
1762 \verb+\thispdfpagelabel{Empty Page-\roman{page}}+
1763
1764 The command affects the page on which it is executed, so asynchronous page breaking
1765 should be taken into account. It should be used in places where for example \verb+\thispagestyle+ can be used too.
1766
1767 \subsection{Utility macros}
1768
1769 \label{hypercalcbp}
1770 \begin{cmdsyntax}
1771 \ci{hypercalcbp}\verb|{|\emph{dimen specification}\verb|}|
1772 \end{cmdsyntax}
1773 \noindent
1774 \verb|\hypercalcbp| takes a \TeX\ dimen specification and
1775 converts it to bp and returns the number without the unit.
1776 This is useful for options \verb|pdfview|, \verb|pdfstartview|
1777 and \verb|pdfremotestartview|.
1778 Example:
1779 \begin{quote}
1780 \begin{verbatim}
1781 \hypersetup{
1782 pdfstartview={FitBH \hypercalcbp{\paperheight-\topmargin-1in
1783 -\headheight-\headsep}}
1784 }
1785 \end{verbatim}
1786 \end{quote}
1787 The origin of the PDF coordinate system is the lower left corner.
1788
1789 Note, for calculations you need either package \xpackage{calc} or
1790 \hologo{eTeX}. Nowadays the latter should automatically be enabled
1791 for \hologo{LaTeX} formats. Users without \hologo{eTeX}, please, look
1792 in the source documentation \verb|hyperref.dtx| for further
1793 limitations.
1794
1795 Also \cs{hypercalcbp} cannot be used in option specifications
1796 of \cs{documentclass} and \cs{usepackage}, because
1797 \hologo{LaTeX} expands the option lists of these commands. However
1798 package \xpackage{hyperref} is not yet loaded and an undefined control
1799 sequence error would arise.
1800
1801 \section[New Features]{New Features%
1802 \footnote{This section moved from the README file, needs more integration into the manual}}
1803
1804
1805 \subsection{Option `pdflinkmargin'}
1806
1807 Option `pdflinkmargin' is an experimental option for specifying
1808 a link margin, if the driver supports this. Default is 1 pt for
1809 supporting drivers.
1810
1811
1812 \begin{description}
1813 \item[pdfTeX]
1814 \begin{itemize}
1815 \item The link area also depends on the surrounding box.
1816 \item Settings have local effect.
1817 \item When a page is shipped out, pdfTeX uses the current setting
1818 of the link margin for all links on the page.
1819 \end{itemize}
1820
1821 \item[pdfmark]
1822 \begin{itemize}
1823 \item Settings have global effect.
1824 \end{itemize}
1825
1826 \item[xetex]
1827 \begin{itemize}
1828 \item Settings must be done in the preamble or the first page and then have global effect.
1829 The key inserts the new (x)dvipdfmx special \verb|\special{dvipdfmx:config g #1}| (with the unit removed).
1830 \end{itemize}
1831
1832 \item[Other drivers]
1833 Unsupported.
1834 \end{description}
1835
1836
1837 \subsection{Field option `calculatesortkey'}
1838
1839 Fields with calculated values are calculated in document order
1840 by default. If calculated field values depend on other calculated
1841 fields that appear later in the document, then the correct calculation
1842 order can be specified with option `calculatesortkey'. Its value is
1843 used as key to lexicographically sort the calculated fields.
1844 The sort key do not need to be unique. Fields that share the same
1845 key are sorted in document order.
1846
1847
1848
1849 Currently the field option `calculatesortkey' is only supported by
1850 the driver for pdfTeX.
1851
1852 \subsection{Option `next-anchor'}
1853 This option allows to overwrite the anchor name of the next anchor.
1854 This makes it possible to give for example the heading of the table of contents
1855 an anchor name which can be referenced with a \verb|\bookmark| command from the bookmark package:
1856
1857 \begin{verbatim}
1858 \hypersetup{next-anchor=toc}
1859 \tableofcontents
1860 \bookmark[dest=\HyperDestNameFilter{toc},level=section]{\contentsname}
1861 \end{verbatim}
1862
1863 \subsection{Option `localanchorname'}
1864
1865 When\marginpar{Deprecated 2022-04-27 v7.00o} an anchor is set (e.g. via \verb|\refstepcounter|, then the
1866 anchor name is globally set to the current anchor name.
1867
1868
1869 For example:
1870 \begin{verbatim}
1871 \section{Foobar}
1872 \begin{equation}\end{equation}
1873 \label{sec:foobar}
1874 \end{verbatim}
1875 With the default global setting (localanchorname=false)
1876 a reference to `sec:foobar' jumps to the equation before.
1877 With option `localanchorname' the anchor of the equation
1878 is forgotten after the environment and the reference
1879 `sec:foobar' jumps to the section title.
1880
1881
1882 Option `localanchorname' is an experimental option, there
1883 might be situations, where the anchor name is not available
1884 as expected.
1885
1886 The option is deprecated: it makes it difficult for package authors
1887 to add targets for links if it is unclear if \verb|\@currentHref| is
1888 set locally or globally.
1889
1890 \subsection{Option `customdriver'}
1891
1892 The value of option `customdriver' is the name of an external
1893 driver file without extension `.def'. The file must have
1894 \verb|\ProvidesFile| with a version date and number that match the
1895 date and number of `hyperref', otherwise a warning is given.
1896
1897 Because the interface, what needs to be defined in the driver,
1898 is not well defined and quite messy, the option is mainly intended
1899 to ease developing, testing, debugging the driver part.
1900
1901
1902 \subsection{Option `psdextra'}
1903
1904 LaTeX's NFSS is used to assist the conversion of arbitrary
1905 TeX strings to PDF strings (bookmarks, PDF information entries).
1906 Many math command names (\verb|\geq|, \verb|\notin|, ...) are not in control
1907 of NFSS, therefore they are defined with prefix `text'
1908 (\verb|\textgeq|, \verb|\textnotin|, ...). They can be mapped to short names
1909 during the processing to PDF strings. The disadvantage is that
1910 they are many hundreds macros that need to be redefined for
1911 each PDF string conversion. Therefore this can be enabled or
1912 disabled as option `psdextra'. On default the option is turned
1913 off (set to `false'). Turning the option on means
1914 that the short names are available. Then \verb|\geq| can directly
1915 be used instead of \verb|\textgeq|.
1916
1917
1918 \subsection{\textbackslash XeTeXLinkBox}
1919
1920 When XeTeX generates a link annotation, it does not look
1921 at the boxes (as the other drivers), but only at the character
1922 glyphs. If there are no glyphs (images, rules, ...), then
1923 it does not generate a link annotation. Macro \verb|\XeTeXLinkBox|
1924 puts its argument in a box and adds spaces at the lower left
1925 and upper right corners. An additional margin can be specified
1926 by setting it to the dimen register \verb|\XeTeXLinkMargin|. The default
1927 is 2pt.
1928
1929 Example:
1930
1931
1932 \begin{verbatim}
1933 % xelatex
1934 \documentclass{article}
1935 \usepackage{hyperref}
1936 \setlength{\XeTeXLinkMargin}{1pt}
1937 \begin{document}
1938 \section{Hello World}
1939 \newpage
1940 \label{sec:hello}
1941 \hyperref[sec:hello]{%
1942 \XeTeXLinkBox{\rule{10mm}{10mm}}%
1943 }
1944 \end{document}
1945 \end{verbatim}
1946
1947 \subsection{\textbackslash IfHyperBooleanExists and \textbackslash IfHyperBoolean}
1948 \begin{verbatim}
1949 \IfHyperBooleanExists{OPTION}{YES}{NO}
1950 \end{verbatim}
1951 If a \xpackage{hyperref} OPTION is a boolean, that means it takes values
1952 `true' or `false', then \verb|\IfHyperBooleanExists| calls YES, otherwise NO.
1953
1954
1955 \begin{verbatim}
1956 \IfHyperBoolean{OPTION}{YES}{NO}
1957 \end{verbatim}
1958 Macro \verb|\IfHyperBoolean| calls YES, if OPTION exists as boolean and is
1959 enabled. Otherwise NO is executed.
1960
1961
1962
1963 Both macros are expandable. Additionally option `stoppedearly' is
1964 available. It is enabled if \verb|\MaybeStopEarly| or \verb|\MaybeStopNow|
1965 end \xpackage{hyperref} prematurely.
1966
1967
1968 \subsection{\textbackslash unichar}
1969
1970 If a Unicode character is not supported by puenc.def, it can
1971 be given by using \verb|\unichar|. Its name and syntax is inherited
1972 from package `ucs'. However it is defined independently for
1973 use in \xpackage{hyperref}'s \verb|\pdfstringdef| (that converts arbitrary
1974 TeX code to PDF strings or tries to do this).
1975
1976
1977
1978 Macro \verb|\unichar| takes a TeX number as argument,
1979 examples for U+263A (WHITE SMILING FACE):
1980 \begin{verbatim}
1981 \unichar{"263A}% hexadecimal notation
1982 \unichar{9786}% decimal notation
1983 \end{verbatim}
1984 `"' must not be a babel shorthand character or otherwise
1985 active. Otherwise prefix it with \verb|\string|:
1986 \begin{verbatim}
1987 \unichar{\string"263A}% converts `"' to `"' with catcode 12 (other)
1988 \end{verbatim}
1989 Users of (n)german packages or babel options may use \verb|\dq| instead:
1990 \begin{verbatim}
1991 \unichar{\dq 263A}% \dq is double quote with catcode 12 (other)
1992 \end{verbatim}
1993
1994
1995 \subsection{\textbackslash ifpdfstringunicode}
1996
1997 Some features of the PDF specification needs PDF strings.
1998 Examples are bookmarks or the entries in the information dictionary.
1999 The PDF specification allows two encodings `PDFDocEncoding'
2000 (8-bit encoding) and `Unicode' (UTF-16). The user can help
2001 using \verb|\texorpdfstring| to replace complicate TeX constructs
2002 by a representation for the PDF string. However \verb|\texorpdfstring|
2003 does not distinguish the two encodings. This gap closes
2004 \verb|\ifpdfstringunicode|. It is only allowed in the second argument
2005 of \verb|\texorpdfstring| and takes two arguments, the first allows
2006 the full range of Unicode. The second is limited to the
2007 characters available in PDFDocEncoding.
2008
2009
2010
2011 As example we take a macro definition for the Vietnamese
2012 name of \hologo{HanTheThanh}. Correctly written it needs some
2013 accented characters, one character even with a double accent.
2014 Class `tugboat.cls' defines a macro for the typesetted name:
2015 \begin{verbatim}
2016 \def\Thanh{%
2017 H\`an~%
2018 Th\^e\llap{\raise 0.5ex\hbox{\'{}}}%
2019 ~Th\`anh%
2020 }
2021 \end{verbatim}
2022 It's not entirely correct, the second accent over the `e' is not
2023 an acute, but a hook. However standard LaTeX does not provide
2024 such an accent.
2025
2026 Now we can extend the definition to support \xpackage{hyperref}.
2027 The first and the last word are already supported automatically.
2028 Characters with two or more accents are a difficult business in
2029 LaTeX, because the NFSS2 macros of the LaTeX kernel do not support
2030 more than one accent. Therefore also puenc.def misses support for
2031 them. But we can provide it using \verb|\unichar|. The character
2032 in question is:
2033 \begin{verbatim}
2034 % U+1EC3 LATIN SMALL LETTER E WITH CIRCUMFLEX AND HOOK ABOVE
2035 \end{verbatim}
2036 Thus we can put this together:
2037 \begin{verbatim}
2038 \def\Thanh{%
2039 H\`an~%
2040 \texorpdfstring{Th\^e\llap{\raise 0.5ex\hbox{\'{}}}}%
2041 {\ifpdfstringunicode{Th\unichar{"1EC3}}{Th\^e}}%
2042 ~Th\`anh%
2043 }
2044 \end{verbatim}
2045 For PDFDocEncoding (PD1) the variant above has dropped the
2046 second accent. Alternatively we could provide a representation
2047 without accents instead of wrong accents:
2048 \begin{verbatim}
2049 \def\Thanh{%
2050 \texorpdfstring{%
2051 H\`an~%
2052 Th\^e\llap{\raise 0.5ex\hbox{\'{}}}}%
2053 ~Th\`anh%
2054 }{%
2055 \ifpdfstringunicode{%
2056 H\`an Th\unichar{"1EC3} Th\`anh%
2057 }{%
2058 Han The Thanh%
2059 }%
2060 }%
2061 }
2062 \end{verbatim}
2063
2064 \subsection{Customizing index style file with \textbackslash nohyperpage}
2065
2066 Since version 2008/08/14~v6.78f.
2067
2068
2069
2070 For hyperlink support in the index, \xpackage{hyperref} inserts \verb|\hyperpage|
2071 into the index macros. After processing with Makeindex, \verb|\hyperpage|
2072 analyzes its argument to detect page ranges and page comma lists.
2073 However, only the standard settings are supported directly:
2074 \begin{verbatim}
2075 delim_r "--"
2076 delim_n ", "
2077 \end{verbatim}
2078 (See manual page/documentation of Makeindex that explains
2079 the keys that can be used in style files for Makeindex.)
2080 Customized versions of
2081 \verb|delim_r, delim_n, suffix_2p, suffix_3p, suffix_mp|
2082 needs markup that \verb|\hyperpage| can detect and knows that
2083 this stuff does not belong to a page number. Macro
2084 \verb|\nohyperpage| serves as this markup. Put the customized
2085 code for these keys inside \verb|\nohyperpage|, e.g.:
2086 \begin{verbatim}
2087 suffix_2p "\\nohyperpage{f.}"
2088 suffix_3p "\\nohyperpage{ff.}"
2089 \end{verbatim}
2090 (Depending on the typesetting tradition some space ``\verb|\\|,'' or ``\verb|~|''
2091 should be put before the first f inside \verb|\nohyperpage|.)
2092
2093
2094 \subsection{Experimental option `ocgcolorlinks'}
2095
2096 The idea are colored links, when viewed, but printed without colors.
2097 This new experimental option `ocgcolorlinks' uses Optional Content
2098 Groups, a feature introduced in PDF 1.5.
2099
2100 A better implementation which hasn't the disadvantage to prevent line breaks is
2101 in the ocgx2 package. Check its documentation for details how to use it.
2102 \begin{itemize}
2103 \item The option must be given for package loading:
2104 \verb|\usepackage[ocgcolorlinks]{hyperref}|
2105 \item Main disadvantage: Links cannot be broken across lines.
2106 PDF reference 1.7: 4.10.2 ``Making Graphical Content Optional'':
2107 Graphics state operations, such as setting the color, ...,
2108 are still applied.
2109 Therefore the link text is put in a box and set twice, with and
2110 without color.
2111 \item The feature can be switched of by \verb|\hypersetup{ocgcolorlinks=false}|
2112 inside the document.
2113 \item Supported drivers: pdftex, dvipdfm
2114 \item The PDF version should be at least 1.5. It is automatically
2115 set for pdfTeX, LuaTeX and dvipdfmx.
2116 \end{itemize}
2117
2118 \subsection{Option `pdfa'}
2119
2120 The new option `pdfa' tries to avoid violations of PDF/A in code
2121 generated by \xpackage{hyperref}. However, the result is usually not in PDF/A,
2122 because many features aren't controlled by \xpackage{hyperref} (XMP metadata,
2123 fonts, colors, driver dependent low level stuff, ...).
2124
2125
2126
2127 Currently, option `pdfa' sets and disables the following items:
2128 \begin{itemize}
2129 \item Enabled annotation flags: Print, NoZoom, NoRotate [PDF/A 6.5.3].
2130 \item Disabled annotation flags: Hidden, Invisible, NoView [PDF/A 6.5.3].
2131 \item Disabled: Launch action (\href{run:...} [PDF/A 6.6.1].
2132 \item Restricted: Named actions (\Acrobatmenu: NextPage, PrevPage,
2133 FirstPage, LastPage) [PDF/A 6.6.1].
2134 \item Many things are disabled in PDF formulars:
2135 \begin{itemize}
2136 \item JavaScript actions [PDF/A 6.6.1]
2137 \item Trigger events (additional actions) [PDF/A 6.6.2]
2138 \item Push button (because of JavaScript)
2139 \item Interactive Forms: Flag NeedAppearances is the default `false'
2140 (Because of this, \xpackage{hyperref}'s implementation of Forms looks ugly).
2141 [PDF/A 6.9]
2142 \end{itemize}
2143 \end{itemize}
2144
2145
2146
2147 The default value of the new option `pdfa' is `false'. It influences
2148 the loading of the package and cannot be changed after \xpackage{hyperref} is
2149 loaded (\verb|\usepackage{hyperref}|).
2150
2151 If the PDF management is loaded with \cs{DocumentMetadata} the option is automatically set/unset depending on if an A-standard is set with the `pdfstandard` key. The manual setting of `pdfa` is then ignored.
2152
2153 \subsection{Option `linktoc' added}
2154
2155 The new option `linktoc' allows more control which part
2156 of an entry in the table of contents is made into a link:
2157 \begin{itemize}
2158 \item `linktoc=none' (no links)
2159 \item `linktoc=section' (default behaviour, same as `linktocpage=false')
2160 \item `linktoc=page' (same as `linktocpage=true')
2161 \item `linktoc=all' (both the section and page part are links)
2162 \end{itemize}
2163
2164 \subsection{Option `pdfnewwindow' changed}
2165
2166 Before 6.77b:
2167 \begin{itemize}
2168 \item pdfnewwindow=true $\rightarrow$ /NewWindow true
2169 \item pdfnewwindow=false $\rightarrow$ (absent)
2170 \item unused pdfnewwindow $\rightarrow$ (absent)
2171 \end{itemize}
2172 Since 6.77b:
2173 \begin{itemize}
2174 \item pdfnewwindow=true $\rightarrow$ /NewWindow true
2175 \item pdfnewwindow=false $\rightarrow$ /NewWindow false
2176 \item pdfnewwindow={} $\rightarrow$ (absent)
2177 \item unused pdfnewwindow $\rightarrow$ (absent)
2178 \end{itemize}
2179
2180
2181
2182 Rationale: There is a difference between setting to `false'
2183 and an absent entry. In the former case the new document
2184 replaces the old one, in the latter case the PDF viewer
2185 application should respect the user preference.
2186
2187
2188 \subsection{Flag options for PDF forms}
2189
2190 PDF form field macros (\verb|\TextField|, \verb|\CheckBox|, ...) support
2191 boolean flag options. The option name is the lowercase
2192 version of the names in the PDF specification (1.7):
2193
2194 \url{http://www.adobe.com/devnet/pdf/pdf_reference.html}
2195
2196 \url{http://www.adobe.com/devnet/acrobat/pdfs/pdf_reference.pdf}
2197
2198 Options (convert to lowercase) except flags in square brackets:
2199
2200 \begin{itemize}
2201 \item Table 8.16 Annotation flags (page 608):
2202
2203 {\obeylines
2204 1 Invisible
2205 2 Hidden (PDF 1.2)
2206 3 Print (PDF 1.2)
2207 4 NoZoom (PDF 1.3)
2208 5 NoRotate (PDF 1.3)
2209 6 NoView (PDF 1.3)
2210 [7 ReadOnly (PDF 1.3)] ignored for widget annotations, see table 8.70
2211 8 Locked (PDF 1.4)
2212 9 ToggleNoView (PDF 1.5)
2213 10 LockedContents (PDF 1.7)
2214 }
2215 \item Table 8.70 Field flags common to all field types (page 676):
2216
2217 {\obeylines
2218 1 ReadOnly
2219 2 Required
2220 3 NoExport
2221 }
2222 \item Table 8.75 Field flags specific to button fields (page 686):
2223
2224 {\obeylines
2225 15 NoToggleToOff (Radio buttons only)
2226 16 Radio (set: radio buttons, clear: check box, pushbutton: clear)
2227 17 Pushbutton
2228 26 RadiosInUniso (PDF 1.5)
2229 }
2230 \item Table 8.77 Field flags specific to text fields (page 691):
2231
2232 {\obeylines
2233 13 Multiline
2234 14 Password
2235 21 FileSelect (PDF 1.4)
2236 23 DoNotSpellCheck (PDF 1.4)
2237 24 DoNotScroll (PDF 1.4)
2238 25 Comb (PDF 1.5)
2239 26 RichText (PDF 1.5)
2240 }
2241 \item Table 8.79 Field flags specific to choice fields (page 693):
2242
2243 {\obeylines
2244 18 Combo (set: combo box, clear: list box)
2245 19 Edit (only useful if Combo is set)
2246 20 (Sort) for authoring tools, not PDF viewers
2247 22 MultiSelect (PDF 1.4)
2248 23 DoNotSpellCheck (PDF 1.4) (only useful if Combo and Edit are set)
2249 27 CommitOnSelChange (PDF 1.5)
2250 }
2251 \item Table 8.86 Flags for submit-form actions (page 704):
2252
2253 {\obeylines
2254 [1 Include/Exclude] unsupported, use `noexport' (table 8.70) instead
2255 2 IncludeNoValueFields
2256 [3 ExportFormat] handled by option `export'
2257 4 GetMethod
2258 5 SubmitCoordinates
2259 [6 XFDF (PDF 1.4)] handled by option `export'
2260 7 IncludeAppendSaves (PDF 1.4)
2261 8 IncludeAnnotations (PDF 1.4)
2262 [9 SubmitPDF (PDF 1.4)] handled by option `export'
2263 10 CanonicalFormat (PDF 1.4)
2264 11 ExclNonUserAnnots (PDF 1.4)
2265 12 ExclFKey (PDF 1.4)
2266 14 EmbedForm (PDF 1.5)
2267 }
2268 \end{itemize}
2269
2270 New option `export' sets the export format of a submit action.
2271 Valid values are (upper- or lowercase):
2272 \begin{itemize}
2273 \item FDF
2274 \item HTML
2275 \item XFDF
2276 \item PDF (not supported by Acrobat Reader)
2277 \end{itemize}
2278
2279 \subsection{Option `pdfversion'}
2280
2281 This is an experimental option. It notifies `hyperref' about
2282 the intended PDF version. Currently this is used in code for
2283 PDF forms (implementation notes 116 and 122 of PDF spec 1.7).
2284
2285
2286
2287 Values: 1.2, 1.3, 1.4, 1.5, 1.6, 1.7. Values below 1.2 are not
2288 supported, because most drivers expect higher PDF versions.
2289
2290
2291
2292 The option must be used early, not after \verb|\usepackage{hyperref}|.
2293
2294
2295 In theory this option should also set the PDF version,
2296 but this is not generally supported.
2297 \begin{itemize}
2298 \item pdfTeX below 1.10a: unsupported.
2299 pdfTeX $\ge$ 1.10a and < 1.30: \verb|\pdfoptionpdfminorversion|
2300 pdfTeX $\ge$ 1.30: \verb|\pdfminorversion|
2301 \item dvipdfm: configuration file, example:
2302 TeX Live 2007, texmf/dvipdfm/config/config, entry `V 2'.
2303 \item dvipdfmx: configuration file, example:
2304 TeX Live 2007, texmf/dvipdfm/dvipdfmx.cfg, entry `V 4'.
2305 \item Ghostscript: option -dCompatibilityLevel (this is set in
2306 `ps2pdf12', `ps2pdf13', `ps2pdf14').
2307 \end{itemize}
2308
2309
2310 The current PDF version is used as default if this version
2311 can be detected (only pdfTeX $\ge$ 1.10a). Otherwise the lowest
2312 version 1.2 is assumed. Thus `hyperref' tries to avoid PDF code
2313 that breaks this version, but is free to use ignorable higher PDF
2314 features.
2315
2316
2317 \subsection{Field option `name'}
2318
2319 Many form objects uses the label argument
2320 for several purposes:
2321 \begin{itemize}
2322 \item Layouted label.
2323 \item As name in HTML structures.
2324 \end{itemize}
2325 Code that is suitable for layouting with TeX can
2326 break in the structures of the output format.
2327 If option `name' is given, then its value is used
2328 as name in the different output structures. Thus
2329 the value should consist of letters only.
2330
2331
2332 \subsection{Option `pdfencoding'}
2333
2334 The PDF format allows two encodings for bookmarks and entries
2335 in the information dictionary: PDFDocEncoding and Unicode
2336 as UTF-16BE. Option \xoption{pdfencoding} selects between these encodings:
2337 \begin{itemize}
2338 \item \xoption{pdfdoc} uses PDFDocEncoding. It uses just one byte per character,
2339 but the supported characters are limited (244 in PDF-1.7).
2340 \item \xoption{unicode} sets Unicode. It is encoded as UTF-16BE. Two bytes
2341 are used for most characters, surrogates need four bytes.
2342 \item \xoption{auto} PDFDocEncoding if the string does not contain characters
2343 outside the encoding (outside ascii if an unicode engine is used)
2344 and Unicode otherwise. This option is not intended for the unicode engines.
2345 \end{itemize}
2346
2347 All drivers use \xoption{unicode} by default now. If another encoding should be forced,
2348 it should be done in \verb|hypersetup|.
2349
2350 \subsection{Color options/package hycolor}
2351
2352 See documentation of package `hycolor'.
2353
2354
2355 \subsection{Option pdfusetitle}
2356
2357 If option pdfusetitle is set then \xpackage{hyperref} tries to
2358 derive the values for pdftitle and pdfauthor from
2359 \verb|\title| and \verb|\author|. An optional argument for \verb|\title| and
2360 \verb|\author| is supported (class amsart).
2361
2362
2363 \subsection{Starred form of \textbackslash autoref}
2364
2365 \verb|\autoref*| generates a reference without link as \verb|\ref*| or \verb|\pageref*|.
2366
2367
2368 \subsection{Link border style}
2369
2370 Links can be underlined instead of the default rectangle or
2371 options \xoption{colorlinks}, \xoption{frenchlinks}. This is done by option
2372 \verb|pdfborderstyle={/S/U/W 1}|
2373
2374 Some remarks:
2375
2376 \begin{itemize}
2377 \item AR7/Linux seems to have a bug, that don't use the default
2378 value \verb"1" for the width, but zero, thus that the underline
2379 is not visible without \verb"/W 1". The same applies for
2380 dashed boxes, eg.:
2381 pdfborderstyle={/S/D/D[3 2]/W 1}
2382
2383 \item The syntax is described in the PDF specification, look for
2384 ``border style'', eg.
2385 Table 8.13 ``Entries in a border style dictionary''
2386 (specification for version 1.6)
2387
2388 \item The border style is removed by
2389 pdfborderstyle={}
2390 This is automatically done if option colorlinks is enabled.
2391
2392 \item Be aware that not all PDF viewers support this feature, not
2393 even Acrobat Reader itself:
2394
2395 Some support:
2396 \begin{itemize}
2397 \item AR7/Linux: \xoption{underline} and \xoption{dashed}, but the border width
2398 must be given.
2399 \item xpdf 3.00: \xoption{underline} and \xoption{dashed}
2400 \end{itemize}
2401
2402 Unsupported:
2403 \begin{itemize}
2404 \item AR5/Linux
2405 \item ghostscript 8.50
2406 \end{itemize}
2407 \end{itemize}
2408
2409 \subsection{Option \xoption{bookmarksdepth}}
2410
2411 The depth of the bookmarks can be controlled by the new
2412 option \xoption{bookmarksdepth}. The option acts globally and
2413 distinguishes three cases:
2414 \begin{itemize}
2415 \item \xoption{bookmarksdepth} without value
2416 Then \xpackage{hyperref} uses the current value of counter \xoption{tocdepth}.
2417 This is the compatible behaviour and the default.
2418 \item \verb"bookmarksdepth=<number>", the value is number (also negative):
2419 The depth for the bookmarks are set to this number.
2420 \item \verb"bookmarksdepth=<name>"
2421 The <name> is a document division name (part, chapter, ...).
2422 It must not start with a digit or minus to avoid mixing up
2423 with the number case. Internally \xpackage{hyperref} uses the value
2424 of macro \verb|\toclevel@<name>|.
2425 Examples:
2426 \begin{verbatim}
2427 \hypersetup{bookmarksdepth=paragraph}
2428 \hypersetup{bookmarksdepth=4} % same as before
2429 \hypersetup{bookmarksdepth} % counter "tocdepth" is used
2430 \end{verbatim}
2431 \end{itemize}
2432
2433 \subsection{Option \xoption{pdfescapeform}}
2434
2435 There are many places where arbitrary strings end up as
2436 PS or PDF strings. The PS/PDF strings in parentheses form
2437 require the protection of some characters, e.g. unmatched
2438 left or right parentheses need escaping or the escape
2439 character itself (backslash).
2440 Since 2006/02/12~v6.75a the PS/PDF driver should do
2441 this automatically. However I assume a problem with
2442 compatibility, especially regarding the form part where
2443 larger amounts of JavaScript code can be present.
2444 It would be a pain to remove all the escaping, because
2445 an additional escaping layer can falsify the code.
2446
2447 Therefore a new option pdfescapeform was introduced:
2448 \begin{itemize}
2449 \item pdfescapeform=false
2450 Escaping for the formulars are disabled, this is
2451 the compatibility behaviour, therefore this is the default.
2452 \item pdfescapeform=true
2453 Then the PS/PDF drivers do all the necessary escaping.
2454 This is the logical choice and the recommended setting.
2455 For example, the user writes JavaScript as JavaScript
2456 and do not care about escaping characters for PS/PDF
2457 output.
2458 \end{itemize}
2459
2460 \subsection{Default driver setting}
2461
2462 (hyperref $\ge$ 6.72s)
2463 If no driver is given, \xpackage{hyperref} tries its best to guess the
2464 most suitable driver. Thus it loads \xoption{hpdftex}, if pdfTeX is
2465 detected running in PDF mode. Or it loads the corresponding
2466 VTeX driver for VTeX's working modes.
2467 Unhappily many driver programs run after the TeX compiler,
2468 so \xpackage{hyperref} does not have a chance (dvips, dvipdfm, ...).
2469 In this case driver \xoption{hypertex} is loaded that supports the
2470 HyperTeX features that are recognized by xdvi for example.
2471 This behaviour, however, can easily be changed in the configuration
2472 file \verb"hyperref.cfg":
2473 \begin{verbatim}
2474 \providecommand*{\Hy@defaultdriver}{hdvips}
2475 \end{verbatim}
2476 for dvips, or
2477 \begin{verbatim}
2478 \providecommand*{\Hy@defaultdriver}{hypertex}
2479 \end{verbatim}
2480 for the default behaviour of \xpackage{hyperref}.
2481
2482 See also the new option `driverfallback'.
2483
2484 \subsection{Backref entries}
2485
2486 Alternative interface for formatting of backref entries, example:
2487
2488 \begin{verbatim}
2489 \documentclass[12pt,UKenglish]{article}
2490
2491 \usepackage{babel}
2492 \usepackage[pagebackref]{hyperref}
2493
2494 % Some language options are detected by package backref.
2495 % This affects the following macros:
2496 % \backrefpagesname
2497 % \backrefsectionsname
2498 % \backrefsep
2499 % \backreftwosep
2500 % \backreflastsep
2501
2502 \renewcommand*{\backref}[1]{
2503 % default interface
2504 % #1: backref list
2505 %
2506 % We want to use the alternative interface,
2507 % therefore the definition is empty here.
2508 }
2509 \renewcommand*{\backrefalt}[4]{%
2510 % alternative interface
2511 % #1: number of distinct back references
2512 % #2: backref list with distinct entries
2513 % #3: number of back references including duplicates
2514 % #4: backref list including duplicates
2515 \par
2516 #3 citation(s) on #1 page(s): #2,\par
2517 \ifnum#1=1 %
2518 \ifnum#3=1 %
2519 1 citation on page %
2520 \else
2521 #3 citations on page %
2522 \fi
2523 \else
2524 #3 citations on #1 pages %
2525 \fi
2526 #2,\par
2527 \ifnum#3=1 %
2528 1 citation located at page %
2529 \else
2530 #3 citations located at pages %
2531 \fi
2532 #4.\par
2533 }
2534
2535 % The list of distinct entries can be further refined:
2536 \renewcommand*{\backrefentrycount}[2]{%
2537 % #1: the original backref entry
2538 % #2: the count of citations of this entry,
2539 % in case of duplicates greater than one
2540 #1%
2541 \ifnum#2>1 %
2542 ~(#2)%
2543 \fi
2544 }
2545
2546 \begin{document}
2547
2548 \section{Hello}
2549 \cite{ref1, ref2, ref3, ref4}
2550 \section{World}
2551 \cite{ref1, ref3}
2552 \newpage
2553
2554 \section{Next section}
2555 \cite{ref1}
2556 \newpage
2557
2558 \section{Last section}
2559 \cite{ref1, ref2}
2560 \newpage
2561
2562 \pdfbookmark[1]{Bibliography}{bib}
2563 \begin{thebibliography}{99}
2564 \bibitem{ref1} Dummy entry one.
2565
2566 \bibitem{ref2} Dummy entry two.
2567
2568 \bibitem{ref3} Dummy entry three.
2569
2570 \bibitem{ref4} Dummy entry four.
2571
2572 \end{thebibliography}
2573
2574 \end{document}
2575 \end{verbatim}
2576
2577 \subsection{\textbackslash phantomsection}
2578
2579 Set an anchor at this location. It is often used in conjunction
2580 with \verb|\addcontentsline| for sectionlike things (index, bibliography,
2581 preface). \verb|\addcontentsline| refers to the latest previous location
2582 where an anchor is set.
2583
2584 \begin{verbatim}
2585 \cleardoublepage
2586 \phantomsection
2587 \addcontentsline{toc}{chapter}{\indexname}
2588 \printindex
2589 \end{verbatim}
2590
2591 Now the entry in the table of contents (and bookmarks) for the
2592 index points to the start of the index page, not to a location
2593 before this page.
2594
2595 \subsection{puenc encoding, puenc-greekbasic.def and puenc-extra.def}
2596
2597 The \texttt{unicode} option loads for the bookmarks \texttt{puenc.def} which contains
2598 quite a lot definitions of commands for the bookmarks.
2599 As \texttt{unicode} is now true for all engines, this file is now also loaded
2600 with pdflatex. Some of the definitions in \texttt{puenc.def} clash with other uses.
2601 To reduce the impact \xpackage{hyperref} uses two strategies.
2602
2603 \begin{itemize}
2604 \item A number of commands are only defined conditionally:
2605 The commands for the cyrillic block if \cs{CYRDZE} is defined,
2606 greek if \cs{textBeta} is defined, and hebrew if \cs{hebdalet} is defined.
2607
2608 The greek block is in an extra file, \texttt{puenc-greekbasic.def}, which can
2609 be loaded manually if needed.
2610
2611 \item Other commands are moved to an extra file \texttt{puenc-extra.def}
2612 which is not loaded automatically, but can be loaded in the preamble if needed.
2613 Currently this file contains all definitions for the accent \cs{G}.
2614 \end{itemize}
2615
2616
2617
2618 \section{Acrobat-specific behavior}
2619 If you want to access the menu options of Acrobat Reader or Exchange, the following
2620 macro is provided in the appropriate drivers:
2621
2622 \begin{cmdsyntax}
2623 \ci{Acrobatmenu}\verb|{|\emph{menuoption}\verb|}{|\emph{text}\verb|}|
2624 \end{cmdsyntax}
2625
2626 \noindent The \emph{text} is used to create a button which activates the appropriate \emph{menuoption}. The following table lists the option names you can use---comparison of this with the menus in Acrobat Reader or Exchange will show what they do. Obviously some are only appropriate to Exchange.
2627
2628 \medskip
2629 \begin{longtable}{@{}l>{\raggedright\arraybackslash}p{9cm}@{}}
2630 File & Open, Close, Scan, Save, SaveAs, Optimizer:SaveAsOpt, Print, PageSetup, Quit \\
2631 File$\rightarrow$Import & ImportImage, ImportNotes, AcroForm:ImportFDF \\
2632 File$\rightarrow$Export & ExportNotes, AcroForm:ExportFDF \\
2633 File$\rightarrow$DocumentInfo & GeneralInfo, OpenInfo, FontsInfo, SecurityInfo, Weblink:Base, AutoIndex:DocInfo \\
2634 File$\rightarrow$Preferences & GeneralPrefs, NotePrefs, FullScreenPrefs, Weblink:Prefs, AcroSearch:Preferences(Windows)
2635 or, AcroSearch:Prefs(Mac), Cpt:Capture \\
2636 Edit & Undo, Cut, Copy, Paste, Clear, SelectAll, Ole:CopyFile, TouchUp:TextAttributes,
2637 TouchUp:FitTextToSelection, TouchUp:ShowLineMarkers, TouchUp:ShowCaptureSuspects,
2638 TouchUp:FindSuspect, \\
2639 & Properties \\
2640 Edit$\rightarrow$Fields & AcroForm:Duplicate, AcroForm:TabOrder \\
2641 Document & Cpt:CapturePages, AcroForm:Actions, CropPages, RotatePages, InsertPages, ExtractPages,
2642 ReplacePages, DeletePages, NewBookmark, SetBookmarkDest, CreateAllThumbs,
2643 DeleteAllThumbs \\
2644 View & ActualSize, FitVisible, FitWidth, FitPage, ZoomTo, FullScreen, FirstPage, PrevPage,
2645 NextPage, LastPage, GoToPage, GoBack, GoForward, SinglePage, OneColumn, TwoColumns,
2646 ArticleThreads, PageOnly, ShowBookmarks, ShowThumbs \\
2647 Tools & Hand, ZoomIn, ZoomOut, SelectText, SelectGraphics, Note, Link, Thread, AcroForm:Tool,
2648 Acro\_Movie:MoviePlayer, TouchUp:TextTool, Find, FindAgain, FindNextNote,
2649 CreateNotesFile \\
2650 Tools$\rightarrow$Search & AcroSrch:Query, AcroSrch:Indexes, AcroSrch:Results, AcroSrch:Assist, AcroSrch:PrevDoc,
2651 AcroSrch:PrevHit, AcroSrch:NextHit, AcroSrch:NextDoc \\
2652 Window & ShowHideToolBar, ShowHideMenuBar, ShowHideClipboard, Cascade, TileHorizontal,
2653 TileVertical, CloseAll \\
2654 Help & HelpUserGuide, HelpTutorial, HelpExchange, HelpScan, HelpCapture, HelpPDFWriter,
2655 HelpDistiller, HelpSearch, HelpCatalog, HelpReader, Weblink:Home \\
2656 Help(Windows) & About
2657 \end{longtable}
2658
2659 \section{PDF and HTML forms}
2660 You must put your fields inside a \texttt{Form} environment.
2661 The environment does some general setups, so should be used only once in a document.
2662 Using simply \cs{Form} at the begin of the document is possible too.
2663
2664 There are six macros to prepare fields:
2665
2666 \begin{cmdsyntax}
2667 \ci{TextField}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}|
2668 \end{cmdsyntax}
2669
2670 \begin{cmdsyntax}
2671 \ci{CheckBox}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}|
2672 \end{cmdsyntax}
2673
2674 \begin{cmdsyntax}
2675 \ci{ChoiceMenu}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}{|\emph{choices}\verb|}|
2676 \end{cmdsyntax}
2677
2678 \begin{cmdsyntax}
2679 \ci{PushButton}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}|
2680 \end{cmdsyntax}
2681
2682 \begin{cmdsyntax}
2683 \ci{Submit}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}|
2684 \end{cmdsyntax}
2685
2686 \begin{cmdsyntax}
2687 \ci{Reset}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}|
2688 \end{cmdsyntax}
2689
2690 The way forms and their labels are laid out is determined by:
2691 \begin{cmdsyntax}
2692 \ci{LayoutTextField}\verb|{|\emph{label}\verb|}{|\emph{field}\verb|}|
2693 \end{cmdsyntax}
2694
2695 \begin{cmdsyntax}
2696 \ci{LayoutChoiceField}\verb|{|\emph{label}\verb|}{|\emph{field}\verb|}|
2697 \end{cmdsyntax}
2698
2699 \begin{cmdsyntax}
2700 \ci{LayoutCheckField}\verb|{|\emph{label}\verb|}{|\emph{field}\verb|}|
2701 \end{cmdsyntax}
2702
2703 These macros default to \#1 \#2
2704
2705 What is actually shown in the field is determined by:
2706 \begin{cmdsyntax}
2707 \ci{MakeRadioField}\verb|{|\emph{width}\verb|}{|\emph{height}\verb|}|
2708 \end{cmdsyntax}
2709
2710 \begin{cmdsyntax}
2711 \ci{MakeCheckField}\verb|{|\emph{width}\verb|}{|\emph{height}\verb|}|
2712 \end{cmdsyntax}
2713 \begin{cmdsyntax}
2714 \ci{MakeTextField}\verb|{|\emph{width}\verb|}{|\emph{height}\verb|}|
2715 \end{cmdsyntax}
2716 \begin{cmdsyntax}
2717 \ci{MakeChoiceField}\verb|{|\emph{width}\verb|}{|\emph{height}\verb|}|
2718 \end{cmdsyntax}
2719
2720 \begin{cmdsyntax}
2721 \ci{MakeButtonField}\verb|{|\emph{text}\verb|}|
2722 \end{cmdsyntax}
2723
2724 These macros default to \verb|\vbox to #2{\hbox to #1{\hfill}\vfill}|, except the
2725 last, which defaults to \#1; it is used for buttons, and the special \ci{Submit} and \ci{Reset}
2726 macros.
2727
2728 You may also want to redefine the following macros:
2729 \begin{verbatim}
2730 \def\DefaultHeightofSubmit{12pt}
2731 \def\DefaultWidthofSubmit{2cm}
2732 \def\DefaultHeightofReset{12pt}
2733 \def\DefaultWidthofReset{2cm}
2734 \def\DefaultHeightofCheckBox{0.8\baselineskip}
2735 \def\DefaultWidthofCheckBox{0.8\baselineskip}
2736 \def\DefaultHeightofChoiceMenu{0.8\baselineskip}
2737 \def\DefaultWidthofChoiceMenu{0.8\baselineskip}
2738 \def\DefaultHeightofText{\baselineskip}
2739 \def\DefaultHeightofTextMultiline{4\baselineskip}
2740 \def\DefaultWidthofText{3cm}
2741 \end{verbatim}
2742
2743 \subsection{Forms environment parameters}
2744
2745 \smallskip
2746 \begin{longtable}{@{}>{\ttfamily}l>{\itshape}lp{9cm}@{}}
2747 action & URL & The URL that will receive the form data if a \textsf{Submit} button is included in the form \\
2748 encoding & name & The encoding for the string set to the URL; FDF-encoding is usual, and \texttt{html} is the only
2749 valid value \\
2750 method & name & Used only when generating HTML; values can be \texttt{post} or \texttt{get} \\
2751 \end{longtable}
2752
2753 \subsection{Forms optional parameters}
2754 Note that all colors must be expressed as rgb triples, in the range 0..1 (i.e.\ \texttt{color=0 0
2755 0.5})
2756
2757 \smallskip
2758 \begin{longtable}{@{}>{\ttfamily}ll>{\itshape}ll@{}}
2759 accesskey & key & & (as per HTML) \\
2760 align & number & 0 & alignment within text field; 0 is left-aligned,\\*
2761 & & & 1 is centered, 2 is right-aligned. \\
2762 altname & name & & alternative name,\\*
2763 & & & the name shown in the user interface\\
2764 backgroundcolor & & & color of box \\
2765 bordercolor & & & color of border \\
2766 bordersep & & & box border gap \\
2767 borderstyle & char & S & box border style; S (Solid) is default, B is Beveled,\\
2768 & & & D is Dashed, I is Inset and U is Underline \\
2769 borderwidth & & 1 & width of box border, the value is a dimension\\
2770 & & & or a number with default unit bp\\
2771 calculate & & & JavaScript code to calculate the value of the field \\
2772 charsize & dimen & & font size of field text \\
2773 checkboxsymbol & char & 4 (\ding{\number`4}) & symbol used for check boxes (ZapfDingbats), \\
2774 &&& the value is a character or \cs{ding}\verb|{|\texttt{\itshape number}\verb|}|, \\
2775 &&& see package \xpackage{pifont} from bundle \xpackage{psnfss} \\
2776 checked & boolean & false & whether option selected by default \\
2777 color & & & color of text in box \\
2778 combo & boolean & false & choice list is `combo' style \\
2779 default & & & default value \\
2780 disabled & boolean & false & field disabled \\
2781 format & & & JavaScript code to format the field \\
2782 height & dimen & & height of field box \\
2783 hidden & boolean & false & field hidden \\
2784 keystroke & & & JavaScript code to control the keystrokes on entry \\
2785 mappingname & name & & the mapping name to be used when exporting\\*
2786 & & & the field data\\
2787 maxlen & number & 0 & number of characters allowed in text field \\
2788 menulength & number & 4 & number of elements shown in list \\
2789 multiline & boolean & false & whether text box is multiline \\
2790 name & name & & name of field (defaults to label) \\
2791 onblur & & & JavaScript code \\
2792 onchange & & & JavaScript code \\
2793 onclick & & & JavaScript code \\
2794 ondblclick & & & JavaScript code \\
2795 onfocus & & & JavaScript code \\
2796 onkeydown & & & JavaScript code \\
2797 onkeypress & & & JavaScript code \\
2798 onkeyup & & & JavaScript code \\
2799 onmousedown & & & JavaScript code \\
2800 onmousemove & & & JavaScript code \\
2801 onmouseout & & & JavaScript code \\
2802 onmouseover & & & JavaScript code \\
2803 onmouseup & & & JavaScript code \\
2804 onselect & & & JavaScript code \\
2805 password & boolean & false & text field is `password' style \\
2806 popdown & boolean & false & choice list is `popdown' style \\
2807 radio & boolean & false & choice list is `radio' style \\
2808 radiosymbol & char & H (\ding{\number`H}) & symbol used for radio fields (ZapfDingbats), \\
2809 &&& the value is a character or \cs{ding}\verb|{|\texttt{\itshape number}\verb|}|, \\
2810 &&& see package \xpackage{pifont} from bundle \xpackage{psnfss} \\
2811 readonly & boolean & false & field is readonly \\
2812 rotation & number & 0 & rotation of the widget annotation \\*
2813 & & & (degree, counterclockwise, multiple of 90)\\
2814 tabkey & & & (as per HTML) \\
2815 validate & & & JavaScript code to validate the entry \\
2816 value & & & initial value \\
2817 width & dimen & & width of field box
2818 \end{longtable}
2819
2820 \section{Defining a new driver}
2821 A \xpackage{hyperref} driver has to provide definitions for eight macros:
2822
2823 \smallskip
2824 \noindent 1. \verb|\hyper@anchor|
2825
2826 \noindent 2. \verb|\hyper@link|
2827
2828 \noindent 3. \verb|\hyper@linkfile|
2829
2830 \noindent 4. \verb|\hyper@linkurl|
2831
2832 \noindent 5. \verb|\hyper@anchorstart|
2833
2834 \noindent 6. \verb|\hyper@anchorend|
2835
2836 \noindent 7. \verb|\hyper@linkstart|
2837
2838 \noindent 8. \verb|\hyper@linkend|
2839 \smallskip
2840
2841 The draft option defines the macros as follows
2842 \begin{verbatim}
2843 \let\hyper@@anchor\@gobble
2844 \gdef\hyper@link##1##2##3{##3}%
2845 \def\hyper@linkurl##1##2{##1}%
2846 \def\hyper@linkfile##1##2##3{##1}%
2847 \let\hyper@anchorstart\@gobble
2848 \let\hyper@anchorend\@empty
2849 \let\hyper@linkstart\@gobbletwo
2850 \let\hyper@linkend\@empty
2851 \end{verbatim}
2852
2853 \section{Special support for other packages}
2854
2855 Package \xpackage{hyperref} aims to cooperate with other packages, but while
2856 the long term goal is to remove patches and to move link support into the
2857 kernel, classes and packages there are still several possible sources for
2858 conflict, such as
2859
2860 \begin{itemize}
2861
2862 \item Packages that manipulate the bibliographic mechanism. Peter William's
2863 \xpackage{harvard} package is supported. However, the recommended
2864 package is either Patrick Daly's \xpackage{natbib} package that has
2865 specific \xpackage{hyperref} hooks to allow reliable interaction or the
2866 \xpackage{biblatex} package. Both packages cover a very wide variety of
2867 layouts and citation styles, all of which work with
2868 \xpackage{hyperref}.
2869
2870 \item Packages that changes \ci{label} and \ci{ref} macros. Since \LaTeX{}
2871 2023-06-01 the kernel and \xpackage{hyperref}/\xpackage{nameref} use
2872 the same \ci{label} definition. \ci{label} has a hook for external
2873 packages. There should be no need for external packages and classes to
2874 redefine them.
2875
2876 \item Packages that do anything serious with the index.
2877
2878 \item Packages that do anything serious with sectioning commands and the
2879 toc.
2880 \end{itemize}
2881
2882
2883
2884 The \xpackage{hyperref} package is distributed with a variant of the
2885 \xpackage{xr}, \xpackage{xr-hyper}\footnote{It will be merged with the
2886 \xpackage{xr} package soon}, which support crossdocument links using
2887 \hologo{LaTeX}'s normal \cs{label}/\cs{ref} mechanisms.
2888
2889
2890 \subsection{Package Compatibility}
2891
2892 Currently only package loading orders are available:
2893
2894
2895 \subsubsection{algorithm}
2896 \begin{verbatim}
2897 \usepackage{float}
2898 \usepackage{hyperref}
2899 \usepackage[chapter]{algorithm}% eg.
2900 \end{verbatim}
2901
2902 \subsubsection{amsmath}
2903
2904 The environments equation and eqnarray are not supported too well.
2905 For example, there might be spacing problems (eqnarray isn't recommended
2906 anyway, see CTAN:info/l2tabu/, the situation for equation is unclear,
2907 because nobody is interested in investigating). Consider using the
2908 environments that package amsmath provide, e.g. gather for equation.
2909 The environment equation can even redefined to use gather:
2910
2911 \begin{verbatim}
2912 \usepackage{amsmath}
2913 \let\equation\gather
2914 \let\endequation\endgather
2915 \end{verbatim}
2916
2917 \subsubsection{amsrefs}
2918
2919 The documentation of \xpackage{amsrefs} claims that the package must be
2920 loaded after \xpackage{hyperref} (it is unclear if that is really true) so
2921 the recommended package loading order is:
2922
2923 \begin{verbatim}
2924 \usepackage{hyperref}
2925 \usepackage{amsrefs}
2926 \end{verbatim}
2927
2928 \subsubsection{arydshln, longtable}
2929
2930 Package \xpackage{longtable} must be put before \xpackage{hyperref} and \xpackage{arydshln},
2931 \xpackage{hyperref} after \xpackage{arydshln} generates an error, thus the
2932 resulting package order is then:
2933
2934 \begin{verbatim}
2935 \usepackage{longtable}
2936 \usepackage{hyperref}
2937 \usepackage{arydshln}
2938 \end{verbatim}
2939
2940 \subsubsection{babel/magyar.ldf}
2941
2942 The old version 2005/03/30 v1.4j will not work.
2943 You need at least version 1.5, maintained by P\'eter Szab\'o,
2944 see CTAN:language/hungarian/babel/.
2945
2946
2947 \subsubsection{babel/spanish.ldf}
2948
2949 Babel's spanish.ldf redefines `\verb|\.|' to support `\verb|\...|'.
2950 In bookmarks (\verb|\pdfstringdef|) only `\verb|\.|' is supported.
2951 If `\verb|\...|' is needed,
2952 \verb|\texorpdfstring{\...}{\dots}|
2953 can be used instead.
2954
2955
2956 \subsubsection{bibentry}
2957
2958 Workaround:
2959
2960 \begin{verbatim}
2961 \makeatletter
2962 \let\saved@bibitem\@bibitem
2963 \makeatother
2964
2965 \usepackage{bibentry}
2966 \usepackage{hyperref}
2967
2968 \begin{document}
2969
2970 \begingroup
2971 \makeatletter
2972 \let\@bibitem\saved@bibitem
2973 \nobibliography{database}
2974 \endgroup
2975 \end{verbatim}
2976
2977 \subsubsection{bigfoot}
2978
2979 \xpackage{hyperref} does not support package \xpackage{bigfoot}. And package
2980 \xpackage{bigfoot} does not support \xpackage{hyperref}'s footnotes and disables
2981 them (hyperfootnotes=false).
2982
2983
2984 \subsubsection{chappg}
2985
2986 Package \xpackage{chappg} uses \verb|\@addtoreset| that is redefined by \xpackage{hyperref}.
2987 The package order is therefore:
2988
2989 \begin{verbatim}
2990 \usepackage{hyperref}
2991 \usepackage{chappg}
2992 \end{verbatim}
2993
2994 \subsubsection{count1to}
2995
2996 Package `count1to' adds several \verb|\@addtoreset| commands that confuse
2997 `hyperref'. Therefore \verb|\theH<...>| has to be fixed:
2998
2999 \begin{verbatim}
3000 \usepackage{count1to}
3001 \AtBeginDocument{% *after* \usepackage{count1to}
3002 \renewcommand*{\theHsection}{\theHchapter.\arabic{section}}%
3003 \renewcommand*{\theHsubsection}{\theHsection.\arabic{subsection}}%
3004 \renewcommand*{\theHsubsubsection}{\theHsubsection.\arabic{subsubsection}}%
3005 \renewcommand*{\theHparagraph}{\theHsubsubsection.\arabic{paragraph}}%
3006 \renewcommand*{\theHsubparagraph}{\theHparagraph.\arabic{subparagraph}}%
3007 }
3008 \end{verbatim}
3009
3010 \subsubsection{dblaccnt}
3011
3012 pd1enc.def or puenc.def should be loaded before:
3013 \begin{verbatim}
3014 \usepackage{hyperref}
3015 \usepackage{dblaccnt}
3016 \end{verbatim}
3017 or see entry for \xoption{vietnam}.
3018
3019
3020 \subsubsection{easyeqn}
3021 Not compatible, breaks.
3022
3023
3024 \subsubsection{ellipsis}
3025
3026 This packages redefines \verb|\textellipsis|
3027 after package \xpackage{hyperref} (pd1enc.def/puenc.def should be loaded before):
3028 \begin{verbatim}
3029 \usepackage{hyperref}
3030 \usepackage{ellipsis}
3031 \end{verbatim}
3032
3033 (this will lead to wrong ellipsis in the bookmarks, so \verb|\texorpdfstring| is needed).
3034
3035 \subsubsection{float}
3036 \begin{verbatim}
3037 \usepackage{float}
3038 \usepackage{hyperref}
3039 \end{verbatim}
3040 \begin{itemize}
3041 \item Several \verb|\caption| commands are not supported inside one float object.
3042 \item Anchor are set at top of the float object, if its style is controlled
3043 by float.sty.
3044 \end{itemize}
3045
3046 \subsubsection{endnotes}
3047 Unsupported.
3048
3049 \subsubsection{foiltex}
3050 Update to version 2008/01/28 v2.1.4b:
3051 Since version 6.77a \xpackage{hyperref} does not hack into \verb|\@begindvi|,
3052 it uses package `atbegshi' instead, that hooks into \verb|\shipout|.
3053 Thus the patch of `foils.cls' regarding \xpackage{hyperref} is now obsolete
3054 and causes an undefined error message about \verb|\@hyperfixhead|.
3055 This is fixed in FoilTeX 2.1.4b.
3056
3057
3058 \subsubsection{footnote}
3059
3060 This package is not supported, you have to disable \xpackage{hyperref}'s footnote
3061 support by using option \verb"hyperfootnotes=false".
3062
3063
3064 \subsubsection{linguex}
3065 \begin{verbatim}
3066 \usepackage{hyperref}
3067 \usepackage{linguex}
3068 \end{verbatim}
3069
3070 \subsubsection{ltabptch}
3071 \begin{verbatim}
3072 \usepackage{longtable}
3073 \usepackage{ltabptch}
3074 \usepackage{hyperref}
3075 \end{verbatim}
3076
3077 \subsubsection{mathenv}
3078
3079 Unsupported.
3080
3081
3082
3083 Both \xpackage{mathenv} and \xpackage{hyperref} messes around with
3084 environment \texttt{eqnarray}. You can load \xpackage{mathenv} after
3085 \xpackage{hyperref} to avoid an error message. But \verb|\label|
3086 will not work inside environment \texttt{eqnarray} properly,
3087 for example.
3088
3089
3090 \subsubsection{minitoc-hyper}
3091
3092 This package is obsolete, use the up-to-date original
3093 package \xpackage{minitoc} instead.
3094
3095
3096
3097 \subsubsection{multind}
3098 \begin{verbatim}
3099 \usepackage{multind}
3100 \usepackage{hyperref}
3101 \end{verbatim}
3102
3103 \subsubsection{natbib}
3104 \begin{verbatim}
3105 \usepackage{natbib}
3106 \usepackage{hyperref}
3107 \end{verbatim}
3108
3109 \subsubsection{nomencl}
3110 Example for introducing links for the page numbers:
3111 \begin{verbatim}
3112 \renewcommand*{\pagedeclaration}[1]{\unskip, \hyperpage{#1}}
3113 \end{verbatim}
3114
3115 \subsubsection{ntheorem}
3116
3117 This package is not fully supported. The \texttt{thref} option should not be used at all as
3118 it breaks the \verb+\label+ command. It also not guaranteed that links to theorems always work
3119 properly as the package redefines many internals and but offers no proper interface for hyperlinks.
3120
3121
3122 \subsubsection{ntheorem-hyper}
3123 This package is obsolete, use the up-to-date original
3124 package \xpackage{ntheorem} instead.
3125
3126
3127 For equations the following might work:
3128 \begin{verbatim}
3129 \renewcommand*{\eqdeclaration}[1]{%
3130 \hyperlink{equation.#1}{(Equation~#1)}%
3131 }
3132 But the mapping from the equation number to the anchor name
3133 is not available in general.
3134 \end{verbatim}
3135
3136
3137 \subsubsection{prettyref}
3138 \begin{verbatim}
3139 %%% example for prettyref %%%
3140 \documentclass{article}
3141 \usepackage{prettyref}
3142 \usepackage{hyperref}
3143
3144 %\newrefformat{FIG}{Figure~\ref{#1}}% without hyperref
3145 \newrefformat{FIG}{\hyperref[{#1}]{Figure~\ref*{#1}}}
3146
3147 \begin{document}
3148 This is a reference to \prettyref{FIG:ONE}.
3149 \newpage
3150 \begin{figure}
3151 \caption{This is my figure}
3152 \label{FIG:ONE}
3153 \end{figure}
3154 \end{document}
3155 %%% example for prettyref %%%
3156 \end{verbatim}
3157
3158
3159 \subsubsection{setspace}
3160 \begin{verbatim}
3161 \usepackage{setspace}
3162 \usepackage{hyperref}
3163 \end{verbatim}
3164
3165 \subsubsection{sidecap}
3166 Nothing special is needed anymore.
3167
3168 \subsubsection{subfigure}
3169 The package is obsolete. Use either \xpackage{subfig}
3170 or \xpackage{subcaption}
3171
3172 \subsubsection{titleref}
3173 \begin{verbatim}
3174 \usepackage{nameref}
3175 \usepackage{titleref}% without usetoc
3176 \usepackage{hyperref}
3177 \end{verbatim}
3178
3179 \subsubsection{tabularx}
3180
3181 Linked footnotes are not supported inside environment \texttt{tabularx},
3182 because they uses the optional argument of \verb|\footnotetext|, see
3183 section `Limitations'. Before version 2011/09/28 6.82i
3184 \xpackage{hyperref} had disabled footnotes entirely by \texttt{hyperfootnotes=false}.
3185
3186
3187 \subsubsection{titlesec}
3188
3189 \xpackage{nameref} supports \xpackage{titlesec}, but \xpackage{hyperref} does not
3190 (unsolved is the anchor setting, missing with unnumbered
3191 section, perhaps problems with page breaks with numbered ones).
3192
3193
3194 \subsubsection{ucs/utf8x.def}
3195 Note: utf8 is now the default in \LaTeX{} and \xpackage{ucs} is no
3196 longer recommended.
3197
3198 The first time a multibyte UTF8 sequence is called, it
3199 does some calculations and stores the result in a macro
3200 for speeding up the next calls of that UTF8 sequence.
3201 However this makes the first call non-expandable and
3202 will break if used in information entries or bookmarks.
3203 Package \xpackage{ucs} offers \verb|\PrerenderUnicode| or \verb|\PreloadUnicodePage|
3204 to solve this:
3205 \begin{verbatim}
3206 \usepackage{ucs}
3207 \usepackage[utf8x]{inputenc}
3208 \usepackage{hyperref}% or with option unicode
3209 \PrerenderUnicode{^^c3^^b6}% or \PrerenderUnicodePage{1}
3210 \hypersetup{pdftitle={Umlaut example: ^^c3^^b6}}
3211 \end{verbatim}
3212 The notation with two carets avoids trouble with 8-bit bytes
3213 for the README file, you can use the characters directly.
3214
3215
3216 \subsubsection{varioref}
3217 Most previous problems with \xpackage{varioref} should be resolved. There is
3218 only an open issue regarding \ci{vrefformat}
3219 (\url{https://github.com/latex3/hyperref/issues/225}).
3220
3221 It is recommended to load \xpackage{varioref} always with the option
3222 \texttt{nospace}, see the documentation.
3223 \begin{verbatim}
3224 \usepackage[nospace]{varioref}
3225 \end{verbatim}
3226
3227 \subsubsection{verse}
3228
3229 Version 2005/08/22 v2.22 contains support for \xpackage{hyperref}.
3230
3231 \subsubsection{vietnam}
3232 \begin{verbatim}
3233 % pd1enc.def should be loaded before package dblaccnt:
3234 \usepackage[PD1,OT1]{fontenc}
3235 \usepackage{vietnam}
3236 \usepackage{hyperref}
3237 \end{verbatim}
3238
3239 \subsubsection{XeTeX}
3240
3241 Default for the encoding of bookmarks is \verb|pdfencoding=unicode|.
3242 That means the strings are always treated as unicode strings.
3243 If \verb|auto| or \verb|pdfdoc| is forced it applies only
3244 if the string restricts to the printable ASCII set,
3245 The reason is that the \verb|\special| does not support PDFDocEncoding.
3246
3247 In older versions \xpackage{hyperref} contained special conversion code from
3248 UTF-16BE back to UTF-8 in a number of places for
3249 xetex to avoid the xdvipdfmx warning
3250
3251 \verb"Failed to convert input string to UTF16..."
3252
3253 This is no longer needed with a current xdvipdfmx, so this code has
3254 been removed. \verb|\csname HyPsd@XeTeXBigCharstrue\endcsname| should no
3255 longer be used.
3256
3257
3258 \section[Limitations]{Limitations%
3259 \footnote{This section moved from the README file, needs more integration into the manual}}
3260 \subsection{Wrapped/broken link support}
3261
3262 Only few drivers support automatically wrapped/broken links,
3263 e.g. pdftex, dvipdfmx, hypertex. Other drivers lack this
3264 feature, e.g. dvips, dvipsone.
3265
3266 Workarounds:
3267 \begin{itemize}
3268 \item For long section or caption titles in the table of contents
3269 or list of figures/tables option \xoption{linktocpage} can be used.
3270 Then the page number will be a link, and the overlong section
3271 title is not forced into an one line link with overfull \verb|\hbox|
3272 warning.
3273 \item ``\verb|\url|''s are caught by package \xpackage{breakurl}.
3274 \item The option \xoption{breaklinks} is intended for internal use. But it
3275 can be used to force link wrapping, e.g. when printing a
3276 document. However, when such a document is converted to PDF
3277 and viewed with a PDF viewer, the active link area will be
3278 misplaced.
3279
3280 Another limitation: some penalties are ``optimized'' by TeX,
3281 thus there are missing break points, especially within
3282 \verb|\url|. (See thread ``hyperref.sty, breaklinks and url.sty 3.2''
3283 in comp.text.tex 2005-09).
3284 \end{itemize}
3285
3286 \subsection{Links across pages}
3287
3288 In general they have problems:
3289 \begin{itemize}
3290 \item Some driver doesn't support them at all (see above).
3291 \item The driver allows it, but the link result might include the footer
3292 and/or header. This can currently (2023) be avoided by using the PDF
3293 management and to load at least the new-or-1 module from latex-lab:
3294
3295 \begin{verbatim}
3296 \DocumentMetadata{testphase=new-or-1}
3297 \end{verbatim}
3298
3299 \end{itemize}
3300
3301 \subsection{Footnotes}
3302
3303 LaTeX allows the separation of the footnote mark and the
3304 footnote text (\verb|\footnotemark|, \verb|\footnotetext|). This interface
3305 might be enough for visual typesetting. But the relation between
3306 \verb|\footnotemark| to \verb|\footnotetext| is not as strong as \verb|\ref| to \verb|\label|.
3307 Therefore it is not clear in general which \verb|\footnotemark| references
3308 which \verb|\footnotetext|. But that is necessary to implement hyperlinking.
3309 Thus the implementation of \xpackage{hyperref} does not support the optional
3310 argument of \verb|\footnotemark| and \verb|\footnotetext|.
3311
3312
3313 \section[Hints]{Hints%
3314 \footnote{This section moved from the README file, needs more integration into the manual}}
3315
3316 \subsection{Spaces in option values}
3317
3318 Unhappily LaTeX strips spaces from options if they are given
3319 in \verb|\documentclass| or \verb|\usepackage| (or \verb|\RequirePackage|), e.g.:
3320 \begin{verbatim}
3321 \usepackage[pdfborder=0 0 1]{hyperref}
3322 \end{verbatim}
3323 Package \xpackage{hyperref} now gets
3324 \begin{verbatim}
3325 pdfborder=001
3326 \end{verbatim}
3327 and the result is an invalid PDF file.
3328 As workaround braces can be used:
3329 \begin{verbatim}
3330 \usepackage[pdfborder={0 0 1}]{hyperref}
3331 \end{verbatim}
3332 Some options can also be given in \verb|\hypersetup|
3333 \begin{verbatim}
3334 \hypersetup{pdfborder=0 0 1}
3335 \end{verbatim}
3336 In \verb|\hypersetup| the options are directly processed as key value
3337 options (see package keyval) without space stripping in the value part.
3338
3339
3340
3341 Alternatively, LaTeX's option handling system can be adapted
3342 to key value options by one of the packages \xpackage{kvoptions-patch}
3343 (from project \xpackage{kvoptions}) or \xpackage{xkvltxp} (from project \xpackage{xsetkeys}).
3344
3345
3346 \subsection{Index with makeindex}
3347 \begin{itemize}
3348 \item Package \xpackage{hyperref} adds \verb|\hyperpage| commands by the encap
3349 mechanism (see documentation of Makeindex),
3350 if option hyperindex is set (default).
3351 \verb|\hyperpage| uses the page anchors that are set by
3352 \xpackage{hyperref} at each page (default). However in the
3353 default case page numbers are used in anchor names
3354 in arabic form. If the page numbers in other formats
3355 are used (book class with \verb|\frontmatter|, \verb|\romannumbering|, ...),
3356 then the page anchors are not unique. Therefore option
3357 \verb"plainpages=false" is recommended.
3358 \item The encap mechanism of Makeindex allows to use one command only
3359 (see documentation of Makeindex).
3360 If the user sets such a command, \xpackage{hyperref} suppresses its
3361 \verb|\hyperpage| command. With logical markup this situation
3362 can easily be solved:
3363 \begin{verbatim}
3364 \usepackage{makeidx}
3365 \makeindex
3366 \usepackage[hyperindex]{hyperref}
3367 \newcommand*{\main}[1]{\textbf{\hyperpage{#1}}}
3368 ...
3369 \index{Some example|main}
3370 \end{verbatim}
3371 \item Scientic Word/Scientific WorkPlace users can use
3372 package robustindex with hyperindex=false.
3373 \item Other encap characters can be set by option \xoption{encap}.
3374 Example for use of ``?'':
3375 \begin{verbatim}
3376 \usepackage[encap=?]{hyperref}
3377 \end{verbatim}
3378 \item Another possibility is the insertion of \verb|\hyperpage| by
3379 a style file for makeindex. For this case, \xpackage{hyperref}'s
3380 insertion will be disabled by \verb"hyperindex=false".
3381 \verb|\hyperpage| will be defined regardless of setting of hyperindex.
3382 \begin{verbatim}
3383 %%% cut %%% hyperindex.ist %%% cut %%%
3384 delim_0 ", \\hyperpage{"
3385 delim_1 ", \\hyperpage{"
3386 delim_2 ", \\hyperpage{"
3387 delim_n "}, \\hyperpage{"
3388 delim_t "}"
3389 encap_prefix "}\\"
3390 encap_infix "{\\hyperpage{"
3391 encap_suffix "}"
3392 %%% cut %%% hyperindex.ist %%% cut %%%
3393 \end{verbatim}
3394 \end{itemize}
3395
3396 \subsection{Warning \texttt{"bookmark level for unknown <foobar> defaults to 0"}}
3397
3398 Getting rid of it:
3399 \begin{verbatim}
3400 \makeatletter
3401 \providecommand*{\toclevel@<foobar>}{0}
3402 \makeatother
3403 \end{verbatim}
3404
3405 \subsection{Link anchors in figures}
3406
3407 The caption command increments the counter and here is the
3408 place where \xpackage{hyperref} set the corresponding anchor. Unhappily
3409 the caption is set below the figure, so the figure is not
3410 visible if a link jumps to a figure.
3411 In this case, try package \xpackage{hypcap} that implements
3412 a method to circumvent the problem.
3413
3414
3415 \subsection{Additional unicode characters in bookmarks and pdf information entries:}
3416 \begin{verbatim}
3417 \documentclass[pdftex]{article}
3418 \usepackage[unicode]{hyperref}
3419 \end{verbatim}
3420
3421 Support for additional unicode characters:
3422
3423 Example: \verb|\.{a}| and \verb|\d{a}|
3424
3425 1. Get a list with unicode data, eg:
3426
3427 http://www.unicode.org/Public/UNIDATA/UnicodeData.txt
3428
3429 2. Identify the characters (\verb|\.{a}|, \verb|\d{a}|):
3430 \begin{verbatim}
3431 0227;LATIN SMALL LETTER A WITH DOT ABOVE;...
3432 1EA1;LATIN SMALL LETTER A WITH DOT BELOW;...
3433 \end{verbatim}
3434
3435 3. Calculate the octal code:
3436
3437 The first characters of the line in the file are
3438 hex values, convert each byte and prepend them
3439 with a backslash. (This will go into the PDF file.)
3440
3441 \begin{verbatim}
3442 0227 -> \002\047
3443 1EA1 -> \036\241
3444 \end{verbatim}
3445
3446 4. Transform into a form understood by \xpackage{hyperref}:
3447
3448 Hyperref must know where the first byte starts,
3449 this is marked by \verb"9" (8 and 9 cannot occur in
3450 octal numbers):
3451
3452 \begin{verbatim}
3453 \002\047 -> \9002\047
3454 \036\241 -> \9036\241
3455 \end{verbatim}
3456
3457 Optional: \verb"8" is used for abbreviations:
3458
3459 \begin{verbatim}
3460 \900 = \80, \901 = \81, \902 = \82, ...
3461
3462 \9002\047 -> \82\047
3463 \end{verbatim}
3464
3465 5. Declare the character with LaTeX:
3466
3467 \begin{verbatim}
3468 \DeclareTextCompositeCommand{\.}{PU}{a}{\82\047}
3469 \DeclareTextCompositeCommand{\d}{PU}{a}{\9036\241}
3470
3471 \begin{document}
3472 \section{\={a}, \d{a}, \'{a}, \.{a}}
3473 \end{document}
3474 \end{verbatim}
3475
3476 \subsection{Footnotes}
3477
3478 The footnote support is rather limited. It is beyond the scope
3479 to use \verb|\footnotemark| and \verb|\footnotetext| out of order or reusing
3480 \verb|\footnotemark|. Here you can either disable \xpackage{hyperref}'s footnote
3481 support by \verb"hyperfootnotes=false" or fiddle with internal macros,
3482 nasty examples:
3483
3484 \begin{verbatim}
3485 \documentclass{article}
3486 \usepackage{hyperref}
3487 \begin{document}
3488 Hello%
3489 \footnote{The first footnote}
3490 World%
3491 \addtocounter{footnote}{-1}%
3492 \addtocounter{Hfootnote}{-1}%
3493 \footnotemark.
3494 \end{document}
3495
3496 or
3497
3498 \documentclass{article}
3499
3500 \usepackage{hyperref}
3501
3502 \begin{document}
3503
3504 \makeatletter
3505
3506 A%
3507 \footnotemark
3508 \let\saved@Href@A\Hy@footnote@currentHref
3509 % remember link name
3510 B%
3511 \footnotemark
3512 \let\saved@Href@B\Hy@footnote@currentHref
3513 b%
3514 \addtocounter{footnote}{-1}%
3515 \addtocounter{Hfootnote}{-1}% generate the same anchor
3516 \footnotemark
3517 C%
3518 \footnotemark
3519 \let\saved@Href@C\Hy@footnote@currentHref
3520
3521 \addtocounter{footnote}{-2}%
3522 \let\Hy@footnote@currentHref\saved@Href@A
3523 \footnotetext{AAAA}%
3524 \addtocounter{footnote}{1}%
3525 \let\Hy@footnote@currentHref\saved@Href@B
3526 \footnotetext{BBBBB}%
3527 \addtocounter{footnote}{1}%
3528 \let\Hy@footnote@currentHref\saved@Href@C
3529 \footnotetext{CCCC}%
3530
3531 \end{document}
3532 \end{verbatim}
3533
3534 \subsection{Subordinate counters}
3535
3536 Some counters do not have unique values and require the value
3537 of other counters to be unique. For example, sections or figures
3538 might be numbered within chapters or \verb|\newtheorem| is used with
3539 an optional counter argument. Internally LaTeX uses \verb|\@addtoreset|
3540 to reset a counter in dependency to another counter. Package
3541 \xpackage{hyperref} hooks into \verb|\@addtoreset| to catch this situation.
3542 Also \verb|\numberwithin| of package amsmath is caught by \xpackage{hyperref}.
3543
3544
3545
3546 However, if the definition of subordinate counters take place
3547 before \xpackage{hyperref} is loaded, the old meaning of \verb|\@addtoreset| is
3548 called without \xpackage{hyperref}'s additions. Then the companion counter
3549 macro \verb|\theH<counter>| can be redefined accordingly. Or move the
3550 definition of subordinate counters after \xpackage{hyperref} is loaded.
3551
3552 Example for \verb|\newtheorem|, problematic case:
3553 \begin{verbatim}
3554 \newtheorem{corA}{CorollaryA}[section]
3555 \usepackage{hyperref}
3556 \end{verbatim}
3557 Solution a)
3558 \begin{verbatim}
3559 \usepackage{hyperref}
3560 \newtheorem{corA}{CorollaryA}[section}
3561 \end{verbatim}
3562 Solution b)
3563 \begin{verbatim}
3564 \newtheorem{corA}{CorollaryA}[section]
3565 \usepackage{hyperref}
3566 \newcommand*{\theHcorA}{\theHsection.\number\value{corA}}
3567 \end{verbatim}
3568
3569 \section{History and acknowledgments}
3570
3571 The original authors of \textsf{hyperbasics.tex} and
3572 \textsf{hypertex.sty}, from which this package descends, are Tanmoy
3573 Bhattacharya and Thorsten Ohl. Package \xpackage{hyperref}
3574 started as a simple port of their work to \hologo{LaTeXe} standards, but
3575 eventually I rewrote nearly everything, because I didn't understand a
3576 lot of the original, and was only interested in getting it to work with
3577 \hologo{LaTeX}. I would like to thank Arthur Smith, Tanmoy Bhattacharya, Mark
3578 Doyle, Paul Ginsparg, David Carlisle, T.\ V.\ Raman and Leslie Lamport
3579 for comments, requests, thoughts and code to get the package into its
3580 first usable state. Various other people are mentioned at the point in
3581 the source where I had to change the code in later versions because of
3582 problems they found.
3583
3584 Tanmoy found a great many of the bugs, and (even better) often provided
3585 fixes, which has made the package more robust. The days spent on
3586 Rev\TeX\ are entirely due to him! The investigations of Bill Moss
3587 into the later versions including
3588 native PDF support uncovered a good many bugs, and his testing is
3589 appreciated. Hans Hagen provided a lot of
3590 insight into PDF.
3591
3592 Berthold Horn provided help, encouragement and sponsorship for the
3593 \textsf{dvipsone} and \textsf{dviwindo} drivers. Sergey Lesenko provided
3594 the changes needed for \textsf{dvipdf}, and \Hologo{HanTheThanh} supplied all the
3595 information needed for \textsf{pdftex}. Patrick Daly kindly updated his
3596 \xpackage{natbib} package to allow easy integration with
3597 \xpackage{hyperref}. Michael Mehlich's \xpackage{hyper} package (developed
3598 in parallel with \xpackage{hyperref}) showed me solutions for some
3599 problems. Hopefully the two packages will combine one day.
3600
3601 The forms creation section owes a great deal to: T.\ V.\ Raman, for
3602 encouragement, support and ideas; Thomas Merz, whose book \emph{Web
3603 Publishing with Acrobat/PDF} provided crucial insights; D.\ P.\ Story,
3604 whose detailed article about pdfmarks and forms solved many practical
3605 problems; and Hans Hagen, who explained how to do it in \textsf{pdftex}.
3606
3607 Steve Peter recreated the manual source in July 2003 after it had been
3608 lost.
3609
3610 Especial extra thanks to David Carlisle for the \xpackage{backref} module,
3611 the ps2pdf and dviwindo support, frequent general rewrites of my bad
3612 code, and for working on changes to the \xpackage{xr} package to suit
3613 \xpackage{hyperref}.
3614
3615 \begingroup
3616 \makeatletter
3617 \let\chapter=\section
3618 % subsections goes into bookmarks but not toc
3619 \hypersetup{bookmarksopenlevel=1}
3620 \addtocontents{toc}{\protect\setcounter{tocdepth}{1}}
3621 % The \section command acts as \subsection.
3622 % Additionally the title is converted to lowercase except
3623 % for the first letter.
3624 \def\section{%
3625 \let\section\lc@subsection
3626 \lc@subsection
3627 }
3628 \def\lc@subsection{%
3629 \@ifstar{\def\mystar{*}\lc@sec}%
3630 {\let\mystar\@empty\lc@sec}%
3631 }
3632 \def\lc@sec#1{%
3633 \lc@@sec#1\@nil
3634 }
3635 \def\lc@@sec#1#2\@nil{%
3636 \begingroup
3637 \def\a{#1}%
3638 \lowercase{%
3639 \edef\x{\endgroup
3640 \noexpand\subsection\mystar{\a#2}%
3641 }%
3642 }%
3643 \x
3644 }
3645 \clearpage
3646
3647
3648 \chapter{GNU Free Documentation License}
3649
3650 Version 1.2, November 2002
3651
3652
3653 Copyright \copyright\ 2000,2001,2002 Free Software Foundation, Inc.\\
3654 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA\\
3655 Everyone is permitted to copy and distribute verbatim copies
3656 of this license document, but changing it is not allowed.
3657
3658
3659 \section*{PREAMBLE}
3660
3661 The purpose of this License is to make a manual, textbook, or other
3662 functional and useful document ``free'' in the sense of freedom: to
3663 assure everyone the effective freedom to copy and redistribute it,
3664 with or without modifying it, either commercially or noncommercially.
3665 Secondarily, this License preserves for the author and publisher a way
3666 to get credit for their work, while not being considered responsible
3667 for modifications made by others.
3668
3669 This License is a kind of ``copyleft'', which means that derivative
3670 works of the document must themselves be free in the same sense. It
3671 complements the GNU General Public License, which is a copyleft
3672 license designed for free software.
3673
3674 We have designed this License in order to use it for manuals for free
3675 software, because free software needs free documentation: a free
3676 program should come with manuals providing the same freedoms that the
3677 software does. But this License is not limited to software manuals;
3678 it can be used for any textual work, regardless of subject matter or
3679 whether it is published as a printed book. We recommend this License
3680 principally for works whose purpose is instruction or reference.
3681
3682
3683 \section{APPLICABILITY AND DEFINITIONS}
3684 \label{applicability}
3685
3686 This License applies to any manual or other work, in any medium, that
3687 contains a notice placed by the copyright holder saying it can be
3688 distributed under the terms of this License. Such a notice grants a
3689 world-wide, royalty-free license, unlimited in duration, to use that
3690 work under the conditions stated herein. The ``Document'', below,
3691 refers to any such manual or work. Any member of the public is a
3692 licensee, and is addressed as ``you''. You accept the license if you
3693 copy, modify or distribute the work in a way requiring permission
3694 under copyright law.
3695
3696 A ``Modified Version'' of the Document means any work containing the
3697 Document or a portion of it, either copied verbatim, or with
3698 modifications and/or translated into another language.
3699
3700 A ``Secondary Section'' is a named appendix or a front-matter section of
3701 the Document that deals exclusively with the relationship of the
3702 publishers or authors of the Document to the Document's overall subject
3703 (or to related matters) and contains nothing that could fall directly
3704 within that overall subject. (Thus, if the Document is in part a
3705 textbook of mathematics, a Secondary Section may not explain any
3706 mathematics.) The relationship could be a matter of historical
3707 connection with the subject or with related matters, or of legal,
3708 commercial, philosophical, ethical or political position regarding
3709 them.
3710
3711 The ``Invariant Sections'' are certain Secondary Sections whose titles
3712 are designated, as being those of Invariant Sections, in the notice
3713 that says that the Document is released under this License. If a
3714 section does not fit the above definition of Secondary then it is not
3715 allowed to be designated as Invariant. The Document may contain zero
3716 Invariant Sections. If the Document does not identify any Invariant
3717 Sections then there are none.
3718
3719 The ``Cover Texts'' are certain short passages of text that are listed,
3720 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
3721 the Document is released under this License. A Front-Cover Text may
3722 be at most 5 words, and a Back-Cover Text may be at most 25 words.
3723
3724 A ``Transparent'' copy of the Document means a machine-readable copy,
3725 represented in a format whose specification is available to the
3726 general public, that is suitable for revising the document
3727 straightforwardly with generic text editors or (for images composed of
3728 pixels) generic paint programs or (for drawings) some widely available
3729 drawing editor, and that is suitable for input to text formatters or
3730 for automatic translation to a variety of formats suitable for input
3731 to text formatters. A copy made in an otherwise Transparent file
3732 format whose markup, or absence of markup, has been arranged to thwart
3733 or discourage subsequent modification by readers is not Transparent.
3734 An image format is not Transparent if used for any substantial amount
3735 of text. A copy that is not ``Transparent'' is called ``Opaque''.
3736
3737 Examples of suitable formats for Transparent copies include plain
3738 ASCII without markup, Texinfo input format, \LaTeX\ input format, SGML
3739 or XML using a publicly available DTD, and standard-conforming simple
3740 HTML, PostScript or PDF designed for human modification. Examples of
3741 transparent image formats include PNG, XCF and JPG. Opaque formats
3742 include proprietary formats that can be read and edited only by
3743 proprietary word processors, SGML or XML for which the DTD and/or
3744 processing tools are not generally available, and the
3745 machine-generated HTML, PostScript or PDF produced by some word
3746 processors for output purposes only.
3747
3748 The ``Title Page'' means, for a printed book, the title page itself,
3749 plus such following pages as are needed to hold, legibly, the material
3750 this License requires to appear in the title page. For works in
3751 formats which do not have any title page as such, ``Title Page'' means
3752 the text near the most prominent appearance of the work's title,
3753 preceding the beginning of the body of the text.
3754
3755 A section ``Entitled XYZ'' means a named subunit of the Document whose
3756 title either is precisely XYZ or contains XYZ in parentheses following
3757 text that translates XYZ in another language. (Here XYZ stands for a
3758 specific section name mentioned below, such as ``Acknowledgements'',
3759 ``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
3760 of such a section when you modify the Document means that it remains a
3761 section ``Entitled XYZ'' according to this definition.
3762
3763 The Document may include Warranty Disclaimers next to the notice which
3764 states that this License applies to the Document. These Warranty
3765 Disclaimers are considered to be included by reference in this
3766 License, but only as regards disclaiming warranties: any other
3767 implication that these Warranty Disclaimers may have is void and has
3768 no effect on the meaning of this License.
3769
3770
3771 \section{VERBATIM COPYING}
3772 \label{verbatim}
3773
3774 You may copy and distribute the Document in any medium, either
3775 commercially or noncommercially, provided that this License, the
3776 copyright notices, and the license notice saying this License applies
3777 to the Document are reproduced in all copies, and that you add no other
3778 conditions whatsoever to those of this License. You may not use
3779 technical measures to obstruct or control the reading or further
3780 copying of the copies you make or distribute. However, you may accept
3781 compensation in exchange for copies. If you distribute a large enough
3782 number of copies you must also follow the conditions in
3783 section~\ref{copying}.
3784
3785 You may also lend copies, under the same conditions stated above, and
3786 you may publicly display copies.
3787
3788
3789 \section{COPYING IN QUANTITY}
3790 \label{copying}
3791
3792 If you publish printed copies (or copies in media that commonly have
3793 printed covers) of the Document, numbering more than 100, and the
3794 Document's license notice requires Cover Texts, you must enclose the
3795 copies in covers that carry, clearly and legibly, all these Cover
3796 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
3797 the back cover. Both covers must also clearly and legibly identify
3798 you as the publisher of these copies. The front cover must present
3799 the full title with all words of the title equally prominent and
3800 visible. You may add other material on the covers in addition.
3801 Copying with changes limited to the covers, as long as they preserve
3802 the title of the Document and satisfy these conditions, can be treated
3803 as verbatim copying in other respects.
3804
3805 If the required texts for either cover are too voluminous to fit
3806 legibly, you should put the first ones listed (as many as fit
3807 reasonably) on the actual cover, and continue the rest onto adjacent
3808 pages.
3809
3810 If you publish or distribute Opaque copies of the Document numbering
3811 more than 100, you must either include a machine-readable Transparent
3812 copy along with each Opaque copy, or state in or with each Opaque copy
3813 a computer-network location from which the general network-using
3814 public has access to download using public-standard network protocols
3815 a complete Transparent copy of the Document, free of added material.
3816 If you use the latter option, you must take reasonably prudent steps,
3817 when you begin distribution of Opaque copies in quantity, to ensure
3818 that this Transparent copy will remain thus accessible at the stated
3819 location until at least one year after the last time you distribute an
3820 Opaque copy (directly or through your agents or retailers) of that
3821 edition to the public.
3822
3823 It is requested, but not required, that you contact the authors of the
3824 Document well before redistributing any large number of copies, to give
3825 them a chance to provide you with an updated version of the Document.
3826
3827
3828 \section{MODIFICATIONS}
3829 \label{modifications}
3830
3831 You may copy and distribute a Modified Version of the Document under
3832 the conditions of sections~\ref{verbatim} and \ref{copying} above,
3833 provided that you release
3834 the Modified Version under precisely this License, with the Modified
3835 Version filling the role of the Document, thus licensing distribution
3836 and modification of the Modified Version to whoever possesses a copy
3837 of it. In addition, you must do these things in the Modified Version:
3838
3839 \renewcommand{\labelenumi}{\Alph{enumi}.}
3840 \begin{enumerate}
3841 \item Use in the Title Page (and on the covers, if any) a title distinct
3842 from that of the Document, and from those of previous versions
3843 (which should, if there were any, be listed in the History section
3844 of the Document). You may use the same title as a previous version
3845 if the original publisher of that version gives permission.
3846 \item List on the Title Page, as authors, one or more persons or entities
3847 responsible for authorship of the modifications in the Modified
3848 Version, together with at least five of the principal authors of the
3849 Document (all of its principal authors, if it has fewer than five),
3850 unless they release you from this requirement.
3851 \item State on the Title page the name of the publisher of the
3852 Modified Version, as the publisher.
3853 \item Preserve all the copyright notices of the Document.
3854 \item Add an appropriate copyright notice for your modifications
3855 adjacent to the other copyright notices.
3856 \item Include, immediately after the copyright notices, a license notice
3857 giving the public permission to use the Modified Version under the
3858 terms of this License, in the form shown in the Addendum below.
3859 \item Preserve in that license notice the full lists of Invariant Sections
3860 and required Cover Texts given in the Document's license notice.
3861 \item Include an unaltered copy of this License.
3862 \item Preserve the section Entitled ``History'', Preserve its Title, and add
3863 to it an item stating at least the title, year, new authors, and
3864 publisher of the Modified Version as given on the Title Page. If
3865 there is no section Entitled ``History'' in the Document, create one
3866 stating the title, year, authors, and publisher of the Document as
3867 given on its Title Page, then add an item describing the Modified
3868 Version as stated in the previous sentence.
3869 \item Preserve the network location, if any, given in the Document for
3870 public access to a Transparent copy of the Document, and likewise
3871 the network locations given in the Document for previous versions
3872 it was based on. These may be placed in the ``History'' section.
3873 You may omit a network location for a work that was published at
3874 least four years before the Document itself, or if the original
3875 publisher of the version it refers to gives permission.
3876 \item For any section Entitled ``Acknowledgements'' or ``Dedications'',
3877 Preserve the Title of the section, and preserve in the section all
3878 the substance and tone of each of the contributor acknowledgements
3879 and/or dedications given therein.
3880 \item Preserve all the Invariant Sections of the Document,
3881 unaltered in their text and in their titles. Section numbers
3882 or the equivalent are not considered part of the section titles.
3883 \item Delete any section Entitled ``Endorsements''. Such a section
3884 may not be included in the Modified Version.
3885 \item Do not retitle any existing section to be Entitled ``Endorsements''
3886 or to conflict in title with any Invariant Section.
3887 \item Preserve any Warranty Disclaimers.
3888
3889 \end{enumerate}
3890
3891 If the Modified Version includes new front-matter sections or
3892 appendices that qualify as Secondary Sections and contain no material
3893 copied from the Document, you may at your option designate some or all
3894 of these sections as invariant. To do this, add their titles to the
3895 list of Invariant Sections in the Modified Version's license notice.
3896 These titles must be distinct from any other section titles.
3897
3898 You may add a section Entitled ``Endorsements'', provided it contains
3899 nothing but endorsements of your Modified Version by various
3900 parties--for example, statements of peer review or that the text has
3901 been approved by an organization as the authoritative definition of a
3902 standard.
3903
3904 You may add a passage of up to five words as a Front-Cover Text, and a
3905 passage of up to 25 words as a Back-Cover Text, to the end of the list
3906 of Cover Texts in the Modified Version. Only one passage of
3907 Front-Cover Text and one of Back-Cover Text may be added by (or
3908 through arrangements made by) any one entity. If the Document already
3909 includes a cover text for the same cover, previously added by you or
3910 by arrangement made by the same entity you are acting on behalf of,
3911 you may not add another; but you may replace the old one, on explicit
3912 permission from the previous publisher that added the old one.
3913
3914 The author(s) and publisher(s) of the Document do not by this License
3915 give permission to use their names for publicity for or to assert or
3916 imply endorsement of any Modified Version.
3917
3918
3919 \section{COMBINING DOCUMENTS}
3920 \label{combining}
3921
3922 You may combine the Document with other documents released under this
3923 License, under the terms defined in section~\ref{modifications}
3924 above for modified
3925 versions, provided that you include in the combination all of the
3926 Invariant Sections of all of the original documents, unmodified, and
3927 list them all as Invariant Sections of your combined work in its
3928 license notice, and that you preserve all their Warranty Disclaimers.
3929
3930 The combined work need only contain one copy of this License, and
3931 multiple identical Invariant Sections may be replaced with a single
3932 copy. If there are multiple Invariant Sections with the same name but
3933 different contents, make the title of each such section unique by
3934 adding at the end of it, in parentheses, the name of the original
3935 author or publisher of that section if known, or else a unique number.
3936 Make the same adjustment to the section titles in the list of
3937 Invariant Sections in the license notice of the combined work.
3938
3939 In the combination, you must combine any sections Entitled ``History''
3940 in the various original documents, forming one section Entitled
3941 ``History''; likewise combine any sections Entitled ``Acknowledgements'',
3942 and any sections Entitled ``Dedications''. You must delete all sections
3943 Entitled ``Endorsements''.
3944
3945
3946 \section{COLLECTIONS OF DOCUMENTS}
3947 \label{collections}
3948
3949 You may make a collection consisting of the Document and other documents
3950 released under this License, and replace the individual copies of this
3951 License in the various documents with a single copy that is included in
3952 the collection, provided that you follow the rules of this License for
3953 verbatim copying of each of the documents in all other respects.
3954
3955 You may extract a single document from such a collection, and distribute
3956 it individually under this License, provided you insert a copy of this
3957 License into the extracted document, and follow this License in all
3958 other respects regarding verbatim copying of that document.
3959
3960
3961 \section{AGGREGATION WITH INDEPENDENT WORKS}
3962 \label{aggregation}
3963
3964 A compilation of the Document or its derivatives with other separate
3965 and independent documents or works, in or on a volume of a storage or
3966 distribution medium, is called an ``aggregate'' if the copyright
3967 resulting from the compilation is not used to limit the legal rights
3968 of the compilation's users beyond what the individual works permit.
3969 When the Document is included in an aggregate, this License does not
3970 apply to the other works in the aggregate which are not themselves
3971 derivative works of the Document.
3972
3973 If the Cover Text requirement of section~\ref{copying} is applicable to
3974 these copies of the Document, then if the Document is less than one half
3975 of the entire aggregate, the Document's Cover Texts may be placed on
3976 covers that bracket the Document within the aggregate, or the
3977 electronic equivalent of covers if the Document is in electronic form.
3978 Otherwise they must appear on printed covers that bracket the whole
3979 aggregate.
3980
3981
3982 \section{TRANSLATION}
3983 \label{translation}
3984
3985 Translation is considered a kind of modification, so you may
3986 distribute translations of the Document under the terms of
3987 section~\ref{modifications}.
3988 Replacing Invariant Sections with translations requires special
3989 permission from their copyright holders, but you may include
3990 translations of some or all Invariant Sections in addition to the
3991 original versions of these Invariant Sections. You may include a
3992 translation of this License, and all the license notices in the
3993 Document, and any Warranty Disclaimers, provided that you also include
3994 the original English version of this License and the original versions
3995 of those notices and disclaimers. In case of a disagreement between
3996 the translation and the original version of this License or a notice
3997 or disclaimer, the original version will prevail.
3998
3999 If a section in the Document is Entitled ``Acknowledgements'',
4000 ``Dedications'', or ``History'', the requirement
4001 (section~\ref{modifications}) to Preserve
4002 its Title (section~\ref{applicability}) will typically require
4003 changing the actual title.
4004
4005
4006 \section{TERMINATION}
4007 \label{termination}
4008
4009 You may not copy, modify, sublicense, or distribute the Document except
4010 as expressly provided for under this License. Any other attempt to
4011 copy, modify, sublicense or distribute the Document is void, and will
4012 automatically terminate your rights under this License. However,
4013 parties who have received copies, or rights, from you under this
4014 License will not have their licenses terminated so long as such
4015 parties remain in full compliance.
4016
4017
4018 \section{FUTURE REVISIONS OF THIS LICENSE}
4019 \label{future}
4020
4021 The Free Software Foundation may publish new, revised versions
4022 of the GNU Free Documentation License from time to time. Such new
4023 versions will be similar in spirit to the present version, but may
4024 differ in detail to address new problems or concerns. See
4025 http://www.gnu.org/copyleft/.
4026
4027 Each version of the License is given a distinguishing version number.
4028 If the Document specifies that a particular numbered version of this
4029 License ``or any later version'' applies to it, you have the option of
4030 following the terms and conditions either of that specified version or
4031 of any later version that has been published (not as a draft) by the
4032 Free Software Foundation. If the Document does not specify a version
4033 number of this License, you may choose any version ever published (not
4034 as a draft) by the Free Software Foundation.
4035
4036
4037 \section*{ADDENDUM: How to use this License for your documents}
4038
4039 To use this License in a document you have written, include a copy of
4040 the License in the document and put the following copyright and
4041 license notices just after the title page:
4042
4043 \begin{quote}
4044 Copyright \copyright\ YEAR YOUR NAME.
4045 Permission is granted to copy, distribute and/or modify this document
4046 under the terms of the GNU Free Documentation License, Version 1.2
4047 or any later version published by the Free Software Foundation;
4048 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
4049 A copy of the license is included in the section entitled ``GNU
4050 Free Documentation License''.
4051 \end{quote}
4052
4053 If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
4054 replace the ``with...Texts.'' line with this:
4055
4056 with the Invariant Sections being LIST THEIR TITLES, with the
4057 Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
4058
4059 If you have Invariant Sections without Cover Texts, or some other
4060 combination of the three, merge those two alternatives to suit the
4061 situation.
4062
4063 If your document contains nontrivial examples of program code, we
4064 recommend releasing these examples in parallel under your choice of
4065 free software license, such as the GNU General Public License,
4066 to permit their use in free software.
4067
4068 \endgroup
4069
4070 \end{document}