[latex3-commits] [git/LaTeX3-latex3-hyperref] cleanup-patches: start document package interfaces (84ccc4f)

[Ulrike Fischer]

Repository : https://github.com/latex3/hyperref
On branch  : cleanup-patches
Link       : https://github.com/latex3/hyperref/commit/84ccc4f65624e9d45203b54d6791810e8e27fd24

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

commit 84ccc4f65624e9d45203b54d6791810e8e27fd24
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date:   Wed Jun 30 21:02:59 2021 +0200

    start document package interfaces


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

84ccc4f65624e9d45203b54d6791810e8e27fd24
 doc/hyperref-doc.tex | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 66 insertions(+), 1 deletion(-)

diff --git a/doc/hyperref-doc.tex b/doc/hyperref-doc.tex
index 88e0a65..d80691b 100644
--- a/doc/hyperref-doc.tex
+++ b/doc/hyperref-doc.tex
@@ -315,6 +315,71 @@ 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 feature are nowadays a common requirement. \xpackage{hyperref}
+patches quite a number of commands from the  \LaTeX{} core and from packages
+to add such features. But this is rather fragile and it add dependencies 
+on the loading order and can break if the external packages break. 
+It is therefore much better if packages add suitable support to their commands directly. 
+Quite a lot packages actually did this, but due to missing documentation of the interface
+they often looked into the code and then used internal commands not meant as public command.
+
+The following tries to describe the existing variables and commands that 
+can be viewed as public interfaces or which should or can be set by packages
+to stay compatible with the \xpackage{hyperref} command. Documented user commands
+are naturally interfaces too, they are not explicitly mentioned here again.
+
+This section is work in progress. Suggestions or comments are welcome.
+
+\subsection{Counters}
+Counters play an important part in the code. They are used to create destination names and 
+to define hierarchies like the bookmarks. To work correctly often they require some additional 
+setups.
+
+\begin{description}
+
+\item[\cs{theH<counter>}]  \xpackage{hyperref} creates destination names for 
+link anchor typically out of the name of the counter and the \cs{the<counter>} value.
+This can fail, e.g. if \cs{the<counter>} is not unique through the document, 
+or if it is not expandable. In such cases \cs{theH<counter>} should be defined so that
+it gives a unique, expandable value. It doesn't harm to define it even if 
+\xpackage{hyperref} is not loaded. 
+
+\item[\cs{toclevel@<counter>}] This is a variable which should contain a number. 
+It is used for the level in the bookmarks. It should be defined for all counters
+which are used in toc like lists and \cs{addcontentsline}. Typical values are
+
+\begin{verbatim}
+\def\toclevel at part{-1}
+\def\toclevel at chapter{0}
+\def\toclevel at section{1}
+\def\toclevel at subsection{2}
+\def\toclevel at subsubsection{3}
+\def\toclevel at paragraph{4}
+\def\toclevel at subparagraph{5}
+\def\toclevel at 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 at anchor {destination name}
+ \hyper at anchorstart {destination name}
+ \hyper at anchorend
+ \hyper at link   {context}{destination name}{link text}  %GoTo
+ \hyper at linkstart {context} {destination name}         %GoTo
+ \hyper at linkend                                        %GoTo
+ \hyper at linkfile  {link text} {filename} {destname}    %GoToR
+ \hyper at linkurl   {link text}{url}                     %URI
+ \hyper at linklaunch{filename} {link text} {Parameters}  %Launch, only with new generic driver 
+ \hyper at linknamed {action}{link text}                  %Named, only with new generic driver
+\end{verbatim}
 
 
 \section{Package options}
@@ -1360,7 +1425,7 @@ command the current bookmark level has not changed.
 \end{itemize}
 Therefore I recommend using this package.
 
-\subsubsection{Replacement macros}
+\subsubsection{Replacement macros}\label{sec:texorpdfstring}
 
 \textsf{hyperref} takes the text for bookmarks from the arguments of
 commands like \ci{section}, which can contain things like math, colors,