summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/hyperref/doc/hyperref-doc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/hyperref/doc/hyperref-doc.tex')
-rw-r--r--macros/latex/contrib/hyperref/doc/hyperref-doc.tex273
1 files changed, 104 insertions, 169 deletions
diff --git a/macros/latex/contrib/hyperref/doc/hyperref-doc.tex b/macros/latex/contrib/hyperref/doc/hyperref-doc.tex
index 88f4c95753..d9d11ef0cc 100644
--- a/macros/latex/contrib/hyperref/doc/hyperref-doc.tex
+++ b/macros/latex/contrib/hyperref/doc/hyperref-doc.tex
@@ -166,7 +166,7 @@
}
\makeatother
\title{Hypertext marks in \hologo{LaTeX}: a manual for \xpackage{hyperref}}
-\date{2023-07-08 v7.01b}
+\date{2023-10-21 v7.01c}
\begin{document}
@@ -830,6 +830,36 @@ plainpages & boolean & false & Forces page anchors to be named by the Arabic
& & & of the page number, rather than the formatted form. \\
\end{longtable}
+\subsection{Page anchors}
+
+In a PDF \xpackage{hyperref} adds to every page an target for links (in the upper left corner). These targets are for example used by the index to references the pages of the entries. Unlike the targets generated by other counters it is not possible to change the names of these targets by defining a \cs{theHpage} command: the name can currently not be stored in a label and so is not referenceable. Nevertheless a few options exists, they are already mentioned elsewhere in the documentation but we provide here a summary:
+
+\begin{description}
+\item[\texttt{pageanchor}] A boolean option that determines whether every page is given an target at the top left corner. If this is turned off, \verb|\printindex| will not contain valid hyperlinks.
+\item[\texttt{hypertexnames}] By default the targets have names built with \cs{thepage}: \verb|page.\thepage|, so e.g., \texttt{page.4} or \texttt{page.iii}. The names require that every page as an unique number representation. A frequent problem here is with title pages which often don't show page numbers but internally use the same number as a following page. If you get messages about \texttt{destination with the same identifier (name{page.1})}, change the number representation of title pages or disable the page target.
+
+ If the boolean option \texttt{hypertexnames} is set to false, an internal page counter is stepped and used as arabic number. In most cases this should mean that you get the absolute page number (exceptions could be with documents throwing away or duplicating pages at shipout). This option avoids the problem with duplicated identifiers, but does not work with an index, as the backlinks have to be created from the represention passed to the index.
+\item[\texttt{plainpages}] This forces page anchors to be named by the arabic form, but unlike the previous option it does not use an internal counter but the page counter. That means if you have for example roman and arabic pages you will get duplicated target names as page i and page 1 both set the anchor \texttt{page.1}.
+\end{description}
+
+\begin{cmdsyntax}
+\ci{@currentHpage}
+\end{cmdsyntax}
+Starting with version 7.01c \xpackage{hyperref} stores the name of the page
+target it has just set into the (global) variable \cs{@currentHpage}. The
+fallback value is \texttt{Doc-Start}. As the target is set when the page is
+shipout, \cs{@currentHpage} is only reliable at shipout. With a
+\hologo{LaTeX} format from 2023-11-01 the name can be labeled like this:
+
+\begin{verbatim}
+%labeling in the document
+\RecordProperties{mylabel}{pagetarget}
+%linking to the page:
+\hyperlink{\RefProperty{mylabel}{pagetarget}}{some text}
+\end{verbatim}
+
+
+
\subsection{Configuration options}
\begin{longtable}{>{\ttfamily}ll>{\itshape}lp{9cm}}
@@ -1002,7 +1032,7 @@ next \TeX\ run if it is edited to contain the line
\let\WriteBookmarks\relax
\end{verbatim}
-\subsection{PDF display and information options}
+\subsection{PDF display and information options}\label{sec:pdfdata}
\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
@@ -1014,6 +1044,8 @@ 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 \\
+pdfcreationdate & date & & Sets the creation date, see below the table for more info about the format\\
+pdfmoddate & date & & Sets the modification date, see below the table for more info about the format\\
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|.
@@ -1086,6 +1118,25 @@ pdfwindowui & boolean & true & make PDF user interface elements visible
unicode & boolean & true & Unicode encoded PDF strings
\end{longtable}
+ The dates \verb|CreationDate| and \verb|ModDate|
+ are normally set automatically to the current date/time when the compilation
+ started. If they should be changed
+ (e.g. for regression tests to produce reproducible documents) they can
+ be set with \verb|\hypersetup| with the keys
+ \verb|pdfcreationdate|, \verb|pdfmoddate| or externally by setting the \verb|SOURCE_DATE_EPOCH| environment variable.
+
+ \begin{verbatim}
+ \hypersetup{pdfcreationdate=D:20010101205959-00'00'}
+ \end{verbatim}
+
+ The format should be a full date/time in PDF format, so one of these (naturally
+ the numbers can change):
+ \begin{verbatim}
+ D:20010101205959-00'00'
+ D:20010101205959+00'00'
+ D:20010101205959Z
+ \end{verbatim}
+
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
@@ -1121,12 +1172,11 @@ TwoPageLeft & Displays two pages, odd-numbered pages to the left (since PDF 1
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}).
+Finally, the \texttt{pdfpagetransition} can be one of the following values,
+where \textit{/Di} stands for direction of motion in degrees, generally in 90
+degree 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
@@ -1240,6 +1290,7 @@ 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} & \\
+pdfcreationdate & & Sets the creation date, see below the table in section~\ref{sec:pdfdata} for more info about the format\\
pdfdirection & \textit{empty} & direction setting \\
pdfdisplaydoctitle & \textit{false} & display document title instead
of file name in title bar\\
@@ -1252,6 +1303,7 @@ 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 \\
+pdfmoddate & & Sets the modification date, see below the table in section~\ref{sec:pdfdata} for more info about the format\\
pdfnewwindow & \textit{false} & make links that open another PDF \\
& & file start a new window \\
pdfnonfullscreenpagemode
@@ -1799,7 +1851,7 @@ sequence error would arise.
\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.
+an anchor name which can be referenced with a \verb|\bookmark| command from the bookmark package:
\begin{verbatim}
\hypersetup{next-anchor=toc}
@@ -2799,33 +2851,39 @@ The draft option defines the macros as follows
\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
+Package \xpackage{hyperref} aims to cooperate with other packages, but while
+the long term goal is to remove patches and to move link support into the
+kernel, classes and packages there are still 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 manipulate the bibliographic mechanism. Peter William's
+ \xpackage{harvard} package is supported. However, the recommended
+ package is either Patrick Daly's \xpackage{natbib} package that has
+ specific \xpackage{hyperref} hooks to allow reliable interaction or the
+ \xpackage{biblatex} package. Both packages cover a very wide variety of
+ layouts and citation styles, all of which work with
+ \xpackage{hyperref}.
-\item Packages that changes \ci{label} and \ci{ref}
-macros.
+\item Packages that changes \ci{label} and \ci{ref} macros. Since \LaTeX{}
+ 2023-06-01 the kernel and \xpackage{hyperref}/\xpackage{nameref} use
+ the same \ci{label} definition. \ci{label} has a hook for external
+ packages. There should be no need for external packages and classes to
+ redefine them.
\item Packages that do anything serious with the index.
-\item Packages that do anything serious with sectioning commands and the toc
+\item Packages that do anything serious with sectioning commands and the
+ toc.
\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.
+The \xpackage{hyperref} package is distributed with a variant of the
+\xpackage{xr}, \xpackage{xr-hyper}\footnote{It will be merged with the
+\xpackage{xr} package soon}, which support crossdocument links using
+\hologo{LaTeX}'s normal \cs{label}/\cs{ref} mechanisms.
\subsection{Package Compatibility}
@@ -2857,7 +2915,9 @@ Currently only package loading orders are available:
\subsubsection{amsrefs}
- Package loading order:
+The documentation of \xpackage{amsrefs} claims that the package must be
+loaded after \xpackage{hyperref} (it is unclear if that is really true) so
+the recommended package loading order is:
\begin{verbatim}
\usepackage{hyperref}
@@ -2930,25 +2990,6 @@ Currently only package loading orders are available:
\usepackage{chappg}
\end{verbatim}
-\subsubsection{cite}
-
- This is from Mike Shell:
- cite.sty cannot currently be used with \xpackage{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 \xpackage{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
@@ -3019,57 +3060,6 @@ Currently only package loading orders are available:
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}
@@ -3195,6 +3185,8 @@ or \xpackage{subcaption}
\subsubsection{ucs/utf8x.def}
+Note: utf8 is now the default in \LaTeX{} and \xpackage{ucs} is no
+ longer recommended.
The first time a multibyte UTF8 sequence is called, it
does some calculations and stores the result in a macro
@@ -3213,84 +3205,22 @@ or \xpackage{subcaption}
The notation with two carets avoids trouble with 8-bit bytes
for the README file, you can use the characters directly.
-Note: utf8 is now the default in \LaTeX{} and \xpackage{ucs} is no
- longer recommended.
\subsubsection{varioref}
- There are too many problems with \xpackage{varioref}. Nobody has time to
- sort them out. Therefore this package is now unsupported.
-
- Perhaps you are lucky and some of the features of \xpackage{varioref} works
- with the following loading order:
+Most previous problems with \xpackage{varioref} should be resolved. There is
+only an open issue regarding \ci{vrefformat}
+(\url{https://github.com/latex3/hyperref/issues/225}).
+
+It is recommended to load \xpackage{varioref} always with the option
+\texttt{nospace}, see the documentation.
\begin{verbatim}
- \usepackage{nameref}
- \usepackage{varioref}
- \usepackage{hyperref}
+ \usepackage[nospace]{varioref}
\end{verbatim}
-
- Also some babel versions can be problematic. For example,
- 2005/05/21 v3.8g contains a patch for \xpackage{varioref} that breaks
- the \xpackage{hyperref} support for \xpackage{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 \xpackage{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:
@@ -3323,7 +3253,7 @@ Note: utf8 is now the default in \LaTeX{} and \xpackage{ucs} is no
\subsection{Wrapped/broken link support}
Only few drivers support automatically wrapped/broken links,
- e.g. pdftex, dvipdfm, hypertex. Other drivers lack this
+ e.g. pdftex, dvipdfmx, hypertex. Other drivers lack this
feature, e.g. dvips, dvipsone.
Workarounds:
@@ -3351,9 +3281,14 @@ Note: utf8 is now the default in \LaTeX{} and \xpackage{ucs} is no
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.
+ \item The driver allows it, but the link result might include the footer
+ and/or header. This can currently (2023) be avoided by using the PDF
+ management and to load at least the new-or-1 module from latex-lab:
+
+ \begin{verbatim}
+ \DocumentMetadata{testphase=new-or-1}
+ \end{verbatim}
+
\end{itemize}
\subsection{Footnotes}