diff options
author | Karl Berry <karl@freefriends.org> | 2022-02-22 21:08:35 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2022-02-22 21:08:35 +0000 |
commit | b6f3ec13279685cdf24a94cec5ad200127a2c595 (patch) | |
tree | 2a269d1887c95ee8cdbb7e2aad37e15065219e57 /Master/texmf-dist/source/latex/hyperref/doc | |
parent | 9d5158d37d74f6401908f8be395bc955664b3f39 (diff) |
hyperref (22feb22)
git-svn-id: svn://tug.org/texlive/trunk@62142 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/hyperref-doc.tex | 171 |
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 \\ |