[latex3-commits] [latex3/hyperref] test-currentHpage: add access to page anchor name (ddf2d88)

[github at latex-project.org]

Repository : https://github.com/latex3/hyperref
On branch  : test-currentHpage
Link       : https://github.com/latex3/hyperref/commit/ddf2d8850311a4367e4e7df3609c8ab174977ebf

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

commit ddf2d8850311a4367e4e7df3609c8ab174977ebf
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date:   Thu Oct 12 17:17:29 2023 +0200

    add access to page anchor name


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

ddf2d8850311a4367e4e7df3609c8ab174977ebf
 doc/hyperref-doc.tex | 28 ++++++++++++++++++++++++++++
 hyperref.dtx         | 20 ++++++++++++++++----
 2 files changed, 44 insertions(+), 4 deletions(-)

diff --git a/doc/hyperref-doc.tex b/doc/hyperref-doc.tex
index d98c263..bbcfc56 100644
--- a/doc/hyperref-doc.tex
+++ b/doc/hyperref-doc.tex
@@ -830,6 +830,34 @@ plainpages     & boolean & false & Forces page anchors to be named by the Arabic
                &         &       & of the page number, rather than the formatted form. \\
 \end{longtable}
 
+\subsection{Page anchors}
+
+In a PDF \xpackage{hyperref} adds to every page an target for links (in the upper left corner). These targets are for example used by the index to references the pages of the entries. Unlike the targets generated by other counters it is not possible to change the names of these targets by defining a \cs{theHpage} command: the name can currently not be stored in a label and so is not referenceable. Nevertheless a few options exists, they are already mentioned elsewhere in the documentation but we provide here a summary:
+
+\begin{description}
+\item[\texttt{pageanchor}] A boolean option that determines whether every page is given an target at the top left corner. If this is turned off, \verb|\printindex| will not contain valid hyperlinks.
+\item[\texttt{hypertexnames}] By default the targets have names built with \cs{thepage}: \verb|page.\thepage|, so e.g., \texttt{page.4} or \texttt{page.iii}. The names require that every page as an unique number representation. A frequent problem here is with title pages which often don't show page numbers but internally use the same number as a following page. If you get messages about \texttt{destination with the same identifier (name{page.1})}, change the number representation of title pages or disable the page target.    
+    
+    If the boolean option \texttt{hypertexnames} is set to false, an internal page counter is stepped and used as arabic number. In most cases this should mean that you get the absolute page number (exceptions could be with documents throwing away or dublicating pages at shipout). This option avoids the problem with duplicated identifiers, but does not work with an index, as the backlinks have to be created from the represention passed to the index.
+\item[\texttt{plainpages}]  This forces page anchors to be named by the arabic form, but unlike the previous option it does not use an internal counter but the page counter. That means if you have for example roman and arabic pages you will get duplicated target names as page i and page 1 both set the anchor \texttt{page.1}. 
+\end{description}
+
+\begin{cmdsyntax}
+\ci{@currentHpage}
+\end{cmdsyntax}
+\marginpar{Experimental!}Starting with version 7.01c \xpackage{hyperref} stores the name of the page target it has just set into the (global) variable \cs{@currentHpage}. As the target is set when the page is shipout, \cs{@currentHpage} is only reliable at shipout. With a \hologo{LaTeX} format from 2023-11-01 the name can be for labeled by a package like this:
+
+\begin{verbatim}
+%preamble
+\NewProperty{mypackage/pagetarget}{shipout}{Doc-Start}{\csname @currentHpage\endcsname}
+%labeling in the document
+\RecordProperties{mylabel}{mypackage/pagetarget}
+%linking to the page:
+\hyperlink{\RefProperty{mylabel}{mypackage/pagetarget}}{some text}
+\end{verbatim}
+
+       
+
 \subsection{Configuration options}
 
 \begin{longtable}{>{\ttfamily}ll>{\itshape}lp{9cm}}
diff --git a/hyperref.dtx b/hyperref.dtx
index 525515c..b97c0dc 100644
--- a/hyperref.dtx
+++ b/hyperref.dtx
@@ -11744,18 +11744,27 @@
 %    Therefore currently nothing is done by hyperref.
 %
 % This where we supply a destination for each page. 
+% 
+% \marginpar{Experimental!}The name of destination
+% is stored in the global command \cs{@currentHpage}, this allows it to retrieve
+% it with an extended reference system like zref or the new property code from \LaTeX{}
+% 2023-11-01.
+%    \begin{macrocode}
+\def\@currentHpage{Doc-Start}
+%    \end{macrocode}
 %    \begin{macrocode}
 \ltx at ifclassloaded{slides}{%
   \def\Hy at SlidesFormatOptionalPage#1{(#1)}%
   \def\Hy at PageAnchorSlidesPlain{%
     \advance\c at page\ltx at one
-    \edef\Hy at TempPageAnchor{%
-      \noexpand\hyper@@anchor{%
-        page.\the\c at slide.\the\c at overlay.\the\c at note%
+    \xdef\@currentHpage{page.\the\c at slide.\the\c at overlay.\the\c at note%
         \ifnum\c at page=\ltx at one
         \else
           .\the\c at page
-        \fi
+        \fi}%
+    \edef\Hy at TempPageAnchor{%
+      \noexpand\hyper@@anchor{%
+        \@currentHpage
       }%
     }%
     \advance\c at page-\ltx at one
@@ -11806,6 +11815,7 @@
     \ifHy at hypertexnames
       \ifHy at plainpages
         \def\Hy at TempPageAnchor{\hyper@@anchor{page.\the\c at page}}%
+        \xdef\@currentHpage{page.\the\c at page}%        
         \Hy at PageAnchorSlidesPlain
       \else
         \begingroup
@@ -11816,12 +11826,14 @@
         \endgroup
         \EdefUnescapeString\@the at H@page{\@the at H@page}%
         \def\Hy at TempPageAnchor{\hyper@@anchor{page.\@the at H@page}}%
+        \xdef\@currentHpage{page.\@the at H@page}%
       \fi
     \else
       \Hy at GlobalStepCount\Hy at pagecounter
       \def\Hy at TempPageAnchor{%
         \hyper@@anchor{page.\the\Hy at pagecounter}%
       }%
+      \xdef\@currentHpage{page.\the\Hy at pagecounter}%
     \fi
     \vbox to 0pt{%
       \kern\voffset