From d3589ab6f2fce7147d841db1dac3287e93f11565 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sat, 14 May 2022 20:32:17 +0000 Subject: hyperref (14may22) git-svn-id: svn://tug.org/texlive/trunk@63298 c570f23f-e606-0410-a88d-b1316a301751 --- .../texmf-dist/source/latex/hyperref/backref.dtx | 2 +- .../source/latex/hyperref/doc/hyperref-doc.tex | 3987 -------------------- .../texmf-dist/source/latex/hyperref/hluatex.dtx | 4 +- .../source/latex/hyperref/hyperref-linktarget.dtx | 584 +++ .../source/latex/hyperref/hyperref-patches.dtx | 2 +- .../texmf-dist/source/latex/hyperref/hyperref.dtx | 534 ++- .../texmf-dist/source/latex/hyperref/hyperref.ins | 35 +- .../texmf-dist/source/latex/hyperref/nameref.dtx | 635 ++-- 8 files changed, 1168 insertions(+), 4615 deletions(-) delete mode 100644 Master/texmf-dist/source/latex/hyperref/doc/hyperref-doc.tex create mode 100644 Master/texmf-dist/source/latex/hyperref/hyperref-linktarget.dtx (limited to 'Master/texmf-dist/source/latex') diff --git a/Master/texmf-dist/source/latex/hyperref/backref.dtx b/Master/texmf-dist/source/latex/hyperref/backref.dtx index 3fe08479a5e..f6dda3d569d 100644 --- a/Master/texmf-dist/source/latex/hyperref/backref.dtx +++ b/Master/texmf-dist/source/latex/hyperref/backref.dtx @@ -3,7 +3,7 @@ %% Copyright (C) 1995-2000 David Carlisle, Sebastian Rahtz, Heiko Oberdiek %% 2001-2012 Heiko Oberdiek %% 2016-2019 Oberdiek Package Suport Group -%% 2019-2021 The LaTeX Project +%% 2019-2022 The LaTeX Project %% https://github.com/latex3/hyperref/issues %% %% This file is part of the `Hyperref Bundle'. diff --git a/Master/texmf-dist/source/latex/hyperref/doc/hyperref-doc.tex b/Master/texmf-dist/source/latex/hyperref/doc/hyperref-doc.tex deleted file mode 100644 index c2375a58e76..00000000000 --- a/Master/texmf-dist/source/latex/hyperref/doc/hyperref-doc.tex +++ /dev/null @@ -1,3987 +0,0 @@ -% This is the manual for the LaTeX hyperref package. -% -% Copyright (C) 1998-2003 Sebastian Rahtz. -% Copyright (C) 2003 Steve Peter and Karl Berry -% Copyright (C) 2006-2012 Heiko Oberdiek. -% Copyright (C) 2017-2019 David Carlisle Ulrike Fischer -% Copyright (C) 2019-2020 The LaTeX3 Project -% -% Permission is granted to copy, distribute and/or modify this document -% under the terms of the GNU Free Documentation License, Version 1.1 or -% any later version published by the Free Software Foundation; with no -% Invariant Sections, with no Front-Cover Texts, and with no Back-Cover -% Texts. A copy of the license is included in the section entitled -% ``GNU Free Documentation License.'' -% - -\def\mydate{January 2020} - -\RequirePackage{iftex} - -\documentclass{article} - - -\usepackage{pifont} -\usepackage{calc} - -\usepackage{hologo} - -\newcommand*{\cs}[1]{% - \texttt{\textbackslash #1}% -} -\newcommand*{\xpackage}[1]{\textsf{#1}} -\newcommand*{\xoption}[1]{\textsf{#1}} - -% from doc.sty -\makeatletter -\ifx\l@nohyphenation\@undefined -\newlanguage\l@nohyphenation -\fi -\ifx\l@nohyphenation\@undefined - \newlanguage\l@nohyphenation -\fi -\DeclareRobustCommand\meta[1]{% - \ensuremath\langle - \ifmmode \expandafter \nfss@text \fi - {% - \meta@font@select - \edef\meta@hyphen@restore - {\hyphenchar\the\font\the\hyphenchar\font}% - \hyphenchar\font\m@ne - \language\l@nohyphenation - #1\/% - \meta@hyphen@restore - }% - \ensuremath\rangle -} -\def\meta@font@select{\ttfamily\itshape} -\makeatother - -% Page layout. -\advance\textwidth by 1.1in -\advance\oddsidemargin by -.55in -\advance\evensidemargin by -.55in -% -\advance\textheight by 1in -\advance\topmargin by -.5in -\advance\footskip by -.5in -% -\pagestyle{headings} -% -% Avoid some overfull boxes. -\emergencystretch=.1\hsize -\hbadness = 3000 - -% these are from lshort.sty, but lshort.sty pulls in so many other -% packages it seems cleaner to just include them here. -% -\newcommand{\bs}{\symbol{'134}}%Print backslash -\newcommand{\ci}[1]{\texttt{\bs#1}} - -\makeatletter -\@ifpackageloaded{tex4ht}{% - % separate definition for HTML case to avoid - % nasty borders with double horizontal lines with - % large gaps. - \newsavebox{\cmdsyntaxbox}% - \newenvironment{cmdsyntax}{% - \par - % \small - \addvspace{3.2ex plus 0.8ex minus 0.2ex}% - \vskip -\parskip - \noindent - \begin{lrbox}{\cmdsyntaxbox}% - \begin{tabular}{l}% - \rule{0pt}{1em}% - \ignorespaces - }{% - \end{tabular}% - \end{lrbox}% - \fbox{\usebox{\cmdsyntaxbox}}% - \par - \nopagebreak - \addvspace{3.2ex plus 0.8ex minus 0.2ex}% - \vskip -\parskip - }% -}{% - \newenvironment{cmdsyntax}{% - \par - \small - \addvspace{3.2ex plus 0.8ex minus 0.2ex}% - \vskip -\parskip - \noindent - \begin{tabular}{|l|}% - \hline - \rule{0pt}{1em}% - \ignorespaces - }{% - \\% - \hline - \end{tabular}% - \par - \nopagebreak - \addvspace{3.2ex plus 0.8ex minus 0.2ex}% - \vskip -\parskip - }% -} -\makeatother - -\usepackage{array,longtable} -\ifTUTeX% - \usepackage{fontspec}% - \renewcommand*{\ttdefault}{lmvtt}% -\else % not \XeTeX* nor \LuaTeX* - \usepackage[T1]{fontenc}% - \usepackage{lmodern}% - \renewcommand*{\ttdefault}{lmvtt}% -\fi - -\newcommand*{\Quote}[1]{\textquotedblleft#1\textquotedblright} - -\ifpdf - \usepackage[% -% pdftex,% might be luatex, just allow automatic default - colorlinks,% - hyperindex,% - plainpages=false,% - bookmarksopen,% - bookmarksnumbered, - pdfusetitle,% - ]{hyperref} - %%?? \def\pdfBorderAttrs{/Border [0 0 0] } % No border arround Links -\else - \usepackage{hyperref} -\fi - -\makeatletter -\@ifpackageloaded{tex4ht}{% -\author{Sebastian Rahtz (deceased)\and - Heiko Oberdiek (inactive)\and - The \LaTeX3 Project (\url{https://github.com/latex3/hyperref/issues})} -}{% - \usepackage{bmhydoc}% -\author{Sebastian Rahtz\thanks{deceased}\and - Heiko Oberdiek\thanks{inactive}\and - The \LaTeX3 Project\thanks{\url{https://github.com/latex3/hyperref/issues}}} -} -\makeatother -\title{Hypertext marks in \hologo{LaTeX}: a manual for \xpackage{hyperref}} -\date{2022-02-21 v7.00n} - -\begin{document} - -% comes out too close to the toc, and we know it's page one anyway. -\thispagestyle{empty} -\maketitle -\tableofcontents -\setcounter{tocdepth}{2}% for bookmark levels - -\section{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} -project, described at \nolinkurl{http://xxx.lanl.gov/hypertex/}\footnote{Now: \url{https://ctan.org/tex-archive/support/hypertex/hypertex}}. It extends -the functionality of all the \hologo{LaTeX} cross-referencing commands -(including the table of contents, bibliographies etc) to produce -\cs{special} commands which a driver can turn into hypertext links; -it also provides new commands to allow the user to write \emph{ad hoc} -hypertext links, including those to external documents and URLs. - -The package is currently maintained at \url{https://github.com/latex3/hyperref/} and issues should -be reported there. - -This manual provides a brief overview of the \xpackage{hyperref} -package. For more details, you should read the additional documentation -distributed with the package, as well as the complete documentation by -processing \texttt{hyperref.dtx}. You should also read the chapter on -\xpackage{hyperref} in \textit{The \hologo{LaTeX} Web Companion}, where you will -find additional examples. - -The Hyper\hologo{TeX} specification\footnote{This is borrowed from an article -by Arthur Smith.} says that conformant viewers/translators must -recognize the following set of \cs{special} constructs: - -\begin{description} -\item[href:] \verb|html:| -\item[name:] \verb|html:| -\item[end:] \verb|html:| -\item[image:] \verb|html:| -\item[base\_name:] \verb|html:| -\end{description} - -The \emph{href}, \emph{name} and \emph{end} commands are used to do the -basic hypertext operations of establishing links between sections of -documents. The \emph{image} command is intended (as with current HTML -viewers) to place an image of arbitrary graphical format on the page in -the current location. The \emph{base\_name} command is be used to -communicate to the DVI viewer the full (URL) location of the current -document so that files specified by relative URLs may be retrieved -correctly. - -The \emph{href} and \emph{name} commands must be paired with an -\emph{end} command later in the \TeX\ file---the \TeX\ commands between -the two ends of a pair form an \emph{anchor} in the document. In the -case of an \emph{href} command, the \emph{anchor} is to be highlighted -in the \emph{DVI viewer}, and when clicked on will cause the scene to -shift to the destination specified by \emph{href\_string}. The -\emph{anchor} associated with a name command represents a possible -location to which other hypertext links may refer, either as local -references (of the form \verb|href="#name_string"| with the -\emph{name\_string} identical to the one in the name command) or as part -of a URL (of the form \emph{URL\#name\_string}). Here -\emph{href\_string} is a valid URL or local identifier, while -\emph{name\_string} could be any string at all: the only caveat is that -`$\verb|"|$' characters should be escaped with a backslash -($\backslash$), and if it looks like a URL name it may cause problems. - -However, the drivers intended to produce \emph{only} PDF use literal -PostScript or PDF \verb|\special| commands. The commands are defined in -configuration files for different drivers, selected by package options; -at present, the following drivers are supported: - -\begin{description} -\item[hypertex] DVI processors conforming to the Hyper\TeX\ guidelines (i.e.\ \textsf{xdvi}, \textsf{dvips} (with -the \textsf{-z} option), \textsf{\hologo{OzTeX}}, and \textsf{Textures}) -\item[dvips] produces \verb|\special| commands tailored for \textsf{dvips} -\item[dvipsone] produces \verb|\special| commands tailored for \textsf{dvipsone} -\item[ps2pdf] a special case of output suitable for processing by earlier versions of Ghost\-script's -PDF writer; this is basically the same as that for \textsf{dvips}, but a few variations remained before version 5.21 -\item[tex4ht] produces \verb|\special| commands for use with \textsf{\TeX4ht} -\item[pdftex] pdf\TeX, \hologo{HanTheThanh}'s \TeX{} variant that writes PDF directly -\item[luatex] lua\TeX, Unicode \TeX{} variant that writes PDF directly -\item[dvipdfm] produces \verb|\special| commands for Mark Wicks' DVI to PDF driver \textsf{dvipdfm} -\item[dvipdfmx] produces \verb|\special| commands for driver - \textsf{dvipdfmx}, a successor of \textsf{dvipdfm} -\item[dviwindo] produces \verb|\special| commands that Y\&Y's Windows previewer interprets as hypertext jumps within the previewer -\item[vtex] produces \verb|\special| commands that MicroPress' HTML and - PDF-producing \TeX\ variants interpret as hypertext jumps within the - previewer -\item[textures] produces \verb|\special| commands that \textsf{Textures} interprets as hypertext jumps within the previewer -\item[xetex] produces \verb|\special| commands for Xe\TeX{} -\end{description} - -Output from \textsf{dvips} or \textsf{dvipsone} must be processed using -Acrobat Distiller to obtain a PDF file.\footnote{Make sure you turn off -the partial font downloading supported by \textsf{dvips} and -\textsf{dvipsone} in favor of Distiller's own system.} The result is -generally preferable to that produced by using the \textsf{hypertex} -driver, and then processing with \textsf{dvips -z}, but the DVI file is -not portable. The main advantage of using the Hyper\TeX\ \ci{special} -commands is that you can also use the document in hypertext DVI viewers, -such as \textsf{xdvi}. - -\begin{description} -\item[driverfallback] - If a driver is not given and cannot be autodetected, then use - the driver option, given as value to this option \textsf{driverfallback}. - Example: - \begin{quote} - \texttt{driverfallback=dvipdfm} - \end{quote} - Autodetected drivers (\textsf{pdftex}, \textsf{xetex}, \textsf{vtex}, - \textsf{vtexpdfmark}) are recognized from within \TeX\ and - therefore cannot be given as value to option \textsf{driverfallback}. - However a DVI driver program is run after the \TeX\ run is finished. - Thus it cannot be detected at \TeX\ macro level. Then package - \xpackage{hyperref} - uses the driver, given by \textsf{driverfallback}. If the driver - is already specified or can be autodetected, then option - \textsf{driverfallback} is ignored. -\end{description} - -\section{Implicit behavior} - -This package can be used with more or less any normal \LaTeX\ document -by specifying in the document preamble - -\begin{verbatim} -\usepackage{hyperref} -\end{verbatim} - -Make sure it comes \emph{last} of your loaded packages, to give it a -fighting chance of not being over-written, since its job is to redefine -many \LaTeX\ commands.\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} -command. - -In addition, the \texttt{hyperindex} option (see below) attempts to make -items in the index by hyperlinked back to the text, and the option -\texttt{backref} inserts extra `back' links into the bibliography for -each entry. Other options control the appearance of links, and give -extra control over PDF output. For example, \texttt{colorlinks}, as its -name well implies, colors the links instead of using boxes; this is the -option used in this document. - -\section{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}] \xpackage{hyperref} creates destination names for -link anchor typically out of the name of the counter and the \cs{the} value. -This can fail, e.g. if \cs{the} is not unique through the document, -or if it is not expandable. In such cases \cs{theH} 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@}] 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} - -All user-configurable aspects of \xpackage{hyperref} are set using a -single `key=value' scheme (using the \xpackage{keyval} package) with the -key \texttt{Hyp}. The options can be set either in the optional argument -to the \cs{usepackage} command, or using the \cs{hypersetup} -macro. When the package is loaded, a file \texttt{hyperref.cfg} is read -if it can be found, and this is a convenient place to set options on a -site-wide basis. - -Note however that some options (for example \texttt{unicode}) can only be used as -package options, and not in \verb|\hypersetup| as the option settings are processed -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} - -\item a site-wide \texttt{hyperref.cfg} setting up the look of links, -adding backreferencing, and setting a PDF display default: - -\begin{verbatim} -\hypersetup{backref, -pdfpagemode=FullScreen, -colorlinks=true} -\end{verbatim} - -\item A global option in the file, which is passed down to -\textsf{hyperref}: - -\begin{verbatim} -\documentclass[dvips]{article} -\end{verbatim} - -\item File-specific options in the \cs{usepackage} commands, which -override the ones set in \texttt{hyperref.cfg}: - -\begin{verbatim} -\usepackage[colorlinks=false]{hyperref} -\hypersetup{pdftitle={A Perfect Day}} -\end{verbatim} -\end{itemize} - -As seen in the previous example, information entries -(pdftitle, pdfauthor, \dots) should be set after the package is loaded. -Otherwise \LaTeX\ expands the values of these options prematurely. -Also \LaTeX\ strips spaces in options. Especially option `pdfborder' -requires some care. Curly braces protect the value, if given -as package option. They are not necessary in \verb|\hypersetup|. - -\begin{verbatim} -\usepackage[pdfborder={0 0 0}]{hyperref} -\hypersetup{pdfborder=0 0 0} -\end{verbatim} - -Some options can be given at any time, but many are restricted: before -\verb|\begin{document}|, only in \verb|\usepackage[...]{hyperref}|, -before first use, etc. - -In the key descriptions that follow, many options do not need a value, -as they default to the value true if used. These are the ones classed as -`boolean'. The values true and false can always be specified, however. - -\subsection{General options} - -Firstly, the options to specify general behavior and page size. - -\medskip -\begin{longtable}{>{\ttfamily}ll>{\itshape}ll} -draft & boolean & false & all hypertext options are turned off \\ -final & boolean & true & all hypertext options are turned on \\ -debug & boolean & false & extra diagnostic messages are printed in \\ - & & & the log file \\ -verbose & boolean & false & same as debug \\ -implicit & boolean & true & redefines \LaTeX\ internals \\ -setpagesize & boolean & true & sets page size by special driver commands -\end{longtable} - -\subsection{Options for destination names} - -Destinations names (also anchor, target or link names) are internal -names that identify a position on a page in the document. They -are used in link targets for inner document links or the bookmarks, -for example. - -Usually anchor are set, if \cs{refstepcounter} is called. -Thus there is a counter name and value. Both are used to -construct the destination name. By default the counter value -follows the counter name separated by a dot. Example for -the fourth chapter: -\begin{quote} - \verb|chapter.4| -\end{quote} -This scheme is used by: -\begin{description} -\item[\cs{autoref}] displays the description label for the - reference depending on the counter name. -\item[\cs{hyperpage}] is used by the index to get -page links. Page anchor setting (\verb|pageanchor|) must not -be turned off. -\end{description} - -It is very important that the destination names are unique, -because two destinations must not share the same name. -The counter value \cs{the} 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} -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}. Defaults -for standard cases (chapter, \dots) are provided. And after \xpackage{hyperref} -is loaded, new counters with parent counters also define -\cs{theH} 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}. If option -\texttt{hypertexnames} is disabled, then a unique artificial -number is used instead of the counter value. In case of page -anchors the absolute page anchor is used. With option \texttt{plainpages} -the page anchors use the arabic form. In both latter cases \cs{hyperpage} -for index links is affected and might not work properly. - -If an unnumbered entity gets an anchor (starred forms of -chapters, sections, \dots) or \cs{phantomsection} is used, -then the dummy counter name \texttt{section*} and an artificial -unique number is used. - -If the final PDF file is going to be merged with another file, than -the destination names might clash, because both documents might -contain \texttt{chapter.1} or \texttt{page.1}. Also \xpackage{hyperref} -sets anchor with name \texttt{Doc-Start} at the begin of the document. -This can be resolved by redefining \cs{HyperDestNameFilter}. -Package \xpackage{hyperref} calls this macro each time, it uses a -destination name. -The macro must be expandable and expects the destination name -as only argument. As example, the macro is redefined to add -a prefix to all destination names: -\begin{quote} -\begin{verbatim} -\renewcommand*{\HyperDestNameFilter}[1]{\jobname-#1} -\end{verbatim} -\end{quote} -In document \texttt{docA} the destination name \texttt{chapter.2} -becomes \texttt{docA-chapter.2}. - -Destination names can also be used from the outside in URIs(, if the -driver has not removed or changed them), for example: -\begin{quote} -\begin{verbatim} -http://somewhere/path/file.pdf#nameddest=chapter.4 -\end{verbatim} -\end{quote} -However using a number seems unhappy. If another chapter is added -before, the number changes. But it is very difficult to pass -a new name for the destination to the anchor setting process that -is usually deep hidden in the internals. The first name of -\cs{label} after the anchor setting seems a good approximation: -\begin{quote} -\begin{verbatim} - \section{Introduction} - \label{intro} -\end{verbatim} -\end{quote} -Option \texttt{destlabel} checks for each \cs{label}, if there is -a new destination name active and replaces the destination -name by the label name. Because the destination name is already in use -because of the anchor setting, the new name is recorded in the \texttt{.aux} -file and used in the subsequent \hologo{LaTeX} run. The renaming is done by -a redefinition of \cs{HyperDestNameFilter}. That leaves the old -destination names intact (e.g., they are needed for \cs{autoref}). -This redefinition is also available as \cs{HyperDestLabelReplace}, -thus that an own redefinition can use it. -The following example also adds a prefix for \emph{all} destination names: -\begin{quote} -\begin{verbatim} -\renewcommand*{\HyperDestNameFilter}[1]{% - \jobname-\HyperDestLabelReplace{#1}% -} -\end{verbatim} -\end{quote} -The other case that only files prefixed that do not have a corresponding -\cs{label} is more complicate, because \cs{HyperDestLabelReplace} needs -the unmodified destination name as argument. This is solved by an -expandable string test (\cs{pdfstrcmp} of \hologo{pdfTeX} -or \cs{strcmp} of \hologo{XeTeX}, package \xpackage{pdftexcmds} also supports -\hologo{LuaTeX}): -\begin{quote} -\begin{verbatim} -\usepackage{pdftexcmds} -\makeatletter -\renewcommand*{\HyperDestNameFilter}[1]{% - \ifcase\pdf@strcmp{#1}{\HyperDestLabelReplace{#1}} % - \jobname-#1% - \else - \HyperDestLabelReplace{#1}% - \fi -} -\makeatother -\end{verbatim} -\end{quote} - -With option \texttt{destlabel} destinations can also named manually, -if the destination is not yet renamed: -\begin{quote} -\verb|\HyperDestRename{|\meta{destination}\verb|}{|\meta{newname}\verb|}| -\end{quote} - -Hint: Anchors can also be named and set by \cs{hypertarget}. - -\medskip -\begin{longtable}{>{\ttfamily}ll>{\itshape}ll} -destlabel & boolean & false & destinations are named by first \cs{label}\\ - & & & after anchor creation\\ -hypertexnames & boolean & true & use guessable names for links \\ -naturalnames & boolean & false & use \LaTeX-computed names for links \\ -plainpages & boolean & false & Forces page anchors to be named by the Arabic form \\ - & & & of the page number, rather than the formatted form. \\ -\end{longtable} - -\subsection{Configuration options} - -\begin{longtable}{>{\ttfamily}ll>{\itshape}lp{9cm}} -raiselinks & boolean & true & In the hypertex driver, the height of links is normally calculated by the driver as - simply the base line of contained text; this options forces \verb|\special| commands to - reflect the real height of the link (which could contain a graphic) \\ -breaklinks & boolean & both & This option is in hyperref only used in the dviwindo driver, in all other cases it doesn't do anything sensible---it neither allows nor prevents links to be broken. The ocgx2 package -checks the state of the boolean.\\ -pageanchor & boolean & true & Determines whether every page is given an implicit anchor at the top left corner. If this - is turned off, \verb|\printindex| will not contain - valid hyperlinks. \\ -nesting & boolean & false & Allows links to be nested; no drivers currently support this. -\end{longtable} - -Note for option \verb|breaklinks|: -The correct value is automatically set according to the driver features. -It can be overwritten for drivers that do not support broken links. -However, at any case, the link area will be wrong and displaced. - -\subsection{Backend drivers} - -If no driver is specified, the package tries to find a driver in -the following order: -\begin{enumerate} -\item Autodetection, some \TeX\ processors can be detected at \TeX\ macro - level (pdf\TeX, Xe\TeX, V\TeX). -\item Option \textsf{driverfallback}. If this option is set, its value - is taken as driver option. -\item Macro \cs{Hy@defaultdriver}. The macro takes a driver file - name (without file extension). -\item Package default is \textsf{hypertex}. -\end{enumerate} -Many distributions are using a driver file \texttt{hypertex.cfg} that -define \cs{Hy@defaultdriver} with \texttt{hdvips}. This is recommended -because driver \textsf{dvips} provides much more features than -\textsf{hypertex} for PDF generation. - -\begin{longtable}{@{}>{\ttfamily}lp{.8\hsize}@{}} -driverfallback & Its value is used as driver option\\ - & if the driver is not given or autodetected.\\ -dvipdfm & Sets up \textsf{hyperref} for use with the \textsf{dvipdfm} driver.\\ -dvipdfmx & Sets up \textsf{hyperref} for use with the \textsf{dvipdfmx} driver.\\ -dvips & Sets up \textsf{hyperref} for use with the \textsf{dvips} driver. \\ -dvipsone & Sets up \textsf{hyperref} for use with the \textsf{dvipsone} driver. \\ -dviwindo & Sets up \textsf{hyperref} for use with the \textsf{dviwindo} Windows previewer. \\ -hypertex & Sets up \textsf{hyperref} for use with the Hyper\TeX-compliant drivers. \\ -latex2html & Redefines a few macros for compatibility with \textsf{latex2html}. \\ -nativepdf & An alias for \textsf{dvips} \\ -pdfmark & An alias for \textsf{dvips} \\ -pdftex & Sets up \textsf{hyperref} for use with the \textsf{pdftex} program.\\ -ps2pdf & Redefines a few macros for compatibility with - Ghostscript's PDF writer, otherwise identical to - \textsf{dvips}. \\ -tex4ht & For use with \textsf{\TeX4ht} \\ -textures & For use with \textsf{Textures} \\ -vtex & For use with MicroPress' \textsf{VTeX}; the PDF - and HTML backends are detected automatically. \\ -vtexpdfmark & For use with \textsf{VTeX}'s PostScript backend. \\ -xetex & For use with Xe\TeX\ (using backend for dvipdfm). -\end{longtable} -\smallskip - -If you use \textsf{dviwindo}, you may need to redefine the macro -\ci{wwwbrowser} (the default is \verb|C:\netscape\netscape|) to tell -\textsf{dviwindo} what program to launch. Thus, users of Internet -Explorer might add something like this to hyperref.cfg: - -\begin{verbatim} -\renewcommand{\wwwbrowser}{C:\string\Program\space - Files\string\Plus!\string\Microsoft\space - Internet\string\iexplore.exe} -\end{verbatim} - -\subsection{Extension options} -\begin{longtable}{@{}>{\ttfamily}ll>{\itshape}lp{8cm}@{}} -extension & text & & Set the file extension (e.g.\ \textsf{dvi}) which will be appended to file links - created if you use the \xpackage{xr} package. \\ -hyperfigures & boolean & & \\ -backref & text & false & Adds `backlink' text to the end of each item in the bibliography, as a list of - section numbers. This can only work properly \emph{if} there is a blank line after - each \verb|\bibitem|. Supported values are \verb|section|, \verb|slide|, \verb|page|, - \verb|none|, or \verb|false|. If no value is given, \verb|section| is taken as default.\\ -pagebackref & boolean & false & Adds `backlink' text to the end of each item in the bibliography, as a list of page - numbers. \\ -hyperindex & boolean & true & Makes the page numbers of index entries into hyperlinks. Relays on unique - page anchors (\verb|pageanchor|, \ldots) - \verb|pageanchors| and \verb|plainpages=false|. \\ -hyperfootnotes & boolean & true & Makes the footnote marks into hyperlinks to the footnote text. - Easily broken \ldots\\ -encap & & & Sets encap character for hyperindex \\ -linktoc & text & section & make text (\verb|section|), page number (\verb|page|), both (\verb|all|) or nothing (\verb|none|) be link on TOC, LOF and LOT \\ -linktocpage & boolean & false & make page number, not text, be link on TOC, LOF and LOT \\ -breaklinks & boolean & false & allow links to break over lines by making links over multiple lines into PDF links to - the same target \\ -colorlinks & boolean & false & Colors the text of links and anchors. The colors chosen depend on the the type of - link. At present the only types of link distinguished are citations, page references, - URLs, local file references, and other links. - Unlike colored boxes, the colored - text remains when printing.\\ -linkcolor & color & red & Color for normal internal links. \\ -anchorcolor & color & black & Color for anchor text. Ignored by most drivers. \\ -citecolor & color & green & Color for bibliographical citations in text. \\ -filecolor & color & cyan & Color for URLs which open local files. \\ -menucolor & color & red & Color for Acrobat menu items. \\ -runcolor & color & filecolor & Color for run links (launch annotations). \\ -urlcolor & color & magenta & Color for linked URLs. \\ -allcolors & color & & Set all color options (without border and field options).\\ -frenchlinks & boolean & false & Use small caps instead of color for links.\\ -hidelinks & & & Hide links (removing color and border). \\ -\end{longtable} \smallskip - -Note that all color names must be defined before use, following the -normal system of the standard \LaTeX\ \xpackage{color} package. - -\subsection{PDF-specific display options} -\begin{longtable}{@{}>{\ttfamily}ll>{\itshape}lp{7.6cm}@{}} -bookmarks & boolean & true & A set of Acrobat bookmarks are written, in a manner similar to the - table of contents, requiring two passes of \LaTeX. Some postprocessing - of the bookmark file (file extension \texttt{.out}) may be needed to - translate \LaTeX\ codes, since bookmarks must be written in PDFEncoding. - To aid this process, the \texttt{.out} file is not rewritten by \LaTeX\ - if it is edited to contain a line \verb|\let\WriteBookmarks\relax| \\ -bookmarksopen & boolean & false & If Acrobat bookmarks are requested, show them with all the subtrees - expanded. \\ -bookmarksopenlevel & parameter & & level (\ci{maxdimen}) to which bookmarks are open \\ -bookmarksnumbered & boolean & false & If Acrobat bookmarks are requested, include section numbers. \\ -bookmarkstype & text & toc & to specify which `toc' file to mimic \\ -CJKbookmarks & boolean & false & - This option should be used to produce CJK bookmarks. - Package \verb|hyperref| - supports both normal and preprocessed mode of the \xpackage{CJK} package; - during the creation of bookmarks, it simply replaces CJK's macros - with special versions which expand to the corresponding character - codes. Note that without the `unicode' option of hyperref you get - PDF files which actually violate the PDF specification because - non-Unicode character codes are used -- some PDF readers localized - for CJK languages (most notably Acroread itself) support this. - Also note that option `CJKbookmarks' cannot be used together - with option `unicode'. - - No mechanism is provided to translate non-Unicode bookmarks to - Unicode; for portable PDF documents only Unicode encoding should - be used.\\ -pdfhighlight & name & /I & How link buttons behave when selected; /I is for inverse (the default); - the other possibilities are /N (no effect), /O (outline), and /P (inset - highlighting). \\ -citebordercolor & RGB color & 0 1 0 & The color of the box around citations \\ -filebordercolor & RGB color & 0 .5 .5 & The color of the box around links to files \\ -linkbordercolor & RGB color & 1 0 0 & The color of the box around normal links \\ -menubordercolor & RGB color & 1 0 0 & The color of the box around Acrobat menu links \\ -urlbordercolor & RGB color & 0 1 1 & The color of the box around links to URLs \\ -runbordercolor & RGB color & 0 .7 .7 & Color of border around `run' links \\ -allbordercolors & & & Set all border color options \\ -pdfborder & & 0 0 1 & The style of box around links; defaults to a box with lines of 1pt thickness, - but the colorlinks option resets it to produce no border. -\end{longtable} - -The color of link borders used to be specified \emph{only} as 3 -numbers in the range 0..1, giving an RGB color. Since version 6.76a, the usual -color specifications of package \xpackage{(x)color} can be used if \xpackage{xcolor} -has been loaded. -For further information see description of package \xpackage{hycolor}. - -The bookmark commands are stored in a file called -\textit{jobname}\texttt{.out}. The files is not processed by \LaTeX\ so -any markup is passed through. You can postprocess this file as needed; -as an aid for this, the \texttt{.out} file is not overwritten on the -next \TeX\ run if it is edited to contain the line -\begin{verbatim} -\let\WriteBookmarks\relax -\end{verbatim} - -\subsection{PDF display and information options} -\begin{longtable}{@{}>{\ttfamily}l>{\raggedright}p{\widthof{key value}}>{\itshape}lp{7cm}@{}} -baseurl & URL & & Sets the base URL of the PDF document \\ -pdfpagemode & name & empty & Determines how the file is opening in Acrobat; the possibilities are - \verb|UseNone|, \verb|UseThumbs| (show thumbnails), \verb|UseOutlines| - (show bookmarks), \verb|FullScreen|, \verb|UseOC| (PDF 1.5), - and \verb|UseAttachments| (PDF 1.6). If no mode if explicitly chosen, but the - bookmarks option is set, \verb|UseOutlines| is used. \\ -pdftitle & text & & Sets the document information Title field \\ -pdfauthor & text & & Sets the document information Author field \\ -pdfsubject & text & & Sets the document information Subject field \\ -pdfcreator & text & & Sets the document information Creator field \\ -addtopdfcreator & text & & Adds additional text to the document information Creator field \\ -pdfkeywords & text & & Sets the document information Keywords field \\ -pdftrapped & name & empty & Sets the document information Trapped entry. Possible values are \verb|True|, \verb|False| and \verb|Unknown|. - An empty value means, the entry is not set.\\ -% -pdfinfo & key value list & empty & Alternative interface for setting the - document information.\\ -pdfview & name & XYZ & Sets the default PDF `view' for each link \\ -pdfstartpage & integer & 1 & Determines on which page the PDF file is opened. An empty value means, the entry is not set.\\ -pdfstartview & name & Fit & Set the startup page view \\ -pdfremotestartview & name & Fit & Set the startup page view of remote PDF files \\ -pdfpagescrop & n n n n & & Sets the default PDF crop box for pages. This should be a set of four numbers \\ -pdfcenterwindow & boolean & false & position the document window in the center of the screen \\ -pdfdirection & name & empty & direction setting. Possible values: \verb|L2R| (left to right) and - \verb|R2L| (right to left)\\ -pdfdisplaydoctitle & boolean & false & display document title instead of file name in title bar\\ -pdfduplex & name & empty & paper handling option for print dialog. Possible vatues are: - \verb|Simplex| (print single-sided), - \verb|DuplexFlipShortEdge| (duplex and flip on the short edge of the sheet), - \verb|DuplexFlipLongEdge| (duplex and flip on the long edge of the sheet)\\ - -pdffitwindow & boolean & false & resize document window to fit document size \\ -pdflang & name & relax & PDF language identifier (RFC 3066)\\ -pdfmenubar & boolean & true & make PDF viewer's menu bar visible \\ -pdfnewwindow & boolean & false & make links that open another PDF file start a new window \\ -pdfnonfullscreenpagemode - & name & empty & page mode setting on exiting full-screen mode. Possible values are - \verb|UseNone|, \verb|UseOutlines|, \verb|UseThumbs|, and \verb|UseOC|\\ -pdfnumcopies & integer & empty & number of printed copies \\ -pdfpagelayout & name & empty & set layout of PDF pages. Possible values: - \verb|SinglePage|, \verb|OneColumn|, - \verb|TwoColumnLeft|, \verb|TwoColumnRight|, - \verb|TwoPageLeft|, and \verb|TwoPageRight| \\ -pdfpagelabels & boolean & true & set PDF page labels \\ -pdfpagetransition & name & empty & set PDF page transition style. Possible values are - \verb|Split|, \verb|Blinds|, \verb|Box|, \verb|Wipe|, - \verb|Dissolve|, \verb|Glitter|, \verb|R|, - \verb|Fly|, \verb|Push|, - \verb|Cover|, \verb|Uncover|, - \verb|Fade|. - The default according to the PDF~Reference is \verb|R|, - which simply replaces the old page with the new one. \\ -pdfpicktraybypdfsize - & boolean & false & specify whether PDF page size is used to select input paper tray in print dialog \\ -pdfprintarea & name & empty & set /PrintArea of viewer preferences. Possible values are - \verb|MediaBox|, \verb|CropBox|, - \verb|BleedBox|, \verb|TrimBox|, and \verb|ArtBox|. - The dafault according to the PDF~Refence is \verb|CropBox| \\ -pdfprintclip & name & empty & set /PrintClip of viewer preferences. Possible values are - \verb|MediaBox|, \verb|CropBox|, - \verb|BleedBox|, \verb|TrimBox|, and \verb|ArtBox|. - The dafault according to the PDF~Refence is \verb|CropBox| \\ -pdfprintpagerange & n n (n n)* - & empty & set /PrintPageRange of viewer preferences\\ -pdfprintscaling & name & empty & page scaling option for print dialog - (option /PrintScaling of viewer - preferences, PDF 1.6); - valid values are \verb|None| and - \verb|AppDefault| \\ -pdftoolbar & boolean & true & make PDF toolbar visible \\ -pdfviewarea & name & empty & set /ViewArea of viewer preferences. Possible values are - \verb|MediaBox|, \verb|CropBox|, - \verb|BleedBox|, \verb|TrimBox|, and \verb|ArtBox|. - The dafault according to the PDF~Refence is \verb|CropBox| \\ -pdfviewclip & name & empty & set /ViewClip of viewer preferences Possible values are - \verb|MediaBox|, \verb|CropBox|, - \verb|BleedBox|, \verb|TrimBox|, and \verb|ArtBox|. - The dafault according to the PDF~Refence is \verb|CropBox| \\ -pdfwindowui & boolean & true & make PDF user interface elements visible \\ -unicode & boolean & true & Unicode encoded PDF strings -\end{longtable} - -Each link in Acrobat carries its own magnification level, which is set -using PDF coordinate space, which is not the same as \TeX's. The unit -is bp and the origin is in the lower left corner. See also -\verb|\hypercalcbp| that is explained on page \pageref{hypercalcbp}. -pdf\TeX\ -works by supplying default values for \texttt{XYZ} (horizontal $\times$ -vertical $\times$ zoom) and \texttt{FitBH}. However, drivers using -\texttt{pdfmark} do not supply defaults, so \textsf{hyperref} passes in -a value of -32768, which causes Acrobat to set (usually) sensible -defaults. The following are possible values for the \texttt{pdfview}, -\texttt{pdfstartview} and \texttt{pdfremotestartview} parameters. - -\begin{longtable}{@{}>{\ttfamily}l>{\itshape}lp{7cm}@{}} -XYZ & left top zoom & Sets a coordinate and a zoom factor. If any one is null, the source link value is used. - \textit{null null null} will give the same values as the current page. \\ -Fit & & Fits the page to the window. \\ -FitH & top & Fits the width of the page to the window. \\ -FitV & left & Fits the height of the page to the window. \\ -FitR & left bottom right top & Fits the rectangle specified by the four coordinates to the window. \\ -FitB & & Fits the page bounding box to the window. \\ -FitBH & top & Fits the width of the page bounding box to the window. \\ -FitBV & left & Fits the height of the page bounding box to the window. \\ -\end{longtable} - -The \texttt{pdfpagelayout} can be one of the following values. - -\begin{longtable}{@{}>{\ttfamily}lp{10cm}@{}} -SinglePage & Displays a single page; advancing flips the page \\ -OneColumn & Displays the document in one column; continuous scrolling. \\ -TwoColumnLeft & Displays the document in two columns, odd-numbered pages to the left. \\ -TwoColumnRight & Displays the document in two columns, odd-numbered pages to the right.\\ -TwoPageLeft & Displays two pages, odd-numbered pages to the left (since PDF 1.5).\\ -TwoPageRight & Displays two pages, odd-numbered pages to the right (since PDF 1.5). -\end{longtable} - -Finally, the \texttt{pdfpagetransition} can be one of the following -values, where \textit{/Di} stands for direction of motion in degrees, -generally in 90$^{\circ}$\ steps, \textit{/Dm} is a horizontal -(\texttt{/H}) or vertical (\texttt{/V}) dimension (e.g.\ \texttt{Blinds -/Dm /V}), and \textit{/M} is for motion, either in (\texttt{/I}) or out -(\texttt{/O}). - -\begin{longtable}{@{}>{\ttfamily}llp{8.5cm}@{}} -Blinds & /Dm & Multiple lines distributed evenly across the screen sweep in the same direction to reveal the new - page. \\ -Box & /M & A box sweeps in or out. \\ -Dissolve & & The page image dissolves in a piecemeal fashion to reveal the new page. \\ -Glitter & /Di & Similar to Dissolve, except the effect sweeps across the screen. \\ -Split & /Dm /M & Two lines sweep across the screen to reveal the new page. \\ -Wipe & /Di & A single line sweeps across the screen to reveal the new page. \\ -R & & Simply replaces the old page with the new one. \\ -Fly & /Di /M & Changes are flown out or in (as specified by /M), in the direction - specified by /Di, to or from a location that is - offscreen except when /Di is None. \\ -Push & /Di & The old page slides off the screen while the new page slides in, - pushing the old page out in the direction - specified by /Di. \\ -Cover & /Di & The new page slides on to the screen in the direction specified - by /Di, covering the old page. \\ -Uncover & /Di & The old page slides off the screen in the direction specified by - /Di, uncovering the new page in the direction - specified by /Di. \\ -Fade & & The new page gradually becomes visible through the old one. - -\end{longtable} - -\subsection{Option \texttt{pdfinfo}} - -The information entries can be set using \texttt{pdftitle}, -\texttt{pdfsubject}, \dots. Option \texttt{pdfinfo} provides an alternative -interface. It takes a key value list. The key names are the names that -appear in the PDF information dictionary directly. Known keys such as -\texttt{Title}, \texttt{Subject}, \texttt{Trapped} and other are mapped to -options \texttt{pdftitle}, \texttt{subject}, \texttt{trapped}, \dots -Unknown keys are added to the information dictionary. Their values are text -strings (see PDF specification). -Example: -\begin{quote} -\begin{verbatim} -\hypersetup{ - pdfinfo={ - Title={My Title}, - Subject={My Subject}, - NewKey={Foobar}, - % ... - } -} -\end{verbatim} -\end{quote} - -\subsection{Big alphabetical list} - -The following is a complete listing of available options for -\textsf{hyperref}, arranged alphabetically. - -\begin{longtable}{@{}>{\ttfamily}llp{7cm}@{}} -allbordercolors & & Set all border color options\\ -allcolors & & Set all color options (without border and field options)\\ -anchorcolor & \textit{black} & set color of anchors, ignored by most drivers. \\ -backref & \textit{false} & do bibliographical back references \\ -baseurl & \textit{empty} & set base URL for document \\ -bookmarks & \textit{true} & make bookmarks \\ -bookmarksnumbered & \textit{false} & put section numbers in bookmarks \\ -bookmarksopen & \textit{false} & open up bookmark tree \\ -bookmarksopenlevel & \ttfamily\ci{maxdimen} & level to which bookmarks are open \\ -bookmarkstype & \textit{toc} & to specify which `toc' file to mimic \\ -breaklinks & \textit{false} & allow links to break over lines \\ -CJKbookmarks & \textit{false} & to produce CJK bookmarks\\ -citebordercolor & \textit{0 1 0} & color of border around cites \\ -citecolor & \textit{green} & color of citation links \\ -colorlinks & \textit{false} & color links \\ - & \textit{true} & (\textsf{tex4ht}, \textsf{dviwindo}) \\ -debug & \textit{false} & provide details of anchors defined; same as verbose \\ -destlabel & \textit{false} & destinations are named by the first \verb|\label| after the anchor creation \\ -draft & \textit{false} & do not do any hyperlinking \\ -driverfallback & & default if no driver specified or detected\\ -dvipdfm & & use \textsf{dvipdfm} backend \\ -dvipdfmx & & use \textsf{dvipdfmx} backend \\ -dvips & & use \textsf{dvips} backend \\ -dvipsone & & use \textsf{dvipsone} backend \\ -dviwindo & & use \textsf{dviwindo} backend \\ -encap & & to set encap character for hyperindex \\ -extension & \textit{dvi} & suffix of linked files \\ -filebordercolor & \textit{0 .5 .5} & color of border around file links \\ -filecolor & \textit{cyan} & color of file links \\ -final & \textit{true} & opposite of option draft \\ -frenchlinks & \textit{false} & use small caps instead of color for links \\ -hidelinks & & Hide links (removing color and border) \\ -hyperfigures & \textit{false} & make figures hyper links \\ -hyperfootnotes & \textit{true} & set up hyperlinked footnotes \\ -hyperindex & \textit{true} & set up hyperlinked indices \\ -hypertex & & use \textsf{Hyper\TeX} backend \\ -hypertexnames & \textit{true} & use guessable names for links \\ -implicit & \textit{true} & redefine \LaTeX\ internals \\ -latex2html & & use \textsf{\LaTeX2HTML} backend \\ -linkbordercolor & \textit{1 0 0} & color of border around links \\ -linkcolor & \textit{red} & color of links \\ -linktoc & \textit{section} & make text be link on TOC, LOF and LOT \\ -linktocpage & \textit{false} & make page number, not text, be link on TOC, LOF and LOT \\ -menubordercolor & \textit{1 0 0} & color of border around menu links \\ -menucolor & \textit{red} & color for menu links \\ -nativepdf & \textit{false} & an alias for \textsf{dvips} \\ -naturalnames & \textit{false} & use \LaTeX-computed names for links \\ -nesting & \textit{false} & allow nesting of links \\ -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 \\ -pdfborder & \textit{0 0 1} & width of PDF link border \\ - & \textit{0 0 0} & (\texttt{colorlinks)} \\ -pdfborderstyle & & border style for links \\ -pdfcenterwindow & \textit{false} & position the document window in the center of the screen \\ -pdfcreator & \textit{LaTeX with} & text for PDF Creator field \\ - & \textit{hyperref} & \\ -pdfdirection & \textit{empty} & direction setting \\ -pdfdisplaydoctitle & \textit{false} & display document title instead - of file name in title bar\\ -pdfduplex & \textit{empty} & paper handling option for - print dialog\\ -pdffitwindow & \textit{false} & resize document window to fit document size \\ -pdfhighlight & \textit{/I} & set highlighting of PDF links \\ -pdfinfo & \textit{empty} & alternative interface for setting document information\\ -pdfkeywords & \textit{empty} & text for PDF Keywords field \\ -pdflang & \textit{relax} & PDF language identifier (RFC 3066) \\ -pdfmark & \textit{false} & an alias for \textsf{dvips} \\ -pdfmenubar & \textit{true} & make PDF viewer's menu bar visible \\ -pdfnewwindow & \textit{false} & make links that open another PDF \\ - & & file start a new window \\ -pdfnonfullscreenpagemode - & \textit{empty} & page mode setting on exiting - full-screen mode\\ -pdfnumcopies & \textit{empty} & number of printed copies\\ -pdfpagelabels & \textit{true} & set PDF page labels \\ -pdfpagelayout & \textit{empty} & set layout of PDF pages \\ -pdfpagemode & \textit{empty} & set default mode of PDF display \\ -pdfpagescrop & \textit{empty} & set crop size of PDF document \\ -pdfpagetransition & \textit{empty} & set PDF page transition style \\ -pdfpicktraybypdfsize - & \textit{empty} & set option for print dialog \\ -pdfprintarea & \textit{empty} & set /PrintArea of viewer preferences \\ -pdfprintclip & \textit{empty} & set /PrintClip of viewer preferences \\ -pdfprintpagerange & \textit{empty} & set /PrintPageRange of viewer preferences \\ -pdfprintscaling & \textit{empty} & page scaling option for print dialog \\ -pdfproducer & \textit{empty} & text for PDF Producer field \\ -pdfremotestartview & \textit{Fit} & starting view of remote PDF documents \\ -pdfstartpage & \textit{1} & page at which PDF document opens \\ -pdfstartview & \textit{Fit} & starting view of PDF document \\ -pdfsubject & \textit{empty} & text for PDF Subject field \\ -pdftex & & use \textsf{pdf\TeX} backend \\ -pdftitle & \textit{empty} & text for PDF Title field \\ -pdftoolbar & \textit{true} & make PDF toolbar visible \\ -pdftrapped & \textit{empty} & Sets the document information Trapped entry. - Possible values are \texttt{True}, \texttt{False} and \texttt{Unknown}. - An empty value means, the entry is not set.\\ -pdfview & \textit{XYZ} & PDF `view' when on link traversal \\ -pdfviewarea & \textit{empty} & set /ViewArea of viewer preferences \\ -pdfviewclip & \textit{empty} & set /ViewClip of viewer preferences \\ -pdfwindowui & \textit{true} & make PDF user interface elements visible \\ -plainpages & \textit{false} & do page number anchors as plain Arabic \\ -ps2pdf & & use \textsf{ps2pdf} backend \\ -psdextra & \textit{false} & define more short names for PDF string commands \\ -raiselinks & \textit{false} & raise up links (for \textsf{Hyper\TeX} backend) \\ -runbordercolor & \textit{0 .7 .7} & color of border around `run' links \\ -runcolor & \textit{filecolor} & color of `run' links\\ -setpagesize & \textit{true} & set page size by special driver commands \\ -tex4ht & & use \textsf{\TeX4ht} backend \\ -textures & & use \textsf{Textures} backend \\ -unicode & \textit{true} & Unicode encoded pdf strings, starting with version v7.00g set by default to true for all engines. It will load a number of definitions in puenc.def. It can be set to false for pdflatex, but this is not recommended.\\ -urlbordercolor & \textit{0 1 1} & color of border around URL links \\ -urlcolor & \textit{magenta} & color of URL links \\ -verbose & \textit{false} & be chatty \\ -vtex & & use \textsf{VTeX} backend\\ -xetex & & use \textsf{Xe\TeX} backend\\ -\end{longtable} - -\section{Additional user macros} - -If you need to make references to URLs, or write explicit links, the -following low-level user macros are provided: - -\begin{cmdsyntax} -\ci{href}\verb|[|\emph{options}\verb|]|\verb|{|\emph{URL}\verb|}{|\emph{text}\verb|}| -\end{cmdsyntax} - -\noindent The \emph{text} is made a hyperlink to the \emph{URL}; this -must be a full URL (relative to the base URL, if that is defined). The -special characters \# and \~{} do \emph{not} need to be escaped in any -way (unless the command is used in the argument of another command). - -The optional argument \emph{options} recognizes the hyperref options -\texttt{pdfremotestartview}, \texttt{pdfnewwindow} and the following -key value options: -\begin{description} -\item[\texttt{page}:] Specifies the start page number of remote -PDF documents. First page is \verb|1|. -\item[\texttt{ismap}:] Boolean key, if set to \verb|true|, the -URL should appended by the coordinates as query parameters by -the PDF viewer. -\item[\texttt{nextactionraw}:] The value of key \verb|/Next| of -action dictionaries, see PDF specification. -\end{description} - -\begin{cmdsyntax} -\ci{url}\verb|{|\emph{URL}\verb|}| -\end{cmdsyntax} - -\noindent Similar to -\ci{href}\verb|{|\emph{URL}\verb|}{|\ci{nolinkurl}\verb|{|\emph{URL}\verb|}}|. -Depending on the driver \verb|\href| also tries to detect the link type. -Thus the result can be a url link, file link, \dots - -\begin{cmdsyntax} -\ci{nolinkurl}\verb|{|\emph{URL}\verb|}| -\end{cmdsyntax} - -\noindent Write \emph{URL} in the same way as \verb|\url|, - without creating a hyperlink. - -\begin{cmdsyntax} -\ci{hyperbaseurl}\verb|{|\emph{URL}\verb|}| -\end{cmdsyntax} - -\noindent A base \emph{URL} is established, which is prepended to other -specified URLs, to make it easier to write portable documents. - -\begin{cmdsyntax} -\ci{hyperimage}\verb|{|\emph{imageURL}\verb|}{|\emph{text}\verb|}| -\end{cmdsyntax} - -\noindent The link to the image referenced by the URL is inserted, using -\emph{text} as the anchor. - - For drivers that produce HTML, the image itself is inserted by the -browser, with the \emph{text} being ignored completely. - -\begin{cmdsyntax} -\ci{hyperdef}\verb|{|\emph{category}\verb|}{|\emph{name}\verb|}{|\emph{text}\verb|}| -\end{cmdsyntax} - -\noindent A target area of the document (the \emph{text}) is marked, and -given the name \emph{category.name} - -\begin{cmdsyntax} -\ci{hyperref}\verb|{|\emph{URL}\verb|}{|\emph{category}\verb|}{|\emph{name}\verb|}{|\emph{text}\verb|}| -\end{cmdsyntax} - -\noindent \emph{text} is made into a link to \emph{URL\#category.name} - -\begin{cmdsyntax} -\ci{hyperref}\verb|[|\emph{label}\verb|]{|\emph{text}\verb|}| -\end{cmdsyntax} - -\noindent -\emph{text} is made into a link to the same place as -\verb|\ref{|\emph{label}\verb|}| would be linked. - -\begin{cmdsyntax} -\ci{hyperlink}\verb|{|\emph{name}\verb|}{|\emph{text}\verb|}| -\end{cmdsyntax} -\begin{cmdsyntax} -\ci{hypertarget}\verb|{|\emph{name}\verb|}{|\emph{text}\verb|}| -\end{cmdsyntax} - -\noindent A simple internal link is created with \verb|\hypertarget|, -with two parameters of an anchor \emph{name}, and anchor -\emph{text}. \verb|\hyperlink| has two arguments, the name of a -hypertext object defined somewhere by \verb|\hypertarget|, and the -\emph{text} which be used as the link on the page. - -Note that in HTML parlance, the \verb|\hyperlink| command inserts a -notional \# in front of each link, making it relative to the current -testdocument; \verb|\href| expects a full URL. - -\begin{cmdsyntax} -\ci{phantomsection} -\end{cmdsyntax} - -\noindent -This sets an anchor at this location. It works similar to -\verb|\hypertarget{}{}| with an automatically chosen anchor name. -Often it is used in conjunction -with \verb|\addcontentsline| for sectionlike things (index, bibliography, -preface). \verb|\addcontentsline| refers to the latest previous location -where an anchor is set. Example: -\begin{quote} -\begin{verbatim} -\cleardoublepage -\phantomsection -\addcontentsline{toc}{chapter}{\indexname} -\printindex -\end{verbatim} -\end{quote} -Now the entry in the table of contents (and bookmarks) for the -index points to the start of the index page, not to a location -before this page. - -\begin{cmdsyntax} -\ci{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} - -\noindent -This is a replacement for the usual \verb|\ref| command that places a -contextual label in front of the reference. This gives your users a -bigger target to click for hyperlinks (e.g.\ `section 2' instead of -merely the number `2'). - -The label is worked out from the context of the original \verb|\label| -command by \textsf{hyperref} by using the macros listed below (shown -with their default values). The macros can be (re)defined in documents -using \verb|\(re)newcommand|; note that some of these macros are already -defined in the standard document classes. The mixture of lowercase and -uppercase initial letters is deliberate and corresponds to the author's -practice. - -For each macro below, \textsf{hyperref} checks \ci{*autorefname} before -\ci{*name}. For instance, it looks for \ci{figureautorefname} before -\ci{figurename}. - -\begin{longtable}{@{}lp{10cm}@{}} -\textit{Macro} & \textit{Default} \\ -\ci{figurename} & Figure \\ -\ci{tablename} & Table \\ -\ci{partname} & Part \\ -\ci{appendixname} & Appendix \\ -\ci{equationname} & Equation \\ -\ci{Itemname} & item \\ -\ci{chaptername} & chapter \\ -\ci{sectionname} & section \\ -\ci{subsectionname} & subsection \\ -\ci{subsubsectionname} & subsubsection \\ -\ci{paragraphname} & paragraph \\ -\ci{Hfootnotename} & footnote \\ -\ci{AMSname} & Equation \\ -\ci{theoremname} & Theorem\\ -\ci{page} & page\\ -\end{longtable} - -Example for a redefinition if \textsf{babel} is used: -\begin{quote} -\begin{verbatim} -\usepackage[ngerman]{babel} -\addto\extrasngerman{% - \def\subsectionautorefname{Unterkapitel}% -} -\end{verbatim} -\end{quote} - -Hint: \cs{autoref} works via the counter name that the reference -is based on. Sometimes \cs{autoref} chooses the wrong name, if -the counter is used for different things. For example, it happens -with \cs{newtheorem} if a lemma shares a counter with theorems. -Then package \xpackage{aliascnt} provides a method to generate a -simulated second counter that allows the differentiation between -theorems and lemmas: -\begin{quote} -\begin{verbatim} -\documentclass{article} - -\usepackage{aliascnt} -\usepackage{hyperref} - -\newtheorem{theorem}{Theorem} - -\newaliascnt{lemma}{theorem} -\newtheorem{lemma}[lemma]{Lemma} -\aliascntresetthe{lemma} - -\providecommand*{\lemmaautorefname}{Lemma} - -\begin{document} - -We will use \autoref{a} to prove \autoref{b}. - -\begin{lemma}\label{a} - Nobody knows. -\end{lemma} - -\begin{theorem}\label{b} - Nobody is right. -\end{theorem}. - -\end{document} -\end{verbatim} -\end{quote} - -\begin{cmdsyntax} -\ci{autopageref}\verb|{|\emph{label}\verb|}| -\end{cmdsyntax} - -\noindent -It replaces \verb|\pageref| and adds the name for page in front of -the page reference. First \ci{pageautorefname} is checked before -\ci{pagename}. - -For instances where you want a reference to use the correct counter, but -not to create a link, there are starred forms (these starred forms exist even if -hyperref has been loaded with \verb|implicit=false|): - -\begin{cmdsyntax} -\ci{ref*}\verb|{|\emph{label}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{pageref*}\verb|{|\emph{label}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{autoref*}\verb|{|\emph{label}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{autopageref*}\verb|{|\emph{label}\verb|}| -\end{cmdsyntax} - -A typical use would be to write -\begin{verbatim} -\hyperref[other]{that nice section (\ref*{other}) we read before} -\end{verbatim} - -We want \verb|\ref*{other}| to generate the correct number, but not to -form a link, since we do this ourselves with \ci{hyperref}. - -\begin{cmdsyntax} -\ci{pdfstringdef}\verb|{|\emph{macroname}\verb|}{|\emph{\TeX string}\verb|}| -\end{cmdsyntax} - -\ci{pdfstringdef} returns a macro containing the PDF string. (Currently -this is done globally, but do not rely on it.) All the following tasks, -definitions and redefinitions are made in a group to keep them local: - -\begin{itemize} -\item Switching to PD1 or PU encoding -\item Defining the \Quote{octal sequence commands} (\verb|\345|): \verb|\edef\3{\string\3}| -\item Special glyphs of \TeX: \verb|\{|, \verb|\%|, \verb|\&|, \verb|\space|, \verb|\dots|, etc. -\item National glyphs (\textsf{german.sty}, \textsf{french.sty}, etc.) -\item Logos: \verb|\TeX|, \verb|\eTeX|, \verb|\MF|, etc. -\item Disabling commands that do not provide useful functionality in bookmarks: -\verb|\label|, \verb|\index|, \verb|\glossary|, \verb|\discretionary|, \verb|\def|, \verb|\let|, etc. -\item \LaTeX's font commands like \verb|\textbf|, etc. -\item Support for \verb|\xspace| provided by the \xpackage{xspace} package -\end{itemize} - -In addition, parentheses are protected to avoid the danger of unsafe -unbalanced parentheses in the PDF string. For further details, see Heiko -Oberdiek's Euro\TeX\ paper distributed with \textsf{hyperref}. - -\begin{cmdsyntax} -\ci{begin}\verb|{NoHyper}|\ldots\ci{end}\verb|{NoHyper}| -\end{cmdsyntax} - Sometimes we just don't want the wretched package interfering - with us. Define an environment we can put in manually, or include - in a style file, which stops the hypertext functions doing anything. - This is used, for instance, in the Elsevier classes, to stop - \verb|hyperref| playing havoc in the front matter. - -\subsection{Bookmark macros} - -\subsubsection{Setting bookmarks} - -Usually \textsf{hyperref} automatically adds bookmarks for -\verb|\section| and similar macros. But they can also set manually. - -\begin{cmdsyntax} -\ci{pdfbookmark}\verb|[|\emph{level}\verb|]{|text\verb|}{|\emph{name}\verb|}| -\end{cmdsyntax} -creates a bookmark with the specified text and at the given level (default is -0). As name for the internal anchor name is used (in conjunction with -level). Therefore the name must be unique (similar to \verb|\label|). - -\begin{cmdsyntax} -\ci{currentpdfbookmark}\verb|{|\emph{text}\verb|}{|\emph{name}\verb|}| -\end{cmdsyntax} -creates a bookmark at the current level. - -\begin{cmdsyntax} -\ci{subpdfbookmark}\verb|{|\emph{text}\verb|}{|\emph{name}\verb|}| -\end{cmdsyntax} -creates a bookmark one step down in the bookmark hierarchy. -Internally the current level is increased by one. - -\begin{cmdsyntax} -\ci{belowpdfbookmark}\verb|{|\emph{text}\verb|}{|\emph{name}\verb|}| -\end{cmdsyntax} -creates a bookmark below the current bookmark level. However after the -command the current bookmark level has not changed. - -\noindent \textbf{Hint:} Package \textsf{bookmark} replaces -\textsf{hyperref}'s bookmark organization by a new algorithm: -\begin{itemize} -\item Usually only one \LaTeX\ run is needed. -\item More control over the bookmark appearance (color, font). -\item Different bookmark actions are supported (external file links, - URLs, \dots). -\end{itemize} -Therefore I recommend using this package. - -\subsubsection{Replacement macros}\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, -or font changes, none of which will display in bookmarks as is. - -\begin{cmdsyntax} -\ci{texorpdfstring}\verb|{|\emph{\TeX string}\verb|}{|\emph{PDFstring}\verb|}| -\end{cmdsyntax} - -For example, -\begin{verbatim} -\section{Pythagoras: - \texorpdfstring{$ a^2 + b^2 = c^2 $}{% - a\texttwosuperior\ + b\texttwosuperior\ = - c\texttwosuperior - }% -} -\section{\texorpdfstring{\textcolor{red}}{}{Red} Mars} -\end{verbatim} - -\ci{pdfstringdef} executes the hook \pdfstringdefPreHook before it -expands the string. Therefore, you can use this hook to perform -additional tasks or to disable additional commands. - -\begin{verbatim} -\expandafter\def\expandafter\pdfstringdefPreHook -\expandafter{% - \pdfstringdefPreHook - \renewcommand{\mycommand}[1]{}% -} -\end{verbatim} - -However, for disabling commands, an easier way is via -\ci{pdfstringdefDisableCommands}, which adds its argument to the -definition of \ci{pdfstringdefPreHook} (`@' can here be used as letter in -command names): - -\begin{verbatim} -\pdfstringdefDisableCommands{% - \let~\textasciitilde - \def\url{\pdfstringdefWarn\url}% - \let\textcolor\@gobble -} -\end{verbatim} - -\subsection{Pagelabels} -\begin{cmdsyntax} -\ci{thispdfpagelabel}\verb|{|\emph{page number format}\verb|}| -\end{cmdsyntax} - -This allows to change format of the page number shown in the tool bar of -a PDF viewer for a specific page, for example - -\verb+\thispdfpagelabel{Empty Page-\roman{page}}+ - -The command affects the page on which it is executed, so asynchronous page breaking -should be taken into account. It should be used in places where for example \verb+\thispagestyle+ can be use too. - -\subsection{Utility macros} - -\label{hypercalcbp} -\begin{cmdsyntax} -\ci{hypercalcbp}\verb|{|\emph{dimen specification}\verb|}| -\end{cmdsyntax} -\noindent -\verb|\hypercalcbp| takes a \TeX\ dimen specification and -converts it to bp and returns the number without the unit. -This is useful for options \verb|pdfview|, \verb|pdfstartview| -and \verb|pdfremotestartview|. -Example: -\begin{quote} -\begin{verbatim} -\hypersetup{ - pdfstartview={FitBH \hypercalcbp{\paperheight-\topmargin-1in - -\headheight-\headsep} -} -\end{verbatim} -\end{quote} -The origin of the PDF coordinate system is the lower left corner. - -Note, for calculations you need either package \xpackage{calc} or -\hologo{eTeX}. Nowadays the latter should automatically be enabled -for \hologo{LaTeX} formats. Users without \hologo{eTeX}, please, look -in the source documentation \verb|hyperref.dtx| for further -limitations. - -Also \cs{hypercalcbp} cannot be used in option specifications -of \cs{documentclass} and \cs{usepackage}, because -\hologo{LaTeX} expands the option lists of these commands. However -package \xpackage{hyperref} is not yet loaded and an undefined control -sequence error would arise. - -\section[New Features]{New Features% -\footnote{This section moved from the README file, needs more integration into the manual}} - - -\subsection{Option `pdflinkmargin'} - - Option `pdflinkmargin' is an experimental option for specifying - a link margin, if the driver supports this. Default is 1 pt for - supporting drivers. - - -\begin{description} -\item[pdfTeX] -\begin{itemize} - \item The link area also depends on the surrounding box. - \item Settings have local effect. - \item When a page is shipped out, pdfTeX uses the current setting - of the link margin for all links on the page. -\end{itemize} - -\item[pdfmark] -\begin{itemize} - \item Settings have global effect. -\end{itemize} - -\item[xetex] -\begin{itemize} - \item Settings must be done in the preamble or the first page and then have global effect. - The key inserts the new (x)dvipdfmx special \verb|\special{dvipdfmx:config g #1}| (with the unit removed). -\end{itemize} - -\item[Other drivers] - Unsupported. -\end{description} - - -\subsection{Field option `calculatesortkey'} - - Fields with calculated values are calculated in document order - by default. If calculated field values depend on other calculated - fields that appear later in the document, then the correct calculation - order can be specified with option `calculatesortkey'. Its value is - used as key to lexicographically sort the calculated fields. - The sort key do not need to be unique. Fields that share the same - key are sorted in document order. - - - - Currently the field option `calculatesortkey' is only supported by - the driver for pdfTeX. - -\subsection{Option `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'} - - 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 \hologo{HanTheThanh}. Correctly written it needs some - accented characters, one character even with a double accent. - Class `tugboat.cls' defines a macro for the typesetted name: -\begin{verbatim} - \def\Thanh{% - H\`an~% - Th\^e\llap{\raise 0.5ex\hbox{\'{}}}% - ~Th\`anh% - } -\end{verbatim} - It's not entirely correct, the second accent over the `e' is not - an acute, but a hook. However standard LaTeX does not provide - such an accent. - - Now we can extend the definition to support hyperref. - The first and the last word are already supported automatically. - Characters with two or more accents are a difficult business in - LaTeX, because the NFSS2 macros of the LaTeX kernel do not support - more than one accent. Therefore also puenc.def misses support for - them. But we can provide it using \verb|\unichar|. The character - in question is: -\begin{verbatim} - % U+1EC3 LATIN SMALL LETTER E WITH CIRCUMFLEX AND HOOK ABOVE -\end{verbatim} - Thus we can put this together: -\begin{verbatim} - \def\Thanh{% - H\`an~% - \texorpdfstring{Th\^e\llap{\raise 0.5ex\hbox{\'{}}}}% - {\ifpdfstringunicode{Th\unichar{"1EC3}}{Th\^e}}% - ~Th\`anh% - } -\end{verbatim} - For PDFDocEncoding (PD1) the variant above has dropped the - second accent. Alternatively we could provide a representation - without accents instead of wrong accents: -\begin{verbatim} - \def\Thanh{% - \texorpdfstring{% - H\`an~% - Th\^e\llap{\raise 0.5ex\hbox{\'{}}}}% - ~Th\`anh% - }{% - \ifpdfstringunicode{% - H\`an Th\unichar{"1EC3} Th\`anh% - }{% - Han The Thanh% - }% - }% - } -\end{verbatim} - -\subsection{Customizing index style file with \textbackslash nohyperpage} - - Since version 2008/08/14~v6.78f. - - - - For hyperlink support in the index, hyperref inserts \verb|\hyperpage| - into the index macros. After processing with Makeindex, \verb|\hyperpage| - analyzes its argument to detect page ranges and page comma lists. - However, only the standard settings are supported directly: -\begin{verbatim} - delim_r "--" - delim_n ", " -\end{verbatim} - (See manual page/documentation of Makeindex that explains - the keys that can be used in style files for Makeindex.) - Customized versions of - \verb|delim_r, delim_n, suffix_2p, suffix_3p, suffix_mp| - needs markup that \verb|\hyperpage| can detect and knows that - this stuff does not belong to a page number. Makro - \verb|\nohyperpage| serves as this markup. Put the customized - code for these keys inside \verb|\nohyperpage|, e.g.: -\begin{verbatim} - suffix_2p "\\nohyperpage{f.}" - suffix_3p "\\nohyperpage{ff.}" -\end{verbatim} - (Depending on the typesetting tradition some space ``\verb|\\|,'' or ``\verb|~|'' - should be put before the first f inside \verb|\nohyperpage|.) - - -\subsection{Experimental option `ocgcolorlinks'} - - The idea are colored links, when viewed, but printed without colors. - This new experimental option `ocgcolorlinks' uses Optional Content - Groups, a feature introduced in PDF 1.5. - - A better implementation which hasn't the disadvantage to prevent line breaks is - in the ocgx2 package. Check its documentation for details how to use it. -\begin{itemize} - \item The option must be given for package loading: - \verb|\usepackage[ocgcolorlinks]{hyperref}| - \item Main disadvantage: Links cannot be broken across lines. - PDF reference 1.7: 4.10.2 ``Making Graphical Content Optional'': - Graphics state operations, such as setting the color, ..., - are still applied. - Therefore the link text is put in a box and set twice, with and - without color. - \item The feature can be switched of by \verb|\hypersetup{ocgcolorlinks=false}| - inside the document. - \item Supported drivers: pdftex, dvipdfm - \item The PDF version should be at least 1.5. It is automatically - set for pdfTeX, LuaTeX and dvipdfmx. -\end{itemize} - -\subsection{Option `pdfa'} - - The new option `pdfa' tries to avoid violations of PDF/A in code - generated by hyperref. However, the result is usually not in PDF/A, - because many features aren't controlled by hyperref (XMP metadata, - fonts, colors, driver dependend low level stuff, ...). - - - - Currently, option `pdfa' sets and disables the following items: -\begin{itemize} - \item Enabled annotation flags: Print, NoZoom, NoRotate [PDF/A 6.5.3]. - \item Disabled annotation flags: Hidden, Invisible, NoView [PDF/A 6.5.3]. - \item Disabled: Launch action (\href{run:...} [PDF/A 6.6.1]. - \item Restricted: Named actions (\Acrobatmenu: NextPage, PrevPage, - FirstPage, LastPage) [PDF/A 6.6.1]. - \item Many things are disabled in PDF formulars: - \begin{itemize} - \item JavaScript actions [PDF/A 6.6.1] - \item Trigger events (additional actions) [PDF/A 6.6.2] - \item Push button (because of JavaScript) - \item Interactive Forms: Flag NeedAppearances is the default `false' - (Because of this, hyperref's implementation of Forms looks ugly). - [PDF/A 6.9] - \end{itemize} -\end{itemize} - - - - The default value of the new option `pdfa' is `false'. It influences - the loading of the package and cannot be changed after hyperref is - loaded (\verb|\usepackage{hyperref}|). - - - -\subsection{Option `linktoc' added} - - The new option `linktoc' allows more control which part - of an entry in the table of contents is made into a link: -\begin{itemize} - \item `linktoc=none' (no links) - \item `linktoc=section' (default behaviour, same as `linktocpage=false') - \item `linktoc=page' (same as `linktocpage=true') - \item `linktoc=all' (both the section and page part are links) -\end{itemize} - -\subsection{Option `pdfnewwindow' changed} - - Before 6.77b: -\begin{itemize} - \item pdfnewwindow=true $\rightarrow$ /NewWindow true - \item pdfnewwindow=false $\rightarrow$ (absent) - \item unused pdfnewwindow $\rightarrow$ (absent) -\end{itemize} - Since 6.77b: -\begin{itemize} - \item pdfnewwindow=true $\rightarrow$ /NewWindow true - \item pdfnewwindow=false $\rightarrow$ /NewWindow false - \item pdfnewwindow={} $\rightarrow$ (absent) - \item unused pdfnewwindow $\rightarrow$ (absent) -\end{itemize} - - - - Rationale: There is a difference between setting to `false' - and an absent entry. In the former case the new document - replaces the old one, in the latter case the PDF viewer - application should respect the user preference. - - -\subsection{Flag options for PDF forms} - - PDF form field macros (\verb|\TextField|, \verb|\CheckBox|, ...) support - boolean flag options. The option name is the lowercase - version of the names in the PDF specification (1.7): - - \url{http://www.adobe.com/devnet/pdf/pdf_reference.html} - - \url{http://www.adobe.com/devnet/acrobat/pdfs/pdf_reference.pdf} - - Options (convert to lowercase) except flags in square brackets: - -\begin{itemize} - \item Table 8.16 Annotation flags (page 608): - -{\obeylines - 1 Invisible - 2 Hidden (PDF 1.2) - 3 Print (PDF 1.2) - 4 NoZoom (PDF 1.3) - 5 NoRotate (PDF 1.3) - 6 NoView (PDF 1.3) - [7 ReadOnly (PDF 1.3)] ignored for widget annotations, see table 8.70 - 8 Locked (PDF 1.4) - 9 ToggleNoView (PDF 1.5) - 10 LockedContents (PDF 1.7) -} - \item Table 8.70 Field flags common to all field types (page 676): - -{\obeylines - 1 ReadOnly - 2 Required - 3 NoExport -} - \item Table 8.75 Field flags specific to button fields (page 686): - -{\obeylines - 15 NoToggleToOff (Radio buttons only) - 16 Radio (set: radio buttons, clear: check box, pushbutton: clear) - 17 Pushbutton - 26 RadiosInUniso (PDF 1.5) -} - \item Table 8.77 Field flags specific to text fields (page 691): - -{\obeylines - 13 Multiline - 14 Password - 21 FileSelect (PDF 1.4) - 23 DoNotSpellCheck (PDF 1.4) - 24 DoNotScroll (PDF 1.4) - 25 Comb (PDF 1.5) - 26 RichText (PDF 1.5) -} - \item Table 8.79 Field flags specific to choice fields (page 693): - -{\obeylines - 18 Combo (set: combo box, clear: list box) - 19 Edit (only useful if Combo is set) - 20 (Sort) for authoring tools, not PDF viewers - 22 MultiSelect (PDF 1.4) - 23 DoNotSpellCheck (PDF 1.4) (only useful if Combo and Edit are set) - 27 CommitOnSelChange (PDF 1.5) -} - \item Table 8.86 Flags for submit-form actions (page 704): - -{\obeylines - [1 Include/Exclude] unsupported, use `noexport' (table 8.70) instead - 2 IncludeNoValueFields - [3 ExportFormat] handled by option `export' - 4 GetMethod - 5 SubmitCoordinates - [6 XFDF (PDF 1.4)] handled by option `export' - 7 IncludeAppendSaves (PDF 1.4) - 8 IncludeAnnotations (PDF 1.4) - [9 SubmitPDF (PDF 1.4)] handled by option `export' - 10 CanonicalFormat (PDF 1.4) - 11 ExclNonUserAnnots (PDF 1.4) - 12 ExclFKey (PDF 1.4) - 14 EmbedForm (PDF 1.5) -} -\end{itemize} - - New option `export' sets the export format of a submit action. - Valid values are (upper- or lowercase): -\begin{itemize} - \item FDF - \item HTML - \item XFDF - \item PDF (not supported by Acrobat Reader) -\end{itemize} - -\subsection{Option `pdfversion'} - - This is an experimental option. It notifies `hyperref' about - the intended PDF version. Currently this is used in code for - PDF forms (implementation notes 116 and 122 of PDF spec 1.7). - - - - Values: 1.2, 1.3, 1.4, 1.5, 1.6, 1.7. Values below 1.2 are not - supported, because most drivers expect higher PDF versions. - - - - The option must be used early, not after \verb|\usepackage{hyperref}|. - - - In theory this option should also set the PDF version, - but this is not generally supported. -\begin{itemize} - \item pdfTeX below 1.10a: unsupported. - pdfTeX $\ge$ 1.10a and < 1.30: \verb|\pdfoptionpdfminorversion| - pdfTeX $\ge$ 1.30: \verb|\pdfminorversion| - \item dvipdfm: configuration file, example: - TeX Live 2007, texmf/dvipdfm/config/config, entry `V 2'. - \item dvipdfmx: configuration file, example: - TeX Live 2007, texmf/dvipdfm/dvipdfmx.cfg, entry `V 4'. - \item Ghostscript: option -dCompatibilityLevel (this is set in - `ps2pdf12', `ps2pdf13', `ps2pdf14'). -\end{itemize} - - - The current PDF version is used as default if this version - can be detected (only pdfTeX $\ge$ 1.10a). Otherwise the lowest - version 1.2 is assumed. Thus `hyperref' tries to avoid PDF code - that breaks this version, but is free to use ignorable higher PDF - features. - - -\subsection{Field option `name'} - - Many form objects uses the label argument - for several purposes: -\begin{itemize} - \item Layouted label. - \item As name in HTML structures. -\end{itemize} - Code that is suitable for layouting with TeX can - break in the structures of the output format. - If option `name' is given, then its value is used - as name in the different output structures. Thus - the value should consist of letters only. - - -\subsection{Option `pdfencoding'} - - The PDF format allows two encodings for bookmarks and entries - in the information dictionary: PDFDocEncoding and Unicode - as UTF-16BE. Option \xoption{pdfencoding} selects between these encodings: -\begin{itemize} - \item \xoption{pdfdoc} uses PDFDocEncoding. It uses just one byte per character, - but the supported characters are limited (244 in PDF-1.7). - \item \xoption{unicode} sets Unicode. It is encoded as UTF-16BE. Two bytes - are used for most characters, surrogates need four bytes. - \item \xoption{auto} PDFDocEncoding if the string does not contain characters - outside the encoding (outside ascii if an unicode engine is used) - and Unicode otherwise. This option is not intended for the unicode engines. -\end{itemize} - - All drivers use \xoption{unicode} by default now. If another encoding should be forced, - it should be done in \verb|hypersetup|. - -\subsection{Color options/package hycolor} - - See documentation of package `hycolor'. - - -\subsection{Option pdfusetitle} - - If option pdfusetitle is set then hyperref tries to - derive the values for pdftitle and pdfauthor from - \verb|\title| and \verb|\author|. An optional argument for \verb|\title| and - \verb|\author| is supported (class amsart). - - -\subsection{Starred form of \textbackslash autoref} - - \verb|\autoref*| generates a reference without link as \verb|\ref*| or \verb|\pageref*|. - - -\subsection{Link border style} - - Links can be underlined instead of the default rectangle or - options \xoption{colorlinks}, \xoption{frenchlinks}. This is done by option - \verb|pdfborderstyle={/S/U/W 1}| - - Some remarks: - -\begin{itemize} - \item AR7/Linux seems to have a bug, that don't use the default - value \verb"1" for the width, but zero, thus that the underline - is not visible without \verb"/W 1". The same applies for - dashed boxes, eg.: - pdfborderstyle={/S/D/D[3 2]/W 1} - - \item The syntax is described in the PDF specification, look for - ``border style'', eg. - Table 8.13 ``Entries in a border style dictionary'' - (specification for version 1.6) - - \item The border style is removed by - pdfborderstyle={} - This is automatically done if option colorlinks is enabled. - - \item Be aware that not all PDF viewers support this feature, not - even Acrobat Reader itself: - - Some support: - \begin{itemize} - \item AR7/Linux: \xoption{underline} and \xoption{dashed}, but the border width - must be given. - \item xpdf 3.00: \xoption{underline} and \xoption{dashed} - \end{itemize} - - Unsupported: - \begin{itemize} - \item AR5/Linux - \item ghostscript 8.50 - \end{itemize} -\end{itemize} - -\subsection{Option \xoption{bookmarksdepth}} - - The depth of the bookmarks can be controlled by the new - option \xoption{bookmarksdepth}. The option acts globally and - distinguishes three cases: -\begin{itemize} - \item \xoption{bookmarksdepth} without value - Then hyperref uses the current value of counter \xoption{tocdepth}. - This is the compatible behaviour and the default. - \item \verb"bookmarksdepth=", the value is number (also negative): - The depth for the bookmarks are set to this number. - \item \verb"bookmarksdepth=" - The 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@|. - Examples: -\begin{verbatim} - \hypersetup{bookmarksdepth=paragraph} - \hypersetup{bookmarksdepth=4} % same as before - \hypersetup{bookmarksdepth} % counter "tocdepth" is used -\end{verbatim} -\end{itemize} - -\subsection{Option \xoption{pdfescapeform}} - - There are many places where arbitrary strings end up as - PS or PDF strings. The PS/PDF strings in parentheses form - require the protection of some characters, e.g. unmatched - left or right parentheses need escaping or the escape - character itself (backslash). - Since 2006/02/12~v6.75a the PS/PDF driver should do - this automatically. However I assume a problem with - compatibility, especially regarding the form part where - larger amounts of JavaScript code can be present. - It would be a pain to remove all the escaping, because - an additional escaping layer can falsify the code. - - Therefore a new option pdfescapeform was introduced: -\begin{itemize} - \item pdfescapeform=false - Escaping for the formulars are disabled, this is - the compatibility behaviour, therefore this is the default. - \item pdfescapeform=true - Then the PS/PDF drivers do all the necessary escaping. - This is the logical choice and the recommended setting. - For example, the user writes JavaScript as JavaScript - and do not care about escaping characters for PS/PDF - output. -\end{itemize} - -\subsection{Default driver setting} - - (hyperref $\ge$ 6.72s) - If no driver is given, hyperref tries its best to guess the - most suitable driver. Thus it loads \xoption{hpdftex}, if pdfTeX is - detected running in PDF mode. Or it loads the corresponding - VTeX driver for VTeX's working modes. - Unhappily many driver programs run after the TeX compiler, - so hyperref does not have a chance (dvips, dvipdfm, ...). - In this case driver \xoption{hypertex} is loaded that supports the - HyperTeX features that are recognized by xdvi for example. - This behaviour, however, can easily be changed in the configuration - file \verb"hyperref.cfg": -\begin{verbatim} - \providecommand*{\Hy@defaultdriver}{hdvips} -\end{verbatim} - for dvips, or -\begin{verbatim} - \providecommand*{\Hy@defaultdriver}{hypertex} -\end{verbatim} - for the default behaviour of hyperref. - - See also the new option `driverfallback'. - -\subsection{Backref entries} - - Alternative interface for formatting of backref entries, example: - -\begin{verbatim} -\documentclass[12pt,UKenglish]{article} - -\usepackage{babel} -\usepackage[pagebackref]{hyperref} - -% Some language options are detected by package backref. -% This affects the following macros: -% \backrefpagesname -% \backrefsectionsname -% \backrefsep -% \backreftwosep -% \backreflastsep - -\renewcommand*{\backref}[1]{ - % default interface - % #1: backref list - % - % We want to use the alternative interface, - % therefore the definition is empty here. -} -\renewcommand*{\backrefalt}[4]{% - % alternative interface - % #1: number of distinct back references - % #2: backref list with distinct entries - % #3: number of back references including duplicates - % #4: backref list including duplicates - \par - #3 citation(s) on #1 page(s): #2,\par - \ifnum#1=1 % - \ifnum#3=1 % - 1 citation on page % - \else - #3 citations on page % - \fi - \else - #3 citations on #1 pages % - \fi - #2,\par - \ifnum#3=1 % - 1 citation located at page % - \else - #3 citations located at pages % - \fi - #4.\par -} - -% The list of distinct entries can be further refined: -\renewcommand*{\backrefentrycount}[2]{% - % #1: the original backref entry - % #2: the count of citations of this entry, - % in case of duplicates greater than one - #1% - \ifnum#2>1 % - ~(#2)% - \fi -} - -\begin{document} - - \section{Hello} - \cite{ref1, ref2, ref3, ref4} - \section{World} - \cite{ref1, ref3} - \newpage - - \section{Next section} - \cite{ref1} - \newpage - - \section{Last section} - \cite{ref1, ref2} - \newpage - - \pdfbookmark[1]{Bibliography}{bib} - \begin{thebibliography}{99} - \bibitem{ref1} Dummy entry one. - - \bibitem{ref2} Dummy entry two. - - \bibitem{ref3} Dummy entry three. - - \bibitem{ref4} Dummy entry four. - - \end{thebibliography} - -\end{document} -\end{verbatim} - -\subsection{\textbackslash phantomsection} - -Set an anchor at this location. It is often used in conjunction -with \verb|\addcontentsline| for sectionlike things (index, bibliography, -preface). \verb|\addcontentsline| refers to the latest previous location -where an anchor is set. - -\begin{verbatim} - \cleardoublepage - \phantomsection - \addcontentsline{toc}{chapter}{\indexname} - \printindex -\end{verbatim} - -Now the entry in the table of contents (and bookmarks) for the -index points to the start of the index page, not to a location -before this page. - -\subsection{puenc encoding, puenc-greek.def and puenc-extra.def} - -The \texttt{unicode} option loads for the bookmarks \texttt{puenc.def} which contains -quite a lot definitions of commands for the bookmarks. -As \texttt{unicode} is now true for all engines, this file is now also loaded -with pdflatex. Some of the definitions in \texttt{puenc.def} clash with other uses. -To reduce the impact \xpackage{hyperref} uses two strategies. - -\begin{itemize} -\item A number of command are only defined conditionally: -The commands for the cyrillic block if \cs{CYRDZE} is defined, -greek if \cs{textBeta} is defined, and hebrew if \cs{hebdalet} is defined. - -The greek block is in an extra file, \texttt{puenc-greek.def}, which can -be loaded manually if needed. - -\item Other commands are moved to an extra file \texttt{puenc-extra.def} -which is not loaded automatically, but can be loaded in the preamble if needed. -Currently this file contains all definitions for the accent \cs{G}. -\end{itemize} - - - -\section{Acrobat-specific behavior} -If you want to access the menu options of Acrobat Reader or Exchange, the following -macro is provided in the appropriate drivers: - -\begin{cmdsyntax} -\ci{Acrobatmenu}\verb|{|\emph{menuoption}\verb|}{|\emph{text}\verb|}| -\end{cmdsyntax} - -\noindent The \emph{text} is used to create a button which activates the appropriate \emph{menuoption}. The following table lists the option names you can use---comparison of this with the menus in Acrobat Reader or Exchange will show what they do. Obviously some are only appropriate to Exchange. - -\medskip -\begin{longtable}{@{}l>{\raggedright\arraybackslash}p{9cm}@{}} -File & Open, Close, Scan, Save, SaveAs, Optimizer:SaveAsOpt, Print, PageSetup, Quit \\ -File$\rightarrow$Import & ImportImage, ImportNotes, AcroForm:ImportFDF \\ -File$\rightarrow$Export & ExportNotes, AcroForm:ExportFDF \\ -File$\rightarrow$DocumentInfo & GeneralInfo, OpenInfo, FontsInfo, SecurityInfo, Weblink:Base, AutoIndex:DocInfo \\ -File$\rightarrow$Preferences & GeneralPrefs, NotePrefs, FullScreenPrefs, Weblink:Prefs, AcroSearch:Preferences(Windows) - or, AcroSearch:Prefs(Mac), Cpt:Capture \\ -Edit & Undo, Cut, Copy, Paste, Clear, SelectAll, Ole:CopyFile, TouchUp:TextAttributes, - TouchUp:FitTextToSelection, TouchUp:ShowLineMarkers, TouchUp:ShowCaptureSuspects, - TouchUp:FindSuspect, \\ - & Properties \\ -Edit$\rightarrow$Fields & AcroForm:Duplicate, AcroForm:TabOrder \\ -Document & Cpt:CapturePages, AcroForm:Actions, CropPages, RotatePages, InsertPages, ExtractPages, - ReplacePages, DeletePages, NewBookmark, SetBookmarkDest, CreateAllThumbs, - DeleteAllThumbs \\ -View & ActualSize, FitVisible, FitWidth, FitPage, ZoomTo, FullScreen, FirstPage, PrevPage, - NextPage, LastPage, GoToPage, GoBack, GoForward, SinglePage, OneColumn, TwoColumns, - ArticleThreads, PageOnly, ShowBookmarks, ShowThumbs \\ -Tools & Hand, ZoomIn, ZoomOut, SelectText, SelectGraphics, Note, Link, Thread, AcroForm:Tool, - Acro\_Movie:MoviePlayer, TouchUp:TextTool, Find, FindAgain, FindNextNote, - CreateNotesFile \\ -Tools$\rightarrow$Search & AcroSrch:Query, AcroSrch:Indexes, AcroSrch:Results, AcroSrch:Assist, AcroSrch:PrevDoc, - AcroSrch:PrevHit, AcroSrch:NextHit, AcroSrch:NextDoc \\ -Window & ShowHideToolBar, ShowHideMenuBar, ShowHideClipboard, Cascade, TileHorizontal, - TileVertical, CloseAll \\ -Help & HelpUserGuide, HelpTutorial, HelpExchange, HelpScan, HelpCapture, HelpPDFWriter, - HelpDistiller, HelpSearch, HelpCatalog, HelpReader, Weblink:Home \\ -Help(Windows) & About -\end{longtable} - -\section{PDF and HTML forms} -You must put your fields inside a \texttt{Form} environment. -The environment does some general setups, so should be used only once in a document. -Using simply \cs{Form} at the begin of the document is possible too. - -There are six macros to prepare fields: - -\begin{cmdsyntax} -\ci{TextField}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{CheckBox}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{ChoiceMenu}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}{|\emph{choices}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{PushButton}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{Submit}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{Reset}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}| -\end{cmdsyntax} - -The way forms and their labels are laid out is determined by: -\begin{cmdsyntax} -\ci{LayoutTextField}\verb|{|\emph{label}\verb|}{|\emph{field}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{LayoutChoiceField}\verb|{|\emph{label}\verb|}{|\emph{field}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{LayoutCheckField}\verb|{|\emph{label}\verb|}{|\emph{field}\verb|}| -\end{cmdsyntax} - -These macros default to \#1 \#2 - -What is actually shown in the field is determined by: -\begin{cmdsyntax} -\ci{MakeRadioField}\verb|{|\emph{width}\verb|}{|\emph{height}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{MakeCheckField}\verb|{|\emph{width}\verb|}{|\emph{height}\verb|}| -\end{cmdsyntax} -\begin{cmdsyntax} -\ci{MakeTextField}\verb|{|\emph{width}\verb|}{|\emph{height}\verb|}| -\end{cmdsyntax} -\begin{cmdsyntax} -\ci{MakeChoiceField}\verb|{|\emph{width}\verb|}{|\emph{height}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{MakeButtonField}\verb|{|\emph{text}\verb|}| -\end{cmdsyntax} - -These macros default to \verb|\vbox to #2{\hbox to #1{\hfill}\vfill}|, except the -last, which defaults to \#1; it is used for buttons, and the special \ci{Submit} and \ci{Reset} -macros. - -You may also want to redefine the following macros: -\begin{verbatim} -\def\DefaultHeightofSubmit{12pt} -\def\DefaultWidthofSubmit{2cm} -\def\DefaultHeightofReset{12pt} -\def\DefaultWidthofReset{2cm} -\def\DefaultHeightofCheckBox{0.8\baselineskip} -\def\DefaultWidthofCheckBox{0.8\baselineskip} -\def\DefaultHeightofChoiceMenu{0.8\baselineskip} -\def\DefaultWidthofChoiceMenu{0.8\baselineskip} -\def\DefaultHeightofText{\baselineskip} -\def\DefaultHeightofTextMultiline{4\baselineskip} -\def\DefaultWidthofText{3cm} -\end{verbatim} - -\subsection{Forms environment parameters} - -\smallskip -\begin{longtable}{@{}>{\ttfamily}l>{\itshape}lp{9cm}@{}} -action & URL & The URL that will receive the form data if a \textsf{Submit} button is included in the form \\ -encoding & name & The encoding for the string set to the URL; FDF-encoding is usual, and \texttt{html} is the only - valid value \\ -method & name & Used only when generating HTML; values can be \texttt{post} or \texttt{get} \\ -\end{longtable} - -\subsection{Forms optional parameters} -Note that all colors must be expressed as RGB triples, in the range 0..1 (i.e.\ \texttt{color=0 0 -0.5}) - -\smallskip -\begin{longtable}{@{}>{\ttfamily}ll>{\itshape}ll@{}} -accesskey & key & & (as per HTML) \\ -align & number & 0 & alignment within text field; 0 is left-aligned,\\* - & & & 1 is centered, 2 is right-aligned. \\ -altname & name & & alternative name,\\* - & & & the name shown in the user interface\\ -backgroundcolor & & & color of box \\ -bordercolor & & & color of border \\ -bordersep & & & box border gap \\ -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 \\ -charsize & dimen & & font size of field text \\ -checkboxsymbol & char & 4 (\ding{\number`4}) & symbol used for check boxes (ZapfDingbats), \\ -&&& the value is a character or \cs{ding}\verb|{|\texttt{\itshape number}\verb|}|, \\ -&&& see package \xpackage{pifont} from bundle \xpackage{psnfss} \\ -checked & boolean & false & whether option selected by default \\ -color & & & color of text in box \\ -combo & boolean & false & choice list is `combo' style \\ -default & & & default value \\ -disabled & boolean & false & field disabled \\ -format & & & JavaScript code to format the field \\ -height & dimen & & height of field box \\ -hidden & boolean & false & field hidden \\ -keystroke & & & JavaScript code to control the keystrokes on entry \\ -mappingname & name & & the mapping name to be used when exporting\\* - & & & the field data\\ -maxlen & number & 0 & number of characters allowed in text field \\ -menulength & number & 4 & number of elements shown in list \\ -multiline & boolean & false & whether text box is multiline \\ -name & name & & name of field (defaults to label) \\ -onblur & & & JavaScript code \\ -onchange & & & JavaScript code \\ -onclick & & & JavaScript code \\ -ondblclick & & & JavaScript code \\ -onfocus & & & JavaScript code \\ -onkeydown & & & JavaScript code \\ -onkeypress & & & JavaScript code \\ -onkeyup & & & JavaScript code \\ -onmousedown & & & JavaScript code \\ -onmousemove & & & JavaScript code \\ -onmouseout & & & JavaScript code \\ -onmouseover & & & JavaScript code \\ -onmouseup & & & JavaScript code \\ -onselect & & & JavaScript code \\ -password & boolean & false & text field is `password' style \\ -popdown & boolean & false & choice list is `popdown' style \\ -radio & boolean & false & choice list is `radio' style \\ -radiosymbol & char & H (\ding{\number`H}) & symbol used for radio fields (ZapfDingbats), \\ -&&& the value is a character or \cs{ding}\verb|{|\texttt{\itshape number}\verb|}|, \\ -&&& see package \xpackage{pifont} from bundle \xpackage{psnfss} \\ -readonly & boolean & false & field is readonly \\ -rotation & number & 0 & rotation of the widget annotation \\* - & & & (degree, counterclockwise, multiple of 90)\\ -tabkey & & & (as per HTML) \\ -validate & & & JavaScript code to validate the entry \\ -value & & & initial value \\ -width & dimen & & width of field box -\end{longtable} - -\section{Defining a new driver} -A hyperref driver has to provide definitions for eight macros: - -\smallskip -\noindent 1. \verb|\hyper@anchor| - -\noindent 2. \verb|\hyper@link| - -\noindent 3. \verb|\hyper@linkfile| - -\noindent 4. \verb|\hyper@linkurl| - -\noindent 5. \verb|\hyper@anchorstart| - -\noindent 6. \verb|\hyper@anchorend| - -\noindent 7. \verb|\hyper@linkstart| - -\noindent 8. \verb|\hyper@linkend| -\smallskip - -The draft option defines the macros as follows -\begin{verbatim} -\let\hyper@@anchor\@gobble -\gdef\hyper@link##1##2##3{##3}% -\def\hyper@linkurl##1##2{##1}% -\def\hyper@linkfile##1##2##3{##1}% -\let\hyper@anchorstart\@gobble -\let\hyper@anchorend\@empty -\let\hyper@linkstart\@gobbletwo -\let\hyper@linkend\@empty -\end{verbatim} - -\section{Special support for other packages} - -Package \xpackage{hyperref} aims to cooperate with other packages, but there are -several possible sources for conflict, such as - -\begin{itemize} - -\item Packages that manipulate the bibliographic mechanism. Peter -William's \xpackage{harvard} package is supported. However, the -recommended package is Patrick Daly's \xpackage{natbib} package that has -specific \xpackage{hyperref} hooks to allow reliable interaction. This -package covers a very wide variety of layouts and citation styles, all -of which work with \xpackage{hyperref}. - -\item Packages that typeset the contents of the \ci{label} and \ci{ref} -macros, such as \xpackage{showkeys}. Since the \xpackage{hyperref} package -redefines these commands, you must set \texttt{implicit=false} for these -packages to work. - -\item Packages that do anything serious with the index. -\end{itemize} - -The \xpackage{hyperref} package is distributed with variants on two useful -packages designed to work especially well with it. These are \xpackage{xr} -and \xpackage{minitoc}, which support crossdocument links using \hologo{LaTeX}'s -normal \cs{label}/\cs{ref} mechanisms and per-chapter tables of contents, -respectively. - - -\subsection{Package Compatibility} - -Currently only package loading orders are available: - - - -Note: hyperref loads package \xpackage{nameref} at \verb|\begin{document}|. -Sometimes this is too late, thus this package must be loaded -earlier. - - -\subsubsection{algorithm} -\begin{verbatim} - \usepackage{float} - \usepackage{hyperref} - \usepackage[chapter]{algorithm}% eg. -\end{verbatim} - -\subsubsection{amsmath} - - The environments equation and eqnarray are not supported too well. - For example, there might be spacing problems (eqnarray isn't recommended - anyway, see CTAN:info/l2tabu/, the situation for equation is unclear, - because nobody is interested in investigating). Consider using the - environments that package amsmath provide, e.g. gather for equation. - The environment equation can even redefined to use gather: - -\begin{verbatim} - \usepackage{amsmath} - \let\equation\gather - \let\endequation\endgather -\end{verbatim} - -\subsubsection{amsrefs} - - Package loading order: - -\begin{verbatim} - \usepackage{hyperref} - \usepackage{amsrefs} -\end{verbatim} - -\subsubsection{arydshln, longtable} - - Package longtable must be put before hyperref and arydshln, - hyperref after arydshln generates an error, thus the - resulting package order is then: - -\begin{verbatim} - \usepackage{longtable} - \usepackage{hyperref} - \usepackage{arydshln} -\end{verbatim} - -\subsubsection{babel/magyar.ldf} - - The old version 2005/03/30 v1.4j will not work. - You need at least version 1.5, maintained by P\'eter Szab\'o, - see CTAN:language/hungarian/babel/. - - -\subsubsection{babel/spanish.ldf} - - Babel's spanish.ldf redefines `\verb|\.|' to support `\verb|\...|'. - In bookmarks (\verb|\pdfstringdef|) only `\verb|\.|' is supported. - If `\verb|\...|' is needed, - \verb|\texorpdfstring{\...}{\dots}| - can be used instead. - - -\subsubsection{bibentry} - - Workaround: - -\begin{verbatim} - \makeatletter - \let\saved@bibitem\@bibitem - \makeatother - - \usepackage{bibentry} - \usepackage{hyperref} - - \begin{document} - - \begingroup - \makeatletter - \let\@bibitem\saved@bibitem - \nobibliography{database} - \endgroup -\end{verbatim} - -\subsubsection{bigfoot} - - Hyperref does not support package `bigfoot'. And package - `bigfoot' does not support hyperref's footnotes and disables - them (hyperfootnotes=false). - - -\subsubsection{chappg} - - Package `chappg' uses \verb|\@addtoreset| that is redefined by `hyperref'. - The package order is therefore: - -\begin{verbatim} - \usepackage{hyperref} - \usepackage{chappg} -\end{verbatim} - -\subsubsection{cite} - - This is from Mike Shell: - cite.sty cannot currently be used with hyperref. - However, I can do a workaround via: - -\begin{verbatim} - \makeatletter - \def\NAT@parse{\typeout{This is a fake Natbib command to fool Hyperref.}} - \makeatother - - \usepackage[hypertex]{hyperref} -\end{verbatim} - - so that hyperref will not redefine any of the biblabel stuff - so cite.sty - will work as normal - although the citations will not be hyperlinked, of - course (But this may not be an issue for many people). - - -\subsubsection{count1to} - - Package `count1to' adds several \verb|\@addtoreset| commands that confuse - `hyperref'. Therefore \verb|\theH<...>| has to be fixed: - -\begin{verbatim} - \usepackage{count1to} - \AtBeginDocument{% *after* \usepackage{count1to} - \renewcommand*{\theHsection}{\theHchapter.\arabic{section}}% - \renewcommand*{\theHsubsection}{\theHsection.\arabic{subsection}}% - \renewcommand*{\theHsubsubsection}{\theHsubsection.\arabic{subsubsection}}% - \renewcommand*{\theHparagraph}{\theHsubsubsection.\arabic{paragraph}}% - \renewcommand*{\theHsubparagraph}{\theHparagraph.\arabic{subparagraph}}% - } -\end{verbatim} - -\subsubsection{dblaccnt} - - pd1enc.def or puenc.def should be loaded before: -\begin{verbatim} - \usepackage{hyperref} - \usepackage{dblaccnt} -\end{verbatim} - or see entry for \xoption{vietnam}. - - -\subsubsection{easyeqn} - Not compatible, breaks. - - -\subsubsection{ellipsis} - - This packages redefines \verb|\textellipsis| - after package hyperref (pd1enc.def/puenc.def should be loaded before): -\begin{verbatim} - \usepackage{hyperref} - \usepackage{ellipsis} -\end{verbatim} - -\subsubsection{float} -\begin{verbatim} - \usepackage{float} - \usepackage{hyperref} -\end{verbatim} -\begin{itemize} - \item Several \verb|\caption| commands are not supported inside one float object. - \item Anchor are set at top of the float object, if its style is controlled - by float.sty. -\end{itemize} - -\subsubsection{endnotes} - Unsupported. - -\subsubsection{foiltex} - Update to version 2008/01/28 v2.1.4b: - Since version 6.77a hyperref does not hack into \verb|\@begindvi|, - it uses package `atbegshi' instead, that hooks into \verb|\shipout|. - Thus the patch of `foils.cls' regarding hyperref is now obsolete - and causes an undefined error message about \verb|\@hyperfixhead|. - This is fixed in FoilTeX 2.1.4b. - - -\subsubsection{footnote} - - This package is not supported, you have to disable hyperref's footnote - support by using option \verb"hyperfootnotes=false". - - -\subsubsection{geometry} - - Driver `dvipdfm' and program `dvipdfm' might generate a warning: - Sorry. Too late to change page size - Then prefer the program `dvipdfmx' or use one of the following - workarounds to move the \verb|\special| of geometry to an earlier - location: - -\begin{verbatim} - \documentclass[dvipdfm]{article}% or other classes - \usepackage{atbegshi} - \AtBeginDocument{% - \let\OrgAtBeginDvi\AtBeginDvi - \let\AtBeginDvi\AtBeginShipoutFirst - } - \usepackage[ - paperwidth=170mm, - paperheight=240mm - ]{geometry} - \AtBeginDocument{% - \let\AtBeginDvi\OrgAtBeginDvi - } - \usepackage{hyperref} - - or - - \documentclass[dvipdfm]{article}% or other classes - \usepackage{atbegshi} - \let\AtBeginDvi\AtBeginShipoutFirst - \usepackage[ - paperwidth=170mm, - paperheight=240mm - ]{geometry} - \usepackage{hyperref} -\end{verbatim} - -\subsubsection{IEEEtran.cls} - - version $\ge$ V1.6b (because of \verb|\@makecaption|, see ChangeLog) - - -\subsubsection{index} - - version $\ge$ 1995/09/28 v4.1 (because of \verb|\addcontentsline| redefinition) - - -\subsubsection{lastpage} - - Compatible. - - -\subsubsection{linguex} -\begin{verbatim} - \usepackage{hyperref} - \usepackage{linguex} -\end{verbatim} - -\subsubsection{ltabptch} -\begin{verbatim} - \usepackage{longtable} - \usepackage{ltabptch} - \usepackage{hyperref} -\end{verbatim} - -\subsubsection{mathenv} - - Unsupported. - - - - Both `mathenv' and `hyperref' messes around with - environment `eqnarray'. You can load `mathenv' after - `hyperref' to avoid an error message. But \verb|\label| - will not work inside environment `eqnarray' properly, - for example. - - -\subsubsection{minitoc-hyper} - - This package is obsolete, use the up-to-date 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} - - -\subsubsection{ntheorem-hyper} - This package is obsolete, use the up-to-date original - package ntheorem instead. - - -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{setspace} -\begin{verbatim} - \usepackage{setspace} - \usepackage{hyperref} -\end{verbatim} - -\subsubsection{sidecap} -\begin{verbatim} - Before 2002/05/24 v1.5h: - \usepackage{nameref} - \usepackage{hyperref} - \usepackage{sidecap} -\end{verbatim} - -\subsubsection{subfigure} -\begin{verbatim} - 1995/03/06 v2.0: - \usepackage{subfigure} - \usepackage{hyperref} - % hypertexnames is set to false. - v2.1: - \usepackage{nameref} - \usepackage{subfigure} - \usepackage{hyperref} - or - \usepackage{hyperref} - \usepackage{subfigure} - v2.1.2: - please update - v2.1.3: - \usepackage{hyperref} - \usepackage{subfigure} - or vice versa? -\end{verbatim} - -\subsubsection{titleref} -\begin{verbatim} - \usepackage{nameref} - \usepackage{titleref}% without usetoc - \usepackage{hyperref} -\end{verbatim} - -\subsubsection{tabularx} - - Linked footnotes are not supported inside environment `tabularx', - because they uses the optional argument of \verb|\footnotetext|, see - section `Limitations'. Before version 2011/09/28 6.82i - hyperref had disabled footnotes entirely by `hyperfootnotes=false'. - - -\subsubsection{titlesec} - - \xpackage{nameref} supports titlesec, but hyperref does not - (unsolved is the anchor setting, missing with unnumbered - section, perhaps problems with page breaks with numbered ones). - - -\subsubsection{ucs/utf8x.def} - - The first time a multibyte UTF8 sequence is called, it - does some calculations and stores the result in a macro - for speeding up the next calls of that UTF8 sequence. - However this makes the first call non-expandable and - will break if used in information entries or bookmarks. - Package \xpackage{ucs} offers \verb|\PrerenderUnicode| or \verb|\PreloadUnicodePage| - to solve this: -\begin{verbatim} - \usepackage{ucs} - \usepackage[utf8x]{inputenc} - \usepackage{hyperref}% or with option unicode - \PrerenderUnicode{^^c3^^b6}% or \PrerenderUnicodePage{1} - \hypersetup{pdftitle={Umlaut example: ^^c3^^b6}} -\end{verbatim} - The notation with two carets avoids trouble with 8-bit bytes - for the README file, you can use the characters directly. - - -\subsubsection{varioref} - There are too many problems with varioref. Nobody has time to - sort them out. Therefore this package is now unsupported. - - - Perhaps you are lucky and some of the features of varioref works - with the following loading order: -\begin{verbatim} - \usepackage{nameref} - \usepackage{varioref} - \usepackage{hyperref} -\end{verbatim} - - - Also some babel versions can be problematic. For example, - 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 \verb|pdfencoding=unicode|. - That means the strings are always treated as unicode strings. - If \verb|auto| or \verb|pdfdoc| is forced it applies only - if the string restricts to the printable ASCII set, - The reason is that the \verb|\special| does not support PDFDocEncoding. - - In older versions hyperref contained special conversion code from - UTF-16BE back to UTF-8 in a number of places for - xetex to avoid the xdvipdfmx warning - - \verb"Failed to convert input string to UTF16..." - - This is no longer needed with a current xdvipdfmx, so this code has - been removed. \verb|\csname HyPsd@XeTeXBigCharstrue\endcsname| should no - longer be used. - - -\section[Limitations]{Limitations% -\footnote{This section moved from the README file, needs more integration into the manual}} -\subsection{Wrapped/broken link support} - - Only few drivers support automatically wrapped/broken links, - e.g. pdftex, dvipdfm, hypertex. Other drivers lack this - feature, e.g. dvips, dvipsone. - - Workarounds: -\begin{itemize} -\item For long section or caption titles in the table of contents - or list of figures/tables option \xoption{linktocpage} can be used. - Then the page number will be a link, and the overlong section - title is not forced into an one line link with overfull \verb|\hbox| - warning. -\item ``\verb|\url|''s are caught by package \xpackage{breakurl}. -\item The option \xoption{breaklinks} is intended for internal use. But it - can be used to force link wrapping, e.g. when printing a - document. However, when such a document is converted to PDF - and viewed with a PDF viewer, the active link area will be - misplaced. - - Another limitation: some penalties are ``optimized'' by TeX, - thus there are missing break points, especially within - \verb|\url|. (See thread ``hyperref.sty, breaklinks and url.sty 3.2'' - in comp.text.tex 2005-09). -\end{itemize} - -\subsection{Links across pages} - - In general they have problems: -\begin{itemize} - \item Some driver doesn't support them at all (see above). - \item The driver allows it, but the link result might include - the footer and/or header, or an error message can - occur sometimes. -\end{itemize} - -\subsection{Footnotes} - - LaTeX allows the separation of the footnote mark and the - footnote text (\verb|\footnotemark|, \verb|\footnotetext|). This interface - might be enough for visual typesetting. But the relation between - \verb|\footnotemark| to \verb|\footnotetext| is not as strong as \verb|\ref| to \verb|\label|. - Therefore it is not clear in general which \verb|\footnotemark| references - which \verb|\footnotetext|. But that is necessary to implement hyperlinking. - Thus the implementation of hyperref does not support the optional - argument of \verb|\footnotemark| and \verb|\footnotetext|. - - -\section[Hints]{Hints% -\footnote{This section moved from the README file, needs more integration into the manual}} - -\subsection{Spaces in option values} - - Unhappily LaTeX strips spaces from options if they are given - in \verb|\documentclass| or \verb|\usepackage| (or \verb|\RequirePackage|), e.g.: -\begin{verbatim} - \usepackage[pdfborder=0 0 1]{hyperref} -\end{verbatim} - Package hyperref now gets -\begin{verbatim} - pdfborder=001 -\end{verbatim} - and the result is an invalid PDF file. - As workaround braces can be used: -\begin{verbatim} - \usepackage[pdfborder={0 0 1}]{hyperref} -\end{verbatim} - Some options can also be given in \verb|\hypersetup| -\begin{verbatim} - \hypersetup{pdfborder=0 0 1} -\end{verbatim} - In \verb|\hypersetup| the options are directly processed as key value - options (see package keyval) without space stripping in the value part. - - - - Alternatively, LaTeX's option handling system can be adapted - to key value options by one of the packages \xpackage{kvoptions-patch} - (from project \xpackage{kvoptions}) or \xpackage{xkvltxp} (from project \xpackage{xsetkeys}). - - -\subsection{Index with makeindex} -\begin{itemize} - \item Package hyperref adds \verb|\hyperpage| commands by the encap - mechanism (see documentation of Makeindex), - if option hyperindex is set (default). - \verb|\hyperpage| uses the page anchors that are set by - hyperref at each page (default). However in the - default case page numbers are used in anchor names - in arabic form. If the page numbers in other formats - are used (book class with \verb|\frontmatter|, \verb|\romannumbering|, ...), - then the page anchors are not unique. Therefore option - \verb"plainpages=false" is recommended. - \item The encap mechanism of Makeindex allows to use one command only - (see documentation of Makeindex). - If the user sets such a command, hyperref suppresses its - \verb|\hyperpage| command. With logical markup this situation - can easily be solved: -\begin{verbatim} - \usepackage{makeidx} - \makeindex - \usepackage[hyperindex]{hyperref} - \newcommand*{\main}[1]{\textbf{\hyperpage{#1}}} - ... - \index{Some example|main} -\end{verbatim} - \item Scientic Word/Scientific WorkPlace users can use - package robustindex with hyperindex=false. - \item Other encap characters can be set by option \xoption{encap}. - Example for use of ``?'': -\begin{verbatim} - \usepackage[encap=?]{hyperref} -\end{verbatim} - \item Another possibility is the insertion of \verb|\hyperpage| by - a style file for makeindex. For this case, hyperref's - insertion will be disabled by \verb"hyperindex=false". - \verb|\hyperpage| will be defined regardless of setting of hyperindex. -\begin{verbatim} -%%% cut %%% hyperindex.ist %%% cut %%% -delim_0 ", \\hyperpage{" -delim_1 ", \\hyperpage{" -delim_2 ", \\hyperpage{" -delim_n "}, \\hyperpage{" -delim_t "}" -encap_prefix "}\\" -encap_infix "{\\hyperpage{" -encap_suffix "}" -%%% cut %%% hyperindex.ist %%% cut %%% -\end{verbatim} -\end{itemize} - -\subsection{Warning \texttt{"bookmark level for unknown defaults to 0"}} - - Getting rid of it: -\begin{verbatim} -\makeatletter -\providecommand*{\toclevel@}{0} -\makeatother -\end{verbatim} - -\subsection{Link anchors in figures} - - The caption command increments the counter and here is the - place where hyperref set the corresponding anchor. Unhappily - the caption is set below the figure, so the figure is not - visible if a link jumps to a figure. - In this case, try package \xpackage{hypcap} that implements - a method to circumvent the problem. - - -\subsection{Additional unicode characters in bookmarks and pdf information entries:} -\begin{verbatim} -\documentclass[pdftex]{article} -\usepackage[unicode]{hyperref} -\end{verbatim} - -Support for additional unicode characters: - - Example: \verb|\.{a}| and \verb|\d{a}| - - 1. Get a list with unicode data, eg: - - http://www.unicode.org/Public/UNIDATA/UnicodeData.txt - - 2. Identify the characters (\verb|\.{a}|, \verb|\d{a}|): -\begin{verbatim} - 0227;LATIN SMALL LETTER A WITH DOT ABOVE;... - 1EA1;LATIN SMALL LETTER A WITH DOT BELOW;... -\end{verbatim} - - 3. Calculate the octal code: - - The first characters of the line in the file are - hex values, convert each byte and prepend them - with a backslash. (This will go into the PDF file.) - -\begin{verbatim} - 0227 -> \002\047 - 1EA1 -> \036\241 -\end{verbatim} - - 4. Transform into a form understood by hyperref: - - Hyperref must know where the first byte starts, - this is marked by \verb"9" (8 and 9 cannot occur in - octal numbers): - -\begin{verbatim} - \002\047 -> \9002\047 - \036\241 -> \9036\241 -\end{verbatim} - - Optional: \verb"8" is used for abbreviations: - -\begin{verbatim} - \900 = \80, \901 = \81, \902 = \82, ... - - \9002\047 -> \82\047 -\end{verbatim} - - 5. Declare the character with LaTeX: - -\begin{verbatim} -\DeclareTextCompositeCommand{\.}{PU}{a}{\82\047} -\DeclareTextCompositeCommand{\d}{PU}{a}{\9036\241} - -\begin{document} -\section{\={a}, \d{a}, \'{a}, \.{a}} -\end{document} - \end{verbatim} - -\subsection{Footnotes} - - The footnote support is rather limited. It is beyond the scope - to use \verb|\footnotemark| and \verb|\footnotetext| out of order or reusing - \verb|\footnotemark|. Here you can either disable hyperref's footnote - support by \verb"hyperfootnotes=false" or fiddle with internal macros, - nasty examples: - -\begin{verbatim} -\documentclass{article} -\usepackage{hyperref} -\begin{document} -Hello% -\footnote{The first footnote} -World% -\addtocounter{footnote}{-1}% -\addtocounter{Hfootnote}{-1}% -\footnotemark. -\end{document} - - or - -\documentclass{article} - -\usepackage{hyperref} - -\begin{document} - -\makeatletter - -A% - \footnotemark - \let\saved@Href@A\Hy@footnote@currentHref - % remember link name -B% - \footnotemark - \let\saved@Href@B\Hy@footnote@currentHref -b% - \addtocounter{footnote}{-1}% - \addtocounter{Hfootnote}{-1}% generate the same anchor - \footnotemark -C% - \footnotemark - \let\saved@Href@C\Hy@footnote@currentHref - - \addtocounter{footnote}{-2}% - \let\Hy@footnote@currentHref\saved@Href@A -\footnotetext{AAAA}% - \addtocounter{footnote}{1}% - \let\Hy@footnote@currentHref\saved@Href@B -\footnotetext{BBBBB}% - \addtocounter{footnote}{1}% - \let\Hy@footnote@currentHref\saved@Href@C -\footnotetext{CCCC}% - -\end{document} -\end{verbatim} - -\subsection{Subordinate counters} - - Some counters do not have unique values and require the value - of other counters to be unique. For example, sections or figures - might be numbered within chapters or \verb|\newtheorem| is used with - an optional counter argument. Internally LaTeX uses \verb|\@addtoreset| - to reset a counter in dependency to another counter. Package - hyperref hooks into \verb|\@addtoreset| to catch this situation. - Also \verb|\numberwithin| of package amsmath is caught by hyperref. - - - - However, if the definition of subordinate counters take place - before hyperref is loaded, the old meaning of \verb|\@addtoreset| is - called without hyperref's additions. Then the companion counter - macro \verb|\theH| can be redefined accordingly. Or move the - definition of subordinate counters after hyperref is loaded. - - Example for \verb|\newtheorem|, problematic case: -\begin{verbatim} - \newtheorem{corA}{CorollaryA}[section] - \usepackage{hyperref} -\end{verbatim} - Solution a) -\begin{verbatim} - \usepackage{hyperref} - \newtheorem{corA}{CorollaryA}[section} -\end{verbatim} - Solution b) -\begin{verbatim} - \newtheorem{corA}{CorollaryA}[section] - \usepackage{hyperref} - \newcommand*{\theHcorA}{\theHsection.\number\value{corA}} -\end{verbatim} - -\section{History and acknowledgments} - -The original authors of \textsf{hyperbasics.tex} and -\textsf{hypertex.sty}, from which this package descends, are Tanmoy -Bhattacharya and Thorsten Ohl. Package \xpackage{hyperref} -started as a simple port of their work to \hologo{LaTeXe} standards, but -eventually I rewrote nearly everything, because I didn't understand a -lot of the original, and was only interested in getting it to work with -\hologo{LaTeX}. I would like to thank Arthur Smith, Tanmoy Bhattacharya, Mark -Doyle, Paul Ginsparg, David Carlisle, T.\ V.\ Raman and Leslie Lamport -for comments, requests, thoughts and code to get the package into its -first useable state. Various other people are mentioned at the point in -the source where I had to change the code in later versions because of -problems they found. - -Tanmoy found a great many of the bugs, and (even better) often provided -fixes, which has made the package more robust. The days spent on -Rev\TeX\ are entirely due to him! The investigations of Bill Moss -into the later versions including -native PDF support uncovered a good many bugs, and his testing is -appreciated. Hans Hagen provided a lot of -insight into PDF. - -Berthold Horn provided help, encouragement and sponsorship for the -\textsf{dvipsone} and \textsf{dviwindo} drivers. Sergey Lesenko provided -the changes needed for \textsf{dvipdf}, and \Hologo{HanTheThanh} supplied all the -information needed for \textsf{pdftex}. Patrick Daly kindly updated his -\xpackage{natbib} package to allow easy integration with -\xpackage{hyperref}. Michael Mehlich's \xpackage{hyper} package (developed -in parallel with \textsf{hyperref}) showed me solutions for some -problems. Hopefully the two packages will combine one day. - -The forms creation section owes a great deal to: T.\ V.\ Raman, for -encouragement, support and ideas; Thomas Merz, whose book \emph{Web -Publishing with Acrobat/PDF} provided crucial insights; D.\ P.\ Story, -whose detailed article about pdfmarks and forms solved many practical -problems; and Hans Hagen, who explained how to do it in \textsf{pdftex}. - -Steve Peter recreated the manual source in July 2003 after it had been -lost. - -Especial extra thanks to David Carlisle for the \xpackage{backref} module, -the ps2pdf and dviwindo support, frequent general rewrites of my bad -code, and for working on changes to the \xpackage{xr} package to suit -\xpackage{hyperref}. - -\begingroup - \makeatletter - \let\chapter=\section - % subsections goes into bookmarks but not toc - \hypersetup{bookmarksopenlevel=1} - \addtocontents{toc}{\protect\setcounter{tocdepth}{1}} - % The \section command acts as \subsection. - % Additionally the title is converted to lowercase except - % for the first letter. - \def\section{% - \let\section\lc@subsection - \lc@subsection - } - \def\lc@subsection{% - \@ifstar{\def\mystar{*}\lc@sec}% - {\let\mystar\@empty\lc@sec}% - } - \def\lc@sec#1{% - \lc@@sec#1\@nil - } - \def\lc@@sec#1#2\@nil{% - \begingroup - \def\a{#1}% - \lowercase{% - \edef\x{\endgroup - \noexpand\subsection\mystar{\a#2}% - }% - }% - \x - } -\clearpage - - -\chapter{GNU Free Documentation License} - -Version 1.2, November 2002 - - - Copyright \copyright\ 2000,2001,2002 Free Software Foundation, Inc.\\ - 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA\\ - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - -\section*{PREAMBLE} - -The purpose of this License is to make a manual, textbook, or other -functional and useful document ``free'' in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - - -\section{APPLICABILITY AND DEFINITIONS} -\label{applicability} - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document'', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you''. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section of -the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall subject -(or to related matters) and contains nothing that could fall directly -within that overall subject. (Thus, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any -mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``Opaque''. - -Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, \LaTeX\ input format, SGML -or XML using a publicly available DTD, and standard-conforming simple -HTML, PostScript or PDF designed for human modification. Examples of -transparent image formats include PNG, XCF and JPG. Opaque formats -include proprietary formats that can be read and edited only by -proprietary word processors, SGML or XML for which the DTD and/or -processing tools are not generally available, and the -machine-generated HTML, PostScript or PDF produced by some word -processors for output purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -A section ``Entitled XYZ'' means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``Acknowledgements'', -``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' -of such a section when you modify the Document means that it remains a -section ``Entitled XYZ'' according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - - -\section{VERBATIM COPYING} -\label{verbatim} - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in -section~\ref{copying}. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - - -\section{COPYING IN QUANTITY} -\label{copying} - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - - -\section{MODIFICATIONS} -\label{modifications} - -You may copy and distribute a Modified Version of the Document under -the conditions of sections~\ref{verbatim} and \ref{copying} above, -provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -\renewcommand{\labelenumi}{\Alph{enumi}.} -\begin{enumerate} -\item Use in the Title Page (and on the covers, if any) a title distinct - from that of the Document, and from those of previous versions - (which should, if there were any, be listed in the History section - of the Document). You may use the same title as a previous version - if the original publisher of that version gives permission. -\item List on the Title Page, as authors, one or more persons or entities - responsible for authorship of the modifications in the Modified - Version, together with at least five of the principal authors of the - Document (all of its principal authors, if it has fewer than five), - unless they release you from this requirement. -\item State on the Title page the name of the publisher of the - Modified Version, as the publisher. -\item Preserve all the copyright notices of the Document. -\item Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. -\item Include, immediately after the copyright notices, a license notice - giving the public permission to use the Modified Version under the - terms of this License, in the form shown in the Addendum below. -\item Preserve in that license notice the full lists of Invariant Sections - and required Cover Texts given in the Document's license notice. -\item Include an unaltered copy of this License. -\item Preserve the section Entitled ``History'', Preserve its Title, and add - to it an item stating at least the title, year, new authors, and - publisher of the Modified Version as given on the Title Page. If - there is no section Entitled ``History'' in the Document, create one - stating the title, year, authors, and publisher of the Document as - given on its Title Page, then add an item describing the Modified - Version as stated in the previous sentence. -\item Preserve the network location, if any, given in the Document for - public access to a Transparent copy of the Document, and likewise - the network locations given in the Document for previous versions - it was based on. These may be placed in the ``History'' section. - You may omit a network location for a work that was published at - least four years before the Document itself, or if the original - publisher of the version it refers to gives permission. -\item For any section Entitled ``Acknowledgements'' or ``Dedications'', - Preserve the Title of the section, and preserve in the section all - the substance and tone of each of the contributor acknowledgements - and/or dedications given therein. -\item Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section titles. -\item Delete any section Entitled ``Endorsements''. Such a section - may not be included in the Modified Version. -\item Do not retitle any existing section to be Entitled ``Endorsements'' - or to conflict in title with any Invariant Section. -\item Preserve any Warranty Disclaimers. - -\end{enumerate} - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties--for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - - -\section{COMBINING DOCUMENTS} -\label{combining} - -You may combine the Document with other documents released under this -License, under the terms defined in section~\ref{modifications} -above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled ``History'' -in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements'', -and any sections Entitled ``Dedications''. You must delete all sections -Entitled ``Endorsements''. - - -\section{COLLECTIONS OF DOCUMENTS} -\label{collections} - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - - -\section{AGGREGATION WITH INDEPENDENT WORKS} -\label{aggregation} - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an ``aggregate'' if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section~\ref{copying} is applicable to -these copies of the Document, then if the Document is less than one half -of the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - - -\section{TRANSLATION} -\label{translation} - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of -section~\ref{modifications}. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled ``Acknowledgements'', -``Dedications'', or ``History'', the requirement -(section~\ref{modifications}) to Preserve -its Title (section~\ref{applicability}) will typically require -changing the actual title. - - -\section{TERMINATION} -\label{termination} - -You may not copy, modify, sublicense, or distribute the Document except -as expressly provided for under this License. Any other attempt to -copy, modify, sublicense or distribute the Document is void, and will -automatically terminate your rights under this License. However, -parties who have received copies, or rights, from you under this -License will not have their licenses terminated so long as such -parties remain in full compliance. - - -\section{FUTURE REVISIONS OF THIS LICENSE} -\label{future} - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -http://www.gnu.org/copyleft/. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. - - -\section*{ADDENDUM: How to use this License for your documents} - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -\begin{quote} - Copyright \copyright\ YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. - A copy of the license is included in the section entitled ``GNU - Free Documentation License''. -\end{quote} - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with...Texts.'' line with this: - - with the Invariant Sections being LIST THEIR TITLES, with the - Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - -\endgroup - -\end{document} diff --git a/Master/texmf-dist/source/latex/hyperref/hluatex.dtx b/Master/texmf-dist/source/latex/hyperref/hluatex.dtx index 571728645e1..ac45cb0d0ce 100644 --- a/Master/texmf-dist/source/latex/hyperref/hluatex.dtx +++ b/Master/texmf-dist/source/latex/hyperref/hluatex.dtx @@ -1,6 +1,6 @@ % \iffalse % Source File: hluatex.dtx -% 2022-02-21 v7.00n +% 2022-05-13 v7.00o % % Copyright % 2016-2019 Oberdiek Package Support Group @@ -31,7 +31,7 @@ % % \begin{macrocode} %<*luatex> -%% 2022-02-21 v7.00n +%% 2022-05-13 v7.00o %% force unicode encoding, see issue #101 %% code mostly copied from hxetex.def \HyPsd@LoadUnicode diff --git a/Master/texmf-dist/source/latex/hyperref/hyperref-linktarget.dtx b/Master/texmf-dist/source/latex/hyperref/hyperref-linktarget.dtx new file mode 100644 index 00000000000..6ebd482295a --- /dev/null +++ b/Master/texmf-dist/source/latex/hyperref/hyperref-linktarget.dtx @@ -0,0 +1,584 @@ +% \iffalse meta-comment +% +%% File: hyperref-linktarget.dtx +% +% Copyright (C) 2022-2022 The LaTeX Project +% +% It may be distributed and/or modified under the conditions of the +% LaTeX Project Public License (LPPL), either version 1.3c of this +% license or (at your option) any later version. The latest version +% of this license is in the file +% +% http://www.latex-project.org/lppl.txt +% +% This file is part of the "Hyperref bundle" (The Work in LPPL) +% and all files in that bundle must be distributed together. +% +% ----------------------------------------------------------------------- +% +% The development version of the bundle can be found at +% +% https://github.com/latex3/hyperref +% +% for those people who are interested. +% +%<*driver> +\RequirePackage{pdfmanagement-testphase} +\DocumentMetadata{pdfstandard=A-2b} +\documentclass[full]{l3doc} +\usepackage{array,booktabs,hyperxmp} +\hypersetup{pdfauthor=The LaTeX Project, + pdftitle=Make link targets (hyperref bundle)} +\usepackage[skins]{tcolorbox} +\definecolor{myblue}{RGB}{00,33,99} +\newtcolorbox{doccomment}[1][]{enhanced,frame hidden,colback=myblue!10,fontupper=\footnotesize,#1} +%\newtcbox{smalldoccomment}{size=small,on line,enhanced,frame hidden,colback=myblue!10,fontupper=\footnotesize} +\begin{document} + \DocInput{\jobname.dtx} +\end{document} +% +% \fi +% \title{^^A +% Make link targets ^^A +% \\ +% hyperref bundle +% } +% +% \author{^^A +% The \LaTeX{} Project\thanks +% {^^A +% E-mail: +% \href{mailto:latex-team@latex-project.org} +% {latex-team@latex-project.org}^^A +% }^^A +% } +% +% \date{Version v7.00o, released 2022-05-13} +% +% \maketitle +% \begin{documentation} +% \section{Commands to create and adapt targets} +% This module provides commands to create targets. +% Their goal is to unify and replace +% a number of user and internal hyperref commands and to provide a clear +% interface for package authors and users. +% \subsection{The main command} +% \begin{function}{\MakeLinkTarget} +% \begin{syntax} +% \cs{MakeLinkTarget}\oarg{prefix}\Arg{counter}\\ +% \cs{MakeLinkTarget}\oarg{prefix}\{\} \\ +% \cs{MakeLinkTarget}*\Arg{manual target} +% \end{syntax} +% \end{function} +% +% \cs{MakeLinkTarget} creates a target for an internal link, (called a destination +% if a PDF is created). In vertical mode the target is created where the command is issued, +% in horizontal mode it is typically (in a PDF) raised by the current \cs{normalbaselineskip} +% (similar to the targets created by \cs{refstepcounter}). +% +% The arguments allow to control the name of the target/anchor/destination. While technically +% any unique name (e.g. some number) would work, names related to the actual counter both +% simplifies the debugging and referencing destinations from external documents. Also \cs{autoref} +% makes use of the name to identify the type of a label: it splits off the part until the first period and +% then looks up for a defined name. So if you create a target name \texttt{ABC.CDE.1.2}, \cs{autoref} tries +% to use \cs{ABCautorefname}. +% +% The name is then stored \emph{globally}\footnote{This means that the deprecated \pkg{hyperref} +% option \texttt{localanchorname} is ignored.} in \cs{@currentHref} and used for example in the +% next \cs{label}. +% A target name must be unique across a document. It is up to the users and package +% authors to ensure this by following the advices given below. +% +% \begin{doccomment} +% A global \cs{@currentHref} means that the target name and +% the label name can get out of sync: if +% for example a numbered equation is used between a section and a \cs{label}, +% a reference will show the section number but a link will jump to the equation. +% +% \pkg{hyperref} allows to switch to local assignment of \cs{@currentHref} +% and so to align with the other \cs{label} values with the +% (so-called experimental) option \texttt{localanchorname}. But while on a document +% level this can work, it makes it difficult for package authors +% to add reliable link targets that can be referenced if it is unclear +% if the assignment is local or global. +% +% So the choice was made to set \cs{@currentHref} globally always +% (and to deprecate \texttt{localanchorname}): +% This is the default in \pkg{hyperref} since ever and it didn't lead to +% major problems. It has the advantage to +% allow to put an anchor in a box and move it around. E.g. in the following +% example the two \cs{ref} commands +% reference the section but the second jumps to the top of the rule: +% +% \begin{verbatim} +% \section{An example}\label{sec:title} +% \newpage \raisebox{3cm}[0pt][0pt]{\phantomsection}% +% \rule{1cm}{3cm}\label{sec:page2} +% page two +% \newpage +% \ref{sec:title}, \ref{sec:page2} +% \end{verbatim} +% +% \end{doccomment} +% +% +% +% \subsection*{Target names from counters} +% \begin{syntax} +% \cs{MakeLinkTarget}\oarg{prefix}\Arg{counter} +% \end{syntax} +% +% If the mandatory argument is not empty it is interpreted as a \LaTeX{} counter name. +% The counter is not stepped by the command. +% If the \meta{counter} doesn't exist, a warning is issued and no target is created. +% +% The target name is created as expansion of +% \texttt{\meta{prefix}.\cs{theH\meta{counter}}} (and so both the prefix +% and \cs{theH\meta{counter}} should be expandable). +% The default prefix is the counter name \meta{counter}. +% +% For example: +% +% \medskip +% \noindent +% {\ttfamily +% \begin{tabular}{@{}l@{}ll} +% \cs{MakeLinkTarget}\{section\} &$\Rightarrow$ section.\cs{theHsection} & $\Rightarrow$ section.1.1\\ +% \cs{MakeLinkTarget}[sec]\{section\} &$\Rightarrow$ sec.\cs{theHsection} +% \end{tabular} +% } +% \medskip +% +% \cs{theH\meta{counter}} must be defined: +% \cs{MakeLinkTarget} does not try like other \pkg{hyperref} commands to +% construct the command on-the-fly but warns and creates no +% target if it doesn't exist. +% Be aware that if \pkg{hyperref} is used with the option \texttt{implicit=false} it +% does not predefine and create \cs{theH\meta{counter}} representations +% so targets could be missing!\footnote{It is planed that \LaTeX{} directly defines +% the \cs{theH\meta{counter}} for all counters created with \cs{newcounter}.} +% +% +% Typically \cs{theH\meta{counter}} should expand to numbers +% and periods and make use of parent counters to give a unique representation. +% The prefix can be a more or less arbitrary string. Spaces are allowed (but not +% really recommended). +% A star at the end should be avoided to prevent clashes with +% the names created when the internal counter is used. +% The use of non-ASCII chars with pdflatex depends on the \LaTeX{} version: With newer +% version many of them are safe and with a format 2022-06-01 or newer +% it should be even possible to use chars in a target name which +% are undeclared and can't be typeset in the document. +% But despite the fact that it works, it is recommended to stick to ASCII +% and to avoid spaces: It is unclear if all PDF viewers and editors can handle +% them, also they give rather unreadable names in the PDF like |(\360\237\246\206)| +% and so make debugging harder. +% +% +% Using a special prefix can be useful if the actual counter +% has an internal name like e.g. \texttt{tcb@cnt@example}. +% \texttt{\cs{MakeLinkTarget}[tcbexample]\{tcb@cnt@example\}} then gives +% a nicer looking target name. Care should be taken not to clash +% with existing counter names and names for \cs{autoref} +% should be adjusted if needed. +% +% +% \subsection*{Targets using the internal counter} +% \begin{syntax} +% \cs{MakeLinkTarget}\oarg{prefix}\{\} +% \end{syntax} +% +% If the mandatory argument is empty a target name based on +% an internal absolute counter is created. +% The counter is stepped at every call (and also by other \pkg{hyperref} commands). +% The prefix is added with a star and a period (see above for +% the allowed chars). The default prefix is \texttt{page}. +% +% +% \begin{syntax} +% \begin{tabular}{@{}ll} +% \cs{MakeLinkTarget}\texttt{\{\}} &$\Rightarrow$ \texttt{page*.1}\\ +% \cs{MakeLinkTarget}\texttt{\{\}} &$\Rightarrow$ \texttt{page*.2}\\ +% \cs{MakeLinkTarget}[section]\texttt{\{\}} &$\Rightarrow$ \texttt{section*.3}\\ +% \end{tabular} +% \end{syntax} +% +% As an example the +% \pkg{hyperref} command \cs{phantomsection} is equivalent to +% \texttt{\cs{MakeLinkTarget}[section]\{\}}. +% +% \subsection*{Manual target names} +% \begin{syntax} +% \cs{MakeLinkTarget}\texttt{*}\Arg{manual target name} +% \end{syntax} +% +% If the starred variant is used a manual target name is created. +% +% \texttt{\cs{MakeLinkTarget}*\{destname\}} is roughly equivalent to +% \texttt{\cs{hypertarget}\{destname\}\{\}} but unlike the +% latter it also raises the destination in a PDF, there is no text argument, +% and---most importantly--it updates \cs{@currentHref}, that means the target +% name is stored by the next \cs{label}, something that \cs{hypertarget} doesn't do). +% The target name is expanded, see the remarks about prefixes above regarding +% the allowed chars. +% +% When creating manually targets care should be taken to avoid +% clashes with automatic target names. +% As all automatic targets contain at least one period, +% names without a period are recommended. +% +% \begin{doccomment} +% The second (text) argument of \cs{hypertarget} is only used +% if the option \texttt{nesting} is set to true---but this option isn't used +% anywhere (in PDF the idea of a text in the anchor or nesting of anchors +% makes no sense anyway but also when html is produced e.g. with \texttt{make4ht} +% it is not used). So probably the option will be deprecated and removed. +% \end{doccomment} +% +% \subsection{Manipulate the next target name} +% +% Targets are sometimes created in places where it is difficult to inject +% a label to retrieve the target name for use e.g. in a bookmark. +% The next command allows to change the next target name: +% +% \begin{function}{\NextLinkTarget} +% \begin{syntax} +% \cs{NextLinkTarget}\Arg{manual target} +% \end{syntax} +% +% The command changes the next target name to \meta{manual target}. +% It does the same as the \cs{hypersetup} key +% \texttt{next-anchor} and also affects targets created by \cs{refstepcounter}. +%\end{function} +% +% A use case are bookmarks for the table of contents +% where you know that the heading will create +% a target: +% +% \begin{verbatim} +% \documentclass{book} +% \usepackage{bookmark} +% +% \begin{document} +% \bookmark[dest=toc]{Table of Contents} +% \NextLinkTarget{toc} +% \tableofcontents +% \chapter{A} +% \end{document} +% \end{verbatim} +% +% +% \subsection*{Hooks} +% +% \begin{function}{makelinktarget} +% The hook \texttt{makelinktarget}\footnote{The hook uses a plain name +% without reference to the \pkg{hyperref} package in anticipation of the move +% of this code into the \LaTeX{} kernel.} +% is executed at the begin of the commands. It is inside a group and +% so can be used to locally change settings. See below for an example. +% \end{function} +% +% +% \subsection*{Suppressing the target} +% +% \begin{function}{\LinkTargetOn,\LinkTargetOff} +% \begin{syntax} +% \cs{LinkTargetOn}\\ +% \cs{LinkTargetOff} +% \end{syntax} +% \end{function} +% +% +% This commands allows to switch on and off locally the creation of a target with +% \cs{MakeLinkTarget}. +% The switches are also honored by \cs{refstepcounter}\footnote{currently +% \cs{refstepcounter} doesn't use \cs{MakeLinkTarget} itself but this +% will probably change.}. +% This allows to suppress the target +% from an internal \cs{refstepcounter} and replace it by some manual version +% by using grouping: +% +% \begin{verbatim} +% \LinkTargetOff %suppress anchor in internal refstepcounter +% ... +% \refstepcounter{...} +% ... +% {\LinkTargetOn\MakeLinkTarget*{mytarget}} %create manual anchor +% ... +% \LinkTargetOn +% \end{verbatim} +% +% +% \subsection*{Raising the target} +% +% In horizontal mode the target is raised by the current value of \cs{normalbaselineskip}. +% +% To change this the hook can be used e.g. to double the value everywhere: +% +% \begin{verbatim} +% \AddToHook{cmd/MakeLinkTarget/before} +% {\setlength\normalbaselineskip{2\normalbaselineskip}} +% \leavevmode\MakeLinkTarget{section} +% \end{verbatim} +% +% +% \subsection{Changing all target names} +% +% \begin{function}{\SetLinkTargetFilter} +% \begin{syntax} +% \cs{SetLinkTargetFilter}\Arg{filter code using \#1} +% \end{syntax} +% \end{function} +% +% \pkg{hyperref} provides the command \cs{HyperDestNameFilter} to change all target names. +% It is applied\footnote{In the backend code, so it depends actually on +% the driver if it is honored or not} +% to every target name and is also used in references, +% but it doesn't change \cs{@currentHref} itself. So after +% +% \begin{verbatim} +% \renewcommand*{\HyperDestNameFilter}[1]{docA-#1} +% \end{verbatim} +% +% you would get in the PDF everywhere the prefix \texttt{docA} +% +% \begin{verbatim} +% %destination names: +% << +% /Names [(docA-Doc-Start) 7 0 R (docA-chapter.1) 8 0 R (docA-page.1) 6 0 R] +% /Limits [(docA-Doc-Start) (docA-page.1)] +% >> +% %link to a chapter +% /A << /S /GoTo /D (docA-chapter.1) >> +% %link from the bookmark +% << /S /GoTo /D (docA-chapter.1) >> +% \end{verbatim} +% +% but the label info in the \texttt{.aux} would show only \texttt{chapter.1}: +% +% \begin{verbatim} +% \newlabel{chap}{{1}{1}{Title}{chapter.1}{}} +% \end{verbatim} +% +% and so \cs{autoref} is still able to extract the counter name. +% +% \cs{MakeLinkTarget} uses this filter too: it would break internal link +% commands if it would ignore it. +% To stay compatible with future development the filter should not be redefined +% directly but be set with \cs{SetLinkTargetFilter}. +% The command can only be used in the preamble. +% +% \begin{verbatim} +% \SetLinkTargetFilter{docA-#1} +% \end{verbatim} +% \end{documentation} +% +% \begin{implementation} +% \section{Implementation} +% \begin{macrocode} +%<@@=hyp> +%<*header> +\ProvidesExplPackage{hyperref-linktarget}{2022-05-13}{v7.00o} + {Making targets, destinations and anchors -- module of hyperref} +% +% \end{macrocode} +%\ExplSyntaxOn +% \subsection{Variables} +% \begin{macrocode} +%<*package> +% \end{macrocode} +% \begin{macro}{\l_@@_target_create_bool} +% This boolean decides if a target is created at all. +% (it will replace \cs{@skiphyperref} long term) +% \begin{macrocode} +\bool_new:N \l_@@_target_create_bool +\bool_set_true:N \l_@@_target_create_bool +% \end{macrocode} +% \end{macro} +% \begin{macro}{makelinktarget} +% This hook is used to adapt for example the raising +% \begin{macrocode} +\hook_new:n {makelinktarget} +% \end{macrocode} +% \end{macro} +% \subsection{Helper commands} +% \begin{macro}{\_@@_target_raise:n} +% We need a command to raise the targets. +% It is mostly a copy from the hyperref command +% but we removed the hooks and use \cs{normalbaselineskip}. +% TODO: The code to save/restore the space factor should +% be replaced by kernel methods. +% \begin{macrocode} +\cs_new_protected:Npn \@@_target_raise:n #1 + { + \mode_if_vertical:TF + { #1 } + { + \Hy@SaveSpaceFactor + \penalty\@M + \smash + { + \box_move_up:nn + { \normalbaselineskip } + { + \hbox:n + { + \Hy@RestoreSpaceFactor + #1 + \Hy@SaveSpaceFactor + } + } + } + \Hy@RestoreSpaceFactor + } + } +% \end{macrocode} +% \end{macro} +% \subsection{Providing the commands} +% In anticipation of the addition of the main commands to the +% kernel as no-ops we provide them: +% \begin{macrocode} +\ProvideDocumentCommand\LinkTargetOn{}{} +\ProvideDocumentCommand\LinkTargetOff{}{} +\ProvideDocumentCommand\MakeLinkTarget{sO{}m}{} +\ProvideDocumentCommand\NextLinkTarget{m}{} +% \end{macrocode} +% +% \subsection{Target on and off switch} +% \begin{macro}{\LinkTargetOn,\LinkTargetOff} +% \begin{macrocode} +\RenewDocumentCommand\LinkTargetOn {} + { + \bool_set_true:N \l_@@_target_create_bool + } + + +\RenewDocumentCommand\LinkTargetOff {} + { + \bool_set_false:N \l_@@_target_create_bool + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\MakeLinkTarget} +% This is the main command. To keep it simple +% we allow an optional argument also for the manual +% command but ignore it for now. +% \begin{macrocode} +\RenewDocumentCommand\MakeLinkTarget {s O{} m} + { + \bool_if:NT \l_@@_target_create_bool + { + \group_begin: + \hook_use:n { makelinktarget } + \IfBooleanTF {#1} + { + \@@_target_manual:nn {#2}{#3} + } + { + \@@_target_counter:nn {#2}{#3} + } + \group_end: + } + } +% \end{macrocode} +% \end{macro} +% \begin{macro}{\@@_target_manual:nn} +% This is the code for the manual target name. The prefix is simply ignored. +% \begin{macrocode} +\cs_new_protected:Npn \@@_target_manual:nn #1 #2 %#1 prefix, #2 name + { + \tl_gset:Nx \@currentHref {#2} + \hook_use:n {__hyp/target/setname} + \@onelevel@sanitize\@currentHref + \@@_target_raise:n {\hyper@anchorstart{\@currentHref}\hyper@anchorend} + } +% \end{macrocode} +% \end{macro} +% \begin{macro}{\@@_target_counter:nn} +% The code for counter related targets must be split into the case +% where the internal counter is used, and where a user counter is used +% \begin{macrocode} +\cs_new_protected:Npn \@@_target_counter:nn #1 #2 %#1 prefix, #2 counter or empty + { + \tl_if_blank:nTF {#2} + { + \@@_target_counter_anon:n {#1} + } + { + \@@_target_counter_doc:nn {#1}{#2} + } + } + +% \end{macrocode} +%\end{macro} +%\begin{macro}{\@@_target_counter_anon:n} +% This creates the target with the internal count. +% We use the same (tex) count \cs{Hy@linkcounter} than the other +% hyperref commands. +% \begin{macrocode} +\cs_new_protected:Npn \@@_target_counter_anon:n #1 + { + \int_gincr:N\Hy@linkcounter + \tl_gset:Nx \@currentHref + {\tl_if_blank:nTF{#1}{page}{#1}*.\int_use:N\Hy@linkcounter} + \hook_use:n {__hyp/target/setname} + \@onelevel@sanitize\@currentHref + \@@_target_raise:n {\hyper@anchorstart{\@currentHref}\hyper@anchorend} + } +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\@@_target_counter_doc:nn} +% And now the target with the user counter. We warn if +% the counter or the representation doesn't exist +% \begin{macrocode} +\cs_new_protected:Npn \@@_target_counter_doc:nn #1 #2 + { + \bool_lazy_and:nnTF { \cs_if_free_p:c {c@#2} } { \cs_if_free_p:c {theH#2} } + { + \PackageWarning {hyperref}{Counter~'#2'~or~the~representation~'\string\theH#2`\MessageBreak + don't~exist.~No~target~created.}{} + } + { + \tl_gset:Nx \@currentHref {\tl_if_blank:nTF{#1}{#2}{#1}.\use:c{theH#2}} + \hook_use:n {@@/target/setname} + \@onelevel@sanitize\@currentHref + \@@_target_raise:n {\hyper@anchorstart{\@currentHref}\hyper@anchorend} + } + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\NextLinkTarget} +% we rely on the internal hook to set the next target name: +% \begin{macrocode} +\RenewDocumentCommand\NextLinkTarget {m} + { + \hook_gput_next_code:nn {@@/target/setname} + { + \tl_gset:Nx \@currentHref {#1} + } + } + +% \end{macrocode} +% \end{macro} +% \begin{macro}{\SetLinkTargetFilter} +% This is an interface to \cs{HyperDestNameFilter} +% \begin{macrocode} +\NewDocumentCommand\SetLinkTargetFilter {m} + { + \cs_set:Npn \HyperDestNameFilter ##1 {#1} + } +\@onlypreamble \SetLinkTargetFilter +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} +% +%<@@=>. +% \end{macrocode} +%\ExplSyntaxOff +%\end{implementation} +% \Finale +\endinput diff --git a/Master/texmf-dist/source/latex/hyperref/hyperref-patches.dtx b/Master/texmf-dist/source/latex/hyperref/hyperref-patches.dtx index cf6dfbb393f..446493224c6 100644 --- a/Master/texmf-dist/source/latex/hyperref/hyperref-patches.dtx +++ b/Master/texmf-dist/source/latex/hyperref/hyperref-patches.dtx @@ -5,7 +5,7 @@ %% 1995-2001 Sebastian Rahtz, with portions written by David Carlisle and Heiko Oberdiek, %% 2001-2015 Heiko Oberdiek. %% 2016-2019 Oberdiek Package Support Group -%% 2019-2021 LaTeX Project +%% 2019-2022 LaTeX Project %% https://github.com/latex3/hyperref/issues %% %% This file is part of the `Hyperref Bundle'. diff --git a/Master/texmf-dist/source/latex/hyperref/hyperref.dtx b/Master/texmf-dist/source/latex/hyperref/hyperref.dtx index 20414ef7e84..6096fad1d1c 100644 --- a/Master/texmf-dist/source/latex/hyperref/hyperref.dtx +++ b/Master/texmf-dist/source/latex/hyperref/hyperref.dtx @@ -1,31 +1,31 @@ % \iffalse %% File: hyperref.dtx -%% Copyright -%% 1995-2001 Sebastian Rahtz, with portions written by David Carlisle and Heiko Oberdiek, -%% 2001-2015 Heiko Oberdiek. -%% 2016-2019 Oberdiek Package Support Group -%% 2019-2021 LaTeX Project -%% https://github.com/latex3/hyperref/issues -%% -%% This file is part of the `Hyperref Bundle'. -%% ------------------------------------------- -%% -%% This work may be distributed and/or modified under the -%% conditions of the LaTeX Project Public License, either version 1.3 -%% of this license or (at your option) any later version. -%% The latest version of this license is in -%% http://www.latex-project.org/lppl.txt -%% and version 1.3 or later is part of all distributions of LaTeX -%% version 2005/12/01 or later. -%% -%% This work has the LPPL maintenance status `maintained'. -%% -%% The Current Maintainer of this work is the LaTeX Project. -%% -%% The list of all files belonging to the `Hyperref Bundle' is -%% given in the file `manifest.txt'. -%% -%\NeedsTeXFormat{LaTeX2e}[1995/12/01] +% Copyright +% 1995-2001 Sebastian Rahtz, with portions written by David Carlisle and Heiko Oberdiek, +% 2001-2015 Heiko Oberdiek. +% 2016-2019 Oberdiek Package Support Group +% 2019-2022 LaTeX Project +% https://github.com/latex3/hyperref/issues +% +% This file is part of the `Hyperref Bundle'. +% ------------------------------------------- +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% This work has the LPPL maintenance status `maintained'. +% +% The Current Maintainer of this work is the LaTeX Project. +% +% The list of all files belonging to the `Hyperref Bundle' is +% given in the file `manifest.txt'. +% +%\NeedsTeXFormat{LaTeX2e}[2020/10/01] %\ProvidesPackage{hyperref} %\ProvidesPackage{nohyperref} %\ProvidesFile{hyperref.drv} @@ -52,7 +52,7 @@ %\ProvidesFile{puvnenc.def} %\ProvidesFile{puarenc.def} %\ProvidesFile{psdextra.def} -% [2022-02-21 v7.00n % +% [2022-05-13 v7.00o % % Hypertext links for LaTeX] % Dummy hyperref (SR)] % Hyperref documentation driver file] @@ -1036,6 +1036,23 @@ % converted to the final form. % \end{enumerate} % +% \cs{MakeUppercase} and \cs{MakeLowercase} do not work by expansion in +% legacy code but if the expl3 code is available we can handle them. +% +% \begin{macro}{\MakeUppercaseUnsupportedInPdfStrings} +% \begin{macro}{\MakeLowercaseUnsupportedInPdfStrings} +% \begin{macrocode} +\ExplSyntaxOn +\@ifundefined{text_uppercase:n}{} + { + \def\MakeUppercaseUnsupportedInPdfStrings#1{\use:e {\text_uppercase:n {#1}}} + \def\MakeLowercaseUnsupportedInPdfStrings#1{\use:e {\text_lowercase:n {#1}}} + } +\ExplSyntaxOff +% \end{macrocode} +% \end{macro} +% \end{macro} +% % \begin{macro}{\pdfstringdef} % \cs{pdfstringdef} works on the tokens in |#2| and converts them to % a PDF string as far as possible: @@ -4219,13 +4236,6 @@ % % \section{Support of other packages} % -% \subsection{Class memoir} -% -% \begin{macrocode} -\@ifclassloaded{memoir}{% - \Hy@AtEndOfPackage{\RequirePackage{memhfixc}}% -}{} -% \end{macrocode} % % \subsection{Package subfigure} % Added fix for version 2.1. Here \cmd{\sub@label} is defined. @@ -4258,10 +4268,6 @@ \fi \@esphack }% - \@ifpackagelater{subfigure}{2002/03/26}{}{% - \providecommand*{\toclevel@subfigure}{1}% - \providecommand*{\toclevel@subtable}{1}% - }% }% }{} % \end{macrocode} @@ -4712,6 +4718,9 @@ % \end{macrocode} % \begin{macrocode} \define@key{Hyp}{localanchorname}[true]{% + \Hy@WarningNoLine{% + Option `localanchorname' is deprecated% + }% \Hy@boolkey{localanchorname}{#1}% } % \end{macrocode} @@ -7288,23 +7297,6 @@ \Hy@DisableOption{colorlinks}% \Hy@DisableOption{frenchlinks}% \ifHy@texht - \long\def\@firstoffive#1#2#3#4#5{#1}% - \long\def\@secondoffive#1#2#3#4#5{#2}% - \long\def\@thirdoffive#1#2#3#4#5{#3}% - \long\def\@fourthoffive#1#2#3#4#5{#4}% - \long\def\@fifthoffive#1#2#3#4#5{#5}% - \providecommand*\@safe@activestrue{}% - \providecommand*\@safe@activesfalse{}% - \def\T@ref#1{% - \Hy@safe@activestrue - \expandafter\@setref\csname r@#1\endcsname\@firstoffive{#1}% - \Hy@safe@activesfalse - }% - \def\T@pageref#1{% - \Hy@safe@activestrue - \expandafter\@setref\csname r@#1\endcsname\@secondoffive{#1}% - \Hy@safe@activesfalse - }% \else \ifHy@typexml \else @@ -7312,36 +7304,34 @@ \RequirePackage{nameref}[2012/07/28]% }% \fi +% \end{macrocode} +% With active links we have to redefine the starred versions +% to avoid that they get links from the include |\@setref|: +% \begin{macrocode} + \ifHy@implicit + \let \T@Ref\HyRef@Ref + \def\@refstar#1{% + \NR@ref@showkeys{#1}% + \HyRef@StarSetRef{#1}\@firstoffive + } + \def\@pagerefstar#1{% + \NR@ref@showkeys{#1}% + \HyRef@StarSetRef{#1}\@secondoffive + } + \def\@namerefstar#1{% + \NR@ref@showkeys{#1}% + \HyRef@StarSetRef{#1}\@thirdoffive + } + \def\@Refstar#1{% + \NR@ref@showkeys{#1}% + \HyRef@StarSetRef{#1}\HyRef@MakeUppercaseFirstOfFive + }% + \else + \fi \fi - \DeclareRobustCommand\ref{% - \@ifstar\@refstar\T@ref - }% - \DeclareRobustCommand\pageref{% - \@ifstar\@pagerefstar\T@pageref - }% -% \@ifclassloaded{memoir}{% -% \ltx@IfUndefined{@mem@titlerefnolink}\ltx@secondoftwo{% -% \ltx@IfUndefined{@mem@titleref}\ltx@secondoftwo\ltx@firstoftwo -% }% -% }\ltx@secondoftwo -% {% -% \DeclareRobustCommand*{\nameref}{% -% \@ifstar\@mem@titlerefnolink\@mem@titleref -% }% -% }{% - \DeclareRobustCommand*{\nameref}{% - \@ifstar\@namerefstar\T@nameref - }% -% }% - \ifHy@implicit - \else - \let \@pagerefstar\T@pageref - \let \@refstar\T@ref - \let \@namerefstar\T@nameref - \fi } \Hy@AtBeginDocument{% - \ifHy@texht + \ifx\ReadBookmarks\relax \else \Hy@CatcodeWrapper\ReadBookmarks \fi @@ -9384,15 +9374,18 @@ % \end{macrocode} % Ignore star from referencing macros: +% This is only needed if LaTeX doesn't define the starred +% variants itself. % \begin{macrocode} -\LetLtxMacro\NoHy@OrgRef\ref -\DeclareRobustCommand*{\ref}{% +\@ifundefined{@kernel@ref} + {\LetLtxMacro\NoHy@OrgRef\ref + \DeclareRobustCommand*{\ref}{% \@ifstar\NoHy@OrgRef\NoHy@OrgRef -} -\LetLtxMacro\NoHy@OrgPageRef\pageref -\DeclareRobustCommand*{\pageref}{% + } + \LetLtxMacro\NoHy@OrgPageRef\pageref + \DeclareRobustCommand*{\pageref}{% \@ifstar\NoHy@OrgPageRef\NoHy@OrgPageRef -} + }}{} % \end{macrocode} % % \section{Localized nullifying of package} @@ -9482,16 +9475,21 @@ \long\def\@gobbleopt[#1]{} \let\hyperpage\@empty % \end{macrocode} -% Ignore star from referencing macros: +% Ignore star from referencing macros. This is only +% needed in older formats. % \begin{macrocode} -\LetLtxMacro\NoHy@OrgRef\ref -\DeclareRobustCommand*{\ref}{% - \@ifstar\NoHy@OrgRef\NoHy@OrgRef -} -\LetLtxMacro\NoHy@OrgPageRef\pageref -\DeclareRobustCommand*{\pageref}{% - \@ifstar\NoHy@OrgPageRef\NoHy@OrgPageRef -} +\@ifl@t@r\fmtversion{2022-06-01} + {}% + {% + \LetLtxMacro\NoHy@OrgRef\ref + \DeclareRobustCommand*{\ref}{% + \@ifstar\NoHy@OrgRef\NoHy@OrgRef + } + \LetLtxMacro\NoHy@OrgPageRef\pageref + \DeclareRobustCommand*{\pageref}{% + \@ifstar\NoHy@OrgPageRef\NoHy@OrgPageRef + }% + } % % \end{macrocode} % @@ -9508,8 +9506,10 @@ % a document. % % Write some stuff into the aux file so if the next run is done -% without hyperref, then |\contentsline| and |\newlabel| are defined +% without hyperref, then |\newlabel| is defined % to cope with the extra arguments. +% change 2022-03-28: removed the code for |\contentsline|, it is no +% longer needed as |\contentsline| has now always four arguments. % \begin{macrocode} \if@filesw \ifHy@typexml @@ -9522,11 +9522,6 @@ \string\AtBeginDocument}^^J% \string\HyperFirstAtBeginDocument{% \string\ifx\string\hyper@anchor\string\@undefined^^J% - \string\global\string\let\string\oldcontentsline\string\contentsline^^J% - \string\gdef\string\contentsline% - \string#1\string#2\string#3\string#4{% - \string\oldcontentsline% - {\string#1}{\string#2}{\string#3}}^^J% \string\global\string\let\string\oldnewlabel\string\newlabel^^J% \string\gdef\string\newlabel\string#1\string#2{% \string\newlabelxx{\string#1}\string#2}^^J% @@ -9540,7 +9535,6 @@ % \begin{macrocode} \string\AtEndDocument{% \string\ifx\string\hyper@anchor\string\@undefined^^J% - \string\let\string\contentsline\string\oldcontentsline^^J% \string\let\string\newlabel\string\oldnewlabel^^J% \string\fi% }^^J% @@ -9561,28 +9555,12 @@ % Now the code to deal with adding the hyperref package to a document % with aux and toc written the standard way. % -% If hyperref was used last time, do nothing. If it was not used, -% or an old version of hyperref was used, don't use that TOC at all -% but generate a warning. Not ideal, but better than failing -% with pre-5.0 hyperref TOCs. +% If hyperref was used last time, do nothing. +% change 2022-03-28: removed the test for an old toc. +% |\contentsline| +% has now always four arguments. % \begin{macrocode} \ifx\hyper@last\@undefined - \def\@starttoc#1{% - \begingroup - \makeatletter - \ltx@ifpackageloaded{parskip}{\parskip\z@}{}% - \IfFileExists{\jobname.#1}{% - \Hy@WarningNoLine{% - old #1 file detected, not used; run LaTeX again% - }% - }{}% - \if@filesw - \expandafter\newwrite\csname tf@#1\endcsname - \immediate\openout\csname tf@#1\endcsname \jobname.#1\relax - \fi - \@nobreakfalse - \endgroup - }% \def\newlabel#1#2{\@newl@bel r{#1}{#2{}{}{}{}}}% \fi } @@ -10256,7 +10234,7 @@ % \end{macrocode} % % \begin{macrocode} -%<*package> +%<*packageEnd> % \end{macrocode} % % \begin{macrocode} @@ -10312,6 +10290,7 @@ \Hy@CounterExists{section}{% \providecommand\theHequation{\theHsection.\arabic{equation}}% } +\providecommand\theHequation{\arabic{equation}}% \Hy@CounterExists{part}{% \providecommand\theHpart{\arabic{part}}% } @@ -10366,36 +10345,42 @@ % \begin{macrocode} \let\H@refstepcounter\refstepcounter \edef\name@of@eq{equation}% -\edef\name@of@slide{slide}% % \end{macrocode} % We do not want the handler for |\refstepcounter| to cut in % during the processing of |\item| (we handle that separately), % so we provide a bypass conditional. +% change 2022-04-22: removed test for the slide counter +% and for the equation name. +% change 2022-05-02: added the new boolean set by +% |\LinkTargetOn/\LinkTargetOff| +% % \begin{macrocode} \newif\if@hyper@item \newif\if@skiphyperref \@hyper@itemfalse \@skiphyperreffalse +\ExplSyntaxOn \def\refstepcounter#1{% - \ifHy@pdfstring - \else + \legacy_if:nF {Hy@pdfstring} + { \H@refstepcounter{#1}% - \edef\This@name{#1}% - \ifx\This@name\name@of@slide - \else - \if@skiphyperref - \else - \if@hyper@item - \stepcounter{Item}% - \hyper@refstepcounter{Item}% - \@hyper@itemfalse - \else - \hyper@refstepcounter{#1}% - \fi - \fi - \fi - \fi + \bool_lazy_and:nnT + { \l__hyp_target_create_bool } + { ! \legacy_if_p:n{@skiphyperref} } + { + \legacy_if:nTF {@hyper@item} + { + \stepcounter{Item}% + \hyper@refstepcounter{Item}% + \@hyper@itemfalse + } + { + \hyper@refstepcounter{#1}% + } + } + } } +\ExplSyntaxOff \let\Hy@saved@refstepcounter\refstepcounter % \end{macrocode} % AMS\LaTeX\ processes all equations twice; we want to make sure @@ -10558,24 +10543,14 @@ } % \end{macrocode} % \end{macro} -% \begin{macro}{\hyper@hook@dest@make} % We define a hook to allow to overwrite the next destination name. % \begin{macrocode} -\@ifl@t@r\fmtversion{2020-10-01} - {% - \NewHook{__hyp/dest/make } - \def\hyper@hook@dest@make - {\UseHook{__hyp/dest/make}} - \define@key{Hyp}{next-anchor}{% - \AddToHookNext{__hyp/dest/make}% +\NewHook{__hyp/target/setname } +\define@key{Hyp}{next-anchor}{% + \AddToHookNext{__hyp/target/setname}% {\Hy@MakeCurrentHref{#1}}% } - } - { - \def\hyper@hook@dest@make{} - } % \end{macrocode} -% \end{macro} % \begin{macro}{\hyper@makecurrent} % Because of Babel mucking around, nullify |\textlatin| when making names. % And |\@number| because of babel's lrbabel.def. @@ -10627,7 +10602,7 @@ \else \global\let\@currentHref\HyperGlobalCurrentHref \fi - \hyper@hook@dest@make + \UseHook{__hyp/target/setname}% } % \end{macrocode} % \end{macro} @@ -10654,7 +10629,7 @@ \def\Hy@MakeCurrentHrefAuto#1{% \Hy@GlobalStepCount\Hy@linkcounter \Hy@MakeCurrentHref{#1.\the\Hy@linkcounter}% - \hyper@hook@dest@make} + \UseHook{__hyp/target/setname}} % \end{macrocode} % \end{macro} % @@ -10728,17 +10703,21 @@ % Fix provided by Felix Neubauer (\Email{felix.neubauer@gmx.net}). % This fix will no longer be needed with latex 2021-11-15. % \begin{macrocode} -\AtBeginDocument{% -\def\Hy@varioref@undefined{{??}{??}{}{}{}} -\@ifpackageloaded{varioref}{% - \def\vref@pagenum#1#2{% - \@ifundefined{r@#2}{% - \expandafter\let\csname r@#2\endcsname\Hy@varioref@undefined - }{}% - \edef#1{\getpagerefnumber{#2}}% - }% -}{} -} +\@ifl@t@r\fmtversion{2021-11-15} + {}% + { + \AtBeginDocument{% + \def\Hy@varioref@undefined{{??}{??}{}{}{}} + \@ifpackageloaded{varioref}{% + \def\vref@pagenum#1#2{% + \@ifundefined{r@#2}{% + \expandafter\let\csname r@#2\endcsname\Hy@varioref@undefined + }{}% + \edef#1{\getpagerefnumber{#2}}% + }% + }{} + } + } % \end{macrocode} % % \section{Package longtable support} @@ -10794,7 +10773,7 @@ % Overload equation, temporarily reverting to original % |\refstepcounter|. If, however, it is in AMS math, we do not % do anything, as the tag mechanism is used there (see section \ref{ams}). -% The execption is that we move the equation incrementation inside +% The exception is that we move the equation incrementation inside % the math environment to avoid specials outside and a wrong vertical % spacing of equation environments. % \begin{macrocode} @@ -11121,8 +11100,10 @@ % text, separately from whatever labels the text assigns. Too hard % to keep track of markers otherwise. If the raw forms |\footnotemark| % and |\footnotetext| are used, force them to use un-hyper original. -% +% If |\hyper@nopatch@footnote| is defined we don't patch but assume +% that addings links to footnotes is handled elsewhere. % \begin{macrocode} +\@ifundefined{hyper@nopatch@footnote}{% \ifHy@hyperfootnotes \newcounter{Hfootnote}% \let\H@@footnotetext\@footnotetext @@ -11315,7 +11296,7 @@ }{}% % \end{macrocode} % -% KOMA-Script defines \cs{footref} that uses both +% KOMA-Script or newer LaTeX defines \cs{footref} that uses both % \cs{ref} and \cs{@footnotemark} resulting in two links, % one of them wrong. % \begin{macrocode} @@ -11368,8 +11349,8 @@ % Does anyone remember the function and purpose of \cmd{\realfootnote}? % \begin{macrocode} \def\realfootnote{% - \@ifnextchar[\@xfootnote{% - \stepcounter{\@mpfn}% + \@ifnextchar[\@xfootnote%] + {\stepcounter{\@mpfn}% \protected@xdef\@thefnmark{\thempfn}% \H@@footnotemark\H@@footnotetext }% @@ -11377,12 +11358,13 @@ % \end{macrocode} % \begin{macrocode} \fi +}{} \Hy@DisableOption{hyperfootnotes} % \end{macrocode} % \end{macro} % % \begin{macrocode} -% +% %<*check> \checklatex \checkcommand\def\@xfootnotenext[#1]{% @@ -11407,7 +11389,7 @@ \relax } % -%<*package> +%<*packageEnd> % \end{macrocode} % % \section{Float captions}\label{captions} @@ -11518,7 +11500,7 @@ % \end{macrocode} % % \begin{macrocode} -% +% %<*check> \checklatex[1999/06/01 - 2000/06/01] \checkcommand\def\caption{% @@ -11546,7 +11528,7 @@ \endgroup } % -%<*package> +%<*packageEnd> % \end{macrocode} % % \section{Bibliographic references}\label{bib} @@ -11559,7 +11541,7 @@ % and \emph{drftcite} may break. % % However, lets make an attempt to get \emph{natbib} right, because -% thats a powerful, important package. +% that's a powerful, important package. % Patrick Daly (\Email{daly@linmpi.mpg.de}) has % provided hooks for us, so all we need to do is activate them. % \begin{macrocode} @@ -11660,7 +11642,7 @@ % \end{macrocode} % % \begin{macrocode} -% +% %<*check> \checklatex \checkcommand\def\@lbibitem[#1]#2{% @@ -11685,7 +11667,7 @@ \ignorespaces } % -%<*package> +%<*packageEnd> % \end{macrocode} % % \subsection{Package harvard} @@ -12065,7 +12047,7 @@ % \end{macro} % % \begin{macrocode} -% +% %<*check> \checklatex \checkcommand\def\addcontentsline#1#2#3{% @@ -12073,7 +12055,7 @@ } \checkcommand\def\contentsline#1{\csname l@#1\endcsname} % -%<*package> +%<*packageEnd> % \end{macrocode} % % \section{New counters}\label{counters} @@ -12179,10 +12161,10 @@ % \end{macrocode} % % \begin{macro}{\numberwithin} -% A appropiate definition of hyperref's companion counter +% A appropriate definition of hyperref's companion counter % (\cmd{\theH...}) is added for correct link names. % \begin{macrocode} -% +% %<*check> \checkpackage{amsmath}[1999/12/14 - 2000/06/06] \checkcommand\newcommand{\numberwithin}[3][\arabic]{% @@ -12196,30 +12178,22 @@ }% }% % -%<*package> +%<*packageEnd> \@ifpackageloaded{amsmath}{% - \@ifpackagelater{amsmath}{1999/12/14}{% - \renewcommand*{\numberwithin}[3][\arabic]{% - \@ifundefined{c@#2}{\@nocounterr{#2}}{% - \@ifundefined{c@#3}{\@nocnterr{#3}}{% - \HyOrg@addtoreset{#2}{#3}% - \@xp\xdef\csname the#2\endcsname{% - \@xp\@nx\csname the#3\endcsname .\@nx#1{#2}% - }% - \@xp\xdef\csname theH#2\endcsname{% - \@xp\@nx - \csname the\@ifundefined{theH#3}{}H#3\endcsname - .\@nx#1{#2}% - }% + \renewcommand*{\numberwithin}[3][\arabic]{% + \@ifundefined{c@#2}{\@nocounterr{#2}}{% + \@ifundefined{c@#3}{\@nocnterr{#3}}{% + \HyOrg@addtoreset{#2}{#3}% + \@xp\xdef\csname the#2\endcsname{% + \@xp\@nx\csname the#3\endcsname .\@nx#1{#2}% + }% + \@xp\xdef\csname theH#2\endcsname{% + \@xp\@nx + \csname the\@ifundefined{theH#3}{}H#3\endcsname + .\@nx#1{#2}% }% }% }% - }{% - \Hy@WarningNoLine{% - \string\numberwithin\space of package `amsmath' % - only fixed\MessageBreak - for version 2000/06/06 v2.12 or newer% - }% }% }{} % \end{macrocode} @@ -12501,7 +12475,7 @@ % \end{macrocode} % % \begin{macrocode} -% +% %<*check> \checklatex \checkcommand\def\@setref#1#2#3{% @@ -12516,7 +12490,7 @@ \fi } % -%<*package> +%<*packageEnd> % \end{macrocode} % % Now some extended referencing. |\ref*| and |\pageref*| are not linked, @@ -12549,26 +12523,25 @@ \def\@namerefstar#1{% \HyRef@StarSetRef{#1}\@thirdoffive } - +\def\@Refstar#1{% + \HyRef@StarSetRef{#1}\HyRef@MakeUppercaseFirstOfFive +}% +\def\HyRef@MakeUppercaseFirstOfFive#1#2#3#4#5{% + \MakeUppercase#1% +}% +\def\HyRef@Ref#1{% + \hyperref[{#1}]{\Ref*{#1}}% +}% \Hy@AtBeginDocument{% \@ifpackageloaded{varioref}{% - \def\@Refstar#1{% - \HyRef@StarSetRef{#1}\HyRef@MakeUppercaseFirstOfFive - }% - \def\HyRef@MakeUppercaseFirstOfFive#1#2#3#4#5{% - \MakeUppercase#1% - }% - \DeclareRobustCommand*{\Ref}{% - \@ifstar\@Refstar\HyRef@Ref - }% - \def\HyRef@Ref#1{% - \hyperref[{#1}]{\Ref*{#1}}% - }% % \end{macrocode} -% Test if we are running new 2019 varioref or old one: +% This are the patches for a varioref newer after 2019-09 +% Older versions are no longer supported. +% If |\hyper@nopatch@varioref| is defined we don't patch but assume +% that varioref handles the hyperlinks. % \begin{macrocode} -%FMi - \ifdefined\vp@gerefstar + \@ifundefined{hyper@nopatch@varioref} + { \renewcommand\Vref@star[2][]{% \begingroup \let\T@pageref\@pagerefstar @@ -12601,33 +12574,11 @@ \vpageref[#1]{#2}% \endgroup }% -% \end{macrocode} -% old varioref: -% \begin{macrocode} - \else - \def\Vr@f#1{% - \leavevmode\unskip\vref@space - \hyperref[{#1}]{% - \Ref*{#1}% - \let\vref@space\nobreakspace - \@vpageref[\unskip]{#1}% - }% - }% - \def\vr@f#1{% - \leavevmode\unskip\vref@space - \begingroup - \let\T@pageref\@pagerefstar - \hyperref[{#1}]{% - \ref*{#1}% - \vpageref[\unskip]{#1}% - }% - \endgroup - }% - \fi -%FMi -end mod + }{}% }{}% } - +% \end{macrocode} +% \begin{macrocode} \DeclareRobustCommand*{\autopageref}{% \@ifstar{% \HyRef@autopagerefname\pageref*% @@ -12651,10 +12602,9 @@ % \cs{leavevmode} is added to make package wrapfigure happy, if % \cs{autoref} starts a paragraph. % \begin{macrocode} -\DeclareRobustCommand*{\autoref}{% - \leavevmode - \@ifstar{\HyRef@autoref\@gobbletwo}{\HyRef@autoref\hyper@@link}% -} +\NewDocumentCommand\autoref{s} + {\leavevmode + \IfBooleanTF{#1}{\HyRef@autoref\@gobbletwo}{\HyRef@autoref\hyper@@link}} \def\HyRef@autoref#1#2{% \begingroup \Hy@safe@activestrue @@ -12737,9 +12687,7 @@ % \begin{macrocode} \let\HyRef@ShowKeysRef\@gobble \def\HyRef@ShowKeysInit{% - \begingroup\expandafter\expandafter\expandafter\endgroup - \expandafter\ifx\csname SK@@label\endcsname\relax - \else + \ifcsname SK@@label\endcsname \ifx\SK@ref\@empty \else \def\HyRef@ShowKeysRef{% @@ -12785,7 +12733,7 @@ % \end{macrocode} % % \begin{macrocode} -% +% % \end{macrocode} % % \section{Configuration files} @@ -13096,15 +13044,7 @@ \expandafter\endgroup \expandafter\pdflinkmargin\the\dimen@\relax } -\ifx\pdfstartlink\@undefined% less than version 14 - \let\pdfstartlink\pdfannotlink - \let\pdflinkmargin\@tempdima - \let\pdfxform\pdfform - \let\pdflastxform\pdflastform - \let\pdfrefxform\pdfrefform -\else - \pdflinkmargin1pt % -\fi +\pdflinkmargin1pt % % \end{macrocode} % First set up the default linking % \begin{macrocode} @@ -15463,7 +15403,7 @@ % is used by writing some clipped text. % \begin{macrocode} %\def\literalps@out#1{\special{ps:#1}}% -%\providecommand*{\Hy@DistillerDestFix}{} +%\providecommand*{\Hy@DistillerDestFix}{} %<*pdfmark|dviwindo> \def\Hy@DistillerDestFix{% \begingroup @@ -19334,7 +19274,7 @@ % \end{macro} % \begin{macrocode} % -%<*package> +%<*packageEnd> % \end{macrocode} % % \section{Bookmarks in the PDF file} @@ -19354,7 +19294,7 @@ \Hy@MakeCurrentHrefAuto{section*}% \Hy@raisedlink{\hyper@anchorstart{\@currentHref}\hyper@anchorend}% } -% +% % \end{macrocode} % % \subsection{Bookmarks} @@ -19827,6 +19767,8 @@ \hss }% } +\@ifundefined{hyper@nopatch@sectioning} +{ \let\H@old@ssect\@ssect \def\@ssect#1#2#3#4#5{% \Hy@MakeCurrentHrefAuto{section*}% @@ -19922,6 +19864,7 @@ \H@old@sect{#1}{#2}{#3}{#4}{#5}{#6}[{#7}]{#8}% }% } +}{} % \end{macrocode} % \begin{macrocode} % @@ -19944,61 +19887,6 @@ % % \end{macrocode} % -% \section{Compatibility with koma-script classes} -% -% \begin{macrocode} -%<*outlines|hypertex> -% \end{macrocode} -% -% Hard-wire in an unpleasant over-ride of komascript `scrbook' class -% for Tobias Isenberg (\Email{Tobias.Isenberg@gmx.de}). -% With version 6.71b the hack is also applied to `scrreprt' class -% and is removed for koma-script versions since 2001/01/01, -% because Markus Kohm supports hyperref in komascript. -% \begin{macrocode} -\def\Hy@tempa{% - \def\@addchap[##1]##2{% - \typeout{##2}% - \if@twoside - \@mkboth{##1}{}% - \else - \@mkboth{}{##1}% - \fi - \addtocontents{lof}{\protect\addvspace{10\p@}}% - \addtocontents{lot}{\protect\addvspace{10\p@}}% - \Hy@MakeCurrentHrefAuto{\Hy@chapapp*}% - \Hy@raisedlink{% - \hyper@anchorstart{\@currentHref}\hyper@anchorend - }% - \if@twocolumn - \@topnewpage[\@makeschapterhead{##2}]% - \else - \@makeschapterhead{##2}% - \@afterheading - \fi - \addcontentsline{toc}{chapter}{##1}% - }% -} -\@ifclassloaded{scrbook}{% - \@ifclasslater{scrbook}{2001/01/01}{% - \let\Hy@tempa\@empty - }{}% -}{% - \@ifclassloaded{scrreprt}{% - \@ifclasslater{scrreprt}{2001/01/01}{% - \let\Hy@tempa\@empty - }{}% - }{% - \let\Hy@tempa\@empty - }% -}% -\Hy@tempa -% \end{macrocode} -% -% \begin{macrocode} -% -% \end{macrocode} -% % \section{Encoding definition files for encodings of PDF strings} % This was contributed by % Heiko Oberdiek. diff --git a/Master/texmf-dist/source/latex/hyperref/hyperref.ins b/Master/texmf-dist/source/latex/hyperref/hyperref.ins index 78c7662b1a8..bbe33cf3133 100644 --- a/Master/texmf-dist/source/latex/hyperref/hyperref.ins +++ b/Master/texmf-dist/source/latex/hyperref/hyperref.ins @@ -7,7 +7,7 @@ %% 1995-2001 Sebastian Rahtz, with portions written by David Carlisle and Heiko Oberdiek %% 2001-2015 Heiko Oberdiek %% 2016-2019 Oberdiek Package Support Group -%% 2019-2021 LaTeX Project +%% 2019-2022 LaTeX Project %% https://github.com/latex3/hyperref/issues %% %% This file is part of the `Hyperref Bundle'. @@ -55,6 +55,32 @@ %\askonceonly %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \preamble + +Copyright +1995-2001 Sebastian Rahtz, with portions written by David Carlisle and Heiko Oberdiek, +2001-2015 Heiko Oberdiek. +2016-2019 Oberdiek Package Support Group +2019-2022 LaTeX Project + https://github.com/latex3/hyperref/issues + +This file is part of the `Hyperref Bundle'. +------------------------------------------- + +This work may be distributed and/or modified under the +conditions of the LaTeX Project Public License, either version 1.3 +of this license or (at your option) any later version. +The latest version of this license is in + http://www.latex-project.org/lppl.txt +and version 1.3 or later is part of all distributions of LaTeX +version 2005/12/01 or later. + +This work has the LPPL maintenance status `maintained'. + +The Current Maintainer of this work is the LaTeX Project. + +The list of all files belonging to the `Hyperref Bundle' is +given in the file `manifest.txt'. + \endpreamble \generate{% @@ -65,7 +91,12 @@ \usedir{tex/latex/hyperref} \file{backref.sty}{\from{backref.dtx}{package}} \file{nameref.sty}{\from{nameref.dtx}{package}} - \file{hyperref.sty}{\from{hyperref.dtx}{package}} + \file{hyperref.sty} + { + \from{hyperref.dtx}{package} + \from{hyperref-linktarget.dtx}{package,package-include} + \from{hyperref.dtx}{packageEnd} + } \file{hypertex.def}{\from{hyperref.dtx}{hypertex}} \file{pdfmark.def}{\from{hyperref.dtx}{pdfmark,pdfmarkbase,pdfform,outlines}} \file{hvtexmrk.def}{\from{hyperref.dtx}{vtexpdfmark}} diff --git a/Master/texmf-dist/source/latex/hyperref/nameref.dtx b/Master/texmf-dist/source/latex/hyperref/nameref.dtx index adc41b8fdcb..dabe4b6d908 100644 --- a/Master/texmf-dist/source/latex/hyperref/nameref.dtx +++ b/Master/texmf-dist/source/latex/hyperref/nameref.dtx @@ -4,7 +4,7 @@ %% 2000 Sebastian Rahtz, Heiko Oberdiek %% 2001-2012 Heiko Oberdiek %% 2016-2019 Oberdiek Package Suport Group -%% 2019-2021 The LaTeX Project +%% 2019-2022 The LaTeX Project %% https://github.com/latex3/hyperref/issues %% %% This file is part of the `Hyperref Bundle'. @@ -33,7 +33,7 @@ %\ProvidesFile{nameref.drv} % \fi % \ProvidesFile{nameref.dtx} - [2021-04-02 v2.47 Cross-referencing by name of section]% + [2022-05-13 v2.48 Cross-referencing by name of section]% % % % \iffalse @@ -78,6 +78,101 @@ % Cross-referencing to include the \emph{name} of the section, rather than % just the number or page. This works by redefining some of the inside % \LaTeX\ macros, so it is vulnerable to future changes. +% +% \section{Background and advice for package and class authors} +% The package redefines the \cs{label} command to write additionally +% \cs{@currentlabelname} to the \texttt{.aux} file. This can then be referenced with +% \cs{nameref}. Package authors who want to support \textsf{nameref} should +% define this command (locally) in a suitable way. +% The content should be so that it can be safely written +% to the \texttt{.aux} file. \textsf{nameref} itself uses the package +% \textsf{gettitlestring} but this is not required. +% +% \textsf{nameref} patches a number of commands (mostly sectioning +% commands) and environments so that they +% store \cs{@currentlabelname}. A class or a package that want to provide native +% support instead can suppress this patches by defining commands described below. +% The commands must be defined before the patch is made, in most cases before +% \textsf{nameref} is loaded, sometimes only before begin document. +% +% \begin{description} +% \item[sectioning commands] Redefined are +% \begin{itemize} +% \item +% \cs{@sect}: beside adding a command that stores the +% title of a sectioning command (if present the optional argument is used) +% \textsf{nameref} also stores the level number in a counter \texttt{section@level} +% (reason is unknown, only two packages, \textsf{e-french} and \textsf{pdfscreen} +% seem to use it), and surrounds the text with \cs{Sectionformat} (only used by +% \textsf{acmart}, \textsf{memoir}, \textsf{pdfscreen}, \textsf{pdfslide}), a +% command which takes two argument: the first the text, the second the level. +% +% \item \cs{@ssect}: command to store the title added, +% \cs{Sectionformat} is added. +% +% \item \cs{M@sect} (memoir class): command to store the title added +% +% \item \cs{@part}, \cs{@spart}, \cs{@chapter}, \cs{@schapter}: +% command to store the title added +% \item \cs{ttl@sect@i} (from the \textsf{titlesec} package): +% command to store the title added +% \end{itemize} +% +% All the patches excepted the last are disabled if the command +% \cs{NR@nopatch@sectioning} is defined (the actual definition is irrelevant, only +% existence is tested. The titlesec patch is disabled if +% \cs{NR@nopatch@titlesec} is defined. +% This currently only suppress the actual patches, the counter, +% \cs{Sectionformat} and also the internal copies \cs{NR@sect} etc are still +% defined. +% +% \item[captions] The following commands are patched +% \begin{itemize} +% \item \cs{@caption}: command to store the title added. This is done at begin +% document, but only if \textsf{hyperref} is not detected. With \textsf{hyperref} +% the patch is done there (and must be disabled in \textsf{hyperref}). +% +% This patch can be disabled by defining \cs{NR@nopatch@caption} +% +% \item \cs{LT@c@ption} (from the \textsf{longtable} package): +% command to store the title added. +% +% This patch can be disabled by defining \cs{NR@nopatch@longtable} +% +% \item \cs{lst@MakeCaption} (from the \textsf{listings} package) +% +% This patch can be disabled by defining \cs{NR@nopatch@listings} +% \end{itemize} +% +% \item[lists] The following command is patched +% \begin{itemize} +% \item \cs{descriptionlabel}: command to store the label text added. To +% reference this text the \cs{label} must be put \emph{inside} the label. +% This is not compatible with the \textsf{enumitem} package as internal +% formatting commands are written to the \texttt{.aux} file too. +% +% This patch can be disabled by defining \cs{NR@nopatch@lists} +% \end{itemize} +% +% \item[theorems] +% +% \begin{itemize} +% \item \cs{@opargbegintheorem}: command to store the title added. +% +% This patch can be disabled by defining \cs{NR@nopatch@theorem} +% +% \item \cs{@begintheorem} (if amsthm is loaded and if +% the command has a tested meaning): command to store the title added. +% +% This patch can be disabled by defining \cs{NR@nopatch@amsthm} +% +% \end{itemize} +% \item[beamer] In the \textsf{beamer} class the following commands are +% patched: \cs{beamer@section}, \cs{beamer@subsection}, \cs{beamer@subsubsection}, +% \cs{beamer@descriptionitem} and the template \texttt{theorem begin}. If +% \cs{NR@nopatch@beamer} is defined nothing is done. +% \end{description} +% % \section{History} % Sebastian Rahtz, for Lou Burnard, March 15th 1994;\\ % SPQR CERN July 1994;\\ @@ -304,11 +399,12 @@ % \end{macrocode} % \begin{macro}{\@sect} % \begin{macrocode} -\def\@sect#1#2#3#4#5#6[#7]#8{% - \setcounter{section@level}{#2}% - \NR@gettitle{#7}% - \NR@sect{#1}{#2}{#3}{#4}{#5}{#6}[{#7}]{\Sectionformat{#8}{#2}}% -} +\@ifundefined{NR@nopatch@sectioning} + {\def\@sect#1#2#3#4#5#6[#7]#8{% + \setcounter{section@level}{#2}% + \NR@gettitle{#7}% + \NR@sect{#1}{#2}{#3}{#4}{#5}{#6}[{#7}]{\Sectionformat{#8}{#2}}% + }}{} % \end{macrocode} % \end{macro} % and now the unnumbered ones @@ -317,33 +413,35 @@ \let\NR@ssect\@ssect % \end{macrocode} % \end{macro} -% \begin{macro}{\NR@ssect} +% \begin{macro}{\@ssect} % \begin{macrocode} -\def\@ssect#1#2#3#4#5{% - \NR@gettitle{#5}% - \NR@ssect{#1}{#2}{#3}{#4}{\Sectionformat{#5}{#1}}% -} +\@ifundefined{NR@nopatch@sectioning} + {\def\@ssect#1#2#3#4#5{% + \NR@gettitle{#5}% + \NR@ssect{#1}{#2}{#3}{#4}{\Sectionformat{#5}{#1}}% + }}{} % \end{macrocode} % \end{macro} % % Support for class memoir. % % \begin{macrocode} -\ltx@IfUndefined{ifheadnameref}{% -}{% - \ltx@IfUndefined{M@sect}{% +\@ifundefined{NR@nopatch@sectioning} + {\ltx@IfUndefined{ifheadnameref}{% }{% - \let\NRorg@M@sect\M@sect - \def\M@sect#1#2#3#4#5#6[#7][#8]{% - \ifheadnameref - \NR@gettitle{#8}% - \else - \NR@gettitle{#7}% - \fi - \NRorg@M@sect{#1}{#2}{#3}{#4}{#5}{#6}[{#7}][{#8}]% + \ltx@IfUndefined{M@sect}{% + }{% + \let\NRorg@M@sect\M@sect + \def\M@sect#1#2#3#4#5#6[#7][#8]{% + \ifheadnameref + \NR@gettitle{#8}% + \else + \NR@gettitle{#7}% + \fi + \NRorg@M@sect{#1}{#2}{#3}{#4}{#5}{#6}[{#7}][{#8}]% + }% }% - }% -} + }}{} % \end{macrocode} % % Parts and chapters are treated differently. sigh. @@ -351,80 +449,85 @@ % % \begin{macrocode} \let\NR@part\@part -\long\def\@part[#1]#2{% - \NR@gettitle{#1}% - \NR@part[{#1}]{#2}% -} \let\NR@spart\@spart -\long\def\@spart#1{% - \NR@gettitle{#1}% - \NR@spart{#1}% -} \let\NR@chapter\@chapter -\def\@chapter[#1]#2{% - \NR@gettitle{#1}% - \NR@chapter[{#1}]{#2}% -} -\@ifclassloaded{memoir}{% - \ltx@IfUndefined{ifheadnameref}{% - }{% - \def\@chapter[#1]#2{% - \ltx@IfUndefined{ch@pt@c}{% - \NR@gettitle{#1}% - }{% - \ifx\ch@pt@c\ltx@empty - \NR@gettitle{#2}% - \else - \def\NR@temp{#1}% - \ifx\NR@temp\ltx@empty - \expandafter\NR@gettitle\expandafter{\ch@pt@c}% +\let\NR@schapter\@schapter +\@ifundefined{NR@nopatch@sectioning} + {% + \long\def\@part[#1]#2{% + \NR@gettitle{#1}% + \NR@part[{#1}]{#2}% + } + \long\def\@spart#1{% + \NR@gettitle{#1}% + \NR@spart{#1}% + } + \def\@chapter[#1]#2{% + \NR@gettitle{#1}% + \NR@chapter[{#1}]{#2}% + } + \@ifclassloaded{memoir}{% + \ltx@IfUndefined{ifheadnameref}{% + }{% + \def\@chapter[#1]#2{% + \ltx@IfUndefined{ch@pt@c}{% + \NR@gettitle{#1}% + }{% + \ifx\ch@pt@c\ltx@empty + \NR@gettitle{#2}% \else - \ifheadnameref - \NR@gettitle{#1}% - \else + \def\NR@temp{#1}% + \ifx\NR@temp\ltx@empty \expandafter\NR@gettitle\expandafter{\ch@pt@c}% + \else + \ifheadnameref + \NR@gettitle{#1}% + \else + \expandafter\NR@gettitle\expandafter{\ch@pt@c}% + \fi \fi \fi - \fi + }% + \NR@chapter[{#1}]{#2}% }% - \NR@chapter[{#1}]{#2}% }% - }% -}{} -\let\NR@schapter\@schapter -\def\@schapter#1{% - \NR@gettitle{#1}% - \NR@schapter{#1}% -} + }{} + \def\@schapter#1{% + \NR@gettitle{#1}% + \NR@schapter{#1}% + }}{} % \end{macrocode} % % Captions % % \begin{macrocode} \AtBeginDocument{% - \@ifpackageloaded{hyperref}{% - \@ifpackagelater{hyperref}{2009/12/05}\@gobble\@firstofone - }\@firstofone + \@ifpackageloaded{hyperref}{} {% - \let\NR@@caption\@caption - \long\def\@caption#1[#2]{% + \@ifundefined{NR@nopatch@caption} + {\let\NR@@caption\@caption + \long\def\@caption#1[#2]{% \NR@gettitle{#2}% \NR@@caption{#1}[{#2}]% - }% + }}% + {}% }% % \end{macrocode} % % \begin{macrocode} \@ifpackageloaded{longtable}{% - \let\NRorg@LT@c@ption\LT@c@ption - \def\LT@c@ption#1[#2]#3{% - \NRorg@LT@c@ption{#1}[{#2}]{#3}% - \def\@tempa{#2}% - \ifx\@tempa\@empty - \else + \@ifundefined{NR@nopatch@longtable} + {% + \let\NRorg@LT@c@ption\LT@c@ption + \def\LT@c@ption#1[#2]#3{% + \NRorg@LT@c@ption{#1}[{#2}]{#3}% + \def\@tempa{#2}% + \ifx\@tempa\@empty + \else \NR@gettitle{#2}% - \fi - }% + \fi + }% + }{}% }{}% % \end{macrocode} % @@ -432,11 +535,13 @@ % \begin{macrocode} \ltx@IfUndefined{descriptionlabel}{% }{% - \let\NRorg@descriptionlabel\descriptionlabel - \def\descriptionlabel#1{% - \NR@gettitle{#1}% - \NRorg@descriptionlabel{#1}% - }% + \@ifundefined{NR@nopatch@longtable} + {\let\NRorg@descriptionlabel\descriptionlabel + \def\descriptionlabel#1{% + \NR@gettitle{#1}% + \NRorg@descriptionlabel{#1}% + }% + }{}% }% } % \end{macrocode} @@ -446,10 +551,13 @@ \AtBeginDocument{% \@ifpackageloaded{titlesec}{% \let\NRorg@ttl@sect@i\ttl@sect@i - \def\ttl@sect@i#1#2[#3]#4{% - \NR@gettitle{#4}% - \NRorg@ttl@sect@i{#1}{#2}[{#3}]{#4}% - }% + \@ifundefined{NR@nopatch@titlesec} + {% + \def\ttl@sect@i#1#2[#3]#4{% + \NR@gettitle{#4}% + \NRorg@ttl@sect@i{#1}{#2}[{#3}]{#4}% + }% + }{}% }{}% } % \end{macrocode} @@ -458,39 +566,42 @@ % % \begin{macrocode} \@ifclassloaded{beamer}{% - \def\NR@PatchBeamer#1{% - \expandafter\let\csname NRorg@beamer@#1\expandafter\endcsname - \csname beamer@#1\endcsname - \begingroup - \edef\x{\endgroup - \long\def\expandafter\noexpand\csname beamer@#1\endcsname - [####1]{% hash-ok - \noexpand\NR@gettitle{####1}% - \expandafter\noexpand\csname NRorg@beamer@#1\endcsname - [{####1}]% + \@ifundefined{NR@nopatch@beamer} + {% + \def\NR@PatchBeamer#1{% + \expandafter\let\csname NRorg@beamer@#1\expandafter\endcsname + \csname beamer@#1\endcsname + \begingroup + \edef\x{\endgroup + \long\def\expandafter\noexpand\csname beamer@#1\endcsname + [####1]{% hash-ok + \noexpand\NR@gettitle{####1}% + \expandafter\noexpand\csname NRorg@beamer@#1\endcsname + [{####1}]% + }% }% - }% - \x - }% - \NR@PatchBeamer{section}% - \NR@PatchBeamer{subsection}% - \NR@PatchBeamer{subsubsection}% + \x + }% + \NR@PatchBeamer{section}% + \NR@PatchBeamer{subsection}% + \NR@PatchBeamer{subsubsection}% % \end{macrocode} % % Theorem names. % \begin{macrocode} - \addtobeamertemplate{theorem begin}{% - \expandafter\NR@gettitle\expandafter{\inserttheoremaddition}% - }{}% + \addtobeamertemplate{theorem begin}{% + \expandafter\NR@gettitle\expandafter{\inserttheoremaddition}% + }{}% % \end{macrocode} % \begin{macrocode} - \@ifdefinable{\NRorg@beamer@descriptionitem}{% - \let\NRorg@beamer@descriptionitem\beamer@descriptionitem - \renewcommand{\beamer@descriptionitem}[1]{% - \NR@gettitle{#1}% - \NRorg@beamer@descriptionitem{#1}% + \@ifdefinable{\NRorg@beamer@descriptionitem}{% + \let\NRorg@beamer@descriptionitem\beamer@descriptionitem + \renewcommand{\beamer@descriptionitem}[1]{% + \NR@gettitle{#1}% + \NRorg@beamer@descriptionitem{#1}% + }% }% - }% + }{}% }{} % \end{macrocode} % @@ -554,13 +665,15 @@ \long\def\@fourthoffive#1#2#3#4#5{#4} % \end{macrocode} % \end{macro} -% \begin{macro}{\@offive} +% \begin{macro}{\@fifthoffive} % \begin{macrocode} \long\def\@fifthoffive#1#2#3#4#5{#5} % \end{macrocode} % \end{macro} -% We have to redefine |\ref| and |\pageref| to know about extra +% We have to redefine |\ref|, |\Ref| and |\pageref| to know about extra % reference elements. Make them robust, and compatible with Babel. +% We also define starred versions so that it doesn't depend on hyperref +% if they are defined or not. We use the same internal names as hyperref. % The Babel switch is mimicked if not already defined. % Some support for package \xpackage{showkeys} is implemented. If % option |notref| of that package is set, |\SK@ref| has the @@ -575,6 +688,11 @@ \providecommand*\@safe@activesfalse{}% % \end{macrocode} % \end{macro} +% \begin{macro}{\NR@ref@showkeys} +% \begin{macrocode} +\newcommand\NR@ref@showkeys[1]{}% +% \end{macrocode} +% \end{macro} % \begin{macro}{\NR@setref} % \begin{macrocode} \def\NR@setref#1{% @@ -599,6 +717,15 @@ % \begin{macro}{\T@ref} % \begin{macrocode} \def\T@ref#1{% + \NR@ref@showkeys{#1}% + \NR@setref{#1}\@firstoffive{#1}% +}% +% \end{macrocode} +% \end{macro} +% \begin{macro}{\@refstar} +% \begin{macrocode} +\def\@refstar#1{% + \NR@ref@showkeys{#1}% \NR@setref{#1}\@firstoffive{#1}% }% % \end{macrocode} @@ -606,111 +733,124 @@ % \begin{macro}{\T@pageref} % \begin{macrocode} \def\T@pageref#1{% + \NR@ref@showkeys{#1}% \NR@setref{#1}\@secondoffive{#1}% }% % \end{macrocode} % \end{macro} +% \begin{macro}{\@pagerefstar} % \begin{macrocode} -\ifNR@showkeys - \ifx\SK@ref\@empty - \else +\def\@pagerefstar#1{% + \NR@ref@showkeys{#1}% + \NR@setref{#1}\@secondoffive{#1}% +}% % \end{macrocode} -% \begin{macro}{\T@ref} +% \end{macro}% +% \begin{macro}{\T@Ref} % \begin{macrocode} - \def\T@ref#1{% - \@safe@activestrue - \SK@\SK@@ref{#1}% - \@safe@activesfalse - \NR@setref{#1}\@firstoffive{#1}% - }% +\def\T@Ref#1{% + \NR@ref@showkeys{#1}% + \NR@setref{#1}\NR@MakeUppercaseFirstOfFive{#1}% + }% +\def\NR@MakeUppercaseFirstOfFive#1#2#3#4#5{% + \MakeUppercase#1% + }% % \end{macrocode} % \end{macro} -% \begin{macro}{\T@pageref} +% \begin{macro}{\@Refstar} % \begin{macrocode} - \def\T@pageref#1{% - \@safe@activestrue - \SK@\SK@@ref{#1}% - \@safe@activesfalse - \NR@setref{#1}\@secondoffive{#1}% - }% +\def\@Refstar#1{% + \NR@ref@showkeys{#1}% + \NR@setref{#1}\NR@MakeUppercaseFirstOfFive{#1}% + }% % \end{macrocode} -% \end{macro} +% \end{macro}% % \begin{macrocode} +\ifNR@showkeys + \ifx\SK@ref\@empty + \else + \renewcommand\NR@ref@showkeys[1]{% + \@safe@activestrue + \SK@\SK@@ref{#1}% + \@safe@activesfalse} \fi \fi % \end{macrocode} -% Package \xpackage{hyperref} uses its own definitions of |\ref| and -% |\pageref| because it extends the syntax by the star form. +% Package \xpackage{hyperref} uses the same +% definitions of |\ref|, |\Ref| and +% |\pageref| but has to redefine the non-starred command to +% add the hyperlink support. % |\DeclareRobustCommand| is used by \xpackage{hyperref}. % Package |nameref| can be loaded before, after % \xpackage{hyperref} or after % \xpackage{hyperref}'s definitions in |\AtBeginDocument|. +% We have to postpone the definition to |\AtBeginDocument| to +% avoid that showkeys overwrites them again. % \begin{macrocode} -\@ifpackageloaded{hyperref}{% -}{% +\AddToHook{begindocument}{% % \end{macrocode} % \begin{macro}{\ref} % \begin{macrocode} - \DeclareRobustCommand{\ref}{\T@ref}% + \DeclareDocumentCommand\ref{s} + {\IfBooleanTF{#1}{\@refstar}{\T@ref}}% % \end{macrocode} % \end{macro} % \begin{macro}{\pageref} % \begin{macrocode} - \DeclareRobustCommand{\pageref}{\T@pageref}% + \DeclareDocumentCommand\pageref{s} + {\IfBooleanTF{#1}{\@pagerefstar}{\T@pageref}}% +% \end{macrocode} +% \end{macro} +% \begin{macro}{\Ref} +% \begin{macrocode} + \DeclareDocumentCommand\Ref{s} + {\IfBooleanTF{#1}{\@Refstar}{\T@Ref}}% % \end{macrocode} % \end{macro} % \begin{macrocode} } % \end{macrocode} +% \begin{macrocode} +\DeclareHookRule{begindocument}{showkeys}{before}{nameref} +% \end{macrocode} +% % % \subsection{Usage and frontend} % Access the (third) name part with |\nameref|; % \begin{macro}{\T@nameref} % \begin{macrocode} \def\T@nameref#1{% + \NR@ref@showkeys{#1}% + \begingroup + \let\label\@gobble + \NR@setref{#1}\@thirdoffive{#1}% + \endgroup +}% +% \end{macrocode} +% \end{macro} +% \begin{macro}{\@namerefstar} +% \begin{macrocode} +\def\@namerefstar#1{% + \NR@ref@showkeys{#1}% \begingroup \let\label\@gobble \NR@setref{#1}\@thirdoffive{#1}% \endgroup }% -\ifNR@showkeys - \ifx\SK@ref\@empty - \else - \def\T@nameref#1{% - \@safe@activestrue - \SK@\SK@@ref{#1}% - \@safe@activesfalse - \begingroup - \let\label\@gobble - \NR@setref{#1}\@thirdoffive{#1}% - \endgroup - }% - \fi -\fi % \end{macrocode} % \end{macro} % \begin{macrocode} -%\@ifclassloaded{memoir}{% -% \ltx@IfUndefined{@mem@titlerefnolink}\ltx@secondoftwo{% -% \ltx@IfUndefined{@mem@titleref}\ltx@secondoftwo\ltx@firstoftwo -% }% -%}\ltx@secondoftwo -%{% -% \DeclareRobustCommand*{\nameref}{% -% \@ifstar\@mem@titlerefnolink\@mem@titleref -% }% -%}{% % \end{macrocode} % \begin{macro}{\nameref} % \begin{macrocode} - \DeclareRobustCommand*{\nameref}{% - \@ifstar\T@nameref\T@nameref - }% -%} +\NewDocumentCommand\nameref{s} + {\IfBooleanTF{#1}{\@namerefstar}{\T@nameref}} % \end{macrocode} % \end{macro} % \begin{macro}{\Nameref} % An extended form which gives title and page number. +% Not really useful, quotes are english, and no starred version. +% varioref can do that better. Remove?? % \begin{macrocode} \def\Nameref#1{`\nameref{#1}' on page~\pageref{#1}} % \end{macrocode} @@ -733,21 +873,24 @@ % to provide expandable versions without link of \cmd{\ref} % and \cmd{\pageref}. As possible target I could only find % \cmd{\begingroup}: -% \begin{macrocode} -\@ifpackageloaded{ifthen}{% - \let\NROrg@ifthenelse\ifthenelse - \def\ifthenelse{% - \let\begingroup\NR@TE@begingroup - \NROrg@ifthenelse - }% - \let\NROrg@begingroup\begingroup - \def\NR@TE@begingroup{% - \let\begingroup\NROrg@begingroup - \begingroup - \def\ref##1{\getrefbykeydefault{##1}{}{??}}% - \def\pageref##1{\getrefbykeydefault{##1}{page}{0}}% - }% -}{} +% Changed/disabled 2022-04-13: ifthen takes care itself to +% change \cmd{\pageref} to an expandable version. +% \begin{macrocode} +\@ifundefined{@kernel@pageref@exp} + {\@ifpackageloaded{ifthen}{% + \let\NROrg@ifthenelse\ifthenelse + \def\ifthenelse{% + \let\begingroup\NR@TE@begingroup + \NROrg@ifthenelse + }% + \let\NROrg@begingroup\begingroup + \def\NR@TE@begingroup{% + \let\begingroup\NROrg@begingroup + \begingroup + \def\ref##1{\getrefbykeydefault{##1}{}{??}}% + \def\pageref##1{\getrefbykeydefault{##1}{page}{0}}% + }% + }{}}{} % \end{macrocode} % % \subsection{Compatibility with varioref} @@ -760,101 +903,11 @@ \AtBeginDocument{% \ifx\csname @@vpageref\endcsname\relax \else -%FMi % \end{macrocode} -% Test if we are using the new varioref ... +% This requires a varioref newer than 2019-09-12 % \begin{macrocode} - \ifdefined\vp@gerefstar \let\NR@@vpageref\@@vpageref -% \end{macrocode} -% if not then old patching code -% \begin{macrocode} - \else - \def\NR@@vpageref#1[#2]#3{% - \leavevmode\unskip - \global\advance\c@vrcnt\@ne - \@ifundefined{r@\the\c@vrcnt @vr}% - {\@namedef{r@\the\c@vrcnt @vr}{{??}{??}{}{}{}}}{}% - \edef\@tempa{% - \expandafter\expandafter\expandafter - \@secondoffive\csname r@\the\c@vrcnt @vr\endcsname - }% - \@ifundefined{r@\the\c@vrcnt @xvr}% - {\@namedef{r@\the\c@vrcnt @xvr}{{??}{??}{}{}{}}}{}% - \edef\@tempb{% - \expandafter\expandafter\expandafter - \@secondoffive\csname r@\the\c@vrcnt @xvr\endcsname - }% - {% - \let\@currentlabel\@empty - \expandafter\label\expandafter{\the\c@vrcnt @xvr}% - }% - \ifx\@tempa\@tempb - \else - \vref@err{% - \noexpand\vref at page boundary % - \@tempb-\@tempa\space (may loop)% - }% - \fi - \@ifundefined{r@#3}{\@namedef{r@#3}{{??}{??}{}{}{}}}{}% - \edef\thevpagerefnum{% - \expandafter\expandafter\expandafter - \@secondoffive\csname r@#3\endcsname - }% - \ifx\vref@space\@undefined - \space - \else - \vref@space - \fi - \ifx\@tempa\thevpagerefnum - #1% - \else - #2% - \is@pos@number\thevpagerefnum{% - \is@pos@number\@tempa{% - \@tempcnta\@tempa - \advance\@tempcnta\@ne - }{% - \@tempcnta\maxdimen - }% - \ifnum \thevpagerefnum =\@tempcnta - \ifodd\@tempcnta - \if@twoside - \reftextfaceafter - \else - \reftextafter - \fi - \else - \reftextafter - \fi - \else - \advance\@tempcnta-2 % - \ifnum \thevpagerefnum =\@tempcnta - \ifodd\@tempcnta - \reftextbefore - \else - \if@twoside - \reftextfacebefore - \else - \reftextbefore - \fi - \fi - \else - \reftextfaraway{#3}% - \fi - \fi - }{% - \reftextfaraway{#3}% - }% - \fi - {% - \let\@currentlabel\@empty - \expandafter\label\expandafter{\the\c@vrcnt @vr}% - }% - }% - \fi -%FM - end mod - \def\@@vpageref#1[#2]#3{% + \def\@@vpageref#1[#2]#3{% \begingroup \csname @safe@activestrue\endcsname \edef\x{#3}% @@ -868,45 +921,29 @@ \x }% \DeclareRobustCommand\vnameref[1]{% - \unskip~\nameref{#1}% + \unskip~\nameref{#1} % \@vpageref[\unskip]{#1}% }% \fi } % \end{macrocode} -% \begin{macrocode} -\@ifundefined{@Refstar}{% - \def\T@Ref#1{% - \NR@setref{#1}\NR@MakeUppercaseFirstOfFive{#1}% - }% - \def\NR@MakeUppercaseFirstOfFive#1#2#3#4#5{% - \MakeUppercase#1% - }% -}{}% -\AtBeginDocument{% - \@ifpackageloaded{varioref}{% - \@ifundefined{@Refstar}{% - \DeclareRobustCommand*{\Ref}[1]{% - \T@Ref{#1}% - }% - }{}% - }{}% -}% -% \end{macrocode} % % \subsection{Support for package \xpackage{listings}} % % \begin{macrocode} \AtBeginDocument{% \@ifpackageloaded{listings}{% - \let\NROrg@lst@MakeCaption\lst@MakeCaption - \def\lst@MakeCaption{% - \ifx\lst@label\@empty - \else - \let\@currentlabelname\lst@@caption - \fi - \NROrg@lst@MakeCaption - }% + \@ifundefined{NR@nopatch@listings} + {% + \let\NROrg@lst@MakeCaption\lst@MakeCaption + \def\lst@MakeCaption{% + \ifx\lst@label\@empty + \else + \let\@currentlabelname\lst@@caption + \fi + \NROrg@lst@MakeCaption + }% + }{}% }{}% } % \end{macrocode} -- cgit v1.2.3