summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/hyperref/doc/manual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/hyperref/doc/manual.tex')
-rw-r--r--macros/latex/contrib/hyperref/doc/manual.tex3383
1 files changed, 3383 insertions, 0 deletions
diff --git a/macros/latex/contrib/hyperref/doc/manual.tex b/macros/latex/contrib/hyperref/doc/manual.tex
new file mode 100644
index 0000000000..ded7aeb799
--- /dev/null
+++ b/macros/latex/contrib/hyperref/doc/manual.tex
@@ -0,0 +1,3383 @@
+% This is the manual for the LaTeX hyperref package.
+%
+% Copyright (C) 1998-2003 Sebastian Rahtz.
+% Copyright (C) 2003 Steve Peter and Karl Berry
+% Copyright (C) 2006-2012 Heiko Oberdiek.
+% Copyright (C) 2017-2019 David Carlisle Ulrike Fischer
+% Copyright (C) 2019-2020 The LaTeX3 Project
+%
+% Permission is granted to copy, distribute and/or modify this document
+% under the terms of the GNU Free Documentation License, Version 1.1 or
+% any later version published by the Free Software Foundation; with no
+% Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+% Texts. A copy of the license is included in the section entitled
+% ``GNU Free Documentation License.''
+%
+
+\def\mydate{January 2020}
+
+\RequirePackage{iftex}
+\ifpdf % We are running pdfTeX in pdf mode
+\ifx\directlua\undefinded
+\documentclass[pdftex]{article}
+\else
+\documentclass[luatex]{article}
+\fi
+\else
+\documentclass{article}
+\fi
+
+
+\usepackage{pifont}
+\usepackage{calc}
+
+\usepackage{hologo}
+
+\def\OzTeX{O\kern-0.03em z\kern-0.15em \TeX}
+
+\newcommand*{\cs}[1]{%
+ \texttt{\textbackslash #1}%
+}
+\newcommand*{\xpackage}[1]{\textsf{#1}}
+\newcommand*{\xoption}[1]{\textsf{#1}}
+
+% from doc.sty
+\makeatletter
+\ifx\l@nohyphenation\@undefined
+\newlanguage\l@nohyphenation
+\fi
+\ifx\l@nohyphenation\@undefined
+ \newlanguage\l@nohyphenation
+\fi
+\DeclareRobustCommand\meta[1]{%
+ \ensuremath\langle
+ \ifmmode \expandafter \nfss@text \fi
+ {%
+ \meta@font@select
+ \edef\meta@hyphen@restore
+ {\hyphenchar\the\font\the\hyphenchar\font}%
+ \hyphenchar\font\m@ne
+ \language\l@nohyphenation
+ #1\/%
+ \meta@hyphen@restore
+ }%
+ \ensuremath\rangle
+}
+\def\meta@font@select{\ttfamily\itshape}
+\makeatother
+
+% Page layout.
+\advance\textwidth by 1.1in
+\advance\oddsidemargin by -.55in
+\advance\evensidemargin by -.55in
+%
+\advance\textheight by 1in
+\advance\topmargin by -.5in
+\advance\footskip by -.5in
+%
+\pagestyle{headings}
+%
+% Avoid some overfull boxes.
+\emergencystretch=.1\hsize
+\hbadness = 3000
+
+% these are from lshort.sty, but lshort.sty pulls in so many other
+% packages it seems cleaner to just include them here.
+%
+\newcommand{\bs}{\symbol{'134}}%Print backslash
+\newcommand{\ci}[1]{\texttt{\bs#1}}
+
+\makeatletter
+\@ifpackageloaded{tex4ht}{%
+ % separate definition for HTML case to avoid
+ % nasty borders with double horizontal lines with
+ % large gaps.
+ \newsavebox{\cmdsyntaxbox}%
+ \newenvironment{cmdsyntax}{%
+ \par
+ % \small
+ \addvspace{3.2ex plus 0.8ex minus 0.2ex}%
+ \vskip -\parskip
+ \noindent
+ \begin{lrbox}{\cmdsyntaxbox}%
+ \begin{tabular}{l}%
+ \rule{0pt}{1em}%
+ \ignorespaces
+ }{%
+ \end{tabular}%
+ \end{lrbox}%
+ \fbox{\usebox{\cmdsyntaxbox}}%
+ \par
+ \nopagebreak
+ \addvspace{3.2ex plus 0.8ex minus 0.2ex}%
+ \vskip -\parskip
+ }%
+}{%
+ \newenvironment{cmdsyntax}{%
+ \par
+ \small
+ \addvspace{3.2ex plus 0.8ex minus 0.2ex}%
+ \vskip -\parskip
+ \noindent
+ \begin{tabular}{|l|}%
+ \hline
+ \rule{0pt}{1em}%
+ \ignorespaces
+ }{%
+ \\%
+ \hline
+ \end{tabular}%
+ \par
+ \nopagebreak
+ \addvspace{3.2ex plus 0.8ex minus 0.2ex}%
+ \vskip -\parskip
+ }%
+}
+\makeatother
+
+\usepackage{array,longtable}
+\ifnum 0\ifluatex 1\else\ifxetex 1\fi\fi=0 %
+ \usepackage[T1]{fontenc}%
+ \usepackage{lmodern}%
+ \renewcommand*{\ttdefault}{lmvtt}%
+\else
+ \usepackage{fontspec}%
+ \renewcommand*{\ttdefault}{lmvtt}%
+\fi
+
+\newcommand*{\Quote}[1]{\textquotedblleft#1\textquotedblright}
+
+\def\Hanh{H\`an Th\^e\llap{\raise 0.5ex\hbox{\'{}}} Th\`anh}
+
+\ifpdf
+ \usepackage[%
+% pdftex,% might be luatex, just allow automatic default
+ colorlinks,%
+ hyperindex,%
+ plainpages=false,%
+ bookmarksopen,%
+ bookmarksnumbered,
+ pdfusetitle,%
+ ]{hyperref}
+ %%?? \def\pdfBorderAttrs{/Border [0 0 0] } % No border arround Links
+\else
+ \usepackage{hyperref}
+\fi
+
+\makeatletter
+\@ifpackageloaded{tex4ht}{%
+\author{Sebastian Rahtz (deceased)\and
+ Heiko Oberdiek (inactive)\and
+ The \LaTeX3 Project (\url{https://github.com/latex3/hyperref/issues})}
+}{%
+ \usepackage{bmhydoc}%
+\author{Sebastian Rahtz\thanks{deceased}\and
+ Heiko Oberdiek\thanks{inactive}\and
+ The \LaTeX3 Project\thanks{\url{https://github.com/latex3/hyperref/issues}}}
+}
+\makeatother
+\title{Hypertext marks in \hologo{LaTeX}: a manual for \xpackage{hyperref}}
+\date{2020-05-15 v7.00e}
+
+\begin{document}
+
+% comes out too close to the toc, and we know it's page one anyway.
+\thispagestyle{empty}
+\maketitle
+\tableofcontents
+\setcounter{tocdepth}{2}% for bookmark levels
+
+\section{Introduction}
+
+The package derives from, and builds on, the work of the Hyper\hologo{TeX}
+project, described at \texttt{http://xxx.lanl.gov/hypertex/}\footnote{Now: \url{https://ctan.org/tex-archive/support/hypertex/hypertex}}. It extends
+the functionality of all the \hologo{LaTeX} cross-referencing commands
+(including the table of contents, bibliographies etc) to produce
+\cs{special} commands which a driver can turn into hypertext links;
+it also provides new commands to allow the user to write \emph{ad hoc}
+hypertext links, including those to external documents and URLs.
+
+The package is currently maintained at \url{https://github.com/latex3/hyperref/} and issues should
+be reported there.
+
+This manual provides a brief overview of the \xpackage{hyperref}
+package. For more details, you should read the additional documentation
+distributed with the package, as well as the complete documentation by
+processing \texttt{hyperref.dtx}. You should also read the chapter on
+\xpackage{hyperref} in \textit{The \hologo{LaTeX} Web Companion}, where you will
+find additional examples.
+
+The Hyper\hologo{TeX} specification\footnote{This is borrowed from an article
+by Arthur Smith.} says that conformant viewers/translators must
+recognize the following set of \cs{special} constructs:
+
+\begin{description}
+\item[href:] \verb|html:<a href = "href_string">|
+\item[name:] \verb|html:<a name = "name_string">|
+\item[end:] \verb|html:</a>|
+\item[image:] \verb|html:<img src = "href_string">|
+\item[base\_name:] \verb|html:<base href = "href_string">|
+\end{description}
+
+The \emph{href}, \emph{name} and \emph{end} commands are used to do the
+basic hypertext operations of establishing links between sections of
+documents. The \emph{image} command is intended (as with current HTML
+viewers) to place an image of arbitrary graphical format on the page in
+the current location. The \emph{base\_name} command is be used to
+communicate to the DVI viewer the full (URL) location of the current
+document so that files specified by relative URLs may be retrieved
+correctly.
+
+The \emph{href} and \emph{name} commands must be paired with an
+\emph{end} command later in the \TeX\ file---the \TeX\ commands between
+the two ends of a pair form an \emph{anchor} in the document. In the
+case of an \emph{href} command, the \emph{anchor} is to be highlighted
+in the \emph{DVI viewer}, and when clicked on will cause the scene to
+shift to the destination specified by \emph{href\_string}. The
+\emph{anchor} associated with a name command represents a possible
+location to which other hypertext links may refer, either as local
+references (of the form \verb|href="#name_string"| with the
+\emph{name\_string} identical to the one in the name command) or as part
+of a URL (of the form \emph{URL\#name\_string}). Here
+\emph{href\_string} is a valid URL or local identifier, while
+\emph{name\_string} could be any string at all: the only caveat is that
+`$\verb|"|$' characters should be escaped with a backslash
+($\backslash$), and if it looks like a URL name it may cause problems.
+
+However, the drivers intended to produce \emph{only} PDF use literal
+PostScript or PDF \verb|\special| commands. The commands are defined in
+configuration files for different drivers, selected by package options;
+at present, the following drivers are supported:
+
+\begin{description}
+\item[hypertex] DVI processors conforming to the Hyper\TeX\ guidelines (i.e.\ \textsf{xdvi}, \textsf{dvips} (with
+the \textsf{-z} option), \textsf{\OzTeX}, and \textsf{Textures})
+\item[dvips] produces \verb|\special| commands tailored for \textsf{dvips}
+\item[dvipsone] produces \verb|\special| commands tailored for \textsf{dvipsone}
+\item[ps2pdf] a special case of output suitable for processing by earlier versions of Ghost\-script's
+PDF writer; this is basically the same as that for \textsf{dvips}, but a few variations remained before version 5.21
+\item[tex4ht] produces \verb|\special| commands for use with \textsf{\TeX4ht}
+\item[pdftex] pdf\TeX, \Hanh{}'s \TeX{} variant that writes PDF directly
+\item[luatex] lua\TeX, Unicode \TeX{} variant that writes PDF directly
+\item[dvipdfm] produces \verb|\special| commands for Mark Wicks' DVI to PDF driver \textsf{dvipdfm}
+\item[dvipdfmx] produces \verb|\special| commands for driver
+ \textsf{dvipdfmx}, a successor of \textsf{dvipdfm}
+\item[dviwindo] produces \verb|\special| commands that Y\&Y's Windows previewer interprets as hypertext jumps within the previewer
+\item[vtex] produces \verb|\special| commands that MicroPress' HTML and
+ PDF-producing \TeX\ variants interpret as hypertext jumps within the
+ previewer
+\item[textures] produces \verb|\special| commands that \textsf{Textures} interprets as hypertext jumps within the previewer
+\item[xetex] produces \verb|\special| commands for Xe\TeX{}
+\end{description}
+
+Output from \textsf{dvips} or \textsf{dvipsone} must be processed using
+Acrobat Distiller to obtain a PDF file.\footnote{Make sure you turn off
+the partial font downloading supported by \textsf{dvips} and
+\textsf{dvipsone} in favor of Distiller's own system.} The result is
+generally preferable to that produced by using the \textsf{hypertex}
+driver, and then processing with \textsf{dvips -z}, but the DVI file is
+not portable. The main advantage of using the Hyper\TeX\ \ci{special}
+commands is that you can also use the document in hypertext DVI viewers,
+such as \textsf{xdvi}.
+
+\begin{description}
+\item[driverfallback]
+ If a driver is not given and cannot be autodetected, then use
+ the driver option, given as value to this option \textsf{driverfallback}.
+ Example:
+ \begin{quote}
+ \texttt{driverfallback=dvipdfm}
+ \end{quote}
+ Autodetected drivers (\textsf{pdftex}, \textsf{xetex}, \textsf{vtex},
+ \textsf{vtexpdfmark}) are recognized from within \TeX\ and
+ therefore cannot be given as value to option \textsf{driverfallback}.
+ However a DVI driver program is run after the \TeX\ run is finished.
+ Thus it cannot be detected at \TeX\ macro level. Then package
+ \xpackage{hyperref}
+ uses the driver, given by \textsf{driverfallback}. If the driver
+ is already specified or can be autodetected, then option
+ \textsf{driverfallback} is ignored.
+\end{description}
+
+\section{Implicit behavior}
+
+This package can be used with more or less any normal \LaTeX\ document
+by specifying in the document preamble
+
+\begin{verbatim}
+\usepackage{hyperref}
+\end{verbatim}
+
+Make sure it comes \emph{last} of your loaded packages, to give it a
+fighting chance of not being over-written, since its job is to redefine
+many \LaTeX\ commands. Hopefully you will find that all cross-references
+work correctly as hypertext. For example, \ci{section} commands will
+produce a bookmark and a link, whereas \ci{section*} commands will only
+show links when paired with a corresponding \ci{addcontentsline}
+command.
+
+In addition, the \texttt{hyperindex} option (see below) attempts to make
+items in the index by hyperlinked back to the text, and the option
+\texttt{backref} inserts extra `back' links into the bibliography for
+each entry. Other options control the appearance of links, and give
+extra control over PDF output. For example, \texttt{colorlinks}, as its
+name well implies, colors the links instead of using boxes; this is the
+option used in this document.
+
+
+\section{Package options}
+
+All user-configurable aspects of \xpackage{hyperref} are set using a
+single `key=value' scheme (using the \xpackage{keyval} package) with the
+key \texttt{Hyp}. The options can be set either in the optional argument
+to the \cs{usepackage} command, or using the \cs{hypersetup}
+macro. When the package is loaded, a file \texttt{hyperref.cfg} is read
+if it can be found, and this is a convenient place to set options on a
+site-wide basis.
+
+Note however that some options (for example \texttt{unicode}) can only be used as
+packge options, and not in \verb|\hypersetup| as the option settings are processed
+as the package is read.
+
+As an example, the behavior of a particular file could be controlled by:
+\begin{itemize}
+
+\item a site-wide \texttt{hyperref.cfg} setting up the look of links,
+adding backreferencing, and setting a PDF display default:
+
+\begin{verbatim}
+\hypersetup{backref,
+pdfpagemode=FullScreen,
+colorlinks=true}
+\end{verbatim}
+
+\item A global option in the file, which is passed down to
+\textsf{hyperref}:
+
+\begin{verbatim}
+\documentclass[dvips]{article}
+\end{verbatim}
+
+\item File-specific options in the \cs{usepackage} commands, which
+override the ones set in \texttt{hyperref.cfg}:
+
+\begin{verbatim}
+\usepackage[colorlinks=false]{hyperref}
+\hypersetup{pdftitle={A Perfect Day}}
+\end{verbatim}
+\end{itemize}
+
+As seen in the previous example, information entries
+(pdftitle, pdfauthor, \dots) should be set after the package is loaded.
+Otherwise \LaTeX\ expands the values of these options prematurely.
+Also \LaTeX\ strips spaces in options. Especially option `pdfborder'
+requires some care. Curly braces protect the value, if given
+as package option. They are not necessary in \verb|\hypersetup|.
+
+\begin{verbatim}
+\usepackage[pdfborder={0 0 0}]{hyperref}
+\hypersetup{pdfborder=0 0 0}
+\end{verbatim}
+
+Package `kvoptions-patch' patches \LaTeX\ to make it aware
+of key value options and to prevent premature value expansions.
+
+Some options can be given at any time, but many are restricted: before
+\verb|\begin{document}|, only in \verb|\usepackage[...]{hyperref}|,
+before first use, etc.
+
+In the key descriptions that follow, many options do not need a value,
+as they default to the value true if used. These are the ones classed as
+`boolean'. The values true and false can always be specified, however.
+
+\subsection{General options}
+
+Firstly, the options to specify general behavior and page size.
+
+\medskip
+\begin{longtable}{>{\ttfamily}ll>{\itshape}ll}
+draft & boolean & false & all hypertext options are turned off \\
+final & boolean & true & all hypertext options are turned on \\
+debug & boolean & false & extra diagnostic messages are printed in \\
+ & & & the log file \\
+verbose & boolean & false & same as debug \\
+implicit & boolean & true & redefines \LaTeX\ internals \\
+setpagesize & boolean & true & sets page size by special driver commands
+\end{longtable}
+
+\subsection{Options for destination names}
+
+Destinations names (also anchor, target or link names) are internal
+names that identify a position on a page in the document. They
+are used in link targets for inner document links or the bookmarks,
+for example.
+
+Usually anchor are set, if \cs{refstepcounter} is called.
+Thus there is a counter name and value. Both are used to
+construct the destination name. By default the counter value
+follows the counter name separated by a dot. Example for
+the fourth chapter:
+\begin{quote}
+ \verb|chapter.4|
+\end{quote}
+This scheme is used by:
+\begin{description}
+\item[\cs{autoref}] displays the description label for the
+ reference depending on the counter name.
+\item[\cs{hyperpage}] is used by the index to get
+page links. Page anchor setting (\verb|pageanchor|) must not
+be turned off.
+\end{description}
+
+It is very important that the destination names are unique,
+because two destinations must not share the same name.
+The counter value \cs{the<counter>} is not always unique
+for the counter. For example, table and figures can be numbered
+inside the chapter without having the chapter number in their
+number. Therefore \xpackage{hyperref} has introduced \cs{theH<counter>}
+that allows a unique counter value without messing up with
+the appearance of the counter number. For example, the number
+of the second table in the third chapter might be printed
+as \texttt{2}, the result of \cs{thetable}. But the
+destination name \texttt{table.2.4} is unique because it
+has used \cs{theHtable} that gives \verb|2.4| in this case.
+
+Often the user do not need to set \cs{theH<counter>}. Defaults
+for standard cases (chapter, \dots) are provided. And after \xpackage{hyperref}
+is loaded, new counters with parent counters also define
+\cs{theH<counter>} automatically, if \cs{newcounter}, \cs{@addtoreset}
+or \cs{numberwithin} of package \xpackage{amsmath} are used.
+
+Usually problems with duplicate destination names can be solved
+by an appropriate definition of \cs{theH<counter>}. If option
+\texttt{hypertexnames} is disabled, then a unique artificial
+number is used instead of the counter value. In case of page
+anchors the absolute page anchor is used. With option \texttt{plainpages}
+the page anchors use the arabic form. In both latter cases \cs{hyperpage}
+for index links is affected and might not work properly.
+
+If an unnumbered entity gets an anchor (starred forms of
+chapters, sections, \dots) or \cs{phantomsection} is used,
+then the dummy counter name \texttt{section*} and an artificial
+unique number is used.
+
+If the final PDF file is going to be merged with another file, than
+the destination names might clash, because both documents might
+contain \texttt{chapter.1} or \texttt{page.1}. Also \xpackage{hyperref}
+sets anchor with name \texttt{Doc-Start} at the begin of the document.
+This can be resolved by redefining \cs{HyperDestNameFilter}.
+Package \xpackage{hyperref} calls this macro each time, it uses a
+destination name.
+The macro must be expandable and expects the destination name
+as only argument. As example, the macro is redefined to add
+a prefix to all destination names:
+\begin{quote}
+\begin{verbatim}
+\renewcommand*{\HyperDestNameFilter}[1]{\jobname-#1}
+\end{verbatim}
+\end{quote}
+In document \texttt{docA} the destination name \texttt{chapter.2}
+becomes \texttt{docA-chapter.2}.
+
+Destination names can also be used from the outside in URIs(, if the
+driver has not removed or changed them), for example:
+\begin{quote}
+\begin{verbatim}
+http://somewhere/path/file.pdf#nameddest=chapter.4
+\end{verbatim}
+\end{quote}
+However using a number seems unhappy. If another chapter is added
+before, the number changes. But it is very difficult to pass
+a new name for the destination to the anchor setting process that
+is usually deep hidden in the internals. The first name of
+\cs{label} after the anchor setting seems a good approximation:
+\begin{quote}
+\begin{verbatim}
+ \section{Introduction}
+ \label{intro}
+\end{verbatim}
+\end{quote}
+Option \texttt{destlabel} checks for each \cs{label}, if there is
+a new destination name active and replaces the destination
+name by the label name. Because the destination name is already in use
+because of the anchor setting, the new name is recorded in the \texttt{.aux}
+file and used in the subsequent \hologo{LaTeX} run. The renaming is done by
+a redefinition of \cs{HyperDestNameFilter}. That leaves the old
+destination names intact (e.g., they are needed for \cs{autoref}).
+This redefinition is also available as \cs{HyperDestLabelReplace},
+thus that an own redefinition can use it.
+The following example also adds a prefix for \emph{all} destination names:
+\begin{quote}
+\begin{verbatim}
+\renewcommand*{\HyperDestNameFilter}[1]{%
+ \jobname-\HyperDestLabelReplace{#1}%
+}
+\end{verbatim}
+\end{quote}
+The other case that only files prefixed that do not have a corresponding
+\cs{label} is more complicate, because \cs{HyperDestLabelReplace} needs
+the unmodified destination name as argument. This is solved by an
+expandable string test (\cs{pdfstrcmp} of \hologo{pdfTeX}
+or \cs{strcmp} of \hologo{XeTeX}, package \xpackage{pdftexcmds} also supports
+\hologo{LuaTeX}):
+\begin{quote}
+\begin{verbatim}
+\usepackage{pdftexcmds}
+\makeatletter
+\renewcommand*{\HyperDestNameFilter}[1]{%
+ \ifcase\pdf@strcmp{#1}{\HyperDestLabelReplace{#1}} %
+ \jobname-#1%
+ \else
+ \HyperDestLabelReplace{#1}%
+ \fi
+}
+\makeatother
+\end{verbatim}
+\end{quote}
+
+With option \texttt{destlabel} destinations can also named manually,
+if the destination is not yet renamed:
+\begin{quote}
+\verb|\HyperDestRename{|\meta{destination}\verb|}{|\meta{newname}\verb|}|
+\end{quote}
+
+Hint: Anchors can also be named and set by \cs{hypertarget}.
+
+\medskip
+\begin{longtable}{>{\ttfamily}ll>{\itshape}ll}
+destlabel & boolean & false & destinations are named by first \cs{label}\\
+ & & & after anchor creation\\
+hypertexnames & boolean & true & use guessable names for links \\
+naturalnames & boolean & false & use \LaTeX-computed names for links \\
+plainpages & boolean & false & Forces page anchors to be named by the Arabic form \\
+ & & & of the page number, rather than the formatted form. \\
+\end{longtable}
+
+\subsection{Configuration options}
+
+\begin{longtable}{>{\ttfamily}ll>{\itshape}lp{9cm}}
+raiselinks & boolean & true & In the hypertex driver, the height of links is normally calculated by the driver as
+ simply the base line of contained text; this options forces \verb|\special| commands to
+ reflect the real height of the link (which could contain a graphic) \\
+breaklinks & boolean & false & Allows link text to break across lines; since this cannot be accommodated in PDF, it is
+ only set true by default if the pdftex driver is used. This makes links on multiple lines
+ into different PDF links to the same target. \\
+pageanchor & boolean & true & Determines whether every page is given an implicit anchor at the top left corner. If this
+ is turned off, \verb|\printindex| will not contain
+ valid hyperlinks. \\
+nesting & boolean & false & Allows links to be nested; no drivers currently support this.
+\end{longtable}
+
+Note for option \verb|breaklinks|:
+The correct value is automatically set according to the driver features.
+It can be overwritten for drivers that do not support broken links.
+However, at any case, the link area will be wrong and displaced.
+
+\subsection{Backend drivers}
+
+If no driver is specified, the package tries to find a driver in
+the following order:
+\begin{enumerate}
+\item Autodetection, some \TeX\ processors can be detected at \TeX\ macro
+ level (pdf\TeX, Xe\TeX, V\TeX).
+\item Option \textsf{driverfallback}. If this option is set, its value
+ is taken as driver option.
+\item Macro \cs{Hy@defaultdriver}. The macro takes a driver file
+ name (without file extension).
+\item Package default is \textsf{hypertex}.
+\end{enumerate}
+Many distributions are using a driver file \texttt{hypertex.cfg} that
+define \cs{Hy@defaultdriver} with \texttt{hdvips}. This is recommended
+because driver \textsf{dvips} provides much more features than
+\textsf{hypertex} for PDF generation.
+
+\begin{longtable}{@{}>{\ttfamily}lp{.8\hsize}@{}}
+driverfallback & Its value is used as driver option\\
+ & if the driver is not given or autodetected.\\
+dvipdfm & Sets up \textsf{hyperref} for use with the \textsf{dvipdfm} driver.\\
+dvipdfmx & Sets up \textsf{hyperref} for use with the \textsf{dvipdfmx} driver.\\
+dvips & Sets up \textsf{hyperref} for use with the \textsf{dvips} driver. \\
+dvipsone & Sets up \textsf{hyperref} for use with the \textsf{dvipsone} driver. \\
+dviwindo & Sets up \textsf{hyperref} for use with the \textsf{dviwindo} Windows previewer. \\
+hypertex & Sets up \textsf{hyperref} for use with the Hyper\TeX-compliant drivers. \\
+latex2html & Redefines a few macros for compatibility with \textsf{latex2html}. \\
+nativepdf & An alias for \textsf{dvips} \\
+pdfmark & An alias for \textsf{dvips} \\
+pdftex & Sets up \textsf{hyperref} for use with the \textsf{pdftex} program.\\
+ps2pdf & Redefines a few macros for compatibility with
+ Ghostscript's PDF writer, otherwise identical to
+ \textsf{dvips}. \\
+tex4ht & For use with \textsf{\TeX4ht} \\
+textures & For use with \textsf{Textures} \\
+vtex & For use with MicroPress' \textsf{VTeX}; the PDF
+ and HTML backends are detected automatically. \\
+vtexpdfmark & For use with \textsf{VTeX}'s PostScript backend. \\
+xetex & For use with Xe\TeX\ (using backend for dvipdfm).
+\end{longtable}
+\smallskip
+
+If you use \textsf{dviwindo}, you may need to redefine the macro
+\ci{wwwbrowser} (the default is \verb|C:\netscape\netscape|) to tell
+\textsf{dviwindo} what program to launch. Thus, users of Internet
+Explorer might add something like this to hyperref.cfg:
+
+\begin{verbatim}
+\renewcommand{\wwwbrowser}{C:\string\Program\space
+ Files\string\Plus!\string\Microsoft\space
+ Internet\string\iexplore.exe}
+\end{verbatim}
+
+\subsection{Extension options}
+\begin{longtable}{@{}>{\ttfamily}ll>{\itshape}lp{8cm}@{}}
+extension & text & & Set the file extension (e.g.\ \textsf{dvi}) which will be appended to file links
+ created if you use the \xpackage{xr} package. \\
+hyperfigures & boolean & & \\
+backref & text & false & Adds `backlink' text to the end of each item in the bibliography, as a list of
+ section numbers. This can only work properly \emph{if} there is a blank line after
+ each \verb|\bibitem|. Supported values are \verb|section|, \verb|slide|, \verb|page|,
+ \verb|none|, or \verb|false|. If no value is given, \verb|section| is taken as default.\\
+pagebackref & boolean & false & Adds `backlink' text to the end of each item in the bibliography, as a list of page
+ numbers. \\
+hyperindex & boolean & true & Makes the page numbers of index entries into hyperlinks. Relays on unique
+ page anchors (\verb|pageanchor|, \ldots)
+ \verb|pageanchors| and \verb|plainpages=false|. \\
+hyperfootnotes & boolean & true & Makes the footnote marks into hyperlinks to the footnote text.
+ Easily broken \ldots\\
+encap & & & Sets encap character for hyperindex \\
+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 \\
+linktocpage & boolean & false & make page number, not text, be link on TOC, LOF and LOT \\
+breaklinks & boolean & false & allow links to break over lines by making links over multiple lines into PDF links to
+ the same target \\
+colorlinks & boolean & false & Colors the text of links and anchors. The colors chosen depend on the the type of
+ link. At present the only types of link distinguished are citations, page references,
+ URLs, local file references, and other links.
+ Unlike colored boxes, the colored
+ text remains when printing.\\
+linkcolor & color & red & Color for normal internal links. \\
+anchorcolor & color & black & Color for anchor text. Ignored by most drivers. \\
+citecolor & color & green & Color for bibliographical citations in text. \\
+filecolor & color & cyan & Color for URLs which open local files. \\
+menucolor & color & red & Color for Acrobat menu items. \\
+runcolor & color & filecolor & Color for run links (launch annotations). \\
+urlcolor & color & magenta & Color for linked URLs. \\
+allcolors & color & & Set all color options (without border and field options).\\
+frenchlinks & boolean & false & Use small caps instead of color for links.\\
+hidelinks & & & Hide links (removing color and border). \\
+\end{longtable} \smallskip
+
+Note that all color names must be defined before use, following the
+normal system of the standard \LaTeX\ \xpackage{color} package.
+
+\subsection{PDF-specific display options}
+\begin{longtable}{@{}>{\ttfamily}ll>{\itshape}lp{7.6cm}@{}}
+bookmarks & boolean & true & A set of Acrobat bookmarks are written, in a manner similar to the
+ table of contents, requiring two passes of \LaTeX. Some postprocessing
+ of the bookmark file (file extension \texttt{.out}) may be needed to
+ translate \LaTeX\ codes, since bookmarks must be written in PDFEncoding.
+ To aid this process, the \texttt{.out} file is not rewritten by \LaTeX\
+ if it is edited to contain a line \verb|\let\WriteBookmarks\relax| \\
+bookmarksopen & boolean & false & If Acrobat bookmarks are requested, show them with all the subtrees
+ expanded. \\
+bookmarksopenlevel & parameter & & level (\ci{maxdimen}) to which bookmarks are open \\
+bookmarksnumbered & boolean & false & If Acrobat bookmarks are requested, include section numbers. \\
+bookmarkstype & text & toc & to specify which `toc' file to mimic \\
+CJKbookmarks & boolean & false &
+ This option should be used to produce CJK bookmarks.
+ Package \verb|hyperref|
+ supports both normal and preprocessed mode of the \xpackage{CJK} package;
+ during the creation of bookmarks, it simply replaces CJK's macros
+ with special versions which expand to the corresponding character
+ codes. Note that without the `unicode' option of hyperref you get
+ PDF files which actually violate the PDF specification because
+ non-Unicode character codes are used -- some PDF readers localized
+ for CJK languages (most notably Acroread itself) support this.
+ Also note that option `CJKbookmarks' cannot be used together
+ with option `unicode'.
+
+ No mechanism is provided to translate non-Unicode bookmarks to
+ Unicode; for portable PDF documents only Unicode encoding should
+ be used.\\
+pdfhighlight & name & /I & How link buttons behave when selected; /I is for inverse (the default);
+ the other possibilities are /N (no effect), /O (outline), and /P (inset
+ highlighting). \\
+citebordercolor & RGB color & 0 1 0 & The color of the box around citations \\
+filebordercolor & RGB color & 0 .5 .5 & The color of the box around links to files \\
+linkbordercolor & RGB color & 1 0 0 & The color of the box around normal links \\
+menubordercolor & RGB color & 1 0 0 & The color of the box around Acrobat menu links \\
+urlbordercolor & RGB color & 0 1 1 & The color of the box around links to URLs \\
+runbordercolor & RGB color & 0 .7 .7 & Color of border around `run' links \\
+allbordercolors & & & Set all border color options \\
+pdfborder & & 0 0 1 & The style of box around links; defaults to a box with lines of 1pt thickness,
+ but the colorlinks option resets it to produce no border.
+\end{longtable}
+
+Note that the color of link borders can be specified \emph{only} as 3
+numbers in the range 0..1, giving an RGB color. You cannot use colors
+defined in \TeX. Since version 6.76a this is no longer true.
+Especially with the help of package \xpackage{xcolor} the usual
+color specifications of package \xpackage{(x)color} can be used.
+For further information see description of package \xpackage{hycolor}.
+
+The bookmark commands are stored in a file called
+\textit{jobname}\texttt{.out}. The files is not processed by \LaTeX\ so
+any markup is passed through. You can postprocess this file as needed;
+as an aid for this, the \texttt{.out} file is not overwritten on the
+next \TeX\ run if it is edited to contain the line
+\begin{verbatim}
+\let\WriteBookmarks\relax
+\end{verbatim}
+
+\subsection{PDF display and information options}
+\begin{longtable}{@{}>{\ttfamily}l>{\raggedright}p{\widthof{key value}}>{\itshape}lp{7cm}@{}}
+baseurl & URL & & Sets the base URL of the PDF document \\
+pdfpagemode & name & empty & Determines how the file is opening in Acrobat; the possibilities are
+ \verb|UseNone|, \verb|UseThumbs| (show thumbnails), \verb|UseOutlines|
+ (show bookmarks), \verb|FullScreen|, \verb|UseOC| (PDF 1.5),
+ and \verb|UseAttachments| (PDF 1.6). If no mode if explicitly chosen, but the
+ bookmarks option is set, \verb|UseOutlines| is used. \\
+pdftitle & text & & Sets the document information Title field \\
+pdfauthor & text & & Sets the document information Author field \\
+pdfsubject & text & & Sets the document information Subject field \\
+pdfcreator & text & & Sets the document information Creator field \\
+addtopdfproducer & text & & Adds additional text to the document information Producer field \\
+pdfkeywords & text & & Sets the document information Keywords field \\
+pdftrapped & name & empty & Sets the document information Trapped entry. Possible values are \verb|True|, \verb|False| and \verb|Unknown|.
+ An empty value means, the entry is not set.\\
+%
+pdfinfo & key value list & empty & Alternative interface for setting the
+ document information.\\
+pdfview & name & XYZ & Sets the default PDF `view' for each link \\
+pdfstartpage & integer & 1 & Determines on which page the PDF file is opened. An empty value means, the entry is not set.\\
+pdfstartview & name & Fit & Set the startup page view \\
+pdfremotestartview & name & Fit & Set the startup page view of remote PDF files \\
+pdfpagescrop & n n n n & & Sets the default PDF crop box for pages. This should be a set of four numbers \\
+pdfcenterwindow & boolean & false & position the document window in the center of the screen \\
+pdfdirection & name & empty & direction setting. Possible values: \verb|L2R| (left to right) and
+ \verb|R2L| (right to left)\\
+pdfdisplaydoctitle & boolean & false & display document title instead of file name in title bar\\
+pdfduplex & name & empty & paper handling option for print dialog. Possible vatues are:
+ \verb|Simplex| (print single-sided),
+ \verb|DuplexFlipShortEdge| (duplex and flip on the short edge of the sheet),
+ \verb|DuplexFlipLongEdge| (duplex and flip on the long edge of the sheet)\\
+
+pdffitwindow & boolean & false & resize document window to fit document size \\
+pdflang & name & relax & PDF language identifier (RFC 3066)\\
+pdfmenubar & boolean & true & make PDF viewer's menu bar visible \\
+pdfnewwindow & boolean & false & make links that open another PDF file start a new window \\
+pdfnonfullscreenpagemode
+ & name & empty & page mode setting on exiting full-screen mode. Possible values are
+ \verb|UseNone|, \verb|UseOutlines|, \verb|UseThumbs|, and \verb|UseOC|\\
+pdfnumcopies & integer & empty & number of printed copies \\
+pdfpagelayout & name & empty & set layout of PDF pages. Possible values:
+ \verb|SinglePage|, \verb|OneColumn|,
+ \verb|TwoColumnLeft|, \verb|TwoColumnRight|,
+ \verb|TwoPageLeft|, and \verb|TwoPageRight| \\
+pdfpagelabels & boolean & true & set PDF page labels \\
+pdfpagetransition & name & empty & set PDF page transition style. Possible values are
+ \verb|Split|, \verb|Blinds|, \verb|Box|, \verb|Wipe|,
+ \verb|Dissolve|, \verb|Glitter|, \verb|R|,
+ \verb|Fly|, \verb|Push|,
+ \verb|Cover|, \verb|Uncover|,
+ \verb|Fade|.
+ The default according to the PDF~Reference is \verb|R|,
+ which simply replaces the old page with the new one. \\
+pdfpicktraybypdfsize
+ & boolean & false & specify whether PDF page size is used to select input paper tray in print dialog \\
+pdfprintarea & name & empty & set /PrintArea of viewer preferences. Possible values are
+ \verb|MediaBox|, \verb|CropBox|,
+ \verb|BleedBox|, \verb|TrimBox|, and \verb|ArtBox|.
+ The dafault according to the PDF~Refence is \verb|CropBox| \\
+pdfprintclip & name & empty & set /PrintClip of viewer preferences. Possible values are
+ \verb|MediaBox|, \verb|CropBox|,
+ \verb|BleedBox|, \verb|TrimBox|, and \verb|ArtBox|.
+ The dafault according to the PDF~Refence is \verb|CropBox| \\
+pdfprintpagerange & n n (n n)*
+ & empty & set /PrintPageRange of viewer preferences\\
+pdfprintscaling & name & empty & page scaling option for print dialog
+ (option /PrintScaling of viewer
+ preferences, PDF 1.6);
+ valid values are \verb|None| and
+ \verb|AppDefault| \\
+pdftoolbar & boolean & true & make PDF toolbar visible \\
+pdfviewarea & name & empty & set /ViewArea of viewer preferences. Possible values are
+ \verb|MediaBox|, \verb|CropBox|,
+ \verb|BleedBox|, \verb|TrimBox|, and \verb|ArtBox|.
+ The dafault according to the PDF~Refence is \verb|CropBox| \\
+pdfviewclip & name & empty & set /ViewClip of viewer preferences Possible values are
+ \verb|MediaBox|, \verb|CropBox|,
+ \verb|BleedBox|, \verb|TrimBox|, and \verb|ArtBox|.
+ The dafault according to the PDF~Refence is \verb|CropBox| \\
+pdfwindowui & boolean & true & make PDF user interface elements visible \\
+unicode & boolean & false & Unicode encoded PDF strings
+\end{longtable}
+
+Each link in Acrobat carries its own magnification level, which is set
+using PDF coordinate space, which is not the same as \TeX's. The unit
+is bp and the origin is in the lower left corner. See also
+\verb|\hypercalcbp| that is explained on page \pageref{hypercalcbp}.
+pdf\TeX\
+works by supplying default values for \texttt{XYZ} (horizontal $\times$
+vertical $\times$ zoom) and \texttt{FitBH}. However, drivers using
+\texttt{pdfmark} do not supply defaults, so \textsf{hyperref} passes in
+a value of -32768, which causes Acrobat to set (usually) sensible
+defaults. The following are possible values for the \texttt{pdfview},
+\texttt{pdfstartview} and \texttt{pdfremotestartview} parameters.
+
+\begin{longtable}{@{}>{\ttfamily}l>{\itshape}lp{7cm}@{}}
+XYZ & left top zoom & Sets a coordinate and a zoom factor. If any one is null, the source link value is used.
+ \textit{null null null} will give the same values as the current page. \\
+Fit & & Fits the page to the window. \\
+FitH & top & Fits the width of the page to the window. \\
+FitV & left & Fits the height of the page to the window. \\
+FitR & left bottom right top & Fits the rectangle specified by the four coordinates to the window. \\
+FitB & & Fits the page bounding box to the window. \\
+FitBH & top & Fits the width of the page bounding box to the window. \\
+FitBV & left & Fits the height of the page bounding box to the window. \\
+\end{longtable}
+
+The \texttt{pdfpagelayout} can be one of the following values.
+
+\begin{longtable}{@{}>{\ttfamily}lp{10cm}@{}}
+SinglePage & Displays a single page; advancing flips the page \\
+OneColumn & Displays the document in one column; continuous scrolling. \\
+TwoColumnLeft & Displays the document in two columns, odd-numbered pages to the left. \\
+TwoColumnRight & Displays the document in two columns, odd-numbered pages to the right.\\
+TwoPageLeft & Displays two pages, odd-numbered pages to the left (since PDF 1.5).\\
+TwoPageRight & Displays two pages, odd-numbered pages to the right (since PDF 1.5).
+\end{longtable}
+
+Finally, the \texttt{pdfpagetransition} can be one of the following
+values, where \textit{/Di} stands for direction of motion in degrees,
+generally in 90$^{\circ}$\ steps, \textit{/Dm} is a horizontal
+(\texttt{/H}) or vertical (\texttt{/V}) dimension (e.g.\ \texttt{Blinds
+/Dm /V}), and \textit{/M} is for motion, either in (\texttt{/I}) or out
+(\texttt{/O}).
+
+\begin{longtable}{@{}>{\ttfamily}llp{8.5cm}@{}}
+Blinds & /Dm & Multiple lines distributed evenly across the screen sweep in the same direction to reveal the new
+ page. \\
+Box & /M & A box sweeps in or out. \\
+Dissolve & & The page image dissolves in a piecemeal fashion to reveal the new page. \\
+Glitter & /Di & Similar to Dissolve, except the effect sweeps across the screen. \\
+Split & /Dm /M & Two lines sweep across the screen to reveal the new page. \\
+Wipe & /Di & A single line sweeps across the screen to reveal the new page. \\
+R & & Simply replaces the old page with the new one. \\
+Fly & /Di /M & Changes are flown out or in (as specified by /M), in the direction
+ specified by /Di, to or from a location that is
+ offscreen except when /Di is None. \\
+Push & /Di & The old page slides off the screen while the new page slides in,
+ pushing the old page out in the direction
+ specified by /Di. \\
+Cover & /Di & The new page slides on to the screen in the direction specified
+ by /Di, covering the old page. \\
+Uncover & /Di & The old page slides off the screen in the direction specified by
+ /Di, uncovering the new page in the direction
+ specified by /Di. \\
+Fade & & The new page gradually becomes visible through the old one.
+
+\end{longtable}
+
+\subsection{Option \texttt{pdfinfo}}
+
+The information entries can be set using \texttt{pdftitle},
+\texttt{pdfsubject}, \dots. Option \texttt{pdfinfo} provides an alternative
+interface. It takes a key value list. The key names are the names that
+appear in the PDF information dictionary directly. Known keys such as
+\texttt{Title}, \texttt{Subject}, \texttt{Trapped} and other are mapped to
+options \texttt{pdftitle}, \texttt{subject}, \texttt{trapped}, \dots
+Unknown keys are added to the information dictionary. Their values are text
+strings (see PDF specification).
+Example:
+\begin{quote}
+\begin{verbatim}
+\hypersetup{
+ pdfinfo={
+ Title={My Title},
+ Subject={My Subject},
+ NewKey={Foobar},
+ % ...
+ }
+}
+\end{verbatim}
+\end{quote}
+
+\subsection{Big alphabetical list}
+
+The following is a complete listing of available options for
+\textsf{hyperref}, arranged alphabetically.
+
+\begin{longtable}{@{}>{\ttfamily}llp{7cm}@{}}
+allbordercolors & & Set all border color options\\
+allcolors & & Set all color options (without border and field options)\\
+anchorcolor & \textit{black} & set color of anchors, ignored by most drivers. \\
+backref & \textit{false} & do bibliographical back references \\
+baseurl & \textit{empty} & set base URL for document \\
+bookmarks & \textit{true} & make bookmarks \\
+bookmarksnumbered & \textit{false} & put section numbers in bookmarks \\
+bookmarksopen & \textit{false} & open up bookmark tree \\
+bookmarksopenlevel & \ttfamily\ci{maxdimen} & level to which bookmarks are open \\
+bookmarkstype & \textit{toc} & to specify which `toc' file to mimic \\
+breaklinks & \textit{false} & allow links to break over lines \\
+CJKbookmarks & \textit{false} & to produce CJK bookmarks\\
+citebordercolor & \textit{0 1 0} & color of border around cites \\
+citecolor & \textit{green} & color of citation links \\
+colorlinks & \textit{false} & color links \\
+ & \textit{true} & (\textsf{tex4ht}, \textsf{dviwindo}) \\
+debug & \textit{false} & provide details of anchors defined; same as verbose \\
+destlabel & \textit{false} & destinations are named by the first \verb|\label| after the anchor creation \\
+draft & \textit{false} & do not do any hyperlinking \\
+driverfallback & & default if no driver specified or detected\\
+dvipdfm & & use \textsf{dvipdfm} backend \\
+dvipdfmx & & use \textsf{dvipdfmx} backend \\
+dvips & & use \textsf{dvips} backend \\
+dvipsone & & use \textsf{dvipsone} backend \\
+dviwindo & & use \textsf{dviwindo} backend \\
+encap & & to set encap character for hyperindex \\
+extension & \textit{dvi} & suffix of linked files \\
+filebordercolor & \textit{0 .5 .5} & color of border around file links \\
+filecolor & \textit{cyan} & color of file links \\
+final & \textit{true} & opposite of option draft \\
+frenchlinks & \textit{false} & use small caps instead of color for links \\
+hidelinks & & Hide links (removing color and border) \\
+hyperfigures & \textit{false} & make figures hyper links \\
+hyperfootnotes & \textit{true} & set up hyperlinked footnotes \\
+hyperindex & \textit{true} & set up hyperlinked indices \\
+hypertex & & use \textsf{Hyper\TeX} backend \\
+hypertexnames & \textit{true} & use guessable names for links \\
+implicit & \textit{true} & redefine \LaTeX\ internals \\
+latex2html & & use \textsf{\LaTeX2HTML} backend \\
+linkbordercolor & \textit{1 0 0} & color of border around links \\
+linkcolor & \textit{red} & color of links \\
+linktoc & \textit{section} & make text be link on TOC, LOF and LOT \\
+linktocpage & \textit{false} & make page number, not text, be link on TOC, LOF and LOT \\
+menubordercolor & \textit{1 0 0} & color of border around menu links \\
+menucolor & \textit{red} & color for menu links \\
+nativepdf & \textit{false} & an alias for \textsf{dvips} \\
+naturalnames & \textit{false} & use \LaTeX-computed names for links \\
+nesting & \textit{false} & allow nesting of links \\
+pageanchor & \textit{true} & put an anchor on every page \\
+pagebackref & \textit{false} & backreference by page number \\
+pdfauthor & \textit{empty} & text for PDF Author field \\
+pdfborder & \textit{0 0 1} & width of PDF link border \\
+ & \textit{0 0 0} & (\texttt{colorlinks)} \\
+pdfborderstyle & & border style for links \\
+pdfcenterwindow & \textit{false} & position the document window in the center of the screen \\
+pdfcreator & \textit{LaTeX with} & text for PDF Creator field \\
+ & \textit{hyperref} & \\
+pdfdirection & \textit{empty} & direction setting \\
+pdfdisplaydoctitle & \textit{false} & display document title instead
+ of file name in title bar\\
+pdfduplex & \textit{empty} & paper handling option for
+ print dialog\\
+pdffitwindow & \textit{false} & resize document window to fit document size \\
+pdfhighlight & \textit{/I} & set highlighting of PDF links \\
+pdfinfo & \textit{empty} & alternative interface for setting document information\\
+pdfkeywords & \textit{empty} & text for PDF Keywords field \\
+pdflang & \textit{relax} & PDF language identifier (RFC 3066) \\
+pdfmark & \textit{false} & an alias for \textsf{dvips} \\
+pdfmenubar & \textit{true} & make PDF viewer's menu bar visible \\
+pdfnewwindow & \textit{false} & make links that open another PDF \\
+ & & file start a new window \\
+pdfnonfullscreenpagemode
+ & \textit{empty} & page mode setting on exiting
+ full-screen mode\\
+pdfnumcopies & \textit{empty} & number of printed copies\\
+pdfpagelabels & \textit{true} & set PDF page labels \\
+pdfpagelayout & \textit{empty} & set layout of PDF pages \\
+pdfpagemode & \textit{empty} & set default mode of PDF display \\
+pdfpagescrop & \textit{empty} & set crop size of PDF document \\
+pdfpagetransition & \textit{empty} & set PDF page transition style \\
+pdfpicktraybypdfsize
+ & \textit{empty} & set option for print dialog \\
+pdfprintarea & \textit{empty} & set /PrintArea of viewer preferences \\
+pdfprintclip & \textit{empty} & set /PrintClip of viewer preferences \\
+pdfprintpagerange & \textit{empty} & set /PrintPageRange of viewer preferences \\
+pdfprintscaling & \textit{empty} & page scaling option for print dialog \\
+pdfproducer & \textit{empty} & text for PDF Producer field \\
+pdfremotestartview & \textit{Fit} & starting view of remote PDF documents \\
+pdfstartpage & \textit{1} & page at which PDF document opens \\
+pdfstartview & \textit{Fit} & starting view of PDF document \\
+pdfsubject & \textit{empty} & text for PDF Subject field \\
+pdftex & & use \textsf{pdf\TeX} backend \\
+pdftitle & \textit{empty} & text for PDF Title field \\
+pdftoolbar & \textit{true} & make PDF toolbar visible \\
+pdftrapped & \textit{empty} & Sets the document information Trapped entry.
+ Possible values are \texttt{True}, \texttt{False} and \texttt{Unknown}.
+ An empty value means, the entry is not set.\\
+pdfview & \textit{XYZ} & PDF `view' when on link traversal \\
+pdfviewarea & \textit{empty} & set /ViewArea of viewer preferences \\
+pdfviewclip & \textit{empty} & set /ViewClip of viewer preferences \\
+pdfwindowui & \textit{true} & make PDF user interface elements visible \\
+plainpages & \textit{false} & do page number anchors as plain Arabic \\
+ps2pdf & & use \textsf{ps2pdf} backend \\
+psdextra & \textit{false} & define more short names for PDF string commands \\
+raiselinks & \textit{false} & raise up links (for \textsf{Hyper\TeX} backend) \\
+runbordercolor & \textit{0 .7 .7} & color of border around `run' links \\
+runcolor & \textit{filecolor} & color of `run' links\\
+setpagesize & \textit{true} & set page size by special driver commands \\
+tex4ht & & use \textsf{\TeX4ht} backend \\
+textures & & use \textsf{Textures} backend \\
+unicode & \textit{false} & Unicode encoded pdf strings, by defaut true with \textsf{Xe\TeX} and \textsf{Lu\TeX} \\
+urlbordercolor & \textit{0 1 1} & color of border around URL links \\
+urlcolor & \textit{magenta} & color of URL links \\
+verbose & \textit{false} & be chatty \\
+vtex & & use \textsf{VTeX} backend\\
+xetex & & use \textsf{Xe\TeX} backend\\
+\end{longtable}
+
+\section{Additional user macros}
+
+If you need to make references to URLs, or write explicit links, the
+following low-level user macros are provided:
+
+\begin{cmdsyntax}
+\ci{href}\verb|[|\emph{options}\verb|]|\verb|{|\emph{URL}\verb|}{|\emph{text}\verb|}|
+\end{cmdsyntax}
+
+\noindent The \emph{text} is made a hyperlink to the \emph{URL}; this
+must be a full URL (relative to the base URL, if that is defined). The
+special characters \# and \~{} do \emph{not} need to be escaped in any
+way (unless the command is used in the argument of another command).
+
+The optional argument \emph{options} recognizes the hyperref options
+\texttt{pdfremotestartview}, \texttt{pdfnewwindow} and the following
+key value options:
+\begin{description}
+\item[\texttt{page}:] Specifies the start page number of remote
+PDF documents. First page is \verb|1|.
+\item[\texttt{ismap}:] Boolean key, if set to \verb|true|, the
+URL should appended by the coordinates as query parameters by
+the PDF viewer.
+\item[\texttt{nextactionraw}:] The value of key \verb|/Next| of
+action dictionaries, see PDF specification.
+\end{description}
+
+\begin{cmdsyntax}
+\ci{url}\verb|{|\emph{URL}\verb|}|
+\end{cmdsyntax}
+
+\noindent Similar to
+\ci{href}\verb|{|\emph{URL}\verb|}{|\ci{nolinkurl}\verb|{|\emph{URL}\verb|}}|.
+Depending on the driver \verb|\href| also tries to detect the link type.
+Thus the result can be a url link, file link, \dots
+
+\begin{cmdsyntax}
+\ci{nolinkurl}\verb|{|\emph{URL}\verb|}|
+\end{cmdsyntax}
+
+\noindent Write \emph{URL} in the same way as \verb|\url|,
+ without creating a hyperlink.
+
+\begin{cmdsyntax}
+\ci{hyperbaseurl}\verb|{|\emph{URL}\verb|}|
+\end{cmdsyntax}
+
+\noindent A base \emph{URL} is established, which is prepended to other
+specified URLs, to make it easier to write portable documents.
+
+\begin{cmdsyntax}
+\ci{hyperimage}\verb|{|\emph{imageURL}\verb|}{|\emph{text}\verb|}|
+\end{cmdsyntax}
+
+\noindent The link to the image referenced by the URL is inserted, using
+\emph{text} as the anchor.
+
+ For drivers that produce HTML, the image itself is inserted by the
+browser, with the \emph{text} being ignored completely.
+
+\begin{cmdsyntax}
+\ci{hyperdef}\verb|{|\emph{category}\verb|}{|\emph{name}\verb|}{|\emph{text}\verb|}|
+\end{cmdsyntax}
+
+\noindent A target area of the document (the \emph{text}) is marked, and
+given the name \emph{category.name}
+
+\begin{cmdsyntax}
+\ci{hyperref}\verb|{|\emph{URL}\verb|}{|\emph{category}\verb|}{|\emph{name}\verb|}{|\emph{text}\verb|}|
+\end{cmdsyntax}
+
+\noindent \emph{text} is made into a link to \emph{URL\#category.name}
+
+\begin{cmdsyntax}
+\ci{hyperref}\verb|[|\emph{label}\verb|]{|\emph{text}\verb|}|
+\end{cmdsyntax}
+
+\noindent
+\emph{text} is made into a link to the same place as
+\verb|\ref{|\emph{label}\verb|}| would be linked.
+
+\begin{cmdsyntax}
+\ci{hyperlink}\verb|{|\emph{name}\verb|}{|\emph{text}\verb|}|
+\end{cmdsyntax}
+\begin{cmdsyntax}
+\ci{hypertarget}\verb|{|\emph{name}\verb|}{|\emph{text}\verb|}|
+\end{cmdsyntax}
+
+\noindent A simple internal link is created with \verb|\hypertarget|,
+with two parameters of an anchor \emph{name}, and anchor
+\emph{text}. \verb|\hyperlink| has two arguments, the name of a
+hypertext object defined somewhere by \verb|\hypertarget|, and the
+\emph{text} which be used as the link on the page.
+
+Note that in HTML parlance, the \verb|\hyperlink| command inserts a
+notional \# in front of each link, making it relative to the current
+testdocument; \verb|\href| expects a full URL.
+
+\begin{cmdsyntax}
+\ci{phantomsection}
+\end{cmdsyntax}
+
+\noindent
+This sets an anchor at this location. It works similar to
+\verb|\hypertarget{}{}| with an automatically chosen anchor name.
+Often it is used in conjunction
+with \verb|\addcontentsline| for sectionlike things (index, bibliography,
+preface). \verb|\addcontentsline| refers to the latest previous location
+where an anchor is set. Example:
+\begin{quote}
+\begin{verbatim}
+\cleardoublepage
+\phantomsection
+\addcontentsline{toc}{chapter}{\indexname}
+\printindex
+\end{verbatim}
+\end{quote}
+Now the entry in the table of contents (and bookmarks) for the
+index points to the start of the index page, not to a location
+before this page.
+
+\begin{cmdsyntax}
+\ci{autoref}\verb|{|\emph{label}\verb|}|
+\end{cmdsyntax}
+
+\noindent
+This is a replacement for the usual \verb|\ref| command that places a
+contextual label in front of the reference. This gives your users a
+bigger target to click for hyperlinks (e.g.\ `section 2' instead of
+merely the number `2').
+
+The label is worked out from the context of the original \verb|\label|
+command by \textsf{hyperref} by using the macros listed below (shown
+with their default values). The macros can be (re)defined in documents
+using \verb|\(re)newcommand|; note that some of these macros are already
+defined in the standard document classes. The mixture of lowercase and
+uppercase initial letters is deliberate and corresponds to the author's
+practice.
+
+For each macro below, \textsf{hyperref} checks \ci{*autorefname} before
+\ci{*name}. For instance, it looks for \ci{figureautorefname} before
+\ci{figurename}.
+
+\begin{longtable}{@{}lp{10cm}@{}}
+\textit{Macro} & \textit{Default} \\
+\ci{figurename} & Figure \\
+\ci{tablename} & Table \\
+\ci{partname} & Part \\
+\ci{appendixname} & Appendix \\
+\ci{equationname} & Equation \\
+\ci{Itemname} & item \\
+\ci{chaptername} & chapter \\
+\ci{sectionname} & section \\
+\ci{subsectionname} & subsection \\
+\ci{subsubsectionname} & subsubsection \\
+\ci{paragraphname} & paragraph \\
+\ci{Hfootnotename} & footnote \\
+\ci{AMSname} & Equation \\
+\ci{theoremname} & Theorem\\
+\ci{page} & page\\
+\end{longtable}
+
+Example for a redefinition if \textsf{babel} is used:
+\begin{quote}
+\begin{verbatim}
+\usepackage[ngerman]{babel}
+\addto\extrasngerman{%
+ \def\subsectionautorefname{Unterkapitel}%
+}
+\end{verbatim}
+\end{quote}
+
+Hint: \cs{autoref} works via the counter name that the reference
+is based on. Sometimes \cs{autoref} chooses the wrong name, if
+the counter is used for different things. For example, it happens
+with \cs{newtheorem} if a lemma shares a counter with theorems.
+Then package \xpackage{aliascnt} provides a method to generate a
+simulated second counter that allows the differentiation between
+theorems and lemmas:
+\begin{quote}
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage{aliascnt}
+\usepackage{hyperref}
+
+\newtheorem{theorem}{Theorem}
+
+\newaliascnt{lemma}{theorem}
+\newtheorem{lemma}[lemma]{Lemma}
+\aliascntresetthe{lemma}
+
+\providecommand*{\lemmaautorefname}{Lemma}
+
+\begin{document}
+
+We will use \autoref{a} to prove \autoref{b}.
+
+\begin{lemma}\label{a}
+ Nobody knows.
+\end{lemma}
+
+\begin{theorem}\label{b}
+ Nobody is right.
+\end{theorem}.
+
+\end{document}
+\end{verbatim}
+\end{quote}
+
+\begin{cmdsyntax}
+\ci{autopageref}\verb|{|\emph{label}\verb|}|
+\end{cmdsyntax}
+
+\noindent
+It replaces \verb|\pageref| and adds the name for page in front of
+the page reference. First \ci{pageautorefname} is checked before
+\ci{pagename}.
+
+For instances where you want a reference to use the correct counter, but
+not to create a link, there are starred forms (these starred forms exist even if
+hyperref has been loaded with \verb|implicit=false|):
+
+\begin{cmdsyntax}
+\ci{ref*}\verb|{|\emph{label}\verb|}|
+\end{cmdsyntax}
+
+\begin{cmdsyntax}
+\ci{pageref*}\verb|{|\emph{label}\verb|}|
+\end{cmdsyntax}
+
+\begin{cmdsyntax}
+\ci{autoref*}\verb|{|\emph{label}\verb|}|
+\end{cmdsyntax}
+
+\begin{cmdsyntax}
+\ci{autopageref*}\verb|{|\emph{label}\verb|}|
+\end{cmdsyntax}
+
+A typical use would be to write
+\begin{verbatim}
+\hyperref[other]{that nice section (\ref*{other}) we read before}
+\end{verbatim}
+
+We want \verb|\ref*{other}| to generate the correct number, but not to
+form a link, since we do this ourselves with \ci{hyperref}.
+
+\begin{cmdsyntax}
+\ci{pdfstringdef}\verb|{|\emph{macroname}\verb|}{|\emph{\TeX string}\verb|}|
+\end{cmdsyntax}
+
+\ci{pdfstringdef} returns a macro containing the PDF string. (Currently
+this is done globally, but do not rely on it.) All the following tasks,
+definitions and redefinitions are made in a group to keep them local:
+
+\begin{itemize}
+\item Switching to PD1 or PU encoding
+\item Defining the \Quote{octal sequence commands} (\verb|\345|): \verb|\edef\3{\string\3}|
+\item Special glyphs of \TeX: \verb|\{|, \verb|\%|, \verb|\&|, \verb|\space|, \verb|\dots|, etc.
+\item National glyphs (\textsf{german.sty}, \textsf{french.sty}, etc.)
+\item Logos: \verb|\TeX|, \verb|\eTeX|, \verb|\MF|, etc.
+\item Disabling commands that do not provide useful functionality in bookmarks:
+\verb|\label|, \verb|\index|, \verb|\glossary|, \verb|\discretionary|, \verb|\def|, \verb|\let|, etc.
+\item \LaTeX's font commands like \verb|\textbf|, etc.
+\item Support for \verb|\xspace| provided by the \xpackage{xspace} package
+\end{itemize}
+
+In addition, parentheses are protected to avoid the danger of unsafe
+unbalanced parentheses in the PDF string. For further details, see Heiko
+Oberdiek's Euro\TeX\ paper distributed with \textsf{hyperref}.
+
+\begin{cmdsyntax}
+\ci{begin}\verb|{NoHyper}|\ldots\ci{end}\verb|{NoHyper}|
+\end{cmdsyntax}
+ Sometimes we just don't want the wretched package interfering
+ with us. Define an environment we can put in manually, or include
+ in a style file, which stops the hypertext functions doing anything.
+ This is used, for instance, in the Elsevier classes, to stop
+ \verb|hyperref| playing havoc in the front matter.
+
+\subsection{Bookmark macros}
+
+\subsubsection{Setting bookmarks}
+
+Usually \textsf{hyperref} automatically adds bookmarks for
+\verb|\section| and similar macros. But they can also set manually.
+
+\begin{cmdsyntax}
+\ci{pdfbookmark}\verb|[|\emph{level}\verb|]{|text\verb|}{|\emph{name}\verb|}|
+\end{cmdsyntax}
+creates a bookmark with the specified text and at the given level (default is
+0). As name for the internal anchor name is used (in conjunction with
+level). Therefore the name must be unique (similar to \verb|\label|).
+
+\begin{cmdsyntax}
+\ci{currentpdfbookmark}\verb|{|\emph{text}\verb|}{|\emph{name}\verb|}|
+\end{cmdsyntax}
+creates a bookmark at the current level.
+
+\begin{cmdsyntax}
+\ci{subpdfbookmark}\verb|{|\emph{text}\verb|}{|\emph{name}\verb|}|
+\end{cmdsyntax}
+creates a bookmark one step down in the bookmark hierarchy.
+Internally the current level is increased by one.
+
+\begin{cmdsyntax}
+\ci{belowpdfbookmark}\verb|{|\emph{text}\verb|}{|\emph{name}\verb|}|
+\end{cmdsyntax}
+creates a bookmark below the current bookmark level. However after the
+command the current bookmark level has not changed.
+
+\noindent \textbf{Hint:} Package \textsf{bookmark} replaces
+\textsf{hyperref}'s bookmark organization by a new algorithm:
+\begin{itemize}
+\item Usually only one \LaTeX\ run is needed.
+\item More control over the bookmark appearance (color, font).
+\item Different bookmark actions are supported (external file links,
+ URLs, \dots).
+\end{itemize}
+Therefore I recommend using this package.
+
+\subsubsection{Replacement macros}
+
+\textsf{hyperref} takes the text for bookmarks from the arguments of
+commands like \ci{section}, which can contain things like math, colors,
+or font changes, none of which will display in bookmarks as is.
+
+\begin{cmdsyntax}
+\ci{texorpdfstring}\verb|{|\emph{\TeX string}\verb|}{|\emph{PDFstring}\verb|}|
+\end{cmdsyntax}
+
+For example,
+\begin{verbatim}
+\section{Pythagoras:
+ \texorpdfstring{$ a^2 + b^2 = c^2 $}{%
+ a\texttwosuperior\ + b\texttwosuperior\ =
+ c\texttwosuperior
+ }%
+}
+\section{\texorpdfstring{\textcolor{red}}{}{Red} Mars}
+\end{verbatim}
+
+\ci{pdfstringdef} executes the hook \pdfstringdefPreHook before it
+expands the string. Therefore, you can use this hook to perform
+additional tasks or to disable additional commands.
+
+\begin{verbatim}
+\expandafter\def\expandafter\pdfstringdefPreHook
+\expandafter{%
+ \pdfstringdefPreHook
+ \renewcommand{\mycommand}[1]{}%
+}
+\end{verbatim}
+
+However, for disabling commands, an easier way is via
+\ci{pdfstringdefDisableCommands}, which adds its argument to the
+definition of \ci{pdfstringdefPreHook} (`@' can here be used as letter in
+command names):
+
+\begin{verbatim}
+\pdfstringdefDisableCommands{%
+ \let~\textasciitilde
+ \def\url{\pdfstringdefWarn\url}%
+ \let\textcolor\@gobble
+}
+\end{verbatim}
+
+\subsection{Utility macros}
+
+\label{hypercalcbp}
+\begin{cmdsyntax}
+\ci{hypercalcbp}\verb|{|\emph{dimen specification}\verb|}|
+\end{cmdsyntax}
+\noindent
+\verb|\hypercalcbp| takes a \TeX\ dimen specification and
+converts it to bp and returns the number without the unit.
+This is useful for options \verb|pdfview|, \verb|pdfstartview|
+and \verb|pdfremotestartview|.
+Example:
+\begin{quote}
+\begin{verbatim}
+\hypersetup{
+ pdfstartview={FitBH \hypercalcbp{\paperheight-\topmargin-1in
+ -\headheight-\headsep}
+}
+\end{verbatim}
+\end{quote}
+The origin of the PDF coordinate system is the lower left corner.
+
+Note, for calculations you need either package \xpackage{calc} or
+\hologo{eTeX}. Nowadays the latter should automatically be enabled
+for \hologo{LaTeX} formats. Users without \hologo{eTeX}, please, look
+in the source documentation \verb|hyperref.dtx| for further
+limitations.
+
+Also \cs{hypercalcbp} cannot be used in option specifications
+of \cs{documentclass} and \cs{usepackage}, because
+\hologo{LaTeX} expands the option lists of these commands. However
+package \xpackage{hyperref} is not yet loaded and an undefined control
+sequence error would arise.
+
+\section[New Features]{New Features%
+\footnote{This section moved from the README file, needs more integration into the manual}}
+
+
+\subsection{Option `pdflinkmargin'}
+
+ Option `pdflinkmargin' is an experimental option for specifying
+ a link margin, if the driver supports this. Default is 1 pt for
+ supporting drivers.
+
+
+\begin{description}
+\item[pdfTeX]
+\begin{itemize}
+ \item The link area also depends on the surrounding box.
+ \item Settings have local effect.
+ \item When a page is shipped out, pdfTeX uses the current setting
+ of the link margin for all links on the page.
+\end{itemize}
+
+\item[pdfmark]
+\begin{itemize}
+ \item Settings have global effect.
+\end{itemize}
+
+\item[xetex]
+\begin{itemize}
+ \item Settings must be done in the preamble or the first page and then have global effect.
+ The key inserts the new (x)dvipdfmx special \verb|\special{dvipdfmx:config g #1}| (with the unit removed).
+\end{itemize}
+
+\item[Other drivers]
+ Unsupported.
+\end{description}
+
+
+\subsection{Field option `calculatesortkey'}
+
+ Fields with calculated values are calculated in document order
+ by default. If calculated field values depend on other calculated
+ fields that appear later in the document, then the correct calculation
+ order can be specified with option `calculatesortkey'. Its value is
+ used as key to lexicographically sort the calculated fields.
+ The sort key do not need to be unique. Fields that share the same
+ key are sorted in document order.
+
+
+
+ Currently the field option `calculatesortkey' is only supported by
+ the driver for pdfTeX.
+
+
+\subsection{Option `localanchorname'}
+
+ When an anchor is set (e.g. via \verb|\refstepcounter|, then the
+ anchor name is globally set to the current anchor name.
+
+
+ For example:
+\begin{verbatim}
+ \section{Foobar}
+ \begin{equation}\end{equation}
+ \label{sec:foobar}
+\end{verbatim}
+ With the default global setting (localanchorname=false)
+ a reference to `sec:foobar' jumps to the equation before.
+ With option `localanchorname' the anchor of the equation
+ is forgotten after the environment and the reference
+ `sec:foobar' jumps to the section title.
+
+
+ Option `localanchorname' is an experimental option, there
+ might be situations, where the anchor name is not available
+ as expected.
+
+
+\subsection{Option `customdriver'}
+
+ The value of option `customdriver' is the name of an external
+ driver file without extension `.def'. The file must have
+ \verb|\ProvidesFile| with a version date and number that match the
+ date and number of `hyperref', otherwise a warning is given.
+
+ Because the interface, what needs to be defined in the driver,
+ is not well defined and quite messy, the option is mainly intended
+ to ease developing, testing, debugging the driver part.
+
+
+\subsection{Option `psdextra'}
+
+ LaTeX's NFSS is used to assist the conversion of arbitrary
+ TeX strings to PDF strings (bookmarks, PDF information entries).
+ Many math command names (\verb|\geq|, \verb|\notin|, ...) are not in control
+ of NFSS, therefore they are defined with prefix `text'
+ (\verb|\textgeq|, \verb|\textnotin|, ...). They can be mapped to short names
+ during the processing to PDF strings. The disadvantage is that
+ they are many hundreds macros that need to be redefined for
+ each PDF string conversion. Therefore this can be enabled or
+ disabled as option `psdextra'. On default the option is turned
+ off (set to `false'). Turning the option on means
+ that the short names are available. Then \verb|\geq| can directly
+ be used instead of \verb|\textgeq|.
+
+
+\subsection{\textbackslash XeTeXLinkBox}
+
+ When XeTeX generates a link annotation, it does not look
+ at the boxes (as the other drivers), but only at the character
+ glyphs. If there are no glyphs (images, rules, ...), then
+ it does not generate a link annotation. Macro \verb|\XeTeXLinkBox|
+ puts its argument in a box and adds spaces at the lower left
+ and upper right corners. An additional margin can be specified
+ by setting it to the dimen register \verb|\XeTeXLinkMargin|. The default
+ is 2pt.
+
+ Example:
+
+
+\begin{verbatim}
+ % xelatex
+ \documentclass{article}
+ \usepackage{hyperref}
+ \setlength{\XeTeXLinkMargin}{1pt}
+ \begin{document}
+ \section{Hello World}
+ \newpage
+ \label{sec:hello}
+ \hyperref[sec:hello]{%
+ \XeTeXLinkBox{\rule{10mm}{10mm}}%
+ }
+ \end{document}
+\end{verbatim}
+
+\subsection{\textbackslash IfHyperBooleanExists and \textbackslash IfHyperBoolean}
+\begin{verbatim}
+ \IfHyperBooleanExists{OPTION}{YES}{NO}
+\end{verbatim}
+ If a hyperref OPTION is a boolean, that means it takes values
+ `true' or `false', then \verb|\IfHyperBooleanExists| calls YES, otherwise NO.
+
+
+\begin{verbatim}
+ \IfHyperBoolean{OPTION}{YES}{NO}
+\end{verbatim}
+ Macro \verb|\IfHyperBoolean| calls YES, if OPTION exists as boolean and is
+ enabled. Otherwise NO is executed.
+
+
+
+ Both macros are expandable. Additionally option `stoppedearly' is
+ available. It is enabled if \verb|\MaybeStopEarly| or \verb|\MaybeStopNow|
+ end hyperref prematurely.
+
+
+\subsection{\textbackslash unichar}
+
+ If a Unicode character is not supported by puenc.def, it can
+ be given by using \verb|\unichar|. Its name and syntax is inherited
+ from package `ucs'. However it is defined independently for
+ use in hyperref's \verb|\pdfstringdef| (that converts arbitrary
+ TeX code to PDF strings or tries to do this).
+
+
+
+ Macro \verb|\unichar| takes a TeX number as argument,
+ examples for U+263A (WHITE SMILING FACE):
+\begin{verbatim}
+ \unichar{"263A}% hexadecimal notation
+ \unichar{9786}% decimal notation
+\end{verbatim}
+ `"' must not be a babel shorthand character or otherwise
+ active. Otherwise prefix it with \verb|\string|:
+\begin{verbatim}
+ \unichar{\string"263A}% converts `"' to `"' with catcode 12 (other)
+\end{verbatim}
+ Users of (n)german packages or babel options may use \verb|\dq| instead:
+\begin{verbatim}
+ \unichar{\dq 263A}% \dq is double quote with catcode 12 (other)
+\end{verbatim}
+
+
+\subsection{\textbackslash ifpdfstringunicode}
+
+ Some features of the PDF specification needs PDF strings.
+ Examples are bookmarks or the entries in the information dictionary.
+ The PDF specification allows two encodings `PDFDocEncoding'
+ (8-bit encoding) and `Unicode' (UTF-16). The user can help
+ using \verb|\texorpdfstring| to replace complicate TeX constructs
+ by a representation for the PDF string. However \verb|\texorpdfstring|
+ does not distinguish the two encodings. This gap closes
+ \verb|\ifpdfstringunicode|. It is only allowed in the second argument
+ of \verb|\texorpdfstring| and takes two arguments, the first allows
+ the full range of Unicode. The second is limited to the
+ characters available in PDFDocEncoding.
+
+
+
+ As example we take a macro definition for the Vietnamese
+ name of Han The Thanh. Correctly written it needs some
+ accented characters, one character even with a double accent.
+ Class `tugboat.cls' defines a macro for the typesetted name:
+\begin{verbatim}
+ \def\Thanh{%
+ H\`an~%
+ Th\^e\llap{\raise 0.5ex\hbox{\'{}}}%
+ ~Th\`anh%
+ }
+\end{verbatim}
+ It's not entirely correct, the second accent over the `e' is not
+ an acute, but a hook. However standard LaTeX does not provide
+ such an accent.
+
+ Now we can extend the definition to support hyperref.
+ The first and the last word are already supported automatically.
+ Characters with two or more accents are a difficult business in
+ LaTeX, because the NFSS2 macros of the LaTeX kernel do not support
+ more than one accent. Therefore also puenc.def misses support for
+ them. But we can provide it using \verb|\unichar|. The character
+ in question is:
+\begin{verbatim}
+ % U+1EC3 LATIN SMALL LETTER E WITH CIRCUMFLEX AND HOOK ABOVE
+\end{verbatim}
+ Thus we can put this together:
+\begin{verbatim}
+ \def\Thanh{%
+ H\`an~%
+ \texorpdfstring{Th\^e\llap{\raise 0.5ex\hbox{\'{}}}}%
+ {\ifpdfstringunicode{Th\unichar{"1EC3}}{Th\^e}}%
+ ~Th\`anh%
+ }
+\end{verbatim}
+ For PDFDocEncoding (PD1) the variant above has dropped the
+ second accent. Alternatively we could provide a representation
+ without accents instead of wrong accents:
+\begin{verbatim}
+ \def\Thanh{%
+ \texorpdfstring{%
+ H\`an~%
+ Th\^e\llap{\raise 0.5ex\hbox{\'{}}}}%
+ ~Th\`anh%
+ }{%
+ \ifpdfstringunicode{%
+ H\`an Th\unichar{"1EC3} Th\`anh%
+ }{%
+ Han The Thanh%
+ }%
+ }%
+ }
+\end{verbatim}
+
+\subsection{Customizing index style file with \textbackslash nohyperpage}
+
+ Since version 2008/08/14~v6.78f.
+
+
+
+ For hyperlink support in the index, hyperref inserts \verb|\hyperpage|
+ into the index macros. After processing with Makeindex, \verb|\hyperpage|
+ analyzes its argument to detect page ranges and page comma lists.
+ However, only the standard settings are supported directly:
+\begin{verbatim}
+ delim_r "--"
+ delim_n ", "
+\end{verbatim}
+ (See manual page/documentation of Makeindex that explains
+ the keys that can be used in style files for Makeindex.)
+ Customized versions of
+ \verb|delim_r, delim_n, suffix_2p, suffix_3p, suffix_mp|
+ needs markup that \verb|\hyperpage| can detect and knows that
+ this stuff does not belong to a page number. Makro
+ \verb|\nohyperpage| serves as this markup. Put the customized
+ code for these keys inside \verb|\nohyperpage|, e.g.:
+\begin{verbatim}
+ suffix_2p "\\nohyperpage{f.}"
+ suffix_3p "\\nohyperpage{ff.}"
+\end{verbatim}
+ (Depending on the typesetting tradition some space ``\verb|\\|,'' or ``\verb|~|''
+ should be put before the first f inside \verb|\nohyperpage|.)
+
+
+\subsection{Experimental option `ocgcolorlinks'}
+
+ The idea are colored links, when viewed, but printed without colors.
+ This new experimental option `ocgcolorlinks' uses Optional Content
+ Groups, a feature introduced in PDF 1.5.
+
+ A better implementation which hasn't the disadvantage to prevent line breaks is
+ in the ocgx2 package. Check its documentation for details how to use it.
+\begin{itemize}
+ \item The option must be given for package loading:
+ \verb|\usepackage[ocgcolorlinks]{hyperref}|
+ \item Main disadvantage: Links cannot be broken across lines.
+ PDF reference 1.7: 4.10.2 ``Making Graphical Content Optional'':
+ Graphics state operations, such as setting the color, ...,
+ are still applied.
+ Therefore the link text is put in a box and set twice, with and
+ without color.
+ \item The feature can be switched of by \verb|\hypersetup{ocgcolorlinks=false}|
+ inside the document.
+ \item Supported drivers: pdftex, dvipdfm
+ \item The PDF version should be at least 1.5. It is automatically
+ set for pdfTeX, LuaTeX and dvipdfmx.
+\end{itemize}
+
+\subsection{Option `pdfa'}
+
+ The new option `pdfa' tries to avoid violations of PDF/A in code
+ generated by hyperref. However, the result is usually not in PDF/A,
+ because many features aren't controlled by hyperref (XMP metadata,
+ fonts, colors, driver dependend low level stuff, ...).
+
+
+
+ Currently, option `pdfa' sets and disables the following items:
+\begin{itemize}
+ \item Enabled annotation flags: Print, NoZoom, NoRotate [PDF/A 6.5.3].
+ \item Disabled annotation flags: Hidden, Invisible, NoView [PDF/A 6.5.3].
+ \item Disabled: Launch action (\href{run:...} [PDF/A 6.6.1].
+ \item Restricted: Named actions (\Acrobatmenu: NextPage, PrevPage,
+ FirstPage, LastPage) [PDF/A 6.6.1].
+ \item Many things are disabled in PDF formulars:
+ \begin{itemize}
+ \item JavaScript actions [PDF/A 6.6.1]
+ \item Trigger events (additional actions) [PDF/A 6.6.2]
+ \item Push button (because of JavaScript)
+ \item Interactive Forms: Flag NeedAppearances is the default `false'
+ (Because of this, hyperref's implementation of Forms looks ugly).
+ [PDF/A 6.9]
+ \end{itemize}
+\end{itemize}
+
+
+
+ The default value of the new option `pdfa' is `false'. It influences
+ the loading of the package and cannot be changed after hyperref is
+ loaded (\verb|\usepackage{hyperref}|).
+
+
+
+\subsection{Option `linktoc' added}
+
+ The new option `linktoc' allows more control which part
+ of an entry in the table of contents is made into a link:
+\begin{itemize}
+ \item `linktoc=none' (no links)
+ \item `linktoc=section' (default behaviour, same as `linktocpage=false')
+ \item `linktoc=page' (same as `linktocpage=true')
+ \item `linktoc=all' (both the section and page part are links)
+\end{itemize}
+
+\subsection{Option `pdfnewwindow' changed}
+
+ Before 6.77b:
+\begin{itemize}
+ \item pdfnewwindow=true $\rightarrow$ /NewWindow true
+ \item pdfnewwindow=false $\rightarrow$ (absent)
+ \item unused pdfnewwindow $\rightarrow$ (absent)
+\end{itemize}
+ Since 6.77b:
+\begin{itemize}
+ \item pdfnewwindow=true $\rightarrow$ /NewWindow true
+ \item pdfnewwindow=false $\rightarrow$ /NewWindow false
+ \item pdfnewwindow={} $\rightarrow$ (absent)
+ \item unused pdfnewwindow $\rightarrow$ (absent)
+\end{itemize}
+
+
+
+ Rationale: There is a difference between setting to `false'
+ and an absent entry. In the former case the new document
+ replaces the old one, in the latter case the PDF viewer
+ application should respect the user preference.
+
+
+\subsection{Flag options for PDF forms}
+
+ PDF form field macros (\verb|\TextField|, \verb|\CheckBox|, ...) support
+ boolean flag options. The option name is the lowercase
+ version of the names in the PDF specification (1.7):
+
+ \url{http://www.adobe.com/devnet/pdf/pdf_reference.html}
+
+ \url{http://www.adobe.com/devnet/acrobat/pdfs/pdf_reference.pdf}
+
+ Options (convert to lowercase) except flags in square brackets:
+
+\begin{itemize}
+ \item Table 8.16 Annotation flags (page 608):
+
+{\obeylines
+ 1 Invisible
+ 2 Hidden (PDF 1.2)
+ 3 Print (PDF 1.2)
+ 4 NoZoom (PDF 1.3)
+ 5 NoRotate (PDF 1.3)
+ 6 NoView (PDF 1.3)
+ [7 ReadOnly (PDF 1.3)] ignored for widget annotations, see table 8.70
+ 8 Locked (PDF 1.4)
+ 9 ToggleNoView (PDF 1.5)
+ 10 LockedContents (PDF 1.7)
+}
+ \item Table 8.70 Field flags common to all field types (page 676):
+
+{\obeylines
+ 1 ReadOnly
+ 2 Required
+ 3 NoExport
+}
+ \item Table 8.75 Field flags specific to button fields (page 686):
+
+{\obeylines
+ 15 NoToggleToOff (Radio buttons only)
+ 16 Radio (set: radio buttons, clear: check box, pushbutton: clear)
+ 17 Pushbutton
+ 26 RadiosInUniso (PDF 1.5)
+}
+ \item Table 8.77 Field flags specific to text fields (page 691):
+
+{\obeylines
+ 13 Multiline
+ 14 Password
+ 21 FileSelect (PDF 1.4)
+ 23 DoNotSpellCheck (PDF 1.4)
+ 24 DoNotScroll (PDF 1.4)
+ 25 Comb (PDF 1.5)
+ 26 RichText (PDF 1.5)
+}
+ \item Table 8.79 Field flags specific to choice fields (page 693):
+
+{\obeylines
+ 18 Combo (set: combo box, clear: list box)
+ 19 Edit (only useful if Combo is set)
+ 20 (Sort) for authoring tools, not PDF viewers
+ 22 MultiSelect (PDF 1.4)
+ 23 DoNotSpellCheck (PDF 1.4) (only useful if Combo and Edit are set)
+ 27 CommitOnSelChange (PDF 1.5)
+}
+ \item Table 8.86 Flags for submit-form actions (page 704):
+
+{\obeylines
+ [1 Include/Exclude] unsupported, use `noexport' (table 8.70) instead
+ 2 IncludeNoValueFields
+ [3 ExportFormat] handled by option `export'
+ 4 GetMethod
+ 5 SubmitCoordinates
+ [6 XFDF (PDF 1.4)] handled by option `export'
+ 7 IncludeAppendSaves (PDF 1.4)
+ 8 IncludeAnnotations (PDF 1.4)
+ [9 SubmitPDF (PDF 1.4)] handled by option `export'
+ 10 CanonicalFormat (PDF 1.4)
+ 11 ExclNonUserAnnots (PDF 1.4)
+ 12 ExclFKey (PDF 1.4)
+ 14 EmbedForm (PDF 1.5)
+}
+\end{itemize}
+
+ New option `export' sets the export format of a submit action.
+ Valid values are (upper- or lowercase):
+\begin{itemize}
+ \item FDF
+ \item HTML
+ \item XFDF
+ \item PDF (not supported by Acrobat Reader)
+\end{itemize}
+
+\subsection{Option `pdfversion'}
+
+ This is an experimental option. It notifies `hyperref' about
+ the intended PDF version. Currently this is used in code for
+ PDF forms (implementation notes 116 and 122 of PDF spec 1.7).
+
+
+
+ Values: 1.2, 1.3, 1.4, 1.5, 1.6, 1.7. Values below 1.2 are not
+ supported, because most drivers expect higher PDF versions.
+
+
+
+ The option must be used early, not after \verb|\usepackage{hyperref}|.
+
+
+ In theory this option should also set the PDF version,
+ but this is not generally supported.
+\begin{itemize}
+ \item pdfTeX below 1.10a: unsupported.
+ pdfTeX $\ge$ 1.10a and < 1.30: \verb|\pdfoptionpdfminorversion|
+ pdfTeX $\ge$ 1.30: \verb|\pdfminorversion|
+ \item dvipdfm: configuration file, example:
+ TeX Live 2007, texmf/dvipdfm/config/config, entry `V 2'.
+ \item dvipdfmx: configuration file, example:
+ TeX Live 2007, texmf/dvipdfm/dvipdfmx.cfg, entry `V 4'.
+ \item Ghostscript: option -dCompatibilityLevel (this is set in
+ `ps2pdf12', `ps2pdf13', `ps2pdf14').
+\end{itemize}
+
+
+ The current PDF version is used as default if this version
+ can be detected (only pdfTeX $\ge$ 1.10a). Otherwise the lowest
+ version 1.2 is assumed. Thus `hyperref' tries to avoid PDF code
+ that breaks this version, but is free to use ignorable higher PDF
+ features.
+
+
+\subsection{Field option `name'}
+
+ Many form objects uses the label argument
+ for several purposes:
+\begin{itemize}
+ \item Layouted label.
+ \item As name in HTML structures.
+\end{itemize}
+ Code that is suitable for layouting with TeX can
+ break in the structures of the output format.
+ If option `name' is given, then its value is used
+ as name in the different output structures. Thus
+ the value should consist of letters only.
+
+
+\subsection{Option `pdfencoding'}
+
+ The PDF format allows two encodings for bookmarks and entries
+ in the information dictionary: PDFDocEncoding and Unicode
+ as UTF-16BE. Option \xoption{pdfencoding} selects between these encodings:
+\begin{itemize}
+ \item \xoption{pdfdoc} uses PDFDocEncoding. It uses just one byte per character,
+ but the supported characters are limited (244 in PDF-1.7).
+ \item \xoption{unicode} sets Unicode. It is encoded as UTF-16BE. Two bytes
+ are used for most characters, surrogates need four bytes.
+ \item \xoption{auto} PDFDocEncoding if the string does not contain characters
+ outside the encoding and Unicode otherwise.
+\end{itemize}
+
+ The luatex driver uses \xoption{unicode} by default. If another encoding should be forced,
+ it should be done in \verb|hypersetup|.
+
+\subsection{Color options/package hycolor}
+
+ See documentation of package `hycolor'.
+
+
+\subsection{Option pdfusetitle}
+
+ If option pdfusetitle is set then hyperref tries to
+ derive the values for pdftitle and pdfauthor from
+ \verb|\title| and \verb|\author|. An optional argument for \verb|\title| and
+ \verb|\author| is supported (class amsart).
+
+
+\subsection{Starred form of \textbackslash autoref}
+
+ \verb|\autoref*| generates a reference without link as \verb|\ref*| or \verb|\pageref*|.
+
+
+\subsection{Link border style}
+
+ Links can be underlined instead of the default rectangle or
+ options \xoption{colorlinks}, \xoption{frenchlinks}. This is done by option
+ \verb|pdfborderstyle={/S/U/W 1}|
+
+ Some remarks:
+
+\begin{itemize}
+ \item AR7/Linux seems to have a bug, that don't use the default
+ value \verb"1" for the width, but zero, thus that the underline
+ is not visible without \verb"/W 1". The same applies for
+ dashed boxes, eg.:
+ pdfborderstyle={/S/D/D[3 2]/W 1}
+
+ \item The syntax is described in the PDF specification, look for
+ ``border style'', eg.
+ Table 8.13 ``Entries in a border style dictionary''
+ (specification for version 1.6)
+
+ \item The border style is removed by
+ pdfborderstyle={}
+ This is automatically done if option colorlinks is enabled.
+
+ \item Be aware that not all PDF viewers support this feature, not
+ even Acrobat Reader itself:
+
+ Some support:
+ \begin{itemize}
+ \item AR7/Linux: \xoption{underline} and \xoption{dashed}, but the border width
+ must be given.
+ \item xpdf 3.00: \xoption{underline} and \xoption{dashed}
+ \end{itemize}
+
+ Unsupported:
+ \begin{itemize}
+ \item AR5/Linux
+ \item ghostscript 8.50
+ \end{itemize}
+\end{itemize}
+
+\subsection{Option \xoption{bookmarksdepth}}
+
+ The depth of the bookmarks can be controlled by the new
+ option \xoption{bookmarksdepth}. The option acts globally and
+ distinguishes three cases:
+\begin{itemize}
+ \item \xoption{bookmarksdepth} without value
+ Then hyperref uses the current value of counter \xoption{tocdepth}.
+ This is the compatible behaviour and the default.
+ \item \verb"bookmarksdepth=<number>", the value is number (also negative):
+ The depth for the bookmarks are set to this number.
+ \item \verb"bookmarksdepth=<name>"
+ The <name> is a document division name (part, chapter, ...).
+ It must not start with a digit or minus to avoid mixing up
+ with the number case. Internally hyperref uses the value
+ of macro \verb|\toclevel@<name>|.
+ Examples:
+\begin{verbatim}
+ \hypersetup{bookmarksdepth=paragraph}
+ \hypersetup{bookmarksdepth=4} % same as before
+ \hypersetup{bookmarksdepth} % counter "tocdepth" is used
+\end{verbatim}
+\end{itemize}
+
+\subsection{Option \xoption{pdfescapeform}}
+
+ There are many places where arbitrary strings end up as
+ PS or PDF strings. The PS/PDF strings in parentheses form
+ require the protection of some characters, e.g. unmatched
+ left or right parentheses need escaping or the escape
+ character itself (backslash).
+ Since 2006/02/12~v6.75a the PS/PDF driver should do
+ this automatically. However I assume a problem with
+ compatibility, especially regarding the form part where
+ larger amounts of JavaScript code can be present.
+ It would be a pain to remove all the escaping, because
+ an additional escaping layer can falsify the code.
+
+ Therefore a new option pdfescapeform was introduced:
+\begin{itemize}
+ \item pdfescapeform=false
+ Escaping for the formulars are disabled, this is
+ the compatibility behaviour, therefore this is the default.
+ \item pdfescapeform=true
+ Then the PS/PDF drivers do all the necessary escaping.
+ This is the logical choice and the recommended setting.
+ For example, the user writes JavaScript as JavaScript
+ and do not care about escaping characters for PS/PDF
+ output.
+\end{itemize}
+
+\subsection{Default driver setting}
+
+ (hyperref $\ge$ 6.72s)
+ If no driver is given, hyperref tries its best to guess the
+ most suitable driver. Thus it loads \xoption{hpdftex}, if pdfTeX is
+ detected running in PDF mode. Or it loads the corresponding
+ VTeX driver for VTeX's working modes.
+ Unhappily many driver programs run after the TeX compiler,
+ so hyperref does not have a chance (dvips, dvipdfm, ...).
+ In this case driver \xoption{hypertex} is loaded that supports the
+ HyperTeX features that are recognized by xdvi for example.
+ This behaviour, however, can easily be changed in the configuration
+ file \verb"hyperref.cfg":
+\begin{verbatim}
+ \providecommand*{\Hy@defaultdriver}{hdvips}
+\end{verbatim}
+ for dvips, or
+\begin{verbatim}
+ \providecommand*{\Hy@defaultdriver}{hypertex}
+\end{verbatim}
+ for the default behaviour of hyperref.
+
+ See also the new option `driverfallback'.
+
+\subsection{Backref entries}
+
+ Alternative interface for formatting of backref entries, example:
+
+\begin{verbatim}
+\documentclass[12pt,UKenglish]{article}
+
+\usepackage{babel}
+\usepackage[pagebackref]{hyperref}
+
+% Some language options are detected by package backref.
+% This affects the following macros:
+% \backrefpagesname
+% \backrefsectionsname
+% \backrefsep
+% \backreftwosep
+% \backreflastsep
+
+\renewcommand*{\backref}[1]{
+ % default interface
+ % #1: backref list
+ %
+ % We want to use the alternative interface,
+ % therefore the definition is empty here.
+}
+\renewcommand*{\backrefalt}[4]{%
+ % alternative interface
+ % #1: number of distinct back references
+ % #2: backref list with distinct entries
+ % #3: number of back references including duplicates
+ % #4: backref list including duplicates
+ \par
+ #3 citation(s) on #1 page(s): #2,\par
+ \ifnum#1=1 %
+ \ifnum#3=1 %
+ 1 citation on page %
+ \else
+ #3 citations on page %
+ \fi
+ \else
+ #3 citations on #1 pages %
+ \fi
+ #2,\par
+ \ifnum#3=1 %
+ 1 citation located at page %
+ \else
+ #3 citations located at pages %
+ \fi
+ #4.\par
+}
+
+% The list of distinct entries can be further refined:
+\renewcommand*{\backrefentrycount}[2]{%
+ % #1: the original backref entry
+ % #2: the count of citations of this entry,
+ % in case of duplicates greater than one
+ #1%
+ \ifnum#2>1 %
+ ~(#2)%
+ \fi
+}
+
+\begin{document}
+
+ \section{Hello}
+ \cite{ref1, ref2, ref3, ref4}
+ \section{World}
+ \cite{ref1, ref3}
+ \newpage
+
+ \section{Next section}
+ \cite{ref1}
+ \newpage
+
+ \section{Last section}
+ \cite{ref1, ref2}
+ \newpage
+
+ \pdfbookmark[1]{Bibliography}{bib}
+ \begin{thebibliography}{99}
+ \bibitem{ref1} Dummy entry one.
+
+ \bibitem{ref2} Dummy entry two.
+
+ \bibitem{ref3} Dummy entry three.
+
+ \bibitem{ref4} Dummy entry four.
+
+ \end{thebibliography}
+
+\end{document}
+\end{verbatim}
+
+\subsection{\textbackslash phantomsection}
+
+Set an anchor at this location. It is often used in conjunction
+with \verb|\addcontentsline| for sectionlike things (index, bibliography,
+preface). \verb|\addcontentsline| refers to the latest previous location
+where an anchor is set.
+
+\begin{verbatim}
+ \cleardoublepage
+ \phantomsection
+ \addcontentsline{toc}{chapter}{\indexname}
+ \printindex
+\end{verbatim}
+
+Now the entry in the table of contents (and bookmarks) for the
+index points to the start of the index page, not to a location
+before this page.
+
+
+
+\section{Acrobat-specific behavior}
+If you want to access the menu options of Acrobat Reader or Exchange, the following
+macro is provided in the appropriate drivers:
+
+\begin{cmdsyntax}
+\ci{Acrobatmenu}\verb|{|\emph{menuoption}\verb|}{|\emph{text}\verb|}|
+\end{cmdsyntax}
+
+\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.
+
+\medskip
+\begin{longtable}{@{}l>{\raggedright\arraybackslash}p{9cm}@{}}
+File & Open, Close, Scan, Save, SaveAs, Optimizer:SaveAsOpt, Print, PageSetup, Quit \\
+File$\rightarrow$Import & ImportImage, ImportNotes, AcroForm:ImportFDF \\
+File$\rightarrow$Export & ExportNotes, AcroForm:ExportFDF \\
+File$\rightarrow$DocumentInfo & GeneralInfo, OpenInfo, FontsInfo, SecurityInfo, Weblink:Base, AutoIndex:DocInfo \\
+File$\rightarrow$Preferences & GeneralPrefs, NotePrefs, FullScreenPrefs, Weblink:Prefs, AcroSearch:Preferences(Windows)
+ or, AcroSearch:Prefs(Mac), Cpt:Capture \\
+Edit & Undo, Cut, Copy, Paste, Clear, SelectAll, Ole:CopyFile, TouchUp:TextAttributes,
+ TouchUp:FitTextToSelection, TouchUp:ShowLineMarkers, TouchUp:ShowCaptureSuspects,
+ TouchUp:FindSuspect, \\
+ & Properties \\
+Edit$\rightarrow$Fields & AcroForm:Duplicate, AcroForm:TabOrder \\
+Document & Cpt:CapturePages, AcroForm:Actions, CropPages, RotatePages, InsertPages, ExtractPages,
+ ReplacePages, DeletePages, NewBookmark, SetBookmarkDest, CreateAllThumbs,
+ DeleteAllThumbs \\
+View & ActualSize, FitVisible, FitWidth, FitPage, ZoomTo, FullScreen, FirstPage, PrevPage,
+ NextPage, LastPage, GoToPage, GoBack, GoForward, SinglePage, OneColumn, TwoColumns,
+ ArticleThreads, PageOnly, ShowBookmarks, ShowThumbs \\
+Tools & Hand, ZoomIn, ZoomOut, SelectText, SelectGraphics, Note, Link, Thread, AcroForm:Tool,
+ Acro\_Movie:MoviePlayer, TouchUp:TextTool, Find, FindAgain, FindNextNote,
+ CreateNotesFile \\
+Tools$\rightarrow$Search & AcroSrch:Query, AcroSrch:Indexes, AcroSrch:Results, AcroSrch:Assist, AcroSrch:PrevDoc,
+ AcroSrch:PrevHit, AcroSrch:NextHit, AcroSrch:NextDoc \\
+Window & ShowHideToolBar, ShowHideMenuBar, ShowHideClipboard, Cascade, TileHorizontal,
+ TileVertical, CloseAll \\
+Help & HelpUserGuide, HelpTutorial, HelpExchange, HelpScan, HelpCapture, HelpPDFWriter,
+ HelpDistiller, HelpSearch, HelpCatalog, HelpReader, Weblink:Home \\
+Help(Windows) & About
+\end{longtable}
+
+\section{PDF and HTML forms}
+You must put your fields inside a \texttt{Form} environment (only one per file).
+
+There are six macros to prepare fields:
+
+\begin{cmdsyntax}
+\ci{TextField}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}|
+\end{cmdsyntax}
+
+\begin{cmdsyntax}
+\ci{CheckBox}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}|
+\end{cmdsyntax}
+
+\begin{cmdsyntax}
+\ci{ChoiceMenu}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}{|\emph{choices}\verb|}|
+\end{cmdsyntax}
+
+\begin{cmdsyntax}
+\ci{PushButton}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}|
+\end{cmdsyntax}
+
+\begin{cmdsyntax}
+\ci{Submit}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}|
+\end{cmdsyntax}
+
+\begin{cmdsyntax}
+\ci{Reset}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}|
+\end{cmdsyntax}
+
+The way forms and their labels are laid out is determined by:
+\begin{cmdsyntax}
+\ci{LayoutTextField}\verb|{|\emph{label}\verb|}{|\emph{field}\verb|}|
+\end{cmdsyntax}
+
+\begin{cmdsyntax}
+\ci{LayoutChoiceField}\verb|{|\emph{label}\verb|}{|\emph{field}\verb|}|
+\end{cmdsyntax}
+
+\begin{cmdsyntax}
+\ci{LayoutCheckField}\verb|{|\emph{label}\verb|}{|\emph{field}\verb|}|
+\end{cmdsyntax}
+
+These macros default to \#1 \#2
+
+What is actually shown in as the field is determined by:
+\begin{cmdsyntax}
+\ci{MakeRadioField}\verb|{|\emph{width}\verb|}{|\emph{height}\verb|}|
+\end{cmdsyntax}
+
+\begin{cmdsyntax}
+\ci{MakeCheckField}\verb|{|\emph{width}\verb|}{|\emph{height}\verb|}|
+\end{cmdsyntax}
+\begin{cmdsyntax}
+\ci{MakeTextField}\verb|{|\emph{width}\verb|}{|\emph{height}\verb|}|
+\end{cmdsyntax}
+\begin{cmdsyntax}
+\ci{MakeChoiceField}\verb|{|\emph{width}\verb|}{|\emph{height}\verb|}|
+\end{cmdsyntax}
+
+\begin{cmdsyntax}
+\ci{MakeButtonField}\verb|{|\emph{text}\verb|}|
+\end{cmdsyntax}
+
+These macros default to \verb|\vbox to #2{\hbox to #1{\hfill}\vfill}|, except the
+last, which defaults to \#1; it is used for buttons, and the special \ci{Submit} and \ci{Reset}
+macros.
+
+You may also want to redefine the following macros:
+\begin{verbatim}
+\def\DefaultHeightofSubmit{12pt}
+\def\DefaultWidthofSubmit{2cm}
+\def\DefaultHeightofReset{12pt}
+\def\DefaultWidthofReset{2cm}
+\def\DefaultHeightofCheckBox{0.8\baselineskip}
+\def\DefaultWidthofCheckBox{0.8\baselineskip}
+\def\DefaultHeightofChoiceMenu{0.8\baselineskip}
+\def\DefaultWidthofChoiceMenu{0.8\baselineskip}
+\def\DefaultHeightofText{\baselineskip}
+\def\DefaultHeightofTextMultiline{4\baselineskip}
+\def\DefaultWidthofText{3cm}
+\end{verbatim}
+
+\subsection{Forms environment parameters}
+
+\smallskip
+\begin{longtable}{@{}>{\ttfamily}l>{\itshape}lp{9cm}@{}}
+action & URL & The URL that will receive the form data if a \textsf{Submit} button is included in the form \\
+encoding & name & The encoding for the string set to the URL; FDF-encoding is usual, and \texttt{html} is the only
+ valid value \\
+method & name & Used only when generating HTML; values can be \texttt{post} or \texttt{get} \\
+\end{longtable}
+
+\subsection{Forms optional parameters}
+Note that all colors must be expressed as RGB triples, in the range 0..1 (i.e.\ \texttt{color=0 0
+0.5})
+
+\smallskip
+\begin{longtable}{@{}>{\ttfamily}ll>{\itshape}ll@{}}
+accesskey & key & & (as per HTML) \\
+align & number & 0 & alignment within text field; 0 is left-aligned,\\*
+ & & & 1 is centered, 2 is right-aligned. \\
+altname & name & & alternative name,\\*
+ & & & the name shown in the user interface\\
+backgroundcolor & & & color of box \\
+bordercolor & & & color of border \\
+bordersep & & & box border gap \\
+borderwidth & & 1 & width of box border, the value is a dimension\\
+ & & & or a number with default unit bp\\
+calculate & & & JavaScript code to calculate the value of the field \\
+charsize & dimen & & font size of field text \\
+checkboxsymbol & char & 4 (\ding{\number`4}) & symbol used for check boxes (ZapfDingbats), \\
+&&& the value is a character or \cs{ding}\verb|{|\texttt{\itshape number}\verb|}|, \\
+&&& see package \xpackage{pifont} from bundle \xpackage{psnfss} \\
+checked & boolean & false & whether option selected by default \\
+color & & & color of text in box \\
+combo & boolean & false & choice list is `combo' style \\
+default & & & default value \\
+disabled & boolean & false & field disabled \\
+format & & & JavaScript code to format the field \\
+height & dimen & & height of field box \\
+hidden & boolean & false & field hidden \\
+keystroke & & & JavaScript code to control the keystrokes on entry \\
+mappingname & name & & the mapping name to be used when exporting\\*
+ & & & the field data\\
+maxlen & number & 0 & number of characters allowed in text field \\
+menulength & number & 4 & number of elements shown in list \\
+multiline & boolean & false & whether text box is multiline \\
+name & name & & name of field (defaults to label) \\
+onblur & & & JavaScript code \\
+onchange & & & JavaScript code \\
+onclick & & & JavaScript code \\
+ondblclick & & & JavaScript code \\
+onfocus & & & JavaScript code \\
+onkeydown & & & JavaScript code \\
+onkeypress & & & JavaScript code \\
+onkeyup & & & JavaScript code \\
+onmousedown & & & JavaScript code \\
+onmousemove & & & JavaScript code \\
+onmouseout & & & JavaScript code \\
+onmouseover & & & JavaScript code \\
+onmouseup & & & JavaScript code \\
+onselect & & & JavaScript code \\
+password & boolean & false & text field is `password' style \\
+popdown & boolean & false & choice list is `popdown' style \\
+radio & boolean & false & choice list is `radio' style \\
+radiosymbol & char & H (\ding{\number`H}) & symbol used for radio fields (ZapfDingbats), \\
+&&& the value is a character or \cs{ding}\verb|{|\texttt{\itshape number}\verb|}|, \\
+&&& see package \xpackage{pifont} from bundle \xpackage{psnfss} \\
+readonly & boolean & false & field is readonly \\
+rotation & number & 0 & rotation of the widget annotation \\*
+ & & & (degree, counterclockwise, multiple of 90)\\
+tabkey & & & (as per HTML) \\
+validate & & & JavaScript code to validate the entry \\
+value & & & initial value \\
+width & dimen & & width of field box
+\end{longtable}
+
+\section{Defining a new driver}
+A hyperref driver has to provide definitions for eight macros:
+
+\smallskip
+\noindent 1. \verb|\hyper@anchor|
+
+\noindent 2. \verb|\hyper@link|
+
+\noindent 3. \verb|\hyper@linkfile|
+
+\noindent 4. \verb|\hyper@linkurl|
+
+\noindent 5. \verb|\hyper@anchorstart|
+
+\noindent 6. \verb|\hyper@anchorend|
+
+\noindent 7. \verb|\hyper@linkstart|
+
+\noindent 8. \verb|\hyper@linkend|
+\smallskip
+
+The draft option defines the macros as follows
+\begin{verbatim}
+\let\hyper@@anchor\@gobble
+\gdef\hyper@link##1##2##3{##3}%
+\def\hyper@linkurl##1##2{##1}%
+\def\hyper@linkfile##1##2##3{##1}%
+\let\hyper@anchorstart\@gobble
+\let\hyper@anchorend\@empty
+\let\hyper@linkstart\@gobbletwo
+\let\hyper@linkend\@empty
+\end{verbatim}
+
+\section{Special support for other packages}
+
+Package \xpackage{hyperref} aims to cooperate with other packages, but there are
+several possible sources for conflict, such as
+
+\begin{itemize}
+
+\item Packages that manipulate the bibliographic mechanism. Peter
+William's \xpackage{harvard} package is supported. However, the
+recommended package is Patrick Daly's \xpackage{natbib} package that has
+specific \xpackage{hyperref} hooks to allow reliable interaction. This
+package covers a very wide variety of layouts and citation styles, all
+of which work with \xpackage{hyperref}.
+
+\item Packages that typeset the contents of the \ci{label} and \ci{ref}
+macros, such as \xpackage{showkeys}. Since the \xpackage{hyperref} package
+redefines these commands, you must set \texttt{implicit=false} for these
+packages to work.
+
+\item Packages that do anything serious with the index.
+\end{itemize}
+
+The \xpackage{hyperref} package is distributed with variants on two useful
+packages designed to work especially well with it. These are \xpackage{xr}
+and \xpackage{minitoc}, which support crossdocument links using \hologo{LaTeX}'s
+normal \cs{label}/\cs{ref} mechanisms and per-chapter tables of contents,
+respectively.
+
+
+\subsection{Package Compatibility}
+
+Currently only package loading orders are available:
+
+
+
+Note: hyperref loads package \xpackage{nameref} at \verb|\begin{document}|.
+Sometimes this is too late, thus this package must be loaded
+earlier.
+
+
+\subsubsection{algorithm}
+\begin{verbatim}
+ \usepackage{float}
+ \usepackage{hyperref}
+ \usepackage[chapter]{algorithm}% eg.
+\end{verbatim}
+
+\subsubsection{amsmath}
+
+ The environments equation and eqnarray are not supported too well.
+ For example, there might be spacing problems (eqnarray isn't recommended
+ anyway, see CTAN:info/l2tabu/, the situation for equation is unclear,
+ because nobody is interested in investigating). Consider using the
+ environments that package amsmath provide, e.g. gather for equation.
+ The environment equation can even redefined to use gather:
+
+\begin{verbatim}
+ \usepackage{amsmath}
+ \let\equation\gather
+ \let\endequation\endgather
+\end{verbatim}
+
+\subsubsection{amsrefs}
+
+ Package loading order:
+
+\begin{verbatim}
+ \usepackage{hyperref}
+ \usepackage{amsrefs}
+\end{verbatim}
+
+\subsubsection{arydshln, longtable}
+
+ Package longtable must be put before hyperref and arydshln,
+ hyperref after arydshln generates an error, thus the
+ resulting package order is then:
+
+\begin{verbatim}
+ \usepackage{longtable}
+ \usepacakge{hyperref}
+ \usepackage{arydshln}
+\end{verbatim}
+
+\subsubsection{babel/magyar.ldf}
+
+ The old version 2005/03/30 v1.4j will not work.
+ You need at least version 1.5, maintained by P\'eter Szab\'o,
+ see CTAN:language/hungarian/babel/.
+
+
+\subsubsection{babel/spanish.ldf}
+
+ Babel's spanish.ldf redefines `\verb|\.|' to support `\verb|\...|'.
+ In bookmarks (\verb|\pdfstringdef|) only `\verb|\.|' is supported.
+ If `\verb|\...|' is needed,
+ \verb|\texorpdfstring{\...}{\dots}|
+ can be used instead.
+
+
+\subsubsection{bibentry}
+
+ Workaround:
+
+\begin{verbatim}
+ \makeatletter
+ \let\saved@bibitem\@bibitem
+ \makeatother
+
+ \usepackage{bibentry}
+ \usepackage{hyperref}
+
+ \begin{document}
+
+ \begingroup
+ \makeatletter
+ \let\@bibitem\saved@bibitem
+ \nobibliography{database}
+ \endgroup
+\end{verbatim}
+
+\subsubsection{bigfoot}
+
+ Hyperref does not support package `bigfoot'. And package
+ `bigfoot' does not support hyperref's footnotes and disables
+ them (hyperfootnotes=false).
+
+
+\subsubsection{chappg}
+
+ Package `chappg' uses \verb|\@addtoreset| that is redefined by `hyperref'.
+ The package order is therefore:
+
+\begin{verbatim}
+ \usepackage{hyperref}
+ \usepackage{chappg}
+\end{verbatim}
+
+\subsubsection{cite}
+
+ This is from Mike Shell:
+ cite.sty cannot currently be used with hyperref.
+ However, I can do a workaround via:
+
+\begin{verbatim}
+ \makeatletter
+ \def\NAT@parse{\typeout{This is a fake Natbib command to fool Hyperref.}}
+ \makeatother
+
+ \usepackage[hypertex]{hyperref}
+\end{verbatim}
+
+ so that hyperref will not redefine any of the biblabel stuff - so cite.sty
+ will work as normal - although the citations will not be hyperlinked, of
+ course (But this may not be an issue for many people).
+
+
+\subsubsection{count1to}
+
+ Package `count1to' adds several \verb|\@addtoreset| commands that confuse
+ `hyperref'. Therefore \verb|\theH<...>| has to be fixed:
+
+\begin{verbatim}
+ \usepackage{count1to}
+ \AtBeginDocument{% *after* \usepackage{count1to}
+ \renewcommand*{\theHsection}{\theHchapter.\arabic{section}}%
+ \renewcommand*{\theHsubsection}{\theHsection.\arabic{subsection}}%
+ \renewcommand*{\theHsubsubsection}{\theHsubsection.\arabic{subsubsection}}%
+ \renewcommand*{\theHparagraph}{\theHsubsubsection.\arabic{paragraph}}%
+ \renewcommand*{\theHsubparagraph}{\theHparagraph.\arabic{subparagraph}}%
+ }
+\end{verbatim}
+
+\subsubsection{dblaccnt}
+
+ pd1enc.def or puenc.def should be loaded before:
+\begin{verbatim}
+ \usepackage{hyperref}
+ \usepackage{dblaccnt}
+\end{verbatim}
+ or see entry for \xoption{vietnam}.
+
+
+\subsubsection{easyeqn}
+ Not compatible, breaks.
+
+
+\subsubsection{ellipsis}
+
+ This packages redefines \verb|\textellipsis|
+ after package hyperref (pd1enc.def/puenc.def should be loaded before):
+\begin{verbatim}
+ \usepackage{hyperref}
+ \usepackage{ellipsis}
+\end{verbatim}
+
+\subsubsection{float}
+\begin{verbatim}
+ \usepackage{float}
+ \usepackage{hyperref}
+\end{verbatim}
+\begin{itemize}
+ \item Several \verb|\caption| commands are not supported inside one float object.
+ \item Anchor are set at top of the float object, if its style is controlled
+ by float.sty.
+\end{itemize}
+
+\subsubsection{endnotes}
+ Unsupported.
+
+\subsubsection{foiltex}
+ Update to version 2008/01/28 v2.1.4b:
+ Since version 6.77a hyperref does not hack into \verb|\@begindvi|,
+ it uses package `atbegshi' instead, that hooks into \verb|\shipout|.
+ Thus the patch of `foils.cls' regarding hyperref is now obsolete
+ and causes an undefined error message about \verb|\@hyperfixhead|.
+ This is fixed in FoilTeX 2.1.4b.
+
+
+\subsubsection{footnote}
+
+ This package is not supported, you have to disable hyperref's footnote
+ support by using option \verb"hyperfootnotes=false".
+
+
+\subsubsection{geometry}
+
+ Driver `dvipdfm' and program `dvipdfm' might generate a warning:
+ Sorry. Too late to change page size
+ Then prefer the program `dvipdfmx' or use one of the following
+ workarounds to move the \verb|\special| of geometry to an earlier
+ location:
+
+\begin{verbatim}
+ \documentclass[dvipdfm]{article}% or other classes
+ \usepackage{atbegshi}
+ \AtBeginDocument{%
+ \let\OrgAtBeginDvi\AtBeginDvi
+ \let\AtBeginDvi\AtBeginShipoutFirst
+ }
+ \usepackage[
+ paperwidth=170mm,
+ paperheight=240mm
+ ]{geometry}
+ \AtBeginDocument{%
+ \let\AtBeginDvi\OrgAtBeginDvi
+ }
+ \usepackage{hyperref}
+
+ or
+
+ \documentclass[dvipdfm]{article}% or other classes
+ \usepackage{atbegshi}
+ \let\AtBeginDvi\AtBeginShipoutFirst
+ \usepackage[
+ paperwidth=170mm,
+ paperheight=240mm
+ ]{geometry}
+ \usepackage{hyperref}
+\end{verbatim}
+
+\subsubsection{IEEEtran.cls}
+
+ version $\ge$ V1.6b (because of \verb|\@makecaption|, see ChangeLog)
+
+
+\subsubsection{index}
+
+ version $\ge$ 1995/09/28 v4.1 (because of \verb|\addcontentsline| redefinition)
+
+
+\subsubsection{lastpage}
+
+ Compatible.
+
+
+\subsubsection{linguex}
+\begin{verbatim}
+ \usepackage{hyperref}
+ \usepackage{linguex}
+\end{verbatim}
+
+\subsubsection{ltabptch}
+\begin{verbatim}
+ \usepackage{longtable}
+ \usepackage{ltabptch}
+ \usepackage{hyperref}
+\end{verbatim}
+
+\subsubsection{mathenv}
+
+ Unsupported.
+
+
+
+ Both `mathenv' and `hyperref' messes around with
+ environment `eqnarray'. You can load `mathenv' after
+ `hyperref' to avoid an error message. But \verb|\label|
+ will not work inside environment `eqnarray' properly,
+ for example.
+
+
+\subsubsection{minitoc-hyper}
+
+ This package is obsolete, use the uptodate original
+ package minitoc instead.
+
+
+\subsubsection{multind}
+\begin{verbatim}
+ \usepackage{multind}
+ \usepackage{hyperref}
+\end{verbatim}
+
+\subsubsection{natbib}
+\begin{verbatim}
+ \usepackage{natbib}
+ \usepackage{hyperref}
+\end{verbatim}
+
+\subsubsection{nomencl}
+Example for introducing links for the page numbers:
+\begin{verbatim}
+ \renewcommand*{\pagedeclaration}[1]{\unskip, \hyperpage{#1}}
+\end{verbatim}
+
+
+For equations the following might work:
+\begin{verbatim}
+ \renewcommand*{\eqdeclaration}[1]{%
+ \hyperlink{equation.#1}{(Equation~#1)}%
+ }
+ But the mapping from the equation number to the anchor name
+ is not available in general.
+\end{verbatim}
+
+\subsubsection{parskip}
+\begin{verbatim}
+ \usepackage{parskip}
+ \usepackage{hyperref}[2012/08/20]
+\end{verbatim}
+
+
+ Both packages want to redefine \verb|\@starttoc|.
+
+
+\subsubsection{prettyref}
+\begin{verbatim}
+%%% example for prettyref %%%
+\documentclass{article}
+\usepackage{prettyref}
+\usepackage[pdftex]{hyperref}
+
+%\newrefformat{FIG}{Figure~\ref{#1}}% without hyperref
+\newrefformat{FIG}{\hyperref[{#1}]{Figure~\ref*{#1}}}
+
+\begin{document}
+ This is a reference to \prettyref{FIG:ONE}.
+ \newpage
+ \begin{figure}
+ \caption{This is my figure}
+ \label{FIG:ONE}
+ \end{figure}
+\end{document}
+%%% example for prettyref %%%
+ \end{verbatim}
+
+\subsubsection{ntheorem}
+\begin{verbatim}
+ ntheorem-hyper.sty is an old patched version of ntheorem.sty.
+ Newer versions of ntheorem know the option hyperref:
+ \usepackage{hyperref}
+ \usepackage[hyperref]{ntheorem}
+ But there are still unsolved problems (options thref, ...).
+\end{verbatim}
+
+\subsubsection{setspace}
+\begin{verbatim}
+ \usepackage{setspace}
+ \usepackage{hyperref}
+\end{verbatim}
+
+\subsubsection{sidecap}
+\begin{verbatim}
+ Before 2002/05/24 v1.5h:
+ \usepackage{nameref}
+ \usepackage{hyperref}
+ \usepackage{sidecap}
+\end{verbatim}
+
+\subsubsection{subfigure}
+\begin{verbatim}
+ 1995/03/06 v2.0:
+ \usepackage{subfigure}
+ \usepackage{hyperref}
+ % hypertexnames is set to false.
+ v2.1:
+ \usepackage{nameref}
+ \usepackage{subfigure}
+ \usepackage{hyperref}
+ or
+ \usepackage{hyperref}
+ \usepackage{subfigure}
+ v2.1.2:
+ please update
+ v2.1.3:
+ \usepackage{hyperref}
+ \usepackage{subfigure}
+ or vice versa?
+\end{verbatim}
+
+\subsubsection{titleref}
+\begin{verbatim}
+ \usepackage{nameref}
+ \usepackage{titleref}% without usetoc
+ \usepackage{hyperref}
+\end{verbatim}
+
+\subsubsection{tabularx}
+
+ Linked footnotes are not supported inside environment `tabularx',
+ because they uses the optional argument of \verb|\footnotetext|, see
+ section `Limitations'. Before version 2011/09/28 6.82i
+ hyperref had disabled footnotes entirely by `hyperfootnotes=false'.
+
+
+\subsubsection{titlesec}
+
+ \xpackage{nameref} supports titlesec, but hyperref does not
+ (unsolved is the anchor setting, missing with unnumbered
+ section, perhaps problems with page breaks with numbered ones).
+
+
+\subsubsection{ucs/utf8x.def}
+
+ The first time a multibyte UTF8 sequence is called, it
+ does some calculations and stores the result in a macro
+ for speeding up the next calls of that UTF8 sequence.
+ However this makes the first call non-expandable and
+ will break if used in information entries or bookmarks.
+ Package \xpackage{ucs} offers \verb|\PrerenderUnicode| or \verb|\PreloadUnicodePage|
+ to solve this:
+\begin{verbatim}
+ \usepackage{ucs}
+ \usepackage[utf8x]{inputenc}
+ \usepackage{hyperref}% or with option unicode
+ \PrerenderUnicode{^^c3^^b6}% or \PrerenderUnicodePage{1}
+ \hypersetup{pdftitle={Umlaut example: ^^c3^^b6}}
+\end{verbatim}
+ The notation with two carets avoids trouble with 8-bit bytes
+ for the README file, you can use the characters directly.
+
+
+\subsubsection{varioref}
+ There are too many problems with varioref. Nobody has time to
+ sort them out. Therefore this package is now unsupported.
+
+
+ Perhaps you are lucky and some of the features of varioref works
+ with the following loading order:
+\begin{verbatim}
+ \usepackage{nameref}
+ \usepackage{varioref}
+ \usepackage{hyperref}
+\end{verbatim}
+
+
+ Also some babel versions can be problematic. For exmample,
+ 2005/05/21 v3.8g contains a patch for varioref that breaks
+ the hyperref support for varioref.
+
+
+
+ Also unsupported:
+\begin{itemize}
+\item \verb|\Ref|, \verb|\Vref| do not uppercase the first letter.
+\item \verb|\vpageref[]{...}|
+ On the same page a previous space is not suppressed.
+\end{itemize}
+
+\subsubsection{verse}
+
+ Version 2005/08/22 v2.22 contains support for hyperref.
+
+ For older versions see example from
+ de.comp.text.tex (2005/08/11, slightly modified):
+
+\begin{verbatim}
+ \documentclass{article}
+
+ % package order does not matter
+ \usepackage{verse}
+ \usepackage{hyperref}
+
+ \makeatletter
+ % make unique poemline anchors
+ \newcounter{verse@env}
+ \setcounter{verse@env}{0}
+ \let\org@verse\verse
+ \def\verse{%
+ \stepcounter{verse@env}%
+ \org@verse
+ }
+ \def\theHpoemline{\arabic{verse@env}.\thepoemline}
+
+ % add anchor for before \addcontentsline in \@vsptitle
+ \let\org@vsptitle\@vsptitle
+ \def\@vsptitle{%
+ \phantomsection
+ \org@vsptitle
+ }
+ \makeatother
+
+ \begin{document}
+
+ \poemtitle{Poem 1}
+ \begin{verse}
+ An one-liner.
+ \end{verse}
+
+ \newpage
+
+ \poemtitle{Poem 2}
+ \begin{verse}
+ Another one-liner.
+ \end{verse}
+
+ \end{document}
+\end{verbatim}
+
+\subsubsection{vietnam}
+\begin{verbatim}
+ % pd1enc.def should be loaded before package dblaccnt:
+ \usepackage[PD1,OT1]{fontenc}
+ \usepackage{vietnam}
+ \usepackage{hyperref}
+\end{verbatim}
+
+\subsubsection{XeTeX}
+
+ Default for the encoding of bookmarks is `pdfencoding=auto'.
+ That means the strings are always treated as unicode strings.
+ Only if the string restricts to the printable ASCII set,
+ it is written as ASCII string. The reason is that the
+ \verb|\special| does not support PDFDocEncoding.
+
+ In older versions hyperref contained special conversion code from
+ UTF-16BE back to UTF-8 in a number of places for
+ xetex to avoid the xdvipdfmx warning
+
+ \verb"Failed to convert input string to UTF16..."
+
+ This is no longer needed with a current xdvipdfmx, so this code has
+ been removed. \verb|\csname HyPsd@XeTeXBigCharstrue\endcsname| should no
+ longer be used.
+
+
+\section[Limitations]{Limitations%
+\footnote{This section moved from the README file, needs more integration into the manual}}
+\subsection{Wrapped/broken link support}
+
+ Only few drivers support automatically wrapped/broken links,
+ e.g. pdftex, dvipdfm, hypertex. Other drivers lack this
+ feature, e.g. dvips, dvipsone.
+
+ Workarounds:
+\begin{itemize}
+\item For long section or caption titles in the table of contents
+ or list of figures/tables option \xoption{linktocpage} can be used.
+ Then the page number will be a link, and the overlong section
+ title is not forced into an one line link with overfull \verb|\hbox|
+ warning.
+\item ``\verb|\url|''s are caught by package \xpackage{breakurl}.
+\item The option \xoption{breaklinks} is intended for internal use. But it
+ can be used to force link wrapping, e.g. when printing a
+ document. However, when such a document is converted to PDF
+ and viewed with a PDF viewer, the active link area will be
+ misplaced.
+
+ Another limitation: some penalties are ``optimized'' by TeX,
+ thus there are missing break points, especially within
+ \verb|\url|. (See thread ``hyperref.sty, breaklinks and url.sty 3.2''
+ in comp.text.tex 2005-09).
+\end{itemize}
+
+\subsection{Links across pages}
+
+ In general they have problems:
+\begin{itemize}
+ \item Some driver doesn't support them at all (see above).
+ \item The driver allows it, but the link result might include
+ the footer and/or header, or an error message can
+ occur sometimes.
+\end{itemize}
+
+\subsection{Footnotes}
+
+ LaTeX allows the separation of the footnote mark and the
+ footnote text (\verb|\footnotemark|, \verb|\footnotetext|). This interface
+ might be enough for visual typesetting. But the relation between
+ \verb|\footnotemark| to \verb|\footnotetext| is not as strong as \verb|\ref| to \verb|\label|.
+ Therefore it is not clear in general which \verb|\footnotemark| references
+ which \verb|\footnotetext|. But that is necessary to implement hyperlinking.
+ Thus the implementation of hyperref does not support the optional
+ argument of \verb|\footnotemark| and \verb|\footnotetext|.
+
+
+\section[Hints]{Hints%
+\footnote{This section moved from the README file, needs more integration into the manual}}
+
+\subsection{Spaces in option values}
+
+ Unhappily LaTeX strips spaces from options if they are given
+ in \verb|\documentclass| or \verb|\usepackage| (or \verb|\RequirePackage|), e.g.:
+\begin{verbatim}
+ \usepackage[pdfborder=0 0 1]{hyperref}
+\end{verbatim}
+ Package hyperref now gets
+\begin{verbatim}
+ pdfborder=001
+\end{verbatim}
+ and the result is an invalid PDF file.
+ As workaround braces can be used:
+\begin{verbatim}
+ \usepackage[pdfborder={0 0 1}]{hyperref}
+\end{verbatim}
+ Some options can also be given in \verb|\hypersetup|
+\begin{verbatim}
+ \hypersetup{pdfborder=0 0 1}
+\end{verbatim}
+ In \verb|\hypersetup| the options are directly processed as key value
+ options (see package keyval) without space stripping in the value part.
+
+
+
+ Alternatively, LaTeX's option handling system can be adapted
+ to key value options by one of the packages \xpackage{kvoptions-patch}
+ (from project \xpackage{kvoptions}) or \xpackage{xkvltxp} (from project \xpackage{xsetkeys}).
+
+
+\subsection{Index with makeindex}
+\begin{itemize}
+ \item Package hyperref adds \verb|\hyperpage| commands by the encap
+ mechanism (see documentation of Makeindex),
+ if option hyperindex is set (default).
+ \verb|\hyperpage| uses the page anchors that are set by
+ hyperref at each page (default). However in the
+ default case page numbers are used in anchor names
+ in arabic form. If the page numbers in other formats
+ are used (book class with \verb|\frontmatter|, \verb|\romannumbering|, ...),
+ then the page anchors are not unique. Therefore option
+ \verb"plainpages=false" is recommended.
+ \item The encap mechanism of Makeindex allows to use one command only
+ (see documentation of Makeindex).
+ If the user sets such a command, hyperref suppresses its
+ \verb|\hyperpage| command. With logical markup this situation
+ can easily be solved:
+\begin{verbatim}
+ \usepackage{makeidx}
+ \makeindex
+ \usepackage[hyperindex]{hyperref}
+ \newcommand*{\main}[1]{\textbf{\hyperpage{#1}}}
+ ...
+ \index{Some example|main}
+\end{verbatim}
+ \item Scientic Word/Scientific WorkPlace users can use
+ package robustindex with hyperindex=false.
+ \item Other encap characters can be set by option \xoption{encap}.
+ Example for use of ``?'':
+\begin{verbatim}
+ \usepackage[encap=?]{hyperref}
+\end{verbatim}
+ \item Another possibility is the insertion of \verb|\hyperpage| by
+ a style file for makeindex. For this case, hyperref's
+ insertion will be disabled by \verb"hyperindex=false".
+ \verb|\hyperpage| will be defined regardless of setting of hyperindex.
+\begin{verbatim}
+%%% cut %%% hyperindex.ist %%% cut %%%
+delim_0 ", \\hyperpage{"
+delim_1 ", \\hyperpage{"
+delim_2 ", \\hyperpage{"
+delim_n "}, \\hyperpage{"
+delim_t "}"
+encap_prefix "}\\"
+encap_infix "{\\hyperpage{"
+encap_suffix "}"
+%%% cut %%% hyperindex.ist %%% cut %%%
+\end{verbatim}
+\end{itemize}
+
+\subsection{Warning \texttt{"bookmark level for unknown <foobar> defaults to 0"}}
+
+ Getting rid of it:
+\begin{verbatim}
+\makeatletter
+\providecommand*{\toclevel@<foobar>}{0}
+\makeatother
+\end{verbatim}
+
+\subsection{Link anchors in figures}
+
+ The caption command increments the counter and here is the
+ place where hyperref set the corresponding anchor. Unhappily
+ the caption is set below the figure, so the figure is not
+ visible if a link jumps to a figure.
+ In this case, try package \xpackage{hypcap} that implements
+ a method to circumvent the problem.
+
+
+\subsection{Additional unicode characters in bookmarks and pdf information entries:}
+\begin{verbatim}
+\documentclass[pdftex]{article}
+\usepackage[unicode]{hyperref}
+\end{verbatim}
+
+Support for additional unicode characters:
+
+ Example: \verb|\.{a}| and \verb|\d{a}|
+
+ 1. Get a list with unicode data, eg:
+
+ http://www.unicode.org/Public/UNIDATA/UnicodeData.txt
+
+ 2. Identify the characters (\verb|\.{a}|, \verb|\d{a}|):
+\begin{verbatim}
+ 0227;LATIN SMALL LETTER A WITH DOT ABOVE;...
+ 1EA1;LATIN SMALL LETTER A WITH DOT BELOW;...
+\end{verbatim}
+
+ 3. Calculate the octal code:
+
+ The first characters of the line in the file are
+ hex values, convert each byte and prepend them
+ with a backslash. (This will go into the PDF file.)
+
+\begin{verbatim}
+ 0227 -> \002\047
+ 1EA1 -> \036\241
+\end{verbatim}
+
+ 4. Transform into a form understood by hyperref:
+
+ Hyperref must know where the first byte starts,
+ this is marked by \verb"9" (8 and 9 cannot occur in
+ octal numbers):
+
+\begin{verbatim}
+ \002\047 -> \9002\047
+ \036\241 -> \9036\241
+\end{verbatim}
+
+ Optional: \verb"8" is used for abbreviations:
+
+\begin{verbatim}
+ \900 = \80, \901 = \81, \902 = \82, ...
+
+ \9002\047 -> \82\047
+\end{verbatim}
+
+ 5. Declare the character with LaTeX:
+
+\begin{verbatim}
+\DeclareTextCompositeCommand{\.}{PU}{a}{\82\047}
+\DeclareTextCompositeCommand{\d}{PU}{a}{\9036\241}
+
+\begin{document}
+\section{\={a}, \d{a}, \'{a}, \.{a}}
+\end{document}
+ \end{verbatim}
+
+\subsection{Footnotes}
+
+ The footnote support is rather limited. It is beyond the scope
+ to use \verb|\footnotemark| and \verb|\footnotetext| out of order or reusing
+ \verb|\footnotemark|. Here you can either disable hyperref's footnote
+ support by \verb"hyperfootnotes=false" or fiddle with internal macros,
+ nasty examples:
+
+\begin{verbatim}
+\documentclass{article}
+\usepackage{hyperref}
+\begin{document}
+Hello%
+\footnote{The first footnote}
+World%
+\addtocounter{footnote}{-1}%
+\addtocounter{Hfootnote}{-1}%
+\footnotemark.
+\end{document}
+
+ or
+
+\documentclass{article}
+
+\usepackage{hyperref}
+
+\begin{document}
+
+\makeatletter
+
+A%
+ \footnotemark
+ \let\saved@Href@A\Hy@footnote@currentHref
+ % remember link name
+B%
+ \footnotemark
+ \let\saved@Href@B\Hy@footnote@currentHref
+b%
+ \addtocounter{footnote}{-1}%
+ \addtocounter{Hfootnote}{-1}% generate the same anchor
+ \footnotemark
+C%
+ \footnotemark
+ \let\saved@Href@C\Hy@footnote@currentHref
+
+ \addtocounter{footnote}{-2}%
+ \let\Hy@footnote@currentHref\saved@Href@A
+\footnotetext{AAAA}%
+ \addtocounter{footnote}{1}%
+ \let\Hy@footnote@currentHref\saved@Href@B
+\footnotetext{BBBBB}%
+ \addtocounter{footnote}{1}%
+ \let\Hy@footnote@currentHref\saved@Href@C
+\footnotetext{CCCC}%
+
+\end{document}
+\end{verbatim}
+
+\subsection{Subordinate counters}
+
+ Some counters do not have unique values and require the value
+ of other counters to be unique. For example, sections or figures
+ might be numbered within chapters or \verb|\newtheorem| is used with
+ an optional counter argument. Internally LaTeX uses \verb|\@addtoreset|
+ to reset a counter in dependency to another counter. Package
+ hyperref hooks into \verb|\@addtoreset| to catch this situation.
+ Also \verb|\numberwithin| of package amsmath is caught by hyperref.
+
+
+
+ However, if the definition of subordinate counters take place
+ before hyperref is loaded, the old meaning of \verb|\@addtoreset| is
+ called without hyperref's additions. Then the companion counter
+ macro \verb|\theH<counter>| can be redefined accordingly. Or move the
+ definition of subordinate counters after hyperref is loaded.
+
+ Example for \verb|\newtheorem|, problematic case:
+\begin{verbatim}
+ \newtheorem{corA}{CorollaryA}[section]
+ \usepackage{hyperref}
+\end{verbatim}
+ Solution a)
+\begin{verbatim}
+ \usepackage{hyperref}
+ \newtheorem{corA}{CorollaryA}[section}
+\end{verbatim}
+ Solution b)
+\begin{verbatim}
+ \newtheorem{corA}{CorollaryA}[section]
+ \usepackage{hyperref}
+ \newcommand*{\theHcorA}{\theHsection.\number\value{corA}}
+\end{verbatim}
+
+\section{History and acknowledgments}
+
+The original authors of \textsf{hyperbasics.tex} and
+\textsf{hypertex.sty}, from which this package descends, are Tanmoy
+Bhattacharya and Thorsten Ohl. Package \xpackage{hyperref}
+started as a simple port of their work to \hologo{LaTeXe} standards, but
+eventually I rewrote nearly everything, because I didn't understand a
+lot of the original, and was only interested in getting it to work with
+\hologo{LaTeX}. I would like to thank Arthur Smith, Tanmoy Bhattacharya, Mark
+Doyle, Paul Ginsparg, David Carlisle, T.\ V.\ Raman and Leslie Lamport
+for comments, requests, thoughts and code to get the package into its
+first useable state. Various other people are mentioned at the point in
+the source where I had to change the code in later versions because of
+problems they found.
+
+Tanmoy found a great many of the bugs, and (even better) often provided
+fixes, which has made the package more robust. The days spent on
+Rev\TeX\ are entirely due to him! The investigations of Bill Moss
+into the later versions including
+native PDF support uncovered a good many bugs, and his testing is
+appreciated. Hans Hagen provided a lot of
+insight into PDF.
+
+Berthold Horn provided help, encouragement and sponsorship for the
+\textsf{dvipsone} and \textsf{dviwindo} drivers. Sergey Lesenko provided
+the changes needed for \textsf{dvipdf}, and \Hanh{} supplied all the
+information needed for \textsf{pdftex}. Patrick Daly kindly updated his
+\xpackage{natbib} package to allow easy integration with
+\xpackage{hyperref}. Michael Mehlich's \xpackage{hyper} package (developed
+in parallel with \textsf{hyperref}) showed me solutions for some
+problems. Hopefully the two packages will combine one day.
+
+The forms creation section owes a great deal to: T.\ V.\ Raman, for
+encouragement, support and ideas; Thomas Merz, whose book \emph{Web
+Publishing with Acrobat/PDF} provided crucial insights; D.\ P.\ Story,
+whose detailed article about pdfmarks and forms solved many practical
+problems; and Hans Hagen, who explained how to do it in \textsf{pdftex}.
+
+Steve Peter recreated the manual source in July 2003 after it had been
+lost.
+
+Especial extra thanks to David Carlisle for the \xpackage{backref} module,
+the ps2pdf and dviwindo support, frequent general rewrites of my bad
+code, and for working on changes to the \xpackage{xr} package to suit
+\xpackage{hyperref}.
+
+\begingroup
+ \makeatletter
+ \let\chapter=\section
+ % subsections goes into bookmarks but not toc
+ \hypersetup{bookmarksopenlevel=1}
+ \addtocontents{toc}{\protect\setcounter{tocdepth}{1}}
+ % The \section command acts as \subsection.
+ % Additionally the title is converted to lowercase except
+ % for the first letter.
+ \def\section{%
+ \let\section\lc@subsection
+ \lc@subsection
+ }
+ \def\lc@subsection{%
+ \@ifstar{\def\mystar{*}\lc@sec}%
+ {\let\mystar\@empty\lc@sec}%
+ }
+ \def\lc@sec#1{%
+ \lc@@sec#1\@nil
+ }
+ \def\lc@@sec#1#2\@nil{%
+ \begingroup
+ \def\a{#1}%
+ \lowercase{%
+ \edef\x{\endgroup
+ \noexpand\subsection\mystar{\a#2}%
+ }%
+ }%
+ \x
+ }
+ \include{fdl}
+\endgroup
+
+\end{document}