summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/hyperref/doc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-09-30 21:23:18 +0000
committerKarl Berry <karl@freefriends.org>2018-09-30 21:23:18 +0000
commit0e00fb64c271b0107e65fdf601df25e39f61b57f (patch)
treed8770513326a4cb339513523d8b7e315c68ed37e /Master/texmf-dist/source/latex/hyperref/doc
parent11e3c92a57cc2bb390d65b5856bc5c1beb47a4ec (diff)
hyperref (30sep18)
git-svn-id: svn://tug.org/texlive/trunk@48792 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/hyperref/doc')
-rw-r--r--Master/texmf-dist/source/latex/hyperref/doc/fdl.tex2
-rw-r--r--Master/texmf-dist/source/latex/hyperref/doc/manual.tex1689
2 files changed, 1669 insertions, 22 deletions
diff --git a/Master/texmf-dist/source/latex/hyperref/doc/fdl.tex b/Master/texmf-dist/source/latex/hyperref/doc/fdl.tex
index 637c1cb63c9..57f9b316217 100644
--- a/Master/texmf-dist/source/latex/hyperref/doc/fdl.tex
+++ b/Master/texmf-dist/source/latex/hyperref/doc/fdl.tex
@@ -3,7 +3,7 @@
\chapter{GNU Free Documentation License}
-Version 1.2, November 2002\\
+Version 1.2, November 2002
Copyright \copyright\ 2000,2001,2002 Free Software Foundation, Inc.\\
diff --git a/Master/texmf-dist/source/latex/hyperref/doc/manual.tex b/Master/texmf-dist/source/latex/hyperref/doc/manual.tex
index baf7149c67a..442fe8b0713 100644
--- a/Master/texmf-dist/source/latex/hyperref/doc/manual.tex
+++ b/Master/texmf-dist/source/latex/hyperref/doc/manual.tex
@@ -12,10 +12,10 @@
% Manual updates:
% * Steve Peter and Karl Berry, 7/03.
% * Heiko Oberdiek, 2006-2012.
-% * HO-support 2017
+% * HO-support 2017-2018
%
-\def\mydate{January 2017}
+\def\mydate{September 2018}
\RequirePackage{ifpdf}
\ifpdf % We are running pdfTeX in pdf mode
@@ -28,7 +28,6 @@
\documentclass{article}
\fi
-\usepackage{etex}% for \eTeX
\usepackage{pifont}
\usepackage{calc}
@@ -162,7 +161,6 @@
pdfusetitle,%
]{hyperref}
%%?? \def\pdfBorderAttrs{/Border [0 0 0] } % No border arround Links
- \usepackage{thumbpdf}
\else
\usepackage{hyperref}
\fi
@@ -254,6 +252,7 @@ the \textsf{-z} option), \textsf{\OzTeX}, and \textsf{Textures})
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}
@@ -330,6 +329,10 @@ 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}
@@ -582,7 +585,7 @@ define \cs{Hy@defaultdriver} with \texttt{hdvips}. This is recommended
because driver \textsf{dvips} provides much more features than
\textsf{hypertex} for PDF generation.
-\noindent\begin{longtable}{>{\ttfamily}lp{.8\hsize}}
+\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.\\
@@ -619,7 +622,7 @@ Explorer might add something like this to hyperref.cfg:
\end{verbatim}
\subsection{Extension options}
-\noindent\begin{longtable}{>{\ttfamily}ll>{\itshape}lp{6cm}}
+\begin{longtable}{@{}>{\ttfamily}ll>{\itshape}lp{5.5cm}@{}}
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 & & \\
@@ -660,7 +663,7 @@ 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}
-\noindent\begin{longtable}{@{}>{\ttfamily}ll>{\itshape}lp{7.5cm}@{}}
+\begin{longtable}{@{}>{\ttfamily}ll>{\itshape}lp{7.5cm}@{}}
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
@@ -713,14 +716,13 @@ 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 \\
-
+next \TeX\ run if it is edited to contain the line
\begin{verbatim}
\let\WriteBookmarks\relax
\end{verbatim}
\subsection{PDF display and information options}
-\noindent\begin{longtable}{@{}>{\ttfamily}l>{\raggedright}p{\widthof{key value}}>{\itshape}lp{7cm}@{}}
+\begin{longtable}{@{}>{\ttfamily}l>{\raggedright}p{\widthof{key value}}>{\itshape}lp{7cm}@{}}
baseurl & URL & & Sets the base URL of the PDF document \\
pdfpagemode & text & empty & Determines how the file is opening in Acrobat; the possibilities are
\texttt{UseNone}, \texttt{UseThumbs} (show thumbnails), \texttt{UseOutlines}
@@ -731,7 +733,7 @@ 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 \\
-pdfproducer & text & & Sets the document information Producer field \\
+addtopdfproducer & text & & Adds additional text to the document information Producer field \\
pdfkeywords & text & & Sets the document information Keywords field \\
pdftrapped & text & empty & Sets the document information Trapped entry.\\
&&& Possible values are \texttt{True}, \texttt{False} and \texttt{Unknown}.\\
@@ -789,7 +791,7 @@ 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.
-\noindent\begin{longtable}{>{\ttfamily}l>{\itshape}lp{7cm}}
+\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. \\
@@ -803,7 +805,7 @@ FitBV & left & Fits the height of the page bounding box to the
The \texttt{pdfpagelayout} can be one of the following values.
-\noindent\begin{longtable}{>{\ttfamily}lp{10cm}}
+\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. \\
@@ -819,7 +821,7 @@ generally in 90$^{\circ}$\ steps, \textit{/Dm} is a horizontal
/Dm /V}), and \textit{/M} is for motion, either in (\texttt{/I}) or out
(\texttt{/O}).
-\noindent\begin{longtable}{>{\ttfamily}llp{8.5cm}}
+\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. \\
@@ -858,7 +860,7 @@ Example:
The following is a complete listing of available options for
\textsf{hyperref}, arranged alphabetically.
-\noindent\begin{longtable}{@{}>{\ttfamily}llp{7cm}@{}}
+\begin{longtable}{@{}>{\ttfamily}llp{7cm}@{}}
anchorcolor & \textit{black} & set color of anchors \\
backref & \textit{false} & do bibliographical back references \\
baseurl & \textit{empty} & set base URL for document \\
@@ -911,7 +913,6 @@ pdfborder & \textit{0 0 1} & width of PDF link border \\
pdfcenterwindow & \textit{false} & position the document window in the center of the screen \\
pdfcreator & \textit{LaTeX with} & text for PDF Creator field \\
& \textit{hyperref} & \\
- & \textit{package} & \\
pdfdirection & \textit{empty} & direction setting \\
pdfdisplaydoctitle & \textit{false} & display document title instead
of file name in title bar\\
@@ -1115,7 +1116,7 @@ For each macro below, \textsf{hyperref} checks \ci{*autorefname} before
\ci{*name}. For instance, it looks for \ci{figureautorefname} before
\ci{figurename}.
-\noindent\begin{longtable}{lp{10cm}}
+\begin{longtable}{@{}lp{10cm}@{}}
\textit{Macro} & \textit{Default} \\
\ci{figurename} & Figure \\
\ci{tablename} & Table \\
@@ -1242,6 +1243,15 @@ 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}
@@ -1363,6 +1373,777 @@ of \cs{documentclass} and \cs{usepackage}, because
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[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 defintion 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.
+\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. Users of dvipdfmx set the version on the command
+ line: dvipdfmx -V 5
+\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 --> /NewWindow true
+ \item pdfnewwindow=false --> (absent)
+ \item unused pdfnewwindow --> (absent)
+\end{itemize}
+ Since 6.77b:
+\begin{itemize}
+ \item pdfnewwindow=true --> /NewWindow true
+ \item pdfnewwindow=false --> /NewWindow false
+ \item pdfnewwindow={} --> (absent)
+ \item unused pdfnewwindow --> (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 >= 1.10a and < 1.30: \verb|\pdfoptionpdfminorversion|
+ pdfTeX >= 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 >= 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 "pdfencoding" selects between these encodings:
+\begin{itemize}
+ \item "pdfdoc" uses PDFDocEncoding. It uses just one byte per character,
+ but the supported characters are limited (244 in PDF-1.7).
+ \item "unicode" sets Unicode. It is encoded as UTF-16BE. Two bytes
+ are used for most characters, surrogates need four bytes.
+ \item "auto" PDFDocEncoding if the string does not contain characters
+ outside the encoding and Unicode otherwise.
+\end{itemize}
+
+\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 "colorlinks", "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 "1" for the width, but zero, thus that the underline
+ is not visible without "/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: "underline" and "dashed", but the border width
+ must be given.
+ \item xpdf 3.00: "underline" and "dashed"
+ \end{itemize}
+
+ Unsupported:
+ \begin{itemize}
+ \item AR5/Linux
+ \item ghostscript 8.50
+ \end{itemize}
+\end{itemize}
+
+\subsection{Option "bookmarksdepth"}
+
+ The depth of the bookmarks can be controlled by the new
+ option "bookmarksdepth". The option acts globally and
+ distinguishes three cases:
+\begin{itemize}
+ \item "bookmarksdepth" without value
+ Then hyperref uses the current value of counter "tocdepth".
+ This is the compatible behaviour and the default.
+ \item "bookmarksdepth=<number>", the value is number (also negative):
+ The depth for the bookmarks are set to this number.
+ \item "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 "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 >= 6.72s)
+ If no driver is given, hyperref tries its best to guess the
+ most suitable driver. Thus it loads "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 "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 "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:
@@ -1374,7 +2155,7 @@ macro is provided in the appropriate drivers:
\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
-\noindent\begin{longtable}{lp{9cm}}
+\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 \\
@@ -1488,7 +2269,8 @@ You may also want to redefine the following macros:
\subsection{Forms environment parameters}
-\smallskip\noindent\begin{longtable}{>{\ttfamily}l>{\itshape}lp{9cm}}
+\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 \\
@@ -1499,7 +2281,8 @@ method & name & Used only when generating HTML; values can be \texttt{post} or
Note that all colors must be expressed as RGB triples, in the range 0..1 (i.e.\ \texttt{color=0 0
0.5})
-\smallskip\noindent\begin{longtable}{>{\ttfamily}ll>{\itshape}ll}
+\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. \\
@@ -1581,7 +2364,7 @@ A hyperref driver has to provide definitions for eight macros:
\smallskip
The draft option defines the macros as follows
-\qquad\begin{verbatim}
+\begin{verbatim}
\let\hyper@@anchor\@gobble
\gdef\hyper@link##1##2##3{##3}%
\def\hyper@linkurl##1##2{##1}%
@@ -1620,6 +2403,870 @@ 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 "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 "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 "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 >= V1.6b (because of \verb|\@makecaption|, see ChangeLog)
+
+
+\subsubsection{index}
+
+ version >= 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}
+
+ "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 "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.
+
+
+
+ XeTeX uses the program xdvipdfmx for PDF output generation.
+ This program behaves a little different from dvipdfm, because
+ of the supported Unicode characters. Strings for bookmarks
+ or information entries can be output directly. The
+ big chars (char code > 255) are written in UTF-8 and
+ xdvipdfmx tries to convert them to UTF-16BE. However
+ hyperref already provides PDF strings encoded in UTF-16BE,
+ thus the result is a warning
+
+ "Failed to convert input string to UTF16..."
+
+ The best way would be, if xdvipdfm could detect the
+ byte order marker (\verb|\376\377|) and skips the conversion
+ if that marker is present.
+
+ For the time being I added the following to hyperref,
+ when option `pdfencoding=auto' is set (default for XeTeX):
+ The string is converted back to big characters thus that the
+ string is written as UTF-8. But I am very unhappy with this
+ solution. Main disadvantage:
+ Two versions of \verb|\pdfstringdef| are needed:
+
+ a) The string is converted back to big characters for
+ the "tainted keys" of xdvipdfmx (\verb|spc_pdfm.c: default_taintkeys|).
+ The subset hyperref uses is /Title, /Author, /Subject,
+ /Keywords, /Creator, /Producer, /T. Any changes of this
+ set in xdvipdfmx cannot be detected by hyperref.
+
+ b) Without conversion for the other strings , providing UTF16be
+ directly. Examples: Prefix of page labels, some elements
+ of formulars.
+
+ Thus \textbf{each} application that uses \verb|\pdfstringdef| now must
+ check, if it defines a string for some of the tained keys.
+ If yes, then the call of \verb|\pdfstringdef| should be preceded
+ by "\verb|\csname HyPsd@XeTeXBigCharstrue\endcsname|".
+ Example: package bookmark.
+
+
+\section[Limitiations]{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 "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 "breakurl".
+\item The option "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\verb| 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 \begin{verbatim}\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 "kvoptions-patch"
+ (from project "kvoptions") or "xkvltxp" (from project "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
+ "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 "encap".
+ Example for use of "?":
+\begin{verbatim}
+ \usepackage[encap=?]{hyperref}
+\end{verbatim}
+ \item An other possibility is the insertion of \verb|\hyperpage| by
+ a style file for makeindex. For this case, hyperref's
+ insertion will be disabled by "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 "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 "hypcap.sty" 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 "9" (8 and 9 cannot occur in
+ octal numbers):
+
+\begin{verbatim}
+ \002\047 -> \9002\047
+ \036\241 -> \9036\241
+\end{verbatim}
+
+ Optional: "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 "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