pdfresources.dtx

% \iffalse meta-comment
%
%% File: pdfresources.dtx
%
% Copyright (C) 2019-2020 The LaTeX3 Project
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
% license or (at your option) any later version.  The latest version
% of this license is in the file
%
%    https://www.latex-project.org/lppl.txt
%
% This file is part of the "pdfresources bundle" (The Work in LPPL)
% and all files in that bundle must be distributed together.
%
% -----------------------------------------------------------------------
%
% The development version of the bundle can be found at
%
%    https://github.com/latex3/pdfresources
%
% for those people who are interested.
%
%<*driver>
\documentclass{l3doc}
\usepackage{tabularx,array,booktabs}
\newcommand\potentialclash{\noindent\llap{\dbend\ }}
\raggedbottom
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
%    \begin{macrocode}
%<@@=pdf>
%<*package>
\RequirePackage{xparse,l3pdf}
\RequirePackage{lthooks,zref-base,bitset}
\ProvidesExplPackage {pdfresources} {2020-06-15} {0.6}
  {experimental pdf-resource management}
\DeclareOption { debug }
  {
    \msg_redirect_module:nnn { pdf } { none } { warning }
  }
\bool_new:N\g_@@_patches_bool
\DeclareOption { patches }{\bool_gset_true:N\g_@@_patches_bool}
\ProcessOptions\relax
%</package>
%    \end{macrocode}
%
% \title{\pkg{pdfresources}}
%
% \author{^^A
%  The \LaTeX3 Project\thanks
%    {^^A
%      E-mail:
%        \href{mailto:latex-team@latex-project.org}
%          {latex-team@latex-project.org}^^A
%    }^^A
% }
%
% \date{Released 2020-XX-XX}
%
% \maketitle
% \section{Introduction}

% The project here tries to resolve this situation by providing interfaces to
% the various resources and objects in a backend independent way.
%
% The supported backends are pdflatex, lualatex, (x)dvipdfmx (latex, xelatex)
% and dvips with ps2pdf (not completely yet). dvips with distiller could work too
% but is untested.
%
% That the interfaces are backend independent doesn't mean that the results and even
% the compilation behavior is identical. The backends are too different to allow
% this. Some backends expand arguments e.g. in a \cs{special} while other don't.
% Some backends can insert a resource at the first compilation, while another uses
% the aux-file and a label and so needs at least two.
%
% \section{messages}
%    \begin{macrocode}
%<*package>
\msg_new:nnn  { pdf } { patches }
              { loading~patch~code }
\msg_new:nnn  { pdf } { pgf-too-late }
              { pgf~is~already~loaded.~Patching~not~possible.}

