summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/hyperref/doc/manual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/hyperref/doc/manual.tex')
-rw-r--r--Master/texmf-dist/source/latex/hyperref/doc/manual.tex283
1 files changed, 225 insertions, 58 deletions
diff --git a/Master/texmf-dist/source/latex/hyperref/doc/manual.tex b/Master/texmf-dist/source/latex/hyperref/doc/manual.tex
index 9e756a17060..bea7ed948c6 100644
--- a/Master/texmf-dist/source/latex/hyperref/doc/manual.tex
+++ b/Master/texmf-dist/source/latex/hyperref/doc/manual.tex
@@ -14,7 +14,7 @@
% * Heiko Oberdiek, 2006-2012.
%
-\def\mydate{April 2012}
+\def\mydate{July 2012}
\RequirePackage{ifpdf}
\ifpdf % We are running pdfTeX in pdf mode
@@ -28,11 +28,33 @@
\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}}
+
+% from doc.sty
+\makeatletter
+\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
@@ -141,7 +163,7 @@
}
\makeatother
-\title{Hypertext marks in \LaTeX: a manual for \textsf{hyperref}}
+\title{Hypertext marks in \hologo{LaTeX}: a manual for \xpackage{hyperref}}
\author{Sebastian Rahtz \and Heiko Oberdiek}
\date{\mydate}
@@ -155,24 +177,24 @@
\section{Introduction}
-The package derives from, and builds on, the work of the Hyper\TeX\
+The package derives from, and builds on, the work of the Hyper\hologo{TeX}
project, described at \url{http://xxx.lanl.gov/hypertex/}. It extends
-the functionality of all the \LaTeX\ cross-referencing commands
+the functionality of all the \hologo{LaTeX} cross-referencing commands
(including the table of contents, bibliographies etc) to produce
-\verb|\special| commands which a driver can turn into hypertext links;
+\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.
-This manual provides a brief overview of the \textsf{hyperref}
+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
-\textsf{hyperref} in \textit{The \LaTeX\ Web Companion}, where you will
+\xpackage{hyperref} in \textit{The \hologo{LaTeX} Web Companion}, where you will
find additional examples.
-The Hyper\TeX\ specification\footnote{This is borrowed from an article
+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 \verb|\special| constructs:
+recognize the following set of \cs{special} constructs:
\begin{description}
\item[href:] \verb|html:<a href = "href_string">|
@@ -254,7 +276,8 @@ such as \textsf{xdvi}.
\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 hyperref
+ 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.
@@ -288,10 +311,10 @@ option used in this document.
\section{Package options}
-All user-configurable aspects of \textsf{hyperref} are set using a
-single `key=value' scheme (using the \textsf{keyval} package) with the
+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 \verb|\usepackage| command, or using the \verb|\hypersetup|
+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.
@@ -315,7 +338,7 @@ colorlinks=true}
\documentclass[dvips]{article}
\end{verbatim}
-\item File-specific options in the \verb|\usepackage| commands, which
+\item File-specific options in the \cs{usepackage} commands, which
override the ones set in \texttt{hyperref.cfg}:
\begin{verbatim}
@@ -359,9 +382,155 @@ 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
+\noindent\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 \\
-setpagesize & boolean & true & sets page size by special driver commands
+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}
@@ -376,8 +545,6 @@ breaklinks & boolean & false & Allows link text to break across lines; since thi
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. \\
-plainpages & boolean & false & Forces page anchors to be named by the Arabic form of the page number, rather than the
- formatted form. \\
nesting & boolean & false & Allows links to be nested; no drivers currently support this.
\end{longtable}
@@ -443,7 +610,7 @@ Explorer might add something like this to hyperref.cfg:
\subsection{Extension options}
\noindent\begin{longtable}{>{\ttfamily}ll>{\itshape}lp{6cm}}
extension & text & & Set the file extension (e.g.\ \textsf{dvi}) which will be appended to file links
- created if you use the \textsf{xr} package. \\
+ 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
@@ -478,7 +645,7 @@ 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\ \textsf{color} package.
+normal system of the standard \LaTeX\ \xpackage{color} package.
\subsection{PDF-specific display options}
\noindent\begin{longtable}{@{}>{\ttfamily}ll>{\itshape}lp{7.5cm}@{}}
@@ -496,7 +663,7 @@ 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 CJK package;
+ 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
@@ -526,9 +693,9 @@ pdfborder & & 0 0 1 & The style of box around links; defaul
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 \textsf{xcolor} the usual
-color specifications of package \textsf{(x)color} can be used.
-For further information see description of package \textsf{hycolor}.
+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
@@ -695,6 +862,7 @@ 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 \\
dvipdfm & & use \textsf{dvipdfm} backend \\
dvipdfmx & & use \textsf{dvipdfmx} backend \\
@@ -963,11 +1131,11 @@ Example for a redefinition if \textsf{babel} is used:
\end{verbatim}
\end{quote}
-Hint: \verb|\autoref| works via the counter name that the reference
-is based on. Sometimes \verb|\autoref| chooses the wrong name, if
+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 \verb|\newtheorem| if a lemma shares a counter with theorems.
-Then package \textsf{aliascnt} provides a method to generate a
+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}
@@ -1054,7 +1222,7 @@ definitions and redefinitions are made in a group to keep them local:
\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 \textsf{xspace} package
+\item Support for \verb|\xspace| provided by the \xpackage{xspace} package
\end{itemize}
In addition, parentheses are protected to avoid the danger of unsafe
@@ -1170,16 +1338,16 @@ Example:
\end{quote}
The origin of the PDF coordinate system is the lower left corner.
-Note, for calculations you need either package |calc| or
-\eTeX. Nowadays the latter should automatically be enabled
-for \LaTeX\ formats. Users without \eTeX, please, look
+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 \verb|\hypercalcbp| cannot be used in option specifications
-of \verb|\documentclass| and \verb|\usepackage|, because
-\LaTeX\ expands the option lists of these commands. However
-package \verb|hyperref| is not yet loaded and an undefined control
+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{Acrobat-specific behavior}
@@ -1333,7 +1501,7 @@ calculate & & & JavaScript code to calculate the value of th
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 `pifont' from bundle `psnfss' \\
+&&& 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 \\
@@ -1368,7 +1536,7 @@ 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 `pifont' from bundle `psnfss' \\
+&&& 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)\\
@@ -1413,42 +1581,41 @@ The draft option defines the macros as follows
\section{Special support for other packages}
-\textsf{hyperref} aims to cooperate with other packages, but there are
+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 \textsf{harvard} package is supported. However, the
-recommended package is Patrick Daly's \textsf{natbib} package that has
-specific \textsf{hyperref} hooks to allow reliable interaction. This
+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 \textsf{hyperref}.
+of which work with \xpackage{hyperref}.
\item Packages that typeset the contents of the \ci{label} and \ci{ref}
-macros, such as \textsf{showkeys}. Since the \textsf{hyperref} package
+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 \textsf{hyperref} package is distributed with variants on two useful
-packages designed to work especially well with it. These are \textsf{xr}
-and \textsf{minitoc}, which support crossdocument links using \LaTeX's
-normal \verb|\label/\ref| mechanisms and per-chapter tables of contents,
+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.
\section{History and acknowledgments}
The original authors of \textsf{hyperbasics.tex} and
\textsf{hypertex.sty}, from which this package descends, are Tanmoy
-Bhattacharya (\texttt{tanmoy@qcd.lanl.gov}) and Thorsten Ohl
-\linebreak(\texttt{thorsten.ohl@physik.th-darmstadt.de}). \textsf{hyperref}
-started as a simple port of their work to \LaTeXe\ standards, but
+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
-\LaTeX. I would like to thank Arthur Smith, Tanmoy Bhattacharya, Mark
+\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
@@ -1458,17 +1625,17 @@ 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
-(\texttt{bmoss@math.clemson.edu}) into the later versions including
+into the later versions including
native PDF support uncovered a good many bugs, and his testing is
-appreciated. Hans Hagen (\texttt{pragma@pi.net}) provided a lot of
+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
-\textsf{natbib} package to allow easy integration with
-\textsf{hyperref}. Michael Mehlich's \textsf{hyper} package (developed
+\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.
@@ -1481,10 +1648,10 @@ 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 \textsf{backref} module,
+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 \textsf{xr} package to suit
-\textsf{hyperref}.
+code, and for working on changes to the \xpackage{xr} package to suit
+\xpackage{hyperref}.
\begingroup
\makeatletter