a \pdfstartlink command with hooks

[u-fischer]

packages like ocgx2 and tagpdf wants to add code to links/annotation created by hyperref. So we need a generic command to start a pdflink which allows packages to add their code to the attr argument through hooks.

A typical start for url link looks e.g. like this

\leavevmode
\pdfstartlink 
 attr
  {
   %added by creator hyperref
   /Border [0 0 0]
   /H       /I
   /C      [0 1 1]
   % "contribuations"
   % e.g. ocgx see e.g. https://tex.stackexchange.com/a/477884/2388
   % \ocgbase@insert@oc:
   /OC <</Type/OCMD/OCGs [5 0 R]/P/AllOn>> 
   % e.g. tagpdf
   % /StructParent \c_space_tl \int_use:N\c@g__uftag_parenttree_obj_int
   /StructParent 6
  } 
 user
  {
   %creator (hyperref)
   /Subtype /Link
   /A <<
       /Type/Action
       /S/URI
       /URI(https://www.latex-project.org/)
      >>
  }

It is probable that other annotations created with \pdfstartlink (named destination, form fields) should have independant hooks. So the new startlink command should have an argument for the "annotation type" The action is then in the second argument: \pdf_startlink:{type}{action spec}. The content of the attr argument is a dictionary, so using a property list to manage it sounds sensible.

A rought draft for possible implementation:

\pdfcompresslevel=0
\pdfobjcompresslevel=0

\documentclass{article}
\usepackage{expl3}

\ExplSyntaxOn
%helper function, other name needed
\cs_new:Nn\use_prop:nn{#1\c_space_tl#2}
\prop_new:N\g__pdf_url_attr_prop

%some example entries
%interface needed ...
\prop_gput:Nnn\g__pdf_url_attr_prop{/Border}{[0 0 0]}
\prop_gput:Nnn\g__pdf_url_attr_prop{/C}{[0 1 1]}
\prop_gput:Nnn\g__pdf_url_attr_prop{/StructParent}{6}

\cs_new:Nn \pdf_startlink:nn %protected?
{
 \pdfstartlink % need to be replaced by driver independant variant
  attr
  {
    \prop_map_function:cN  {g__pdf_#1_attr_prop} \use_prop:nn
  }
 #2 % user, goto etc added by code?
}
\begin{document}

\ExplSyntaxOn
\leavevmode
 \pdf_startlink:nn{url}
 {
  user 
  {
   /Subtype /Link
   /A <<
       /Type/Action
       /S/URI
       /URI(https://www.latex-project.org/)
      >>
  }
 } 
link
\pdfendlink %endlink is another issue ...
\end{document}

[josephwright]

Looks reasonable: I'd be minded to split this between a driver part (for the back-end dependent code) plus a higher-level interface. Depending on exacly how we want to tackle the higher level, we might have \pdf_ as a prefix I guess.

[u-fischer]

@josephwright yes I think too that there is driver and a pdf part involved. And I think that we will need at least two variants for the driver part: \driver_pdf_startlink_user:nn and \driver_pdf_startlink_goto:nn as I don't see how to unify pdftex/luatex and dvipdfmx syntax without it.

[car222222]

Should this be revisited ‘in the time of hooks’?

[u-fischer]

The hooks are already implemented. The code uses our new hooks, and also a property/dictionary. See the definition of \pdfannot_link:nnn in l3pdfutils.dtx.