[latex3-commits] [git/LaTeX3-latex3-pdfresources] develop: add document about link contexts (df93b7c)

[Ulrike Fischer]

Repository : https://github.com/latex3/pdfresources
On branch  : develop
Link       : https://github.com/latex3/pdfresources/commit/df93b7cc0823919c27bfe6694c0c58a0f20b4fd2

>---------------------------------------------------------------

commit df93b7cc0823919c27bfe6694c0c58a0f20b4fd2
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date:   Fri Jul 15 12:34:18 2022 +0200

    add document about link contexts


>---------------------------------------------------------------

df93b7cc0823919c27bfe6694c0c58a0f20b4fd2
 info/linkcontext-hooks.pdf | Bin 0 -> 193481 bytes
 info/linkcontext-hooks.tex | 106 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 106 insertions(+)

diff --git a/info/linkcontext-hooks.pdf b/info/linkcontext-hooks.pdf
new file mode 100644
index 0000000..8566147
Binary files /dev/null and b/info/linkcontext-hooks.pdf differ
diff --git a/info/linkcontext-hooks.tex b/info/linkcontext-hooks.tex
new file mode 100644
index 0000000..a3d6726
--- /dev/null
+++ b/info/linkcontext-hooks.tex
@@ -0,0 +1,106 @@
+% !Mode:: "TeX:UTF-8:Main"
+\DocumentMetadata{}
+\documentclass{l3doc}
+\usepackage{tcolorbox}
+\tcbuselibrary{listings}
+
+\MakeShortVerb|
+\hypersetup{pdfborder=0 0 1}
+
+\IfFormatAtLeastTF{2021-11-15}
+ {}
+ {\providecommand\ActivateGenericHook{\ProvideHook}}
+
+\ActivateGenericHook{hyp/link/acro} %cheating
+\ActivateGenericHook{hyp/link/link}
+
+\title{Handling conceptual links  with generic hooks}
+\author{Ulrike Fischer}
+\begin{document}
+
+\maketitle
+
+The basic command \pkg{hyperref} uses to create an internal document link (a \enquote{GoTo} link in PDF speech)
+has a quite unknown first argument which can be used to differentiate the links.
+Only two values for this argument are currently in use: |cite| used by various citation commands and |link| used
+for everything else. The actual effect of the argument is quite restricted in older \pkg{hyperref} versions:
+It only calls |\csname @#1color\endcsname| at some point, so it simply
+selects a color.
+
+In the new \pkg{hyperref} driver which is used when the pdfmanagement is active this argument has been connected
+with a generic hook, |hyp/link/|\meta{name}. This hook is executed at the begin of the link command, outside
+the actual link but inside a group.
+
+Packages or code which create links which are used for a specific concept,
+like e.g. citations, or acronyms, or glossary terms,
+or links to an author list can make use of this to make the links customizable by the user.
+They only need to create the link with |\hyper at linkstart| and |\hyper at linkend| with a suitable
+first argument (both commands are official interfaces of \pkg{hyperref} for links) and to activate the
+relevant hook (for |cite| the hook is already declared, \pkg{hyperref} uses it to reimplement
+the |citecolor| keys. So it can be used directly).
+For other types (including the default type |link|) the hooks must be activated first.
+This can be done with |\ActivateGenericHook|.
+
+
+The hook can e.g. change colors with |\hypersetup| or add some text before the link.
+The color of a internal link is stored in |hyp/color/link|,
+using |\colorlet| to change it is possible too, but this method is less clean: it relies a bit
+on some knowledge about the internal processing, and doesn't work for border colors which are
+set differently to text colors.
+
+
+
+
+
+\hypertarget{some-target}{}
+
+\begin{tcblisting}{title= Example with the predefined hook for the keyword \enquote{cite}}
+\makeatletter
+\hyper at linkstart{cite}{some-target}1234\hyper at linkend
+
+\AddToHook{hyp/link/cite}
+ {Cite:~\hypersetup{linkcolor=blue,linkbordercolor=yellow}}
+
+\hyper at linkstart{cite}{some-target}1234\hyper at linkend
+
+\end{tcblisting}
+
+
+
+\begin{tcblisting}{title= Activation of a new keyword}
+
+\ActivateGenericHook{hyp/link/acro}
+\AddToHookNext{hyp/link/acro}{Acro:~\colorlet{hyp/color/link}{blue}\sffamily}
+
+\makeatletter
+\hyper at linkstart{acro}{some-target}acronym\hyper at linkend\ more text
+\makeatother
+
+\end{tcblisting}
+
+
+\begin{tcblisting}{title= Activation of the existing keyword \enquote{link}}
+
+\AddToHook{hyp/link/link}{Link:~\colorlet{hyp/color/link}{orange}\sffamily}
+\ActivateGenericHook{hyp/link/link}
+
+\makeatletter
+\hyper at linkstart{link}{some-target}see 1\hyper at linkend
+\makeatother
+
+\hyperlink{some-target}{see 2}
+\end{tcblisting}
+
+
+\begin{tcblisting}{title= keyword without hook activation}
+
+\hypersetup{linkcolor=brown,linkbordercolor=red}
+\AddToHook{hyp/link/unknown}{Blub??}
+\makeatletter
+\hyper at linkstart{unknown}{some-target}acronym\hyper at linkend\ more text
+\makeatother
+
+\end{tcblisting}
+
+
+\end{document} 
\ No newline at end of file