[latex3-commits] [git/LaTeX3-latex3-hyperref] cleanup-patches: allow to suppress the sectioning patches (d3b7c80)

[Ulrike Fischer]

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

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

commit d3b7c8071d78a465147c071b39763acbb6a7003b
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date:   Mon May 2 00:39:13 2022 +0200

    allow to suppress the sectioning patches


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

d3b7c8071d78a465147c071b39763acbb6a7003b
 doc/hyperref-doc.tex | 32 ++++++++++++++++++++++++++++----
 hyperref.dtx         |  4 +++-
 2 files changed, 31 insertions(+), 5 deletions(-)

diff --git a/doc/hyperref-doc.tex b/doc/hyperref-doc.tex
index 0114a8c..dda8369 100644
--- a/doc/hyperref-doc.tex
+++ b/doc/hyperref-doc.tex
@@ -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,30 @@ are naturally interfaces too, they are not explicitly mentioned here again.
 
 This section is work in progress. Suggestions or comments are welcome.
 
+\subsection{Patches and how to suppress them}
+
+Patches to external commands can be avoided alltogether by loading hyperref with the option \texttt{implicit=false}. But 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.
+
+We start with the sectioning commands. 
+
+\begin{itemize}
+\item hyperref patches \cs{@sect}, \cs{@ssect}, \cs{@chapter}, \cs{@schapter},
+\cs{@part}, \cs{@spart}.  
+
+To commands for the starred sections a target for a link is added. To the other commands
+it is added if the sectioning is unnumbered, e.g. because of the \texttt{secnumdepth} setting or in the 
+frontmatter. 
+
+The patch can be suppressed by defining the command \cs{hyper at nopatch@sectioning}. This should normally
+be done only by a class or a package which provides sectioning commands and can add the targets itself.
+Targets have a location on the page and e.g. the section commands should take indents into
+account. Note that the nameref package patches these commands too to add commands to store the title text
+for a label. Check the nameref documentation about a way to suppress these patches. 
+\end{itemize}
+
+
+
 \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
diff --git a/hyperref.dtx b/hyperref.dtx
index 01e779a..a94d630 100644
--- a/hyperref.dtx
+++ b/hyperref.dtx
@@ -10232,7 +10232,6 @@
 \fi
 %</pdfmarkbase|dvipdfm|xetex>
 %    \end{macrocode}
-%
 %    \begin{macrocode}
 %<*package>
 %    \end{macrocode}
@@ -19756,6 +19755,8 @@
     \hss
   }%
 }
+\@ifundefined{hyper at nopatch@sectioning}
+{
 \let\H at old@ssect\@ssect
 \def\@ssect#1#2#3#4#5{%
   \Hy at MakeCurrentHrefAuto{section*}%
@@ -19851,6 +19852,7 @@
     \H at old@sect{#1}{#2}{#3}{#4}{#5}{#6}[{#7}]{#8}%
   }%
 }
+}{}
 %    \end{macrocode}
 %    \begin{macrocode}
 %</outlines|hypertex>