start document package interfaces

doc/hyperref-doc.tex

@@ -315,6 +315,71 @@ \section{Implicit behavior}
 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@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}
@@ -1360,7 +1425,7 @@ \subsubsection{Setting bookmarks}
 \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,