summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/hyperref/doc/hyperref-doc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/hyperref/doc/hyperref-doc.tex')
-rw-r--r--Master/texmf-dist/source/latex/hyperref/doc/hyperref-doc.tex171
1 files changed, 167 insertions, 4 deletions
diff --git a/Master/texmf-dist/source/latex/hyperref/doc/hyperref-doc.tex b/Master/texmf-dist/source/latex/hyperref/doc/hyperref-doc.tex
index f4b06157c36..c2375a58e76 100644
--- a/Master/texmf-dist/source/latex/hyperref/doc/hyperref-doc.tex
+++ b/Master/texmf-dist/source/latex/hyperref/doc/hyperref-doc.tex
@@ -166,7 +166,7 @@
}
\makeatother
\title{Hypertext marks in \hologo{LaTeX}: a manual for \xpackage{hyperref}}
-\date{2021-06-07 v7.00m}
+\date{2022-02-21 v7.00n}
\begin{document}
@@ -176,6 +176,37 @@
\tableofcontents
\setcounter{tocdepth}{2}% for bookmark levels
+\section{Preface---February 2022}
+As can be already seen in the following introduction, \xpackage{hyperref}
+has a long history and has seen many changes over time. The introduction
+mentions workflows, drivers and problems which are no longer relevant,
+or only in edge cases. The documentation reflect this varied history: changes
+and extensions and explanations were and are spread over various papers and sources and
+only incorporated later and so are not always in a coherent order and in sync which each other.
+
+
+This history is continuing: If you are using the new \hologo{LaTeX} PDF management
+which is currently distributed as testphase package \xpackage{pdfmanagement-testphase}
+then \xpackage{hyperref} will for the PDF output use a new generic driver which
+contains a number of changes and new features. The documentation of this driver
+\texttt{hyperref-generic.pdf}
+is currently a part of the \xpackage{pdfmanagement-testphase} documentation.
+One important change of the new driver is
+that it removed the old \xpackage{hyperref} code for book marks and uses
+the \xpackage{bookmark} package instead. So to learn
+about options to extend the bookmarks you should consult the \xpackage{bookmark} documentation
+too.
+
+\subsection{Restoring removed patches}
+
+\xpackage{hyperref} has over time patched quite a number of packages to resolve clashes and incompabilities.
+Quite a number are either no longer needed or should be done by by the original packages.
+These patches are now slowly removed from \xpackage{hyperref}. It should normally not lead to problems, but
+in case that the patches should be restored they can be loaded through the package \xpackage{hyperref-patches} which
+is a part of this bundle.
+
+
+
\section{Introduction}
The package derives from, and builds on, the work of the Hyper\hologo{TeX}
@@ -299,7 +330,9 @@ by specifying in the document preamble
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
+many \LaTeX\ commands.\footnote{But work has started to reduce the
+number of redefinition and so the dependencies on the loading order.}
+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}
@@ -313,6 +346,72 @@ 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{Interfaces for class and package authors}
+
+hyperlink features are nowadays a common requirement. \xpackage{hyperref}
+patches quite a number of commands from the \LaTeX{} core and from packages
+to add such features. But this is rather fragile and it add dependencies
+on the loading order and can break if the external packages break.
+It is therefore much better if packages add suitable support to their commands directly.
+Quite a lot packages actually did this, but due to missing documentation of the interface
+they often looked into the code and then used internal commands not meant as public command.
+
+The following tries to describe the existing variables and commands that
+can be viewed as public interfaces or which should or can be set by packages
+to stay compatible with the \xpackage{hyperref} command. Documented user commands
+are naturally interfaces too, they are not explicitly mentioned here again.
+
+This section is work in progress. Suggestions or comments are welcome.
+
+\subsection{Counters}
+Counters play an important part in the code. They are used to create destination names and
+to define hierarchies like the bookmarks. To work correctly often they require some additional
+setups.
+
+\begin{description}
+
+\item[\cs{theH<counter>}] \xpackage{hyperref} creates destination names for
+link anchor typically out of the name of the counter and the \cs{the<counter>} value.
+This can fail, e.g. if \cs{the<counter>} is not unique through the document,
+or if it is not expandable. In such cases \cs{theH<counter>} should be defined so that
+it gives a unique, expandable value. It doesn't harm to define it even if
+\xpackage{hyperref} is not loaded.
+
+\item[\cs{toclevel@<counter>}] This is a variable which should contain a number.
+It is used for the level in the bookmarks. It should be defined for all counters
+which are used in toc like lists and \cs{addcontentsline}. Typical values are
+
+\begin{verbatim}
+\def\toclevel@part{-1}
+\def\toclevel@chapter{0}
+\def\toclevel@section{1}
+\def\toclevel@subsection{2}
+\def\toclevel@subsubsection{3}
+\def\toclevel@paragraph{4}
+\def\toclevel@subparagraph{5}
+\def\toclevel@figure{0}
+\end{verbatim}
+
+\end{description}
+
+\subsection{Links commands}
+The following commands are provided by all drivers to create links.
+They can be used by packages if the user commands are not sufficient.
+New drivers must provide this commands with similar arguments.
+
+\begin{verbatim}
+ \hyper@anchor {destination name}
+ \hyper@anchorstart {destination name}
+ \hyper@anchorend
+ \hyper@link {context}{destination name}{link text} %GoTo
+ \hyper@linkstart {context} {destination name} %GoTo
+ \hyper@linkend %GoTo
+ \hyper@linkfile {link text} {filename} {destname} %GoToR
+ \hyper@linkurl {link text}{url} %URI
+ \hyper@linklaunch{filename} {link text} {Parameters} %Launch, only with new generic driver
+ \hyper@linknamed {action}{link text} %Named, only with new generic driver
+\end{verbatim}
+
\section{Package options}
@@ -326,7 +425,34 @@ site-wide basis.
Note however that some options (for example \texttt{unicode}) can only be used as
package options, and not in \verb|\hypersetup| as the option settings are processed
-as the package is read.
+as the package is read. The following tabular lists (hopefully all) these options.
+Be aware that some of the option do nothing or have
+changed behaviour if the new pdfmanagement and so the new generic hyperref driver is used.
+
+\begin{tabular}{>{\ttfamily}l>{\raggedright\arraybackslash}p{5cm}}
+option & remark \\\hline
+all driver options, e.g. \texttt{pdftex} & often not needed, as detected automatically\\
+implicit \\
+pdfa & no-op with new pdfmanagement, set the standard in \cs{DeclareDocumentMetadata}.\\
+unicode & is the default now anyway\\
+pdfversion & no-op with new pdfmanagement, set the version in \cs{DeclareDocumentMetadata}.\\
+bookmarks & this will probably change at some time. \\
+backref &\\
+pagebackref & \\
+destlabel &\\
+pdfusetitle &\\
+pdfpagelabels &\\
+hyperfootnotes &\\
+hyperfigures&\\
+hyperindex &\\
+encap &\\
+typexml & \\
+CJKbookmarks & only with the new pdfmanagement, in other cases it can be used in \cs{hypersetup}\\
+psdextra & only with the new pdfmanagement, in other cases it can be used in \cs{hypersetup}\\
+nesting & only with the new pdfmanagement, in other cases it can be used in \cs{hypersetup} (but
+ is quite unclear if it has any use)\\
+
+\end{tabular}
As an example, the behavior of a particular file could be controlled by:
\begin{itemize}
@@ -939,6 +1065,7 @@ 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 \\
+next-anchor & & allow to set the name of the next anchor\\
pageanchor & \textit{true} & put an anchor on every page \\
pagebackref & \textit{false} & backreference by page number \\
pdfauthor & \textit{empty} & text for PDF Author field \\
@@ -1131,6 +1258,30 @@ index points to the start of the index page, not to a location
before this page.
\begin{cmdsyntax}
+\ci{hyperget}\verb|{|\emph{anchor}\verb|}{|\emph{label}\verb|}|
+\ci{hyperget}\verb|{|\emph{pageanchor}\verb|}{|\emph{label}\verb|}|
+\end{cmdsyntax}
+
+This retrieves the anchor or the page anchor from a label in an expandable way.
+It takes \verb|\HyperDestNameFilter| into account. It can e.g. be used with the
+\verb|\bookmark| from the bookmark package to set a destination to a label:
+
+\begin{verbatim}
+\bookmark[dest=\hyperget{anchor}{sec}]{section}
+\end{verbatim}
+
+As \emph{pageanchor} retrieves the page number from the label it can't be use together with
+the option \texttt{plainpages}.
+
+\begin{cmdsyntax}
+\ci{hyperget}\verb|{|\emph{currentanchor}\verb|}{}|
+\end{cmdsyntax}
+
+This retrieves the last anchor that has been set. It too takes \verb|\HyperDestNameFilter| into account.
+
+
+
+\begin{cmdsyntax}
\ci{autoref}\verb|{|\emph{label}\verb|}|
\end{cmdsyntax}
@@ -1330,7 +1481,7 @@ command the current bookmark level has not changed.
\end{itemize}
Therefore I recommend using this package.
-\subsubsection{Replacement macros}
+\subsubsection{Replacement macros}\label{sec:texorpdfstring}
\textsf{hyperref} takes the text for bookmarks from the arguments of
commands like \ci{section}, which can contain things like math, colors,
@@ -1474,6 +1625,16 @@ sequence error would arise.
Currently the field option `calculatesortkey' is only supported by
the driver for pdfTeX.
+\subsection{Option `next-anchor'}
+This option allows to overwrite the anchor name of the next anchor.
+This makes it possible to give for example the heading of the table of contents
+an anchor name which can be referenced with a bookmark command.
+
+\begin{verbatim}
+\hypersetup{next-anchor=toc}
+\tableofcontents
+\bookmark[dest=\HyperDestNameFilter{toc},level=section]{\contentsname}
+\end{verbatim}
\subsection{Option `localanchorname'}
@@ -2376,6 +2537,8 @@ altname & name & & alternative name,\\*
backgroundcolor & & & color of box \\
bordercolor & & & color of border \\
bordersep & & & box border gap \\
+borderstyle & char & S & box border style; S (Solid) is default, B is Beveled,\\
+ & & & D is Dashed, I is Inset and U is Underline \\
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 \\