CTAN sync 202205150300

1 files changed, 99 insertions, 6 deletions

diff --git a/macros/latex/contrib/hyperref/doc/hyperref-doc.tex b/macros/latex/contrib/hyperref/doc/hyperref-doc.tex
index c2375a58e7..4fb70918e8 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{2022-02-21 v7.00n}
+\date{2022-05-13 v7.00o}
 
 \begin{document}
 
@@ -180,7 +180,7 @@
 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
+or only in edge cases. The documentation reflects 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.
 
@@ -200,8 +200,8 @@ 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
+Quite a number are either no longer needed or should be done by the original packages.
+Those 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.
 
@@ -351,7 +351,7 @@ option used in this document.
 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.
+on the loading order and can break if the external packages changes.
 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.
@@ -363,6 +363,7 @@ 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
@@ -412,6 +413,95 @@ New drivers must provide this commands with similar arguments.
  \hyper@linknamed {action}{link text}                  %Named, only with new generic driver
 \end{verbatim}
 
+\subsection{Creating targets}
+
+Internal links and bookmarks need something they can jump to. In a PDF this is normally called
+a \emph{destination} (and the primitive is therefor called \cs{pdfdest}), in HTML it is more
+common to call this an \emph{anchor} (and the \xpackage{hyperref} uses therefor \cs{hyper@anchor}).
+History can not be undone but future commands and descriptions will use the generic
+\emph{target} unless the PDF specific destination is meant.
+
+Targets are created automatically when \cs{refstepcounter} is used and in many cases this
+does the right thing and nothing more is needed.
+But there are exceptions:
+\begin{itemize}
+\item A needed target can be missing for example
+if a sectioning command doesn't have a number as the starred version is used or due to the
+setting of \texttt{secnumdepth}.
+\item The target created by the \cs{refstepcounter} can be in the wrong place.
+\item The target created by the \cs{refstepcounter} can affect spacing.
+\item The target name created by the \cs{refstepcounter} is not usable, e.g. in
+\cs{bibitem} where you need a target name bases on the bib-key.
+\end{itemize}
+
+Package authors and users can use the following commands to create and manipulate
+targets. The commands are described in more detail in \texttt{hyperref-linktarget.pdf}.
+
+\begin{verbatim}
+ \MakeLinkTarget
+ \LinkTargetOff
+ \LinkTargetOn
+ \NextLinkTarget
+ \SetLinkTargetFilter
+\end{verbatim}
+
+The first four commands will be defined also in \LaTeX{} directly as no-op and so can be
+used even if \xpackage{hyperref} is not loaded.
+
+Until \LaTeX{} is updated package authors can also provide these definitions directly:
+
+\begin{verbatim}
+\ProvideDocumentCommand\MakeLinkTarget{sO{}m}{}
+\ProvideDocumentCommand\LinkTargetOn{}{}
+\ProvideDocumentCommand\LinkTargetOff{}{}
+\ProvideDocumentCommand\NextLinkTarget{m}{}
+\end{verbatim}
+
+\subsection{Patches and how to suppress them}
+
+The patches to external commands made by
+\xpackage{hyperref} can be avoided in toto by loading \xpackage{hyperref}
+with the option \texttt{implicit=false}.
+But suppressing everything is often too drastic.
+There is a work in progress to classify
+the patches and to offer interfaces to suppress them in a more granular way.
+
+\begin{description}
+\item[sectioning commands]
+\begin{itemize}
+\item hyperref patches \cs{@sect}, \cs{@ssect}, \cs{@chapter}, \cs{@schapter},
+\cs{@part}, \cs{@spart}.
+
+\item It adds to the starred commands a target for a link (with the
+prefix \texttt{chapter*} for chapters and \texttt{section*} otherwise).
+To the other commands it adds a target for a link
+if the sectioning is unnumbered, e.g. because of the \texttt{secnumdepth}
+setting or in the front matter.
+
+\item The patch can be suppressed by defining the command \cs{hyper@nopatch@sectioning}.
+This should normally be done only by a class or a package
+which provides sectioning commands and adds the targets itself.
+Targets have a location on the page and e.g. the section commands should take indents into
+account. Targets are needed for bookmarks and the table of contents,
+so \cs{@currentHref} should get the correct meaning before
+\cs{addcontentsline} is used.
+
+\item Note that the \xpackage{nameref} package patches these commands too
+to add commands to store the title text in \cs{@currentlabelname}.
+Check the \xpackage{nameref} documentation about a way to suppress these patches.
+\end{itemize}
+
+\item[footnotes] To enable (partly) the linking of footnotes hyperref redefines or patches various commands, in part package dependant.
+\begin{itemize}
+\item hyperref redefines \cs{@xfootnotenext}, \cs{@xfootnotemark}, \cs{@mpfootnotetext},
+    \cs{@footnotetext}, \cs{@footnotemark}.
+    If \xpackage{tabularx} is loaded it changes \cs{TX@endtabularx}. If \xpackage{longtable} is loaded it changes \cs{LT@p@ftntext}.
+    If \xpackage{fancyvfb} is loaded it redefines \cs{V@@footnotetext}. It also redefines \cs{footref} and \cs{maketitle}.
+    
+\item \emph{All} those redefinitions can be suppressed by defining \cs{hyper@nopatch@footnote}. Be aware that this can suppress links but also make unwanted links appear.
+\end{itemize}
+
+\end{description}
 
 \section{Package options}
 
@@ -1638,7 +1728,7 @@ an anchor name which can be referenced with a bookmark command.
 
 \subsection{Option `localanchorname'}
 
- When an anchor is set (e.g. via \verb|\refstepcounter|, then the
+  When\marginpar{Deprecated 2022-04-27 v7.00o} an anchor is set (e.g. via \verb|\refstepcounter|, then the
   anchor name is globally set to the current anchor name.
 
 
@@ -1659,6 +1749,9 @@ an anchor name which can be referenced with a bookmark command.
   might be situations, where the anchor name is not available
   as expected.
 
+ The option is deprecated: it makes it difficult for package authors
+ to add targets for links if it is unclear if \verb|\@currentHref| is
+ set locally or globally.
 
 \subsection{Option `customdriver'}