%</package>
%    \end{macrocode}
% \section{Preparation/helper Code}
%^^A still needed:
%^^A \pdf@strcmp??
%^^A \pdf@escapestring?? \pdfescapestring
% \begin{variable}{\l_@@_tmpa_prop, \l_@@_tmpa_tl }
% Some scratch variables
%    \begin{macrocode}
%<*package>
\prop_new:N \l_@@_tmpa_prop
\prop_new:N \g_@@_tmpa_prop
\tl_new:N   \l_@@_tmpa_tl
\box_new:N  \l_@@_tmpa_box
\box_new:N  \l_@@_tmpb_box
%</package>
%    \end{macrocode}
% \end{variable}
%
% \subsection{references to page objects}
% \begin{NOTE}{UF}
% a reference to the current page would be useful, but difficult to
% abstract in a sensible way. With xetex it is simply @thispage, but the other
% engines are unclear.
% \end{NOTE}
% \begin{function}[EXP, added = 2019-08-18]
%   {\pdf_pageobject_ref:n}
%   \begin{syntax}
%     \cs{pdf_pageobject_ref:n} \Arg{number}
%   \end{syntax}
%   This returns the object reference of a page object. The \Arg{number} is
%   the absolute page number. The count starts with one.
% \end{function}
% \begin{macro}{ \pdf_pageobject_ref:n }
%    \begin{macrocode}
%<*package>
\cs_new:Npn \pdf_pageobject_ref:n #1 { \@@_backend_pageobject_ref:n { #1 }}
%</package>
%    \end{macrocode}
% \end{macro}
% This loads the dict packages.
% \begin{NOTE}{UF}
% The loading order must be sorted ...
% \end{NOTE}
%    \begin{macrocode}
%<*package>
\RequirePackage{l3pdfdict}
\RequirePackage{l3pdfcoredict}
%</package>
%    \end{macrocode}
%
% \subsection{The \enquote{Info} dictionary (pdfinfo)}
% \begin{NOTE}{UF}
% path: Info
% The info dictionary is filled by e.g. \cs{pdfinfo}. Multiple appearances of
% \cs{pdfinfo} are concatenated, so one could end with multiple /Title or /Author entries.
% It is then viewer dependent which one is showed, so it is better to avoid this.
% We therefore setup a property which is filled and written to the info
% directory in one go. According to hyperref a few odd drivers (hvtex, dvipsone, dviwind)
% don't support arbitrary keys, but this should be handle elsewhere. Most entries are
% strings so there is a special command for this. As entries with empty content
% should be omitted we add a test. The string command should perhaps escape the argument,
% but for now we are assuming that the argument is pdf safe.
% hyperref writes to the info dictionary at the shipout of the first page --
% probably to catch the  case that \cs{title} is issued after the begin of the document.
% We are outputting at the last page -- this needs a second compilation but
% this is needed anyway.
% \end{NOTE}
%
% \subsubsection{\enquote{Info}/backend}
% The backend code is already in expl3.
% \cs{@@_backend_info_gput:nn} inserts one name/value pair.
%
% \subsubsection{\enquote{Info}/management}
% moved to l3pdfcoredict
%
% \subsection{The \enquote{Pages} dictionary (pdfpagesattr)}
% The content of the property list associated with this dictionary name is written to the
% /Pages object. This replaces \cs{pdfpagesattr}. This dictionary is global.
% \subsubsection{\enquote{Pages} / backend}
% \begin{NOTE}{UF}
%  path: Pages
%  pdfpagesattr is a single token register which is used at the end of the compilation.
%  dvips syntax: \verb+\special{ps: [/ABC /CDE /EFG /FGH /Rotate 90 /PAGES pdfmark}+
%  dvipdfmx syntax: \verb+\special{pdf:put @pages <</ABC /WEZ /EFG /XYZ /Rotate 0>>}+
%  both remove duplicate entries automatically, so there is no need to be careful.
% \end{NOTE}
%
% \subsubsection{\enquote{Pages} / management}
% \begin{NOTE}{UF}
% The register is normally used only a few times in a document, so it would be
% okay to update the register/add the special at every change,
% but with dvips/dvipdfmx this would disable removing entries.
% So we issue the push code only at the end of the document.
% \end{NOTE}
%  code moved to l3pdfcoredict
%
% \subsection{\enquote{Page} and \enquote{ThisPage} (pdfpageattr)}
% \subsubsection{\enquote{Page} and \enquote{ThisPage} /backend}
% moved to l3backend-pdf-extra
% \subsubsection{\enquote{Page} and \enquote{ThisPage} / management}
% \begin{NOTE}{UF}
% Open is the question if one need a command to set attribute on a page by page number.
% Open is the setter for /AF (and perhaps /OutputIntents).
% See also https://tex.stackexchange.com/questions/479812/extension-of-rotating-package-to-set-pdf-rotation
% (should work now)
% \end{NOTE}
% code moved to l3pdfcoredict ...
%
% \subsection{\enquote{Page/Resources}: ExtGState, ColorSpace, Shading, Pattern }
% \begin{NOTE}{UF}
% Only for pdf/luatex and xdvipdfmx backend- and pdf-code is needed to add values
% to these resources.
% With dvips the resources are added through high-level code (e.g. transparency), so the
% backend/pdf commands are no-ops.
% For every resources there is only one object. References to these objects are added to
% all pages starting from the page where the first time something has been added to the
% resource and to all XObjects. For luatex and pdftex it must be done together
% with the /Properties, see above.
% I don't see a need to set e.g. /ColorSpace page wise: preflight handles this
% fine, see experiment colorspace-resources.
% As pgf does the same, there is a need to patch it for now. Ditto for package colorspace.
% \end{NOTE}
% \subsubsection{\enquote{Page/Resources}: ExtGState, ColorSpace, Shading, Pattern / backend}
% moved to l3backend-pdf-extra
%
% \subsection{\enquote{Catalog} \& subdirectories (pdfcatalog) }
% \subsubsection{\enquote{Catalog} \& subdirectories / backend}
% the backend command is already in the driver:
% \cs{@@_backend_catalog_gput:nn}
%

% \subsubsection{\enquote{Catalog} \& subdirectories / management }
% \begin{NOTE}{UF}
% The catalog dictionary is filled by e.g. \cs{pdfcatalog}. Multiple appearances of
% \cs{pdfcatalog} are concatenated, so one could end with multiple entries
% for the same value with luatex and pdftex -- the other backends normally
% avoid this problem.
% We therefore setup a property which is filled and executed at a sensible
% (not fixed) place.
% /AF is even an array of dictionaries.
% There is probably no way to test what has already been added to the catalog,
% so doublets can only be avoided with ``don't do it''.
% see catalogue.tex for a list of entries ...
% Perhaps some tools to create the AF-file specification dictionaries is useful.
% Open for now:
% /Extensions               (dict, pdf 2.0)
% /Dests ? difference to subdict in Names?
% /DSS                      (dict, pdf 2.0)
% /Acroform/DR/ExtGState etc probably unneeded.
% \end{NOTE}
%
% \subsection{Local dictionaries}
%
% All dictionaries described above were global dictionaries and basically they
% are written at most once (or at most once per page) to the PDF. The pdfdict module
% predefines also a number of local dictionaries. These are used in objects like
% link annotations (see the pdfannot module) which are written in varying
% numbers to the PDF and allow to set their features and change them locally
% if needed. The predefined dictionaries are
% \begin{NOTE}{UF}
% sync that with the table in pdfdict ...
% \end{NOTE}
% \begin{tabular}{lp{6cm}}
%  \multicolumn{2}{l}{annotation related: here are
%                     \texttt{Border} and \texttt{C} (color)}\\
%  annot/Link/Goto   & used in GoTo links (internal references) \\
%  annot/Link/URI    & used in URI links (external uri references) \\
%  annot/Link/GotoR  & used in GoToR links (file  references) \\
%  annot/Link/Named  & used in Named actions (menu calls) \\
%  annot/Link/Launch & used in Launch links (application calls) \\
% \end{tabular}
% \section{Various PDF contents}
% The following commands allow to create a number of important pdf objects and contents in a
% backend independant way.
%
% \subsection{BDC operator / Properties resource}
% \begin{NOTE}{UF}
%  we need a switch for the case that the resource should be added to
%  xform resource instead of a page resources, see pdfbase.sty
% - xdvipdfmx: looks fine, the resource is added to the xform resource automatically
% - pdftex should now work okay too
% \end{NOTE}
% Entries to the /Properties dictionary in the page resources can
% be added with dvips only through side-effects: if a BDC-mark is created
% dvips/ghostscript will automatically create the necessary objects and names.
% To get a sensible abstraction the code does the same for the other backends:
% There are no public commands to add values to the /Properties dictionary
% directly, only commands to set BDC-marks.
% \begin{function}[added = 2019-06-29]
%   {
%     \pdf_bdc:nn
%   }
%   \begin{syntax}
%     \cs{pdf_bdc:nn} \Arg{tag} \Arg{object name}
%   \end{syntax}
%    This command adds a BDC marked content operator to the current page stream.
%   \meta{tag} is the tag of this operator (without the leading slash),
%   \meta{object name}  is a the name of an dictionary object reserved with
%   \cs{pdf_object_new:nn} and filled with \cs{pdf_object_write:n} with
%   the properties of the BDC.
% \end{function}
% \begin{function}[added = 2019-10-18]
%   {
%     \pdf_bdc:n
%   }
%   \begin{syntax}
%     \cs{pdf_bdc:n} \Arg{tag}
%   \end{syntax}
%    This command adds a BDC marked content operator to the current page stream.
%   \meta{tag} is the tag of this operator (without the leading slash).
%   As object this commands uses the last anonymous dictionary object created with
%   \cs{pdf_object_now:nn}. It lies in the responsibility of the user that the last
%   object is the wanted one.
% \end{function}
% \begin{function}[added = 2019-10-17]
%   {
%     \pdf_bmc:n
%   }
%   \begin{syntax}
%     \cs{pdf_bmc:n} \Arg{tag}
%   \end{syntax}
%    This command created a BMC marked content operator. The argument is the
%    tag without the leading slash. It can be e.g. used for simple artifact
%    markers.
% \end{function}
% \begin{function}[added = 2019-06-30]
%   {
%     \pdf_emc:
%   }
%   \begin{syntax}
%     \cs{pdf_emc:}
%   \end{syntax}
%    This command closes the  BDC marked content operator opened with \cs{pdf_bdc:nn}.
%    It should be on the same page as the bdc-command.
%
%   \begin{verbatim}
%   \pdf_object_new:nn   {objA}{dict}
%   \pdf_object_write:nn {objA}{/Type/Artifact}
%   \pdf_bdc:nn {Span}{objA}
%   text
%   \pdf_emc:
%   \end{verbatim}
% \end{function}
%
% \subsubsection{BDC and Properties / backend}
% \begin{macro}
%   {
%     \@@_backend_bdc:nn,
%     \@@_backend_bdc:n,
%     \@@_backend_bmc:n,
%     \@@_backend_emc:,
%     \@@_backend_PageResources_gpush:n
%   }
% \cs{@@_backend_bdc:nn}, \cs{@@_backend_bmc:n} and \cs{@@_backend_emc:}
%  are the backend command that
%  create the bdc/emc marker and store the properties.
% \cs{@@_backend_PageResources_gpush:n} outputs the /Properties and/or the other
% resources  in
% \cs{@@_BACKEND_thispage_shipout_gput:n} for the current page.
%    \begin{macrocode}
% pdftex and luatex (and perhaps dvips ...) need to know if there are in a
% xform stream ...
%<*drivers>
\bool_new:N \l_@@_backend_xform_bool
%</drivers>
%<*dvips>
% dvips is easy: create an object, and reference it in the bdc
% ghostscript will then automatically replace it by a name
% and add the name to the /Properties dict
% special variant von accsupp
% https://chat.stackexchange.com/transcript/message/50831812#50831812
%
\cs_set_protected:Npn \@@_backend_bdc:nn #1 #2 % #1 eg. Span, #2: object name
  {
    \special {ps:~mark~/#1~\@@_backend_object_ref:n{#2}~/BDC~pdfmark}
  }
\cs_set_protected:Npn \@@_backend_bdc:n #1  % #1 eg. Span,
  {
    \special {ps:~mark~/#1~\@@_backend_object_last:~/BDC~pdfmark}
  }
\cs_set_protected:Npn \@@_backend_emc:
  {
    \special {ps:~mark~/EMC~pdfmark} %
  }
\cs_set_protected:Npn \@@_backend_bmc:n #1
  {
    \special {ps:~mark~/#1~/BMC~pdfmark} %
  }
\cs_new_protected:Npn \@@_backend_PageResources_gpush:n #1 {}

%</dvips>
% xetex has to create the entries in the /Properties manually
% (like the other backends)
% use pdfbase special
% https://chat.stackexchange.com/transcript/message/50832016#50832016
% the property is added to xform resources automatically,
% no need to worry about it.
%<*dvipdfmx|xdvipdfmx>
 \cs_set_protected:Npn \@@_backend_bdc:nn #1 #2 % #1 eg. Span, #2: object name
   {
     \int_gincr:N \g_@@_backend_name_int
     \__kernel_backend_literal:x
       {
         pdf:code~/#1/l3pdf\int_use:N\g_@@_backend_name_int\c_space_tl BDC
       }
     \__kernel_backend_literal:x
       {
         pdf:put~@resources~
           <<
             /Properties~
               <<
                 /l3pdf\int_use:N\g_@@_backend_name_int\c_space_tl
                 \@@_backend_object_ref:n { #2 }
               >>
           >>
       }
   }
 \cs_set_protected:Npn \@@_backend_bdc:n #1  % #1 eg. Span
   {
     \int_gincr:N \g_@@_backend_name_int
     \__kernel_backend_literal:x
       {
         pdf:code~/#1/l3pdf\int_use:N\g_@@_backend_name_int\c_space_tl BDC
       }
     \__kernel_backend_literal:x
       {
         pdf:put~@resources~
           <<
             /Properties~
               <<
                 /l3pdf\int_use:N\g_@@_backend_name_int\c_space_tl
                 \@@_backend_object_last:
               >>
           >>
       }
   }
\cs_set_protected:Npn \@@_backend_bmc:n #1
   {
     \__kernel_backend_literal:n {pdf:code~/#1~BMC}  %pdfbase
   }
\cs_set_protected:Npn \@@_backend_emc:
  {
    \__kernel_backend_literal:n {pdf:code~EMC}  %pdfbase
  }
  % properties are handled automatically, but the other resources should be added
  % at shipout
\cs_new_protected:Npn \@@_backend_PageResources_gpush:n #1
  {
    \clist_map_inline:Nn \c_@@_backend_PageResources_clist
      {
        \prop_if_empty:cF { \pdfdict_gname:n {Core/Page/Resources/##1} }
          {
            \__kernel_backend_literal:x
              {
                pdf:put~@resources~
                  <</##1~\@@_backend_object_ref:n {Page/Resources/##1}>>
              }
          }
      }
  }
%</dvipdfmx|xdvipdfmx>
% luatex
%<*pdfmode>
\sys_if_engine_luatex:T
  {
    \cs_set_protected:Npn \@@_backend_bdc:nn #1 #2 % #1 eg. Span, #2: object name
      {
        \int_gincr:N \g_@@_backend_name_int
        \exp_args:Nx\__kernel_backend_literal_page:n
          { /#1 ~ /l3pdf\int_use:N\g_@@_backend_name_int\c_space_tl BDC }
        \bool_if:NTF \l_@@_backend_xform_bool
          {
            \exp_args:Nnx\pdfdict_gput:nnn
              { Core/Xform/Resources/Properties }
              { l3pdf\int_use:N\g_@@_backend_name_int }
              { \@@_backend_object_ref:n { #2 } }
          }
          {
            \exp_args:Nx \tex_latelua:D
              {
                l3kernel.pdf.Page_Resources_Properties_gput
                  (
                    tex.count["g_shipout_readonly_int"],
                    "l3pdf\int_use:N\g_@@_backend_name_int",
                    "\@@_backend_object_ref:n { #2 }"
                  )
              }
          }
    }
    \cs_set_protected:Npn \@@_backend_bdc:n #1% #1 eg. Span
      {
        \int_gincr:N \g_@@_backend_name_int
        \exp_args:Nx\__kernel_backend_literal_page:n
          { /#1 ~ /l3pdf\int_use:N\g_@@_backend_name_int\c_space_tl BDC }
        \bool_if:NTF \l_@@_backend_xform_bool
          {
            \exp_args:Nnx\pdfdict_gput:nnn %no handler needed
              { Core/Xform/Resources/Properties }
              { l3pdf\int_use:N\g_@@_backend_name_int }
              { \@@_backend_object_last: }
          }
          {
            \exp_args:Nx \tex_latelua:D
              {
                l3kernel.pdf.Page_Resources_Properties_gput
                  (
                    tex.count["g_shipout_readonly_int"],
                    "l3pdf\int_use:N\g_@@_backend_name_int",
                    "\@@_backend_object_last:"
                  )
              }
          }
    }
   \cs_set_protected:Npn \@@_backend_bmc:n #1
      {
        \__kernel_backend_literal_page:n { /#1~BMC }
      }
    \cs_set_protected:Npn \@@_backend_emc:
      {
        \__kernel_backend_literal_page:n { EMC }
      }

    \cs_new_protected:Npn \@@_backend_PageResources_gpush:n #1 {}
  }

% pdflatex is the most complicated as it has to go through the aux ...
% the push command is extended to take other resources too
\sys_if_engine_pdftex:T
  {
    \cs_set_protected:Npn \@@_backend_bdc:nn #1 #2 % #1 eg. Span, #2: object name
      {
        \int_gincr:N \g_@@_backend_name_int
        \exp_args:Nx\__kernel_backend_literal_page:n
          { /#1 ~ /l3pdf\int_use:N\g_@@_backend_name_int\c_space_tl BDC }
        % code to set the property ....
        \int_gincr:N\g_@@_backend_resourceid_int
        \bool_if:NTF \l_@@_backend_xform_bool
          {
            \exp_args:Nnxx\pdfdict_gput:nnn %no handler needed
              { Core/Xform/Resources/Properties }
              { l3pdf\int_use:N\g_@@_backend_resourceid_int }
              { \@@_backend_object_ref:n { #2 } }
          }
          {
            \zref@labelbylist
              { l3pdf\int_use:N\g_@@_backend_resourceid_int }
              { l3pdf }
            \tl_set:Nx \l_@@_tmpa_tl
              {
                \zref@extractdefault
                  { l3pdf\int_use:N\g_@@_backend_resourceid_int }
                  {pdf@abspage}
                  {0}
              }
            \pdfdict_if_gexist:nF { Core/backend_Page\l_@@_tmpa_tl/Resources/Properties }
              {
                \pdfdict_gnew:n  { Core/backend_Page\l_@@_tmpa_tl/Resources/Properties }
              }
            \exp_args:Nnxx\pdfdict_gput:nnn
              { Core/backend_Page\l_@@_tmpa_tl/Resources/Properties }
              { l3pdf\int_use:N\g_@@_backend_resourceid_int }
              { \@@_backend_object_ref:n{#2} }
          }
      }
    \cs_set_protected:Npn \@@_backend_bdc:n #1% #1 eg. Span
      {
        \int_gincr:N \g_@@_backend_name_int
        \exp_args:Nx\__kernel_backend_literal_page:n
          { /#1 ~ /l3pdf\int_use:N\g_@@_backend_name_int\c_space_tl BDC }
        % code to set the property ....
        \int_gincr:N\g_@@_backend_resourceid_int
        \bool_if:NTF \l_@@_backend_xform_bool
          {
            \exp_args:Nnxx\pdfdict_gput:nnn
              { Core/Xform/Resources/Properties }
              { l3pdf\int_use:N\g_@@_backend_resourceid_int }
              { \@@_backend_object_last: }
          }
          {
            \zref@labelbylist
              { l3pdf\int_use:N\g_@@_backend_resourceid_int }
              { l3pdf }
            \tl_set:Nx \l_@@_tmpa_tl
              {
                \zref@extractdefault
                  { l3pdf\int_use:N\g_@@_backend_resourceid_int }
                  {pdf@abspage}
                  {0}
              }
            \pdfdict_if_gexist:nF { Core/backend_Page\l_@@_tmpa_tl/Resources/Properties }
              {
                \pdfdict_gnew:n { Core/backend_Page\l_@@_tmpa_tl/Resources/Properties }
              }
            \exp_args:Nnxx\pdfdict_gput:nnn
              { Core/backend_Page\l_@@_tmpa_tl/Resources/Properties }
              { l3pdf\int_use:N\g_@@_backend_resourceid_int }
              { \@@_backend_object_last: }
            %\pdfdict_show:n { backend_Page\l_@@_tmpa_tl/Resources/Properties }
          }
      }
  \cs_set_protected:Npn \@@_backend_bmc:n #1
    {
      \__kernel_backend_literal_page:n { /#1~BMC }
    }
  \cs_set_protected:Npn \@@_backend_emc:
    {
      \__kernel_backend_literal_page:n { EMC }
    }

  \cs_new:Npn \@@_backend_PageResources_gpush_aux:n #1 %#1 ExtGState etc
    {
      \prop_if_empty:cF
        { \pdfdict_gname:n {Core/Page/Resources/#1} }
        {
          \pdfdict_item:ne { #1 }{ \pdf_object_ref:n {Page/Resources/#1}}
        }
    }

  \cs_new_protected:Npn \@@_backend_PageResources_gpush:n #1
    {
       \exp_args:NNx \tex_global:D \tex_pdfpageresources:D
         {
           \prop_if_exist:cT
             { \pdfdict_gname:n  { Core/backend_Page#1/Resources/Properties } }
             {
               /Properties~
                 <<
                   \prop_map_function:cN
                     { \pdfdict_gname:n  { Core/backend_Page#1/Resources/Properties } }
                     \pdfdict_item:ne
                 >>
             }
           %% add ExtGState etc
           \clist_map_function:NN
             \c_@@_backend_PageResources_clist
             \@@_backend_PageResources_gpush_aux:n
         }
    }
  }
%</pdfmode>
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{BDC and Properties  / management}
%    \begin{macrocode}
%<*package>
\cs_new_protected:Npn  \pdf_bdc:nn #1 #2 { \@@_backend_bdc:nn { #1 }{ #2 } }
\cs_new_protected:Npn  \pdf_bdc:n #1     { \@@_backend_bdc:n  { #1 } }
\cs_new_protected:Npn  \pdf_bmc:n #1     { \@@_backend_bmc:n  { #1 } }
\cs_new_protected:Npn  \pdf_emc:         { \@@_backend_emc: }
%</package>
%    \end{macrocode}
%
% \subsection{Form XObject (pdfxform)}
% \begin{NOTE}{UF}
%  - As in dvi mode the xform is immediate, this is done for pdftex/luatex too.
%    If needed a delayed version can be added later.
%  - the argument for attributes is needed to add e.g. /StructParents
%  - it is not clear if an argument for additional resources is needed, probably they
%    should / need to be added automatically.
%  - code for adding ExtGState etc to the local resource is missing, will be
%    added when the object name is clear.!!!!!!!!!!!!
%  - should the size be stored in dim or tl?
%  - dvips implementation is missing for ideas: pdfbase, atfi-dvips.def,
%  \end{NOTE}
%
%  \subsubsection{Form XObject / management}
%  \begin{function}[added = 2019-08-05]
%   {
%     \pdf_xform_new:nnn
%   }
%   \begin{syntax}
%     \cs{pdf_xform_new:nnn} \Arg{name} \Arg{attributes} \Arg{content}
%   \end{syntax}
%    This command create a new form XObject that can be used as appearance or
%    directly later.
%    If the content contains BDC-marks it should \emph{not} be given as a
%    previously typeset box, but directly so that the names of the
%    BDC-marks can be added to the resources of the xform. The xform will automatically
%    include the resources of the current page.
%    The content will be typeset in a hbox. With pdflatex and luatex
%    the surrounding color is \emph{not} stored in the XObject
%    but should be if wanted added e.g. with |\color_select:n{.}|. This keeps
%    the option of color injection open.
%   \end{function}
%   \begin{function}[added = 2019-08-05]
%     {
%      \pdf_xform_use:n
%     }
%   \begin{syntax}
%     \cs{pdf_xform_use:n} \Arg{name}
%   \end{syntax}
%    This command uses (typesets) a previously created form XObject.
%    If the surrounding color is different, it is injected in the XObject with the
%    engines pdftex or luatex.
%   \end{function}
%   \begin{function}[EXP,added = 2019-08-05]
%     {
%       \pdf_xform_ref:n
%     }
%   \begin{syntax}
%     \cs{pdf_xform_ref:n} \Arg{name}
%   \end{syntax}
%   Inserts the appropriate information to reference the xform \meta{name}
%   in for example appearance dictionaries.
%   \end{function}
%   \begin{function}[EXP,added = 2019-08-05]
%     {
%       \pdf_xform_wd:n, \pdf_xform_ht:n, \pdf_xform_dp:n
%     }
%   \begin{syntax}
%     \cs{pdf_xform_wd:n} \Arg{name}
%   \end{syntax}
%    These command give back the sizes of the XObject. The values are stored in
%    tl-variables with the unit pt and not in dimensions!
%   \end{function}
%   \begin{function}[EXP,pTF,added = 2020-04-29]
%     {
%       \pdf_xform_if_exist:n
%     }
%   \begin{syntax}
%     \cs{pdf_xform_if_exist_p:n} \Arg{name}
%     \cs{pdf_xform_if_exist:NTF} \meta{name} \Arg{true code} \Arg{false code}
%   \end{syntax}
%    These command tests if an xform with name \Arg{name} has been already defined.
%   \end{function}%
%    \begin{macrocode}
%<*package>
\cs_new_protected:Npn  \pdf_xform_new:nnn #1 #2 #3
  {
    \@@_backend_xform_new:nnnn { #1 } { #2 } {  } { #3 }
  }

\cs_new_protected:Npn \pdf_xform_use:n #1
  {
    \@@_backend_xform_use:n { #1 }
  }
% expansion?
\cs_new:Npn \pdf_xform_ref:n #1
  {
    \@@_backend_xform_ref:n { #1 }
  }

\cs_generate_variant:Nn \pdf_xform_ref:n {o}

\cs_new:Npn \pdf_xform_wd:n #1
  {
    \tl_use:c { c_@@_backend_xform_wd_ \tl_to_str:n { #1 } _tl }
  }

\cs_new:Npn \pdf_xform_ht:n #1
  {
    \tl_use:c { c_@@_backend_xform_ht_ \tl_to_str:n { #1 } _tl }
  }

\cs_new:Npn \pdf_xform_dp:n #1
  {
    \tl_use:c { c_@@_backend_xform_dp_ \tl_to_str:n { #1 } _tl }
  }
%</package>
%    \end{macrocode}
%
%  \subsubsection{Form XObject / backend }
%  \begin{macro}{ \@@_backend_xform_new:nnnn }
%  \begin{arguments}
%  \item name
%  \item attributes
%  \item resources %needed?? or are all resources autogenerated?
%  \item content, this doesn't need to be a box!
%  \end{arguments}
%  \begin{macro}{ \@@_backend_xform_use:n, \@@_backend_xform_ref:n }
%    \begin{macrocode}
%<*pdfmode>
\sys_if_engine_pdftex:T
  {
    \cs_new_protected:Npn \@@_backend_xform_new:nnnn #1 #2 #3 #4
    % #1 name
    % #2 attributes
    % #3 resources
    % #4 content, not necessarily a box!
      {
        \hbox_set:Nn \l_@@_tmpa_box
          {
            \bool_set_true:N \l_@@_backend_xform_bool
            \prop_gclear:c {\pdfdict_gname:n { Core/Xform/Resources/Properties }}
            #4
          }
        %store the dimensions
        \tl_const:cx
          { c_@@_backend_xform_wd_ \tl_to_str:n {#1} _tl }
          { \tex_the:D \box_wd:N \l_@@_tmpa_box }
        \tl_const:cx
          { c_@@_backend_xform_ht_ \tl_to_str:n {#1} _tl }
          { \tex_the:D \box_ht:N \l_@@_tmpa_box }
        \tl_const:cx
          { c_@@_backend_xform_dp_ \tl_to_str:n {#1} _tl }
          { \tex_the:D \box_dp:N \l_@@_tmpa_box }
        %% do we need to test if #2 and #3 are empty??
        \tex_immediate:D \tex_pdfxform:D
          ~  attr      ~ { #2 }
        %% which other resources should be default? Is an argument actually needed?
          ~  resources ~
          {
            #3
            \int_compare:nNnT
              { \prop_count:c { \pdfdict_gname:n { Core/Xform/Resources/Properties } } }
              >
              { 0 }
              {
                /Properties~
                  <<
                    \pdfdict_gmap:n { Core/Xform/Resources/Properties }
                  >>
              }

            \prop_if_empty:cF
              { \pdfdict_gname:n { Core/Page/Resources/ExtGState } }
              {
                /ExtGState~ \pdf_object_ref:n { Page/Resources/ExtGState }
              }
            \prop_if_empty:cF
              { \pdfdict_gname:n { Core/Page/Resources/Pattern } }
              {
                /Pattern~ \pdf_object_ref:n { Page/Resources/Pattern }
              }
            \prop_if_empty:cF
              { \pdfdict_gname:n { Core/Page/Resources/Shading } }
              {
                /Shading~ \pdf_object_ref:n { Page/Resources/Shading }
              }
            \prop_if_empty:cF
              { \pdfdict_gname:n { Core/Page/Resources/ColorSpace } }
              {
                /ColorSpace~ \pdf_object_ref:n { Page/Resources/ColorSpace }
              }
          }
          \l_@@_tmpa_box
       \int_const:cn
         { c_@@_backend_xform_ \tl_to_str:n {#1} _int }
         { \tex_pdflastxform:D }
      }

  \cs_new_protected:Npn \@@_backend_xform_use:n #1
    {
      \tex_pdfrefxform:D
        \int_use:c { c_@@_backend_xform_ \tl_to_str:n {#1} _int }
        \scan_stop:
    }

  \cs_new:Npn \@@_backend_xform_ref:n #1
    {
      \int_use:c { c_@@_backend_xform_ \tl_to_str:n {#1} _int } ~ 0 ~ R
    }
  }

%luatex
%nearly identical but not completely ...
\sys_if_engine_luatex:T
  {
    \cs_new:Npn \@@_backend_xform_new:nnnn #1 #2 #3 #4
    % #1 name
    % #2 attributes
    % #3 resources
    % #4 content, not necessarily a box!
      {
        \hbox_set:Nn \l_@@_tmpa_box
          {
            \bool_set_true:N \l_@@_backend_xform_bool
            \prop_gclear:c { \pdfdict_gname:n { Core/Xform/Resources/Properties } }
            #4
          }
        \tl_const:cx
          { c_@@_backend_xform_wd_ \tl_to_str:n {#1} _tl }
          { \tex_the:D \box_wd:N \l_@@_tmpa_box }
        \tl_const:cx
          { c_@@_backend_xform_ht_ \tl_to_str:n {#1} _tl }
          { \tex_the:D \box_ht:N \l_@@_tmpa_box }
        \tl_const:cx
          { c_@@_backend_xform_dp_ \tl_to_str:n {#1} _tl }
          { \tex_the:D \box_dp:N \l_@@_tmpa_box }
        %% do we need to test if #2 and #3 are empty??
        \tex_immediate:D \tex_pdfxform:D
          ~  attr      ~ { #2 }
          %% which resources should be default? Is an argument actually needed?
          ~  resources ~
          {
            #3
            \int_compare:nNnT
              {\prop_count:c { \pdfdict_gname:n { Core/Xform/Resources/Properties } }}
              >
              { 0 }
              {
                /Properties~
                  <<
                    \pdfdict_gmap:n { Core/Xform/Resources/Properties }
                  >>
              }
            \prop_if_empty:cF
              { \pdfdict_gname:n { Core/Page/Resources/ExtGState } }
              {
                /ExtGState~ \pdf_object_ref:n { Page/Resources/ExtGState }
              }
            \prop_if_empty:cF
              { \pdfdict_gname:n { Core/Page/Resources/Pattern } }
              {
                /Pattern~ \pdf_object_ref:n { Page/Resources/Pattern }
              }
            \prop_if_empty:cF
              { \pdfdict_gname:n { Core/Page/Resources/Shading } }
              {
                /Shading~ \pdf_object_ref:n { Page/Resources/Shading }
              }
            \prop_if_empty:cF
              { \pdfdict_gname:n { Core/Page/Resources/ColorSpace } }
              {
                /ColorSpace~ \pdf_object_ref:n { Page/Resources/ColorSpace }
              }
          }
          \l_@@_tmpa_box
          \int_const:cn
            { c_@@_backend_xform_ \tl_to_str:n {#1} _int }
            { \tex_pdflastxform:D }
      }

    \cs_new:Npn \@@_backend_xform_use:n #1
      {
        \tex_pdfrefxform:D \int_use:c
          {
            c_@@_backend_xform_ \tl_to_str:n {#1} _int
          }
          \scan_stop:
      }

    \cs_new:Npn \@@_backend_xform_ref:n #1
      { \int_use:c { c_@@_backend_xform_ \tl_to_str:n {#1} _int } ~ 0 ~ R }
  }
%</pdfmode>
%<*dvipdfmx|xdvipdfmx>
% xetex
   % it needs a bit testing if it really works to set the box to 0 before the special ...
   % does it disturb viewing the xobject?
   % what happens with the resources (bdc)? (should work as they are specials too)
   % xetex requires that the special is in horizontal mode. This means it affects
   % typesetting. But we can no delay the whole form code to shipout
   % as the object reference and the size is often wanted on the current page.
   % so we need to allocate a box - but probably they won't be thousands xform
   % in a document so it shouldn't matter.
    \cs_new:Npn \@@_backend_xform_new:nnnn #1 #2 #3 #4
    % #1 name
    % #2 attributes
    % #3 resources
    % #4 content, not necessarily a box!
      {
         \int_gincr:N \g_@@_backend_object_int
         \int_const:cn
           { c_@@_backend_xform_ \tl_to_str:n {#1} _int }
           { \g_@@_backend_object_int }
         \box_new:c { g_@@_backend_xform_#1_box }
         \hbox_gset:cn { g_@@_backend_xform_#1_box }
           {
             \bool_set_true:N \l_@@_backend_xform_bool
             #4
           }
         \tl_const:cx
           { c_@@_backend_xform_wd_ \tl_to_str:n {#1} _tl }
           { \tex_the:D \box_wd:c { g_@@_backend_xform_#1_box } }
         \tl_const:cx
           { c_@@_backend_xform_ht_ \tl_to_str:n {#1} _tl }
           { \tex_the:D \box_ht:c { g_@@_backend_xform_#1_box } }
         \tl_const:cx
           { c_@@_backend_xform_dp_ \tl_to_str:n {#1} _tl }
           { \tex_the:D \box_dp:c { g_@@_backend_xform_#1_box } }
         \box_set_dp:cn  { g_@@_backend_xform_#1_box } { \c_zero_dim }
         \box_set_ht:cn  { g_@@_backend_xform_#1_box } { \c_zero_dim }
         \box_set_wd:cn  { g_@@_backend_xform_#1_box } { \c_zero_dim }
         \hook_gput_next_code:nn {shipout/background}
           {
             \mode_leave_vertical: %needed, the xform disappears without it.
             \@@_backend:x
               {
                 bxobj  ~ \@@_backend_xform_ref:n  { #1 }
                 \c_space_tl width  ~ \pdf_xform_wd:n { #1 }
                 \c_space_tl height ~ \pdf_xform_ht:n { #1 }
                 \c_space_tl depth  ~ \pdf_xform_dp:n { #1 }
               }
             \box_use_drop:c { g_@@_backend_xform_#1_box }
             \@@_backend:x {put ~ @resources ~<<#3>> }
             \@@_backend:x
               {
                 put~ @resources ~
                   <<
                     /ExtGState~ \pdf_object_ref:n { Page/Resources/ExtGState }
                   >>
               }
             \@@_backend:x
               {
                 put~ @resources ~
                 <<
                   /Pattern~ \pdf_object_ref:n { Page/Resources/Pattern }
                 >>
               }
             \@@_backend:x
               {
                 put~ @resources ~
                 <<
                   /Shading~ \pdf_object_ref:n { Page/Resources/Shading }
                 >>
               }
             \@@_backend:x
               {
                 put~ @resources ~
                 <<
                   /ColorSpace~
                   \pdf_object_ref:n { Page/Resources/ColorSpace }
                 >>
               }
             \exp_args:Nx
             \@@_backend:x {exobj ~<<#2>>}
           }
      }



    \cs_new:Npn \@@_backend_xform_ref:n #1
      {
        @pdf.xform \int_use:c { c_@@_backend_xform_ \tl_to_str:n {#1} _int }
      }

    \cs_new:Npn \@@_backend_xform_use:n #1
     {
       \hbox_set:Nn \l_@@_tmpa_box
         {
           \@@_backend:x
             {
               uxobj~ \@@_backend_xform_ref:n { #1 }
             }
         }
       \box_set_wd:Nn  \l_@@_tmpa_box { \pdf_xform_wd:n { #1 } }
       \box_set_ht:Nn  \l_@@_tmpa_box { \pdf_xform_ht:n { #1 } }
       \box_set_dp:Nn  \l_@@_tmpa_box { \pdf_xform_dp:n { #1 } }
       \box_use_drop:N \l_@@_tmpa_box
     }
%</dvipdfmx|xdvipdfmx>
%<*drivers>
%% all
\prg_new_conditional:Npnn \@@_backend_xform_if_exist:n #1 { p , T , F , TF }
  {
    \int_if_exist:cTF { c_@@_backend_xform_ \tl_to_str:n {#1} _int }
     { \prg_return_true: }
     { \prg_return_false:}
  }
\prg_new_eq_conditional:NNn \pdf_xform_if_exist:n\@@_backend_xform_if_exist:n
  { TF , T , F , p }
%</drivers>
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%\subsection{Annotations}
% \begin{NOTE}{UF}
% The code/naming tries to unify general annotations and the special type of
% link under a common name.
% regarding naming and relation of annotation commands see
% https://github.com/FrankMittelbach/AccessiblePDF/issues/73
% This should probably be moved to l3annot. Or can it be merged with the xform?
% \end{NOTE}

%\subsubsection{Annotations / backend}
% The backend commands are already in the driver:
% \cs{@@_backend_annotation:nnnn} and \cs{@@_backend_annotation_last:}
% \cs{@@_backend_link_begin_user:nnw}, etc
%
% \subsubsection{ general Annotation/management }
% \begin{NOTE}{UF}
% !!!type or not type? Syntax for type???
% \end{NOTE}
%  \begin{function}[added = 2020-04-14]
%   {\pdfannot:nnn}
%   \begin{syntax}
%     \cs{pdfannot:nnn} \Arg{type} \Arg{action spec} \Arg{annot text}
%   \end{syntax}
%   This creates an /Type/Annot object whose rectangle is defined by \Arg{annot text}.
%   If \Arg{type} is a known type the hooks of this type are executed at the begin and
%   the end, and the attribute dictionary of the type is inserted as attributes.
%   This allows to create for example a link annotation which shares border settings
%   with other links. \Arg{type} should e.g. be |Link/URI|. %!!!!!syntax?
% \end{function}
% %!!!!!! should there be a version without type??
% \begin{function}[added = 2019-09-05, updated = 2020-04-14]
%   {\pdfannot_box:nnnn}
%   \begin{syntax}
%     \cs{pdfannot_box:nnnn} \Arg{width} \Arg{height} \Arg{depth} \Arg{annot spec}
%   \end{syntax}
%   This creates an /Type/Annot object with the given dimensions.
% \end{function}
% \begin{function}[added = 2020-03-30]
%   {\pdfannot_box:nnnnn}
%   \begin{syntax}
%     \cs{pdfannot_box:nnnnn} \Arg{type} \Arg{width} \Arg{height} \Arg{depth} \Arg{annot spec}
%   \end{syntax}
%   This creates an /Type/Annot object.
%   If \Arg{type} is a known type the hooks of this type are executed at the begin and
%   the end, and the attribute dictionary of the type is inserted as attributes.
%   This allows to create for example a link annotation which shares border settings
%   with other links. \Arg{type} should e.g. be |Link/URI|. %!!!!!syntax?
% \end{function}
% \begin{function}[added = 2019-09-05]
%   {\pdfannot_box_last:}
%   \begin{syntax}
%     \cs{pdfannot_box_last:}
%   \end{syntax}
%   This retrieves the object reference of the last annotation created. This is not
%   available with xetex.
% \end{function}
%    \begin{macrocode}
%<*package>
\cs_new_protected:Npn \pdfannot_box:nnnn #1 #2 #3 #4
  {
    \@@_backend_annotation:nnnn {#1}{#2}{#3}{#4}
  }

\cs_new:Npn \pdfannot_box_last:
  {
    \@@_backend_annotation_last:
  }

\cs_new_protected:Npn \pdfannot_box:nnnnn #1 #2 #3 #4 #5
  {
    \exp_args:Nx
    \@@_backend_annotation:nnnn {#2}{#3}{#4}
      {
        \pdfdict_if_exist:nT { annot/#1 }
          {
            \pdfdict_map:n {annot/#1}
          }
        #5
      }
  }
%</package>
%    \end{macrocode}
% \subsection{Annotations, Flags}
% Every flag should have an associated property that allows to set/clear flag positions by
% name. The name is \cs{_pdfannot_flag_\#1_prop}
% \begin{NOTE}{UF}
% not sure about this yes, reconsider (naming, implementation ...)
% \end{NOTE}
%    \begin{macrocode}
%<*package>
\cs_new_protected:Npn \pdfannot_flag_new:nn #1 #2
  {
    \bitsetReset  { @@_#1_flag }
    \prop_const_from_keyval:cn { c_pdfannot_flag_#1_prop }
      {
        #2
      }
  }

\pdfannot_flag_new:nn {annot/Link}
  {
    Invisible      = 0,
    Hidden         = 1,
    Print          = 2,
    NoZoom         = 3,
    NoRotate       = 4,
    NoView         = 5,
    ReadOnly       = 6,
    Locked         = 7,
    ToggleNoView   = 8,
    LockedContents = 9
  }

\pdfannot_flag_new:nn {annot/Field} %it is not really an annot, but we will put
  {                                 % form field in this module.
    ReadOnly          = 0,
    Required          = 1,
    NoExport          = 2,
    Multiline         = 12,%Tx
    Password          = 13,
    NoToggleToOff     = 14,%Btn, radio button
    Radio             = 15,%Btn: Radio:    15=1, 16=0
    Pushbutton        = 16,%Btn: Checkbox: 15=0, 16=0
                           %Btn: Pushbutton: 16=1
    Combo             = 17,%Ch: Combo=1 List=0
    Edit              = 18,%Ch, Combo=1 -> + edit field
    Sort              = 19,%Ch, not relevant for view...
    FileSelect        = 20,%Tx
    MultiSelect       = 21,%Ch
    DoNotSpellCheck   = 22,%Tx, Ch (if Combo + Edit set)
    DoNotScroll       = 23,%Tx
    Comb              = 24,%Tx, requires MaxLen in dict
    RadiosInUnison    = 25,%Btn Radio
    RichText          = 25,%Tx
    CommitOnSelChange = 26
  }

\pdfannot_flag_new:nn {annot/field/submit}
  {
    Include/Exclude       = 0,
    IncludeNoValueFields  = 1,
    ExportFormat          = 2,
    GetMethod             = 3, % if ExportFormat=0 -> =0 to
    SubmitCoordinates     = 4, % if ExportFormat=0 -> =0 to
    XFDF                  = 5,
    IncludeAppendSaves    = 6,
    IncludeAnnotations    = 7,
    SubmitPDF             = 8,
    CanonicalFormat       = 9,
    ExclNonUserAnnots     = 10,
    ExclFKey              = 11,
    EmbedForm             = 12
  }

% #1: type, e.g. annot/Link
% #2: name of flag, e.g. Print
\cs_new_protected:Npn \pdfannot_flag_set:nn #1 #2
  {
    \bitsetSet  { @@_#1_flag }
      { \prop_item:cn {c_pdfannot_flag_#1_prop} {#2} }
  }

\cs_new_protected:Npn \pdfannot_flag_clear:nn #1 #2
  {
    \bitsetClear{ @@_#1_flag }
      { \prop_item:cn {c_pdfannot_flag_#1_prop} {#2} }
  }

%flags are output as decimals.
\cs_new:Npn \pdfannot_flag_use:n #1
  {
    \bitsetGetDec { @@_#1_flag }
  }
%</package>
%    \end{macrocode}
% \subsection{Annotations, subtype Widget}\label{pdf:annot:widget}
% The local dictionary \texttt{annot/Widget} is a sceleton
% dictionary for this subtype. It currently contains as only entry
% the subtype setting (the /Type is added by the backend).
%    \begin{macrocode}
%<*package>
\pdfdict_new:n   {annot/Widget}
\pdfdict_put:nnn {annot/Widget}{Subtype}{/Widget}
%</package>
%    \end{macrocode}
% \subsection{Annotations, subtype Link}\label{sec:links}
% Packages like hyperref, ocgx2 and tagpdf all wants to add code
% to link annotation. So we need commands to start and end a link which allows
% packages to add their code through hooks. There are three places in a link where
% hooks are needed: At the begin (for example for a structure command or color),
% in the \emph{attr spec} of the link (for example for the border), and
% at the end of the link (to close a structure or the color group).
%
% The values for \emph{attr spec} are dictionary values, the order they are
% inserted in the dictionary doesn't matter. So they are stored
% like for other dictionary values in a property list, with the key the name
% without a slash. Packages can add \emph{attr spec} entries through
% dedicated hook commands described below.
%
% Code for the begin and end hooks are stored in sequences. This allows some
% ordering.
%
% The code assumes that there will be different link types
% (currently URI, GoToR, Launch, GoTo, Named, hyperref uses the names
%  url,file,run,link,menu) and that
% links of the same type share the \emph{attr spec} and also the same begin/end
% code. The list of link types need to stay restricted and well documented so that
% all packages know which types they have to handle. It is stored in a constant
% seq.
% \begin{NOTE}{UF}
% Perhaps a |cite| type will be useful at some time. -- Thinking more about it,
% a |cite| type is not sensible. hyperref supports it, but it doesn't fit in.
% Commands like cite, gls, acro, footnote and so one should locally change
% linkcolor and linkbordercolor.
% Probably we will need some commands to add an attribute to all link types
% at once.
% hyperref commands for the various type:
% url  |\hyper@linkurl|,
% file |\hyper@linkfile|,
% run  |\@hyper@launch run|,
% link |\hyper@link|, |\find@pdflink|
% menu |\Acrobatmenu|
% \end{NOTE}
% \begin{variable}[added = 2020-03-12]{ \c_pdfannot_link_types_seq }
% This constant sequence contains the list of currently supported link types
% for which hooks and dictionaries exist.
% \end{variable}
%
%    \begin{macrocode}
%<*package>
\seq_const_from_clist:Nn \c_pdfannot_link_types_seq { URI , GoToR , Launch , GoTo, Named }

\seq_map_inline:Nn \c_pdfannot_link_types_seq
  {
    \pdfdict_new:n   { annot/Link/#1 }
    \pdfdict_put:nnn { annot/Link/#1}{ F }{ \pdfannot_flag_use:n { annot/Link} }
    \hook_new_pair:nn
      {pdf/annot/Link/#1/before}
      {pdf/annot/Link/#1/after}
    \seq_new:c  { l_@@_hook_annot/Link/#1_begin_seq }
    \seq_new:c  { l_@@_hook_annot/Link/#1_end_seq }
  }
%</package>
%    \end{macrocode}


% \subsubsection{Annotations, subtype Link /management}
% \begin{function}[added = 2020-03-12, updated = 2020-04-14]{ \pdfannot_link:nnn }
%   \begin{syntax}
%     \cs{pdfannot_link:nnn} \Arg{type} \Arg{user action spec} \Arg{link text}
%   \end{syntax}
%  This creates a link around the \Arg{link text} with the specified
%  \Arg{user action spec}\footnote{The wording follows the pdftex documentation}.
%  \texttt{/Subtype/Link} is added automatically.
%  If \texttt{annot/Link/}\Arg{type} is a known local dictionary
%  attributes stored in dictionary of type \Arg{type} are inserted as
%  \emph{attr spec} and the code in
%  the begin and end hook is executed  before and after the link. \Arg{type} should
%  normally be identical to the value of the |/S| key in the action dictionary.
%  As example
%  \begin{verbatim}
%    \pdfannot_link:nnn { URI }
%     {
%       /A
%         <<
%           /Type/Action
%           /S/URI
%           /URI(https://www.latex-project.org)
%         >>
%     }
%     { link text }
%    \end{verbatim}
% \end{function}
%
%    \begin{macrocode}
%<*package>
\cs_new_protected:Nn \pdfannot_link:nnn %#1 type (URI, GoTo etc),
                                        %#2 action spec, #3 link text
  {
    \hook_use:n { pdf/annot/Link/#1/before}
    \mode_leave_vertical:
    \exp_args:Nxx %xetex needs expansion
    \@@_backend_link_begin_user:nnw
      {
         \pdfdict_if_exist:nT { annot/Link/#1 }
          {
            \pdfdict_map:n {annot/Link/#1}
          }
      }
      {
        /Subtype/Link
        #2
      }
    #3
    \@@_backend_link_end:
    \hook_use:n { pdf/annot/Link/#1/after}
  }
%</package>
%    \end{macrocode}
% \begin{function}[added = 2020-03-12]{ \pdfannot_link_begin:nnw, \pdfannot_link_end:n }
%   \begin{syntax}
%     \cs{pdfannot_link_begin:nnw} \Arg{type} \Arg{user action spec} \meta{content}
%     \cs{pdfannot_link_end:n} \Arg{type}
%   \end{syntax}
%  This creates a link around the \meta{content} with the specified
%  \meta{user action spec} (e.g. an /A dictionary with an URI) or
%  \meta{destination} (a name as defined with the
%  first argument of \cs{pdf_destination:nn}).
%  \texttt{/Subtype/Link} is added automatically.
%  In contrast to \cs{pdfannot_link:nnn} this function
%  does not absorb the argument when finding the \meta{content}, and so can
%  be used in circumstances where the \meta{content} may not be a simple
%  argument.
%  If \texttt{annot/Link/}\Arg{type} is a known local dictionary
%  attributes stored in dictionary of type \Arg{type} are inserted as
%  \emph{attr spec} and the code in the begin and end hook is executed
%  before and after the link. As example
%  \begin{verbatim}
%    \pdfannot_link_begin:nnw { URI }
%     {
%       /A<<
%         /Type/Action
%         /S/URI
%         /URI(https://www.latex-project.org)
%       >>
%     }
%     link text
%    \pdfannot_link_end:n { URI }
%    \end{verbatim}
% \end{function}
%    \begin{macrocode}
%<*package>
\cs_new_protected:Npn \pdfannot_link_begin:nnw #1 #2 %#1 type, #2 action spec
  {
    \hook_use:n { pdf/annot/Link/#1/before}
    \exp_args:Nxx %xetex needs expansion
      \@@_backend_link_begin_user:nnw
        {
           \pdfdict_if_exist:nT { annot/Link/#1 }
            {
              \pdfdict_map:n {annot/Link/#1}
            }
        }
        { #2 }
  }

\cs_new_protected:Nn \pdfannot_link_end:n %#1 type, e.g. url
  {
    \@@_backend_link_end:
    \hook_use:n { pdf/annot/Link/#1/after}
  }
%</package>
%    \end{macrocode}
% \begin{function}[updated = 2020-03-30]{ \pdfannot_link_goto_begin:nw, \pdfannot_link_goto_end: }
%   \begin{syntax}
%     \cs{pdfannot_link_goto_begin:nw} \Arg{destination} \meta{content}
%     \cs{pdfannot_link_goto_end:}
%   \end{syntax}
% This is a special, shorter version for links to internal destinations. It always
% uses the hooks and dictionary of the |GoTo| link type.
% \end{function}
%     \begin{macrocode}
%<*package>
\cs_new_protected:Npn \pdfannot_link_goto_begin:nw #1 %#1 destination
  {
    \hook_use:n { pdf/annot/Link/GoTo/before}
    \exp_args:Nxx %xetex needs expansion
    \@@_backend_link_begin_goto:nnw
      {
        \pdfdict_map:n {annot/Link/GoTo}

      }
      { #1 }
  }

\cs_new_protected:Nn \pdfannot_link_goto_end:
  {
    \@@_backend_link_end:
     \hook_use:n { pdf/annot/Link/GoTo/before}
  }
%</package>
%    \end{macrocode}
% \begin{function}[added = 2020-03-12]{  \pdfannot_link_last: }
%   This retrieves the object reference a previously link created with the commands
%   above
% \end{function}
%    \begin{macrocode}
%<*package>
\cs_set_eq:NN \pdfannot_link_last: \@@_backend_link_last:
%</package>
%    \end{macrocode}
% %!!!! only annot link or also annot??
% \begin{function}[added = 2020-03-12]{  \pdfannot_link_margin:n }
%  \begin{syntax}
%    \cs{pdfannot_link_margin:n} \Arg{dimen}
%  \end{syntax}
%   This sets the dimension of the link margin.
% \end{function}
%    \begin{macrocode}
%<*package>
\cs_set_eq:NN \pdfannot_link_margin:n \@@_backend_link_margin:n
%</package>
%    \end{macrocode}

% \subsection{Destinations}
% \begin{NOTE}{UF}
% I'm unsure about the backend code of the rectangle (FitR) variant. Should it
% really typeset a box???
% I'm also unsure if \cs{pdf_destination:nn} should really allow both
% a type and an integer as second argument. Perhaps a \cs{pdf_destination_zoom:nn}
% would be better??
% \end{NOTE}
% Destinations are \enquote{anchors} for links. The commands here
% create named destinations. The pdf\LaTeX{} primitive doesn't support all
% variants described in the pdf reference. The backend code expect lower case
% arguments, but we add support for the casing of hyperref and the pdf reference.
%
% \begin{tabular}{llll}
% Type & status    & input    &remark \\\hline
% /Fit & supported & fit, Fit \\%
% /FitH& supported & fith, FitH \\
% /FitH \emph{top} & not supported\\
% /FitV & supported& fitv, FitV\\
% /FitV \emph{left} & not supported\\
% /FitB & supported & fitb, FitB\\
% /FitBH & supported & fitbh, FitBH\\
% /FitBH \emph{top}& not supported\\
% /FitBV & supported & fitbv, FitBV\\
% /FitBV \emph{left} & not supported\\
% /FitR \emph{left bottom right top} & supported in part& typesets a box\\
% /XYZ \emph{left} \emph{top} NULL & supported & xyz, XYZ &left, top are automatic\\
% /XYZ \emph{left} \emph{top} zoom & supported & integer (percent) &left, top are automatic\\
% \end{tabular}
%
% \begin{function}[added = 2020-03-10]
%   {\pdf_destination:nn}
%   \begin{syntax}
%     \cs{pdf_destination:nn} \Arg{name} \Arg{type or integer}
%   \end{syntax}
%   This creates a destination. \Arg{type or Integer} can be one of |Fit|, |FitH|,
%   |FitV|, |FitB|, |FitBH|, |FitBV|, |XYZ| and the lower case variants,
%   or an integer representing a  scale factor in percent.
% \end{function}
% \begin{function}[added = 2020-03-10]
%   {\pdf_destination_box:nn}
%   \begin{syntax}
%     \cs{pdf_destination_box:nn} \Arg{name} \Arg{content}
%   \end{syntax}
%   This stores the content in a hbox, outputs the box and
%   creates a destination with |FitR| type encompassing this box.
% \end{function}
%    \begin{macrocode}
%<*package>
% perhaps some manipulation of the argument will be needed to map the current
% hyperref syntax
% unclear currently if is this is useful for anything.
\prop_new:N \l_@@_views_map_prop
\prop_put:Nnn \l_@@_views_map_prop {XYZ} { xyz }
\prop_put:Nnn \l_@@_views_map_prop {xyz} { xyz }
\prop_put:Nnn \l_@@_views_map_prop {Fit} { fit }
\prop_put:Nnn \l_@@_views_map_prop {fit} { fit }
\prop_put:Nnn \l_@@_views_map_prop {FitB} { fitb }
\prop_put:Nnn \l_@@_views_map_prop {fitb} { fitb }
\prop_put:Nnn \l_@@_views_map_prop {FitBH} { fitbh }
\prop_put:Nnn \l_@@_views_map_prop {fitbh} { fitbh }
\prop_put:Nnn \l_@@_views_map_prop {FitBv} { fitbv }
\prop_put:Nnn \l_@@_views_map_prop {fitbv} { fitbv }
\prop_put:Nnn \l_@@_views_map_prop {FitH} { fith }
\prop_put:Nnn \l_@@_views_map_prop {fith} { fith }
\prop_put:Nnn \l_@@_views_map_prop {FitV} { fitv }
\prop_put:Nnn \l_@@_views_map_prop {fitv} { fitv }

\cs_new_protected:Npn \pdf_destination:nn #1 #2
 {
  \prop_if_in:NnTF \l_@@_views_map_prop { #2 }
   {
    \exp_args:Nox %xetex?
    \@@_backend_destination:nn { #1 } { \prop_item:Nn \l_@@_views_map_prop {#2} }
   }
   {
    \exp_args:No %xetex?
    \@@_backend_destination:nn { #1 } { #2 }
    % should we assume that it is a zoom value then??
    % should we test that it is really a number?
    % or should there be a third argument for this case and for other coordinates?
   }
 }
\cs_generate_variant:Nn\pdf_destination:nn {no,nf}

\cs_new_protected:Npn \pdf_destination_box:nn #1 #2 %#1 name, #2 box content
 {
   \@@_backend_destination_box:nn { #1 }{ #2 } %new name!!
 }

%avoid that destinations names are optimized.
% is this still needed??
%see https://tug.org/pipermail/dvipdfmx/2019-May/000002.html
%</package>
%<*dvipdfmx|xdvipdfmx>
    \__kernel_backend_literal:x { dvipdfmx:config~C~ 0x10 }
%</dvipdfmx|xdvipdfmx>
%    \end{macrocode}
% \section{Drop?}
% \subsubsection{Doc View/Openaction}
% \begin{NOTE}{UF}
%   /OpenAction can be an array:
%   |/OpenAction [5 0 R /Fit]| or an action: |<< /S /GoTo /D [ 7 0 R /Fit ] >>|.
%  The implementation below allows only the first. It is not quite clear, if
%  this is sensible (and if a special docview command is needed at all).
%  The second could be set directly.
% \end{NOTE}
%
% \begin{function}[added = 2019-08-18]
%   {\pdf_docview:nn}
%   \begin{syntax}
%     \cs{pdf_docview:nn} \Arg{page} \Arg{view}
%   \end{syntax}
% This command allows to set the OpenAction array. The \meta{page}
% is an absolute page number. \Arg{view} a string for the destination
% without the leading slash. Examples are e.g. |XYZ left top zoom| or |Fit|.
% The OpenAction uses (and could also be set directly with)
% \cs{pdfcoredict_gput:nnn}|{Catalog}|.
% \end{function}
%
%    \begin{macrocode}
%<*package>
\cs_new_protected:Npn \pdf_docview:nn #1 #2
  {
    \pdfcoredict_gput:nnx {Catalog }{ OpenAction }{[\pdf_pageobject_ref:n {#1}~/#2]}
  }
%</package>
%    \end{macrocode}
%
% \section{Document metadata}
% We plan a \cs{DeclareDocumentMetaData} so let's start with it.
% It should for the begin allow to set the version, to uncompress a pdf,
% and set the language. We also add a key to activate the metadata stream and
% to set a standard. The code has been moved to l3pdfmeta.
% \begin{NOTE}{UF}
% how to setup a backend/driver key? Can it be copied from expl3?
% \end{NOTE}
% \begin{function}[added=2019-08-25]{\DeclareDocumentMetaData}
%    \begin{macrocode}
%<*package>
\RequirePackage{l3pdfmeta} %
%</package>
%    \end{macrocode}
% \end{function}
% %load backend driver
%    \begin{macrocode}
%<*package>
\file_input:n {l3\g__sys_backend_tl-pdf.def}
%</package>
%    \end{macrocode}
%
% \section{Patches}
% This code is temporary! It tries to patch commands of other packages which
% fills pdfresources too, to remove clashes and test if everything works as expected.
% This code should disappear when packages adapt to the central interfaces.
%
% \subsection{\pkg{pgf}}
%
% In \pkg{pgf}, resource management is set up in the file |pgfutil-common.tex|.
% This then provides three functions for adding to the resources, all of which
% are objects:
% \begin{itemize}
%   \item \cs{pgfutil@addpdfresource@extgs}: Extended graphics state
%   \item \cs{pgfutil@addpdfresource@colorspaces}: Color spaces
%   \item \cs{pgfutil@addpdfresource@patterns}: Patterns
% \end{itemize}
%
% These resource dictionaries are used by adding entries in a cumulative sense;
% the macro layer deals with ensuring that each entry is only given once. Note
% that the objects themselves must be given only once for each page.
%
% To support these functions, there are a series of set-up macros which install
% these resources. That has to take place for every page: the exact route
% therefore depends on the driver.
%
% For the pageresources project we need to avoid that pgf interferes in ExtGState,
% ColorSpace and Pattern (Shadings are added to the xform resources and so probably
% unproblematic for now).
%    \begin{macrocode}
%<*package>
% patches for xetex/dvips doesn't make much sense for colorspace and
% transparent. But pgf should be tested sometimes.
% currently only pdftex/luatex is handled here.
\bool_if:nT { !\g_@@_patches_bool || \sys_if_output_dvi_p:  }
  {
    \file_input_stop:
  }
\RequirePackage{etoolbox}
\@ifpackageloaded{pgfrcs}
 {
  \msg_warning:nn{pdf}{pgf-too-late}
  \file_input_stop:
 }
 {
  \msg_info:nn{pdf}{patches}
 }
\RequirePackage{pgfrcs}
%
%\def\pgfutil@addpdfresource@extgs#1{\pgf@sys@addpdfresource@extgs@plain{#1}}
%\def\pgfutil@addpdfresource@colorspaces#1{\pgf@sys@addpdfresource@colorspaces@plain{#1}}
%\def\pgfutil@addpdfresource@patterns#1{\pgf@sys@addpdfresource@patterns@plain{#1}}
%\def\pgfutil@setuppdfresources{\pgf@sys@setuppdfresources@plain}
% \pgf@sys@pdf@possible@resources %used in xform
%Trying to patch pgf ..
\cs_new_protected:Npn \@@_pgf_sys_setuppdfresources_plain:
  {
   %objects are already created ...
    \def\pgf@sys@pdf@possible@resources
      {
        /ColorSpace~\pdf_object_ref:n {Page/Resources/ColorSpace}
        /Pattern   ~\pdf_object_ref:n {Page/Resources/Pattern}
        /ExtGState ~\pdf_object_ref:n {Page/Resources/ExtGState}
      }
    \let\pgf@sys@pdf@check@resources=\relax%
    %not sure if needed, but perhaps the lists are used somewhere else ...
    \let\pgf@sys@pgf@resource@list@extgs=\pgfutil@empty%
    \let\pgf@sys@pgf@resource@list@patterns=\pgfutil@empty%
    \let\pgf@sys@pgf@resource@list@colorspaces=\pgfutil@empty%
    % the commands to add page resources
    \def\pgf@sys@addpdfresource@extgs@plain##1
      {
        \exp_after:wN %for transparent which passes a command
          \@@_patch_pgfextgs:w ##1\q_stop
      }
    \def\pgf@sys@addpdfresource@patterns@plain##1
      {
        \@@_patch_pgfpatterns:w ##1\q_stop
      }
   \def\pgf@sys@addpdfresource@colorspaces@plain##1
      {
        \@@_patch_pgfcolorspaces:w ##1\q_stop
      }
  }
\def\pgfutil@setuppdfresources{\@@_pgf_sys_setuppdfresources_plain:}

%label??
\hook_gput_code:nnn {begindocument/end} {pdf} { \pgfutil@setuppdfresources }
%\AtEndPreamble{\pgfutil@setuppdfresources}
% helper commands as pgf doesn't pass resources as two arguments
% code to add to the resources existing stuff in the format "/name value":
\cs_new:Npn \@@_split_dict_entry_aux:NNw #1 #2 /#3~#4\q_stop
  {
    \tl_set:Nn #1 {#3}
    \tl_set:Nn #2 {#4}
  }
\tl_new:N \l_@@_name_tmp_tl
\tl_new:N \l_@@_value_tmp_tl

\cs_new:Npn \@@_patch_pgfextgs:w  #1/#2<<#3>>#4\q_stop
  {
    \exp_args:Nne \@@_backend_PageResources_gput:nnn {ExtGState}{\tl_trim_spaces:n{#2}}{<<#3>>}
  }
\cs_new:Npn \@@_patch_pgfpatterns:w  #1/#2\space#3\q_stop
  {
    \exp_args:Nnxx \@@_backend_PageResources_gput:nnn {Pattern}{\tl_trim_spaces:n{#2}}{#3}
  }
\cs_new:Npn \@@_patch_pgfcolorspaces:w  #1/#2[#3]#4\q_stop
  {
    \exp_args:Nne
    \@@_backend_PageResources_gput:nnn {ColorSpace}{\tl_trim_spaces:n{#2}}{[#3]}
  }
%</package>
%    \end{macrocode}
% \subsection{\pkg{transparent}}
% transparent, we assume that pdfresource is loaded first.
% the code does nothing is with new-transparent ...
%    \begin{macrocode}
%<*package>
%label??
\hook_gput_code:nnn {begindocument/end} {pdf}
  {
    \def\TRP@addresource
      {
        \@@_backend_PageResources_gput:nnn{ExtGState}{TRP1}{<</ca~1/CA~1>>}
      }
    \def\transparent@use#1
      {
        \tl_if_exist:cF{TRP#1}
          {
            \@@_backend_PageResources_gput:nnn
              {ExtGState}
              {TRP#1}
              {<</ca~#1/CA~#1>>}
            \tl_const:cn{TRP#1}{/TRP#1~gs}
          }
       }
  }
%</package>
%    \end{macrocode}
% \subsection{\pkg{colorspace}}
% This is rather difficult as no real places to inject patches
% at first a try to avoid that its ExtGState is missing:
% it can not be avoided to recreate the objects (and so to get duplicates)
% as colorspace uses temporary macros whose contents is lost.
%    \begin{macrocode}
%<*package>
% this must be earlier, to avoid problems with luatex which has two pageresources
% lua/tex
\hook_gput_code:nnn {begindocument} {pdf}
  {
    \tl_if_exist:NT \spc@op
      {
        \def\spc@Pageresources#1{}
      }

  }

\hook_gput_code:nnn {begindocument/end} {pdf}
  {
    \tl_if_exist:NT \spc@op
      {
        \@@_backend_object_new:nn  {__spc_extgstate_op_false}{dict}
        \@@_backend_object_write:nn
          {__spc_extgstate_op_false}
          {/Type /ExtGState~/op~false~/OP~false}
        \pdfcoredict_gput:nnn
          {Page/Resources/ExtGState}
          {SPCko}
          {\@@_backend_object_ref:n {__spc_extgstate_op_false}}
        \@@_backend_object_new:nn  {__spc_extgstate_op_true0}{dict}
        \@@_backend_object_write:nn
          {__spc_extgstate_op_true0}
          {/Type /ExtGState~/op~true~/OP~true~/OPM~0}%
        \pdfcoredict_gput:nnn
          {Page/Resources/ExtGState}
          {SPCmz}
          {\@@_backend_object_ref:n {__spc_extgstate_op_true0}}
        \@@_backend_object_new:nn  {__spc_extgstate_op_true1}{dict}
        \@@_backend_object_write:nn
          {__spc_extgstate_op_true1}
          {/Type /ExtGState~/op~true~/OP~true~/OPM~1}%
         \pdfcoredict_gput:nnn
          {Page/Resources/ExtGState}
          {SPCop}
          {\@@_backend_object_ref:n {__spc_extgstate_op_true1}}
      }
  }
%</package>
%    \end{macrocode}
% \subsection{lua code for lualatex}
%    \begin{macrocode}
%<*lua>
l3kernel= l3kernel or {}
l3kernel.@@      = l3kernel.@@ or {}
l3kernel.@@.Page = l3kernel.@@.Page or {}
l3kernel.@@.Page.dflt = l3kernel.@@.Page.dflt or {}
l3kernel= l3kernel or {}
l3kernel.@@.Page.Resources = l3kernel.@@.Resources or {}
l3kernel.@@.Page.Resources.Properties = l3kernel.@@.Page.Resources.Properties or {}
l3kernel.@@.Page.Resources.List={"ExtGState","ColorSpace","Pattern","Shading"}
l3kernel.@@.object = l3kernel.@@.object or {}

l3kernel.pdf= l3kernel.pdf or {} -- for "public" functions

local @@ = l3kernel.@@
local pdf = pdf

local function @@_backend_Page_gput (name,value)
 @@.Page.dflt[name]=value
end

local function @@_backend_Page_gremove (name)
 @@.Page.dflt[name]=nil
end

local function @@_backend_Page_gclear ()
 @@.Page.dflt={}
end

local function @@_backend_ThisPage_gput (page,name,value)
 @@.Page[page] = @@.Page[page] or {}
 @@.Page[page][name]=value
end

local function @@_backend_ThisPage_gpush (page)
 local token=""
 local t = {}
 local tkeys= {}
 for name,value in pairs(@@.Page.dflt) do
   t[name]=value
 end
 if @@.Page[page] then
  for name,value in pairs(@@.Page[page]) do
   t[name] = value
  end
 end
 -- sort the table to get reliable test files.
 for name,value in pairs(t) do
  table.insert(tkeys,name)
 end
 table.sort(tkeys)
 for _,name in ipairs(tkeys) do
   token = token .. "/"..name.." "..t[name]
 end
 return token
end

function l3kernel.@@.backend_ThisPage_gput (page,name,value) -- tex.count["g_shipout_readonly_int"]
 @@_backend_ThisPage_gput (page,name,value)
end

function l3kernel.@@.backend_ThisPage_gpush (page)
  pdf.setpageattributes(@@_backend_ThisPage_gpush (page))
end

function l3kernel.@@.backend_Page_gput (name,value)
  @@_backend_Page_gput (name,value)
end

function l3kernel.@@.backend_Page_gremove (name)
  @@_backend_Page_gremove (name)
end

function l3kernel.@@.backend_Page_gclear ()
  @@_backend_Page_gclear ()
end


local Properties  = l3kernel.@@.Page.Resources.Properties
local ResourceList= l3kernel.@@.Page.Resources.List
local function @@_backend_PageResources_gpush (page)
 local token=""
 if Properties[page] then
-- we sort the table, so that the pdf test works
  local t = {}
  for name,value in pairs  (Properties[page]) do
   table.insert (t,name)
  end
  table.sort (t)
  for _,name in ipairs(t) do
   token = token .. "/"..name.." ".. Properties[page][name]
  end
  token = "/Properties <<"..token..">>"
 end
  for i,name in ipairs(ResourceList) do
   if l3kernel.@@.Page.Resources[name] then
   token = token .. "/"..name.." "..l3kernel.pdf.object_ref("Page/Resources/"..name)
   end
  end
 return token
end

-- the function is public, as I probably need it in tagpdf too ...
function l3kernel.pdf.Page_Resources_Properties_gput (page,name,value) -- tex.count["g_shipout_readonly_int"]
 Properties[page] = Properties[page] or {}
 Properties[page][name]=value
 pdf.setpageresources(@@_backend_PageResources_gpush (page))
end

function l3kernel.pdf.Page_Resources_gpush(page)
 pdf.setpageresources(@@_backend_PageResources_gpush (page))
end

function l3kernel.pdf.object_ref (objname)
 if l3kernel.@@.object[objname] then
  local ref= l3kernel.@@.object[objname]
  return ref
 else
  return "false"
 end
end
%</lua>
%    \end{macrocode}
% \PrintIndex