pdfresources.dtx

% \iffalse meta-comment
%
%% File: pdfresources.dtx
%
% Copyright (C) 2019 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/latex3
%
% for those people who are interested.
%
%<*driver>
\documentclass{l3doc}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
%    \begin{macrocode}
%<@@=pdf>
%<*package>
\RequirePackage{xparse,l3pdf}
%\RequirePackage{tmpl3shipout}
\RequirePackage{atbegshi,zref-lastpage}
\ProvidesExplPackage {pdfresources} {2019-07-01} {0.2}
  {experimental pdf-resource management}
\DeclareOption { debug }
 {
  %\msg_redirect_module:nnn { pdf } { warning }{ error }
  \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 2019-03-04}
%
% \maketitle
% \section{Existing resource usage}
%
% \subsection{\pkg{hyperref}}
%
% \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.
%
% \subsection{\pkg{media9}}
% \section{Preparation/helper Code}
%^^A still needed:
%^^A \pdf@strcmp??
%^^A \pdf@escapestring?? \pdfescapestring
%    \begin{macrocode}
%<*package>
\prop_new:N\l_@@_tmpa_prop
\tl_new:N\l_@@_tmpa_tl

% helper command to output a key + value of a prop as needed in a dict.
% I don't check if #1 or #2 is empty, imho this should be done only in the pdf layer
% at the input?
\cs_new:Npn \@@_dict_item:nn #1 #2 {/#1~#2~}

%</package>
%    \end{macrocode}
% \subsection{some zref code, needs to be replaced later}
%    \begin{macrocode}
%<*package>
\int_new:N \g_@@_abspage_int
\int_new:N \g_@@_backend_resourceid_int
\int_new:N \g_@@_backend_name_int
\zref@newlist  {l3pdf}
\zref@newprop* {pdf@abspage} [0] {\int_use:N\g_@@_abspage_int}
\zref@addprop  {l3pdf} {pdf@abspage}
%</package>
%    \end{macrocode}
% \subsection{luacode}
%    \begin{macrocode}
%<*package>
\sys_if_engine_luatex:T
{
 \directlua{require("pdfresources.lua")}
}
%</package>
%    \end{macrocode}
% \subsection{end of run}
% \begin{NOTE}{UF}
% the \enquote{end-of-run} command is temporary until shipout/atendshipout code
% is ready. dvips implementation missing. Currently a noop.
% \end{NOTE}
%    \begin{macrocode}
%<*package>
%
%   \AtEndDocument{\clearpage #1} ? (not dvi)
%   \AtEndDvi{#1}                 ?
\cs_new_protected:Npn \@@_backend_end_run:n #1 {} %check ...
%</package>
%    \end{macrocode}
% \subsection{Shipoutcode}
% For now -- until a expl3/kernel interface exists -- code is added with atbegshi:
%    \begin{macrocode}
%<*package>
\AtBeginShipout
 {
  \AtBeginShipoutAddToBox
  {
   \@@_shipout_code:
  }
 }

\cs_new_protected:Npn \@@_shipout_code:
 {
  \int_gincr:N \g_@@_abspage_int
  \@@_everypage_shipout_code:V \g_@@_abspage_int
  \int_compare:nNnT { \g_@@_abspage_int }={\zref@extractdefault{LastPage}{abspage}{0}}
  {
   \@@_lastpage_shipout_code:
  }
 }

\cs_new_protected:Npn \@@_everypage_shipout_code:n #1
 {
  \@@_backend_PageN_gpush:n { #1 }
  \@@_backend_PageN_Resources_gpush:n { #1 }
 }
\cs_generate_variant:Nn \@@_everypage_shipout_code:n {V}
\cs_new_protected:Npn \@@_lastpage_shipout_code:
 {
   \@@_Pages_gpush:
   \@@_Info_gpush:
 }
%</package>
%    \end{macrocode}
%
% \subsection{Tree / path-Code}
%  This is a bit experimental. Many code parts are quite similar: props are
%  filled and output. So we define some generic commands
%  based on pathes. The main question will be if one can encode the different
%  inner structures (array/dict) and the cases where users shouldn't fill a value
%  but it should be done by subtrees ...
%  \begin{verbatim}
%  /Pages           %w,  \pagesattr
%  /PageN           %w, N=1,..n or empty (=all pages) \pageattr
%  /PageN/Resources %nw? \pageresources
%  /PageN/Resources/ExtGState
%  /PageN/Resources/ColorSpace
%  /PageN/Resources/Pattern
%  /PageN/Resources/Shading
%  /PageN/Resources/Properties
%  /Info           %w, \pdfinfo
%  /Catalog/OCProperties
%  /Catalog/OutputIntents
%  \end{verbatim}
%    \begin{macrocode}
%<*package>
\cs_new:Npn \@@_tree_prop_name:n #1 % path name without /
 {
   g_@@_/#1_prop
 }

\cs_new_protected:Npn \@@_tree_new:n #1
 {
  \prop_if_exist:cF { \@@_tree_prop_name:n {#1} }
   {
    \prop_new:c  { \@@_tree_prop_name:n {#1} }
   }
 }


\cs_new_protected:Npn \@@_tree_gput:nnn #1 #2 #3  %#1 path, #2 name, #3 value
 { %test if tree path is allowed here?
  \tl_if_empty:nTF { #3 }
   {
    \msg_none:nnn { pdf }{ empty-value }{ /#1/#2 }
   }
   {
    \prop_gput:cnn { \@@_tree_prop_name:n {#1} }{ #2 } { #3 }
   }
 }
\cs_new_protected:Npn \@@_tree_get:nnnN  #1 #2 #3
  {
   \prop_get:cnN { \@@_tree_prop_name:n {#1} } { #2} #3
  }

\cs_new_protected:Npn \@@_tree_gremove:nn #1 #2
  {
   \prop_gremove:cn { \@@_tree_prop_name:n {#1} } { #2 }
  }

\cs_new:Npn \@@_tree_map_dict_item:n #1
 {
   \prop_map_function:cN { \@@_tree_prop_name:n {#1}} \@@_dict_item:nn
 }

\cs_new_protected:Npn \@@_tree_merge:nnN #1 #2 #3 % merges: first #1 then optionally #2 into prop #3
 {
   \prop_set_eq:Nc #3 { \@@_tree_prop_name:n  { #1 } }
   \prop_if_exist:cT  { \@@_tree_prop_name:n  { #2 } }
   {
    \prop_map_inline:cn { \@@_tree_prop_name:n  { #2 } }
    {
      \prop_put:Nnn #3 { ##1 }{ ##2 }
    }
   }
 }
%</package>
%    \end{macrocode}
% \section{Resources management}
% \subsection{pdfpagesattr}
% \subsubsection{pdfpagesattr/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}
%    \begin{macrocode}
%<*package>
%pdftex
\bool_if:nT {\sys_if_engine_pdftex_p: && \sys_if_output_pdf_p:}
{
 \cs_new_protected:Npn \@@_backend_Pages_primitive:n #1
  {
    \tex_global:D \tex_pdfpagesattr:D {#1}
  }
}
%luatex
\sys_if_engine_luatex:T
 {
  \cs_new_protected:Npn \@@_backend_Pages_primitive:n #1
   {
     \tex_directlua:D {pdf.setpagesattributes(\@@_backend_luastring:n {#1})}
   }
 }
%dvips
\bool_if:nT {\sys_if_engine_pdftex_p: && !\sys_if_output_pdf_p: }
{
 \cs_new_protected:Npx \@@_backend_Pages_primitive:n #1
  {
    \tex_special:D{ps:~[#1~/PAGES~pdfmark} %]
  }
}

%xetex
\sys_if_engine_xetex:T
 {
  \cs_new_protected:Npn \@@_backend_Pages_primitive:n #1
   {
    \@@_backend:n{put~@pages~<<#1>>}
   }
 }
%</package>
%    \end{macrocode}
% \subsubsection{pdfpagesattr/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}
% \begin{function}[added = 2019-06-04]
%   {\pdf_pagesattr_gput:nn}
%   \begin{syntax}
%     \cs{pdf_pagesattr_gput:nn} \Arg{name} \Arg{value}
%   \end{syntax}
%   Adds |/|\meta{name} \meta{value} to the |/Pages| dictionary.
%   It is always stored globally. The content is written to the pdf
%   at the end of the compilation, so values can be added, changed or removed until then.
%   \meta{name} should be a valid pdf name without the leading slash,
%   \meta{value} should be a valid pdf value. Any escaping or (re)encoding must be
%   done explictly. If a \meta{name} is used twice, only the last \meta{value}
%   set will be used.
% \end{function}
% \begin{function}[added = 2019-06-04]
%   {\pdf_pagesattr_get:nN}
%   \begin{syntax}
%     \cs{pdf_pagesattr_get:nN} \Arg{name} \meta{tl var}
%   \end{syntax}
%   Recovers the \meta{value} stored by \cs{pdf_pagesattr_gput:nn} for
%   \meta{name} and places this in the \meta{token list
%   variable}. If \meta{name} is not found
%   then the \meta{token list variable} is set
%   to the special marker \cs{q_no_value}. The \meta{token list
%   variable} is set within the current \TeX{} group.
% \end{function}
% \begin{function}[added = 2019-06-04]
%   {
%    \pdf_pagesattr_gremove:n
%   }
%   \begin{syntax}
%     \pdf_pagesattr_gremove:n \Arg{name}
%   \end{syntax}
%   Removes  |/|\meta{name} and its associated \meta{value} from the |/Pages| dictionary
%   (if the name-value pair has been added by  \cs{pdf_pagesattr_gput:nn}).
%   If \meta{name} is not found no change occurs,
%   \emph{i.e}~there is no need to test for the existence of a name before
%   trying to remove it.
% \end{function}
%    \begin{macrocode}
%<*package>
\@@_tree_new:n {Pages}
% setter:
%^^A documentated
\cs_new_protected:Npn \pdf_pagesattr_gput:nn #1 #2
  {
   \@@_tree_gput:nnn {Pages}{#1}{#2}
  }

% getter from the prop:
%^^A documentated
\cs_new_protected:Npn \pdf_pagesattr_get:nN #1 #2
  {
   \@@_tree_get:nnN {Pages}{#1} #2
  }

% remove:
%^^A documentated
\cs_new_protected:Npn \pdf_pagesattr_gremove:n #1
  {
   \@@_tree_gremove:nn {Pages}{#1}
  }

% push to the register command / issue the special
\cs_new_protected:Npn \@@_Pages_gpush:
  {
    \exp_args:Nx \@@_backend_Pages_primitive:n
    {
     \@@_tree_map_dict_item:n {Pages}
    }
  }

%</package>
%    \end{macrocode}
% \subsection{pdfpageattr}
% \subsubsection{pdfpageattr/backend}
% \begin{NOTE}{UF}
%  path: Page
%  The engines differ a lot here: pdflatex and lualatex uses a register while with
%  dvips/dvipdfmx a one-shot-special ist used. So for pdflatex and lualatex code
%  to assemble the content of the register is needed. Specials are used at shipout,
%  the registers is set directly. With lualatex one can use
%  \cs{latelua} to delay the setting, with pdflatex one has to use a shipout hook.
%  To get the code on the correct page one has to use the aux with pdflatex.
%  In sum this means that quite a lot backend commands are needed to handle
%  this differences. Simply variants of \cs{pdfpageattr} are not enough ...%
%  dvips syntax: \special{ps: [{ThisPage}<</Rotate 90>> /PUT pdfmark}%
%  There seem to be an in-built management code: multiple uses don't lead to
%  multiple entries (/Rotate is special: there is always a /Rotate 0 in the dict, but seems
%  not to do harm).
%  dvipdfmx syntax: \special{pdf: put @thispage << /Rotate 90 >>}, like dvips has an in-built
%  management code.
%  Both change only the current page, so to get the pdftex behaviour (which sets
%  also the following pages) one need to repeat it on every shipout.
% \end{NOTE}
%    \begin{macrocode}
%<*package>
%% backend commands
% a prop for global/default settings which are used for more than
% one page
\@@_tree_new:n {backend_Page}
%pdflatex
\bool_if:nT {\sys_if_engine_pdftex_p: && \sys_if_output_pdf_p: }
 {
  %the primitive
  \cs_new_protected:Npn \@@_backend_Page_primitive:n #1
   {
     \tex_global:D \tex_pdfpageattr:D {#1}
   }
  % the command to store default values.
  % Uses a prop with pdflatex + dvi,
  % sets a lua table with lualatex
  \cs_new_protected:Npn \@@_backend_Page_gput:nn #1 #2
  {
   \@@_tree_gput:nnn {backend_Page}{ #1 }{ #2 }
  }
  % the command to remove a default value.
  % Uses a prop with pdflatex + dvi,
  % changes a lua table with lualatex
  \cs_new_protected:Npn \@@_backend_Page_gremove:n #1
  {
   \@@_tree_gremove:nn  {backend_Page}{ #1 }
  }
 % the command used in the document.
 % direct call of the primitive special with dvips/dvipdfmx
 % \latelua: fill a page related table with lualatex, merge it with the page
 % table and push it directly
 % write to aux and store in prop with pdflatex
  \cs_new_protected:Npn \@@_backend_PageN_gput:nn #1 #2
   {
    \int_gincr:N\g_@@_resourceid_int
    \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}
     }
    \@@_tree_new:n    {backend_Page\l_@@_tmpa_tl}
    \@@_tree_gput:nnn {backend_Page\l_@@_tmpa_tl}{#1}{#2}
   }
  %the code to push the values, used in shipout
  %merges the two props and then fills the register in pdflatex
  %merges the two tables and then fills (in lua) in luatex
  %issues the values stored in the global prop with dvi
  \cs_new_protected:Npn \@@_backend_PageN_gpush:n #1
  {
   \@@_tree_merge:nnN {backend_Page}{backend_Page#1}\l_@@_tmpa_prop
   \exp_args:Nx \@@_backend_Page_primitive:n
   {
    \prop_map_function:NN \l_@@_tmpa_prop \@@_dict_item:nn
   }
  }
 }

\sys_if_engine_luatex:T
{% do we need to use some escaping for the values?????
 \cs_new:Npn \@@_backend_luastring:n #1
  {
   "\tex_luaescapestring:D{\tex_unexpanded:D {#1}}"
  }
 %not used, only there for consistency
 \cs_new_protected:Npn \@@_backend_Page_primitive:n #1
   {
     \tex_latelua:D {pdf.setpageattributes(\@@_backend_luastring:n {#1})}
   }
  % the command to store default values.
  % Uses a prop with pdflatex + dvi,
  % sets a lua table with lualatex
 \cs_new_protected:Npn \@@_backend_Page_gput:nn #1 #2
 {
   \tex_directlua:D
    {
     l3kernel.@@.backend_Page_gput
      (
       \@@_backend_luastring:n {#1},
       \@@_backend_luastring:n {#2}
      )
    }
 }
  % the command to remove a default value.
  % Uses a prop with pdflatex + dvi,
  % changes a lua table with lualatex
 \cs_new_protected:Npn \@@_backend_Page_gremove:n #1
 {
  \tex_directlua:D { l3kernel.@@.backend_Page_gremove (\@@_backend_luastring:n {#1}) }
 }
 % the command used in the document.
 % direct call of the primitive special with dvips/dvipdfmx
 % \latelua: fill a page related table with lualatex, merge it with the page
 % table and push it directly
 % write to aux and store in prop with pdflatex
 \cs_new_protected:Npn \@@_backend_PageN_gput:nn #1 #2
  {
   \tex_latelua:D
    {
     l3kernel.@@.backend_PageN_gput
      (
       tex.count["g_@@_abspage_int"],
       \@@_backend_luastring:n {#1},
       \@@_backend_luastring:n {#2}
      )
     l3kernel.@@.backend_PageN_gpush (tex.count["g_@@_abspage_int"])
    }
  }
  %the code to push the values, used in shipout
  %merges the two props and then fills the register in pdflatex
  %merges the two tables (the one is probably still empty) and then fills (in lua) in luatex
  %issues the values stored in the global prop with dvi
  \cs_new_protected:Npn \@@_backend_PageN_gpush:n #1
  {
    \tex_latelua:D
    {
     l3kernel.@@.backend_PageN_gpush (tex.count["g_@@_abspage_int"])
    }
  }
}

\sys_if_engine_xetex:T
 {
  %the primitive
  \cs_new_protected:Npn \@@_backend_Page_primitive:n #1
   {
    \tex_special:D{pdf:~put~@thispage~<<#1>>}
   }
  % the command to store default values.
  % Uses a prop with pdflatex + dvi,
  % sets a lua table with lualatex
  \cs_new_protected:Npn \@@_backend_Page_gput:nn #1 #2
  {
   \@@_tree_gput:nnn {backend_Page}{ #1 }{ #2 }
  }
  % the command to remove a default value.
  % Uses a prop with pdflatex + dvi,
  % changes a lua table with lualatex
  \cs_new_protected:Npn \@@_backend_Page_gremove:n #1
  {
   \@@_tree_gremove:nn  {backend_Page}{ #1 }
  }
  % the command used in the document.
  % direct call of the primitive special with dvips/dvipdfmx
  % \latelua: fill a page related table with lualatex, merge it with the page
  % table and push it directly
  % write to aux and store in prop with pdflatex
  \cs_new_protected:Npn \@@_backend_PageN_gput:nn #1 #2
   {\tl_set:Nn\l_tmpa_tl{#1xx#2}\tl_show:N\l_tmpa_tl
    \@@_backend_Page_primitive:n { /#1~#2 }
   }
  %the code to push the values, used in shipout
  %merges the two props and then fills the register in pdflatex
  %merges the two tables (the one is probably still empty) and then fills (in lua) in luatex
  %issues the values stored in the global prop with dvi
  \cs_new_protected:Npn \@@_backend_PageN_gpush:n #1
  {
    \exp_args:Nx \@@_backend_Page_primitive:n { \@@_tree_map_dict_item:n {backend_Page} }
  }
 }
%dvips
\bool_if:nT {\sys_if_engine_pdftex_p: && !\sys_if_output_pdf_p: }
{
  \cs_new_protected:Npn \@@_backend_Page_primitive:n #1
  {
   \tex_special:D{ps:~[{ThisPage}<<#1>>~/PUT~pdfmark} %]
  }
  % the command to store default values.
  % Uses a prop with pdflatex + dvi,
  % sets a lua table with lualatex
  \cs_new_protected:Npn \@@_backend_Page_gput:nn #1 #2
  {
   \@@_tree_gput:nnn {backend_Page}{ #1 }{ #2 }
  }
  % the command to remove a default value.
  % Uses a prop with pdflatex + dvi,
  % changes a lua table with lualatex
  \cs_new_protected:Npn \@@_backend_Page_gremove:n #1
  {
   \@@_tree_gremove:nn  {backend_Page}{ #1 }
  }
  % the command used in the document.
  % direct call of the primitive special with dvips/dvipdfmx
  % \latelua: fill a page related table with lualatex, merge it with the page
  % table and push it directly
  % write to aux and store in prop with pdflatex
  \cs_new_protected:Npn \@@_backend_PageN_gput:nn #1 #2
   {
    \@@_backend_Page_primitive:n { /#1~#2 }
   }
  %the code to push the values, used in shipout
  %merges the two props and then fills the register in pdflatex
  %merges the two tables (the one is probably still empty) and then fills (in lua) in luatex
  %issues the values stored in the global prop with dvi
  \cs_new_protected:Npn \@@_backend_PageN_gpush:n #1
  {
    \exp_args:Nx \@@_backend_Page_primitive:n { \@@_tree_map_dict_item:n {backend_Page} }
  }
}
%</package>
%    \end{macrocode}
% \subsubsection{pdfpageattr/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}
% \begin{function}[added = 2019-06-04]
%   {\pdf_pageattr_gput:nn}
%   \begin{syntax}
%     \cs{pdf_pageattr_gput:nn} \Arg{name} \Arg{value}
%   \end{syntax}
%   Adds |/|\meta{name} \meta{value} to the page dictionary of the
%   current page and the following pages. The values are assigned directly,
%   so one should take into account the asynchronous page breaking and use the
%   command only e.g. after a \cs{clearpage} and not inside
%   floats. It is always stored globally.
%   \meta{name} should be a valid pdf name without the leading slash,
%   \meta{value} should be a valid pdf value. Any escaping or (re)encoding must be
%   done explictly. If a \meta{name} is used twice, only the last \meta{value}
%   set will be used. Names set with \cs{pdf_thispageattr_gput:nn} will overwrite
%   names set with \cs{pdf_pageattr_gput:nn} if there is a clash.
% \end{function}
% \begin{function}[added = 2019-06-04]
%   {
%    \pdf_pageattr_gremove:n
%   }
%   \begin{syntax}
%     \pdf_pageattr_gremove:n \Arg{name}
%   \end{syntax}
%   Removes |/|\meta{name} and its associated \meta{value} added by \cs{pdf_pageattr_gput:nn}
%   from the page dictionaries of the current and the following pages.
%   If \meta{name} is not found no change occurs,
%   \emph{i.e}~there is no need to test for the existence of a name before
%   trying to remove it. It doesn't affect values set with \cs{pdf_thispageattr_gput:nn}.
% \end{function}
% \begin{function}[added = 2019-06-19]
%   {\pdf_thispageattr_gput:nn}
%   \begin{syntax}
%     \cs{pdf_thispageattr_gput:nn}  \Arg{name} \Arg{value}
%   \end{syntax}
%   Adds |/|\meta{name} \meta{value} at shipout to the page dictionary of the
%   current page.
%   It is always stored globally. If \Arg{name} has already a value set with
%   \cs{pdf_pageattr_gput:nn} it will overwrite it for this page.
%   \meta{name} should be a valid pdf name without the leading slash,
%   \meta{value} should be a valid pdf value. Any escaping or (re)encoding must be
%   done explictly. If a \meta{name} is used twice, only the last \meta{value}
%   set will be used. With the engine pdflatex (at least) a second compilation is needed.
% \end{function}
%    \begin{macrocode}
%<*package>
\@@_tree_new:n {Page}
% setter.
%^^A documentated
\cs_new_protected:Npn \pdf_pageattr_gput:nn #1 #2
  {
   \@@_backend_Page_gput:nn {#1}{#2}
  }

% remove:
%^^A documentated
\cs_new_protected:Npn \pdf_pageattr_gremove:n #1
  {
   \@@_backend_Page_gremove:n { #1 }
  }

% add to this page:
%^^A documentated
\cs_new_protected:Npn \pdf_thispageattr_gput:nn #1 #2
  {
   \@@_backend_PageN_gput:nn { #1 }{ #2 }
  }

%</package>
%    \end{macrocode}
% \subsection{The info dictionary}
% \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 dependant 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 omited 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{Info / backend}
% The backend code is already in expl3. \verb+\__pdf_backend_info_gput:nn+
% inserts one name/value pair.
% \subsubsection{Info / management}
%  \begin{function}[added = 2019-06-22]
%   {
%    \pdf_info_gput:nn
%   }
%   \begin{syntax}
%     \pdf_info_gput:nn \Arg{name} \Arg{value}
%   \end{syntax}
%   Adds |/|\meta{name} and the \meta{value} to the info dictionary.
%   \meta{name} should be a valid pdf name without the leading slash,
%   \meta{value} should be a valid pdf value. Any escaping or (re)encoding must be
%   done explictly.
%   The info dictionary expects utf8 in the strings, so a conversion like this is
%   normally sensible:
%   \begin{verbatim}
%   \str_set_convert:Nnnn \l_tmpa_str { Grüße }{ utf8 } {utf8/string}
%   \pdf_info_string_gput:nn {Title}{\l_tmpa_str}
%   \end{verbatim}
%   If a \meta{name} is used twice, only the last \meta{value}
%   set will be used. The info dictionary is written at the end of the compilation,
%   so values can be set at any time.
% \end{function}
% \begin{function}[added = 2019-06-22]
%   {
%    \pdf_info_string_gput:nn
%   }
%   \begin{syntax}
%     \pdf_info_string_gput:nn \Arg{name} \Arg{value}
%   \end{syntax}
%   Adds |/|\meta{name} and the \meta{value} surrounded by parentheses to the info dictionary.
%   \meta{name} should be a valid pdf name without the leading slash,
%   \meta{value} should be a valid content of pdf string. Any escaping or (re)encoding must be
%   done explictly.
%   The info dictionary expects utf8 in the strings, so a conversion like this is
%   normally sensible:
%   \begin{verbatim}
%   \str_set_convert:Nnnn \l_tmpa_str { Grüße }{ utf8 } {utf8/string}
%   \pdf_info_string_gput:no {Title}{\l_tmpa_str}
%   \end{verbatim}
%   If a \meta{name} is used twice, only the last \meta{value}
%   set will be used. The info dictionary is written at the end of the compilation,
%   so values can be set at any time.
% \end{function}
%    \begin{macrocode}
%<*package>
\@@_tree_new:n {Info}

\cs_new_protected:Npn \pdf_info_gput:nn #1 #2 %#1 key without /, #2 content
  {
   \@@_tree_gput:nnn {Info}{#1}{#2}
  }

\cs_generate_variant:Nn \pdf_info_gput:nn {no}

%  should #2 be inside a some escaping command? (no)
%  hyperref passes them through
%  \HyXeTeX@CheckUnicode
%  \HyPsd@XeTeXBigCharstrue
%  \HyPsd@PrerenderUnicode{#1}%
%  \pdfstringdef\@pdftitle{#1}%
\cs_new_protected:Npn \pdf_info_string_gput:nn #1 #2 %#1 key without /, #2 content
  {
   \@@_tree_gput:nnn {Info}{#1}{(#2)}
  }

\cs_generate_variant:Nn \pdf_info_string_gput:nn {no,oo,on}

% push to the register command / issue the special
\cs_new_protected:Npn \@@_Info_gpush:
  {
    \prop_map_function:cN  { \@@_tree_prop_name:n {Info} } \@@_backend_info_gput:nn
    \prop_gclear:c { \@@_tree_prop_name:n {Info} }
  }
%</package>
%    \end{macrocode}
% \subsection{page resources / Properties and bdc-mark}
% \begin{NOTE}{UF}
% we still need a switch for the case that the resource should be added to
% xform resource instead of a page resources, see pdfbase.sty
% \end{NOTE}
% Entries to the /Properties dictionary in the page resources can
% be added with dvips only through side-effect: 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}
%     \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.
%   \begin{function}[added = 2019-06-30]
%   {
%    \pdf_emc:
%   }
%   \begin{syntax}
%     \pdf_emc:
%   \end{syntax}
%    This command closes the  BDC marked content operator opened with \cs{pdf_bdc:nn}.
%    It should be one 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{bcd/Properties, backend code}
%    \begin{macrocode}
%<*package>
% 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
\bool_if:nT {\sys_if_engine_pdftex_p: && !\sys_if_output_pdf_p: }
 {
  \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_emc:
   {
    \special{ps:~mark~/EMC~pdfmark} %
   }
  \cs_new_protected:Npn \@@_backend_PageN_Resources_gpush:n #1 {}
 }
% xetex has so create the entries in the /Properties manually (like the other backends)
% use pdfbase special https://chat.stackexchange.com/transcript/message/50832016#50832016
\sys_if_engine_xetex:T
{
 \cs_set_protected:Npn \@@_backend_bdc:nn #1 #2 % #1 eg. Span, #2: object name
   {
     \int_gincr:N \g_@@_backend_name_int
     \special{pdf:code~/#1/l3pdf\int_use:N\g_@@_backend_name_int\c_space_tl BDC}
     \special{
        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_emc:
   {
    \special{pdf:code~EMC}  %pdfbase
   }
  \cs_new_protected:Npn \@@_backend_PageN_Resources_gpush:n #1 {}
}
% luatex
\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}
     \exp_args:Nx\tex_latelua:D
      {
       l3kernel.pdf.Page_Resources_Properties_gput
        ( tex.count["g_@@_abspage_int"],
          "l3pdf\int_use:N\g_@@_backend_name_int",
          "\@@_backend_object_ref:n{#2}"
        )
      }
   }
  \cs_set_protected:Npn \@@_backend_emc:
   {
    \__kernel_backend_literal_page:n { EMC }
   }
  \cs_new_protected:Npn \@@_backend_PageN_Resources_gpush:n #1 {}
}

% pdflatex is the most complicated as it has to go through the aux ...
% !!! the push command will have to be extended to take other resources too
\bool_if:nT {\sys_if_engine_pdftex_p: && \sys_if_output_pdf_p: }
{
 \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
    \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}
     }
    \@@_tree_new:n    {backend_Page\l_@@_tmpa_tl/Resources/Properties}
    \exp_args:Nnx\@@_tree_gput:nnn
     {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_emc:
   {
    \__kernel_backend_literal_page:n { EMC }
   }

 \cs_new_protected:Npn \@@_backend_PageN_Resources_gpush:n #1
  {
   \exp_args:NNx \tex_global:D \tex_pdfpageresources:D
   {
    \prop_if_exist:cT  { \@@_tree_prop_name:n  { backend_Page#1/Resources/Properties } }
     {
      /Properties~<<
       \prop_map_function:cN
        { \@@_tree_prop_name:n  { backend_Page#1/Resources/Properties } } \@@_dict_item:nn
       >>
     }
    %% add ExtGState etc
   }
  }
}
%</package>
%    \end{macrocode}
% ===================================
%\subsubsection{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. dvips, dvipdfmx implementation is missing
%  \end{NOTE}
%    \begin{macrocode}
%<*package>

\prop_new:N \g_@@_backend_xform_prop

\bool_if:nT {\sys_if_engine_pdftex_p: && \sys_if_output_pdf_p: }
{
 \cs_new_protected:Npn \@@_backend_xform_new:nnnN #1 #2 #3 #4 %name, attr, resources, box
 {
  \tex_immediate:D \tex_pdfxform:D~attr { #2 }~resources {#3} #4
  \int_const:cn
   { c_@@_backend_xform_ \tl_to_str:n {#1} _int }
   { \tex_pdflastxform:D }
  \prop_gput:Nnx \g_@@_backend_xform_prop {#1}
   {
    \tex_pdfxformname:D \int_use:c {c_@@_backend_xform_ \tl_to_str:n {#1} _int}
   }
 }

\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:
 }

% should there be a test if the name exists???
\cs_new:Npn \@@_backend_xform_ref:n #1
  { \int_use:c { c_@@_backend_xform_ \tl_to_str:n {#1} _int } ~ 0 ~ R }

\cs_new:Npn \@@_backend_xform_name_ref:n #1
  { /Fm\prop_item:Nn \g_@@_backend_xform_prop {#1} }
}

%nearly identical but not completly ...
\sys_if_engine_luatex:T
{
 \cs_new_protected:Npn \@@_backend_xform_new:nnnN #1 #2 #3 #4 %name, attr, resources, box
 {
  \tex_immediate:D \tex_pdfxform:D~attr { #2 }~resources {#3} #4
  \int_const:cn
   { c_@@_backend_xform_ \tl_to_str:n {#1} _int }
   { \tex_pdflastxform:D }
  \prop_gput:Nnx \g_@@_backend_xform_prop {#1}
   {
    \tex_pdffeedback:D~xformname  \int_use:c {c_@@_backend_xform_ \tl_to_str:n {#1} _int}
   }
 }

\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 }

\cs_new:Npn \@@_backend_xform_name_ref:n #1
  { /Fm\prop_item:Nn \g_@@_backend_xform_prop {#1} }
}

%</package>
%    \end{macrocode}


% \subsection{backend / pageresources}
% \begin{NOTE}{UF} Implementation for dvips missing (perhaps impossible ...), for xetex untested.
% \enquote{Correct} content needed at every shipout
% \end{NOTE}
%    \begin{macrocode}
%<*package>
% backend commands the command to fill the register
\bool_if:nT { (\sys_if_engine_pdftex_p: && \sys_if_output_pdf_p:) || \sys_if_engine_luatex_p: }
{
 \cs_new_protected:Npx \@@_backend_pageresources:n #1
  {
    \exp_not:N \tex_global:D
    \cs_if_exist:NTF \tex_pdfpageresources:D
      { \tex_pdfpageresources:D }
      { \tex_pdfvariable:D pageresources }
      {#1}
  }
}

\sys_if_engine_xetex:T
{
 \cs_new_protected:Npx \@@_backend_pageresources:n #1
  {
   \special{pdf:pageresources<<#1>>} %???????
  }
}

%dvips missing
%</package>
%    \end{macrocode}
%
%
%
%
% \section{Management code}
%
%
%
% \subsection{pdfpageresources /management}
% We need code for ExtGState, ColorSpace, Pattern, Shading and Properties.
% All are dictionaries which can receive entries from more than one source.
% For at least ColorSpace (colorspace) and Properties (ocgx/tagpdf) there is also a need for page related
% resources, so we have to check on every page if a local resource list for this page
% exists. A global dictionary can be empty but as this is known only at the end of the document
% it would require a two-pass compilation to test it and the overhead is small so we ignore this.
% Example for ColorSpace:
%^^A Global resources are stored in g_@@_pageresources_ColorSpace_prop
%^^A An object {g_@@_pageresources_ColorSpace_obj} is reserved
%^^A At the end of the document the obj is written to the pdf with the content of the prop:
%^^A \pdf_object_write:nn { g_@@_pageresources_ColorSpace_obj }
%^^A           {
%^^A             \prop_map_function:cN { g_@@_pageresources_#1_prop} \@@_dict_item:nn
%^^A           }
%^^A local resources for page N are stored in g_@@_pageresources_N_ColorSpace_prop
%^^A An object {g_@@_pageresources_N_ColorSpace_obj} is reserved
%^^A At the end of the document first the global then the local property is
%^^A added to a temporary prop:
%^^A \prop_set_eq:Nc \g_tmpa_prop { g_@@_pageresource_ColorSpace_prop}
%^^A \prop_map_inline:cn { g_@@_pageresource_N_ColorSpace_prop}
%^^A {\prop_gput:Nnn \g_tmpa_prop {#1}{#2}}
%^^A
%^^A then obj is written to the pdf with the combined content of the global and the
%^^A local prop:
%^^A \pdf_object_write:nn { g_@@_pageresources_N_ColorSpace_obj }
%^^A           {
%^^A             \prop_map_function:cN \g_tmpa_prop \@@_dict_item:nn
%^^A           }
%^^A This means that local entries can overwrite global entries, it is up to the user to avoid this
%^^A with sensible names spaces.
%^^A At every shipout we check if g_@@_pageresource_N_ColorSpace_prop exists.
%^^A (That's probably more effective than trying to keep a list of pages with local settings.)
%^^A If yes we put "ColorSpace = objnum  of g_@@_pageresources_N_ColorSpace_obj" into
%^^A \g_@@_pdf_pageresources_prop and push this into pdfpageresources
%^^A If not we put "ColorSpace = objnum of g_@@_pageresources_ColorSpace_obj" into
%^^A \g_@@_pageresources_prop and push this into pdfpageresources


%    \begin{macrocode}
%<*package>
%message
% lowlevel stuff


% push a prop to the register:
 \cs_new_protected:Npn \@@_pageresources_gpush:N #1
  {
    \exp_args:Nx  \@@_backend_pageresources:n
    {
     \prop_map_function:NN #1 \@@_dict_item:nn
    }
  }

% management code
% the list of standard resources which are handle with objects
 \clist_const:Nn \c_@@_pageresources_clist
  {
   ExtGState,
   ColorSpace,
   Pattern,
   Shading,
   Properties
  }

\prop_new:N \g_@@_pageresources_prop

% the global objects
 \clist_map_inline:Nn \c_@@_pageresources_clist
  {
   \prop_new:c {g_@@_pageresources_#1_prop}
   \@@_backend_object_new:nn {g_@@_pageresources_#1_obj}{dict}
  }

% setter:  #1 is the name of the resource
\cs_new_protected:Npn \pdf_pageresources_gput:nnn #1 #2 #3
  {
   \prop_gput:cnn { g_@@_pageresources_#1_prop} { #2 }{ #3 }
  }

% local resources
% a general bool if local resources as been used at all:
% saves use to map through the five resources if not

\bool_new:N \g_@@_pageresources_local_bool

% setter for page wise settings:
% #1 is the absolute page number, #2 the resource name, #3 the key, #4 the content
\cs_new_protected:Npn \pdf_pageresources_gput:nnnn #1 #2 #3 #4
  {
   \prop_if_exist:cF { g_@@_pageresources_#1_#2_prop }
    {
     \prop_new:c { g_@@_pageresources_#1_#2_prop }
     \@@_backend_object_new:nn {g_@@_pageresources_#1_#2_obj}{dict}
    }
   \prop_gput:cnn { g_@@_pageresources_#1_#2_prop} { #3 }{ #4 }
   \bool_gset_true:N \g_@@_pageresources_local_bool
  }
%
% The shipout code:
%

\cs_new_protected:Npn \@@_pageresources_shipout:n #1 %#1 the page number
 {
  \clist_map_inline:Nn \c_@@pageresources_clist
  {
   \prop_if_exist:cTF { g_@@_pageresources_#1_##1_prop }
   {
    \prop_gput:Nnx { \g_@@_pageresources_prop } {##1}
    {
      \@@_backend_object_ref:n { g_@@_pageresources_#1_##1_obj }
    }
   }
   {
    \prop_gput:Nnx { \g_@@_pageresources_prop } {##1}
    {
      \@@_backend_object_ref:n { g_@@_pageresources_##1_obj }
    }
   }
  }
  %\prop_show:N\g_@@_pdf_pageresources_prop
  \@@_pageresources_gpush:N \g_@@_pageresources_prop
 }

%???????????????
% shipout code missing currently
%\hook_post_push:nn {shipout}
%{
% \shipout_page_add:nn { fg }
%  {
%   \exp_args:Nx  \@@_pageresources_shipout:n {\int_eval:n { \g_shipout_page_int }}
%  }
%}

% doesn't work: ocg layer of float gets lost ...
%\AtEndDocument % must perhaps be even later??
%
%\RequirePackage{etoolbox}
%\AfterEndDocument %works better
% Alternative?
%\RequirePackage{atenddvi}
%\AtEndDvi
\@@_backend_end_run:n
 {
   % write the global objects:
  \clist_map_inline:Nn \c_@@_pageresources_clist
  {
   \exp_args:Nnx
     \pdf_object_write:nn { g_@@_pageresources_#1_obj }
     {
      \prop_map_function:cN { g_@@_pageresources_#1_prop} \@@_dict_item:nn
     }
    }
   % write the local objects
  \bool_if:NT \g_@@_pageresources_local_bool
  {
   \clist_map_inline:Nn \c_@@_pageresources_clist
   {
    \int_step_inline:nn {\g_shipout_page_int} %<---- isn't the lastpage number
                                              %with \AtEndDocument when floats
                                              %are involved
    {%\tl_set:Nn\l_tmpa_tl{##1}\tl_show:N\l_tmpa_tl
     \prop_if_exist:cT { g_@@_pageresources_##1_#1_prop }
     {
      \prop_set_eq:Nc \g_tmpa_prop { g_@@_pageresources_#1_prop}
      \prop_map_inline:cn { g_@@_pageresources_##1_#1_prop}
      {
       \prop_gput:Nnn \g_tmpa_prop {####1}{####2}
      }
      \exp_args:Nnx
       \pdf_object_write:nn { g_@@_pageresources_##1_#1_obj }
       {
        \prop_map_function:NN \g_tmpa_prop \@@_dict_item:nn
       }
     }
    }
   }
  }
 }

%</package>
%    \end{macrocode}
% \subsubsection{other stuff}
%    \begin{macrocode}
%<*package>

\bool_if:nT {\sys_if_engine_pdftex_p: && \sys_if_output_pdf_p: }
{
 \cs_new_protected:Nn \@@_backend_docview:nn %#1 page number, #2 e.g. /FitH
 {
  \pdfcatalog {  } openaction~goto~page #1 {#2}
 }


%\input{l3pdfmode-pdf.def}
}

\sys_if_engine_luatex:T
{
 %allow version 2.0 in luatex. Needs sorting out later.
 \@namedef{Hy@pdfversion@2.0}{10}%
 \cs_new_protected:Nn \@@_backend_docview:nn %#1 page number, #2 e.g. /FitH
 {
  \pdfextension catalog {  } openaction~goto~page #1 {#2}
 }

%\input{l3pdfmode-pdf.def}
}

\sys_if_engine_xetex:T
{
 %% need to be checked if resources are ok!!!!
 \cs_new_protected:Npn \@@_backend_bmc:n #1
  {
    \special{pdf:code~/#1~BMC}
    %\special{pdf:content~#1~BMC}%
  }
}
%</package>
%    \end{macrocode}
% \section{Management code / pdf Module}
%<@@=pdf>
% \subsection{Messages}
%    \begin{macrocode}
%<*package>
\msg_new:nnn  { pdf } { patches } { loading~patch~code }
\msg_new:nnn  { pdf } { empty-value }{ The~value~for~#1~is~empty~and~will~be~ignored }
\msg_new:nnnn { pdf } { pagesattr-changed }
 {
   The~content~of~pagesattr ~has~changed.~
   Check~if~it~is~correct.
 }
 {
  This~is~probably~due~to~some~package~or~command~using~the~
  primitive~\token_to_str:N\pdfpagesattr\c_space_tl or~an~equivalent~command~
  instead~of~the~expl3~interface.
 }
\msg_new:nnnn { pdf }{ pageattr-changed }
 {
   The~content~of~pageattr ~has~changed.~
   Check~if~it~is~correct.
 }
 {
  This~is~probably~due~to~some~package~or~command~using~the~
  primitive~\token_to_str:N\pdfpageattr\c_space_tl or~an~equivalent~command~
  instead~of~the~expl3~interface.
 }
\msg_new:nnn { pdf } { setup-after-documentclass }
  { \token_to_str:N \documentsetup\c_space_tl
    should~be~used~only~before~\token_to_str:N\documentclass}
\msg_new:nnn { pdf } { object-compression-disabled }
             { object~compression~is~not~supported~in~pdf~version~#1 }
\msg_new:nnn { pdf } { catalog-special }
             { values~to~the~catalog~entry~#1~should~be~added~with~
               \token_to_str:N\pdf_catalog_ #1_gput:nn }

%</package>
%    \end{macrocode}
% \subsection{Objects and other rather low-level stuff}
% NEEDS REVISING!!!
%    \begin{macrocode}
%<*package>
\cs_set_eq:NN \pdf_link_margin:n \@@_backend_link_margin:n
\cs_set_eq:NN \pdf_xform_new:nnnN \@@_backend_xform_new:nnnN
\cs_set_eq:NN \pdf_link_last: \@@_backend_link_last:
\cs_set_eq:NN \pdf_xform_ref:n \@@_backend_xform_ref:n
\cs_set_eq:NN\pdf_DONTUSE_catalog_gput:nn \@@_backend_catalog_gput:nn
%</package>
%    \end{macrocode}
% \subsection{BDC/EMC commands}
% NEEDS SORTING OUT! Properties for arg 2?????
%    \begin{macrocode}
%<*package>
 \cs_set_eq:NN\pdf_bdc:nn\@@_backend_bdc:nn
 \cs_set_eq:NN\pdf_emc: \@@_backend_emc:

%</package>
%    \end{macrocode}
% \subsection{generic commands}
% \paragraph{Values that are dictionaries}
% In a number of cases a value is a dictionary and users/packages must be able to
% \emph{append} entries to this dictionary. It makes sense to create an object for this
% and use the reference as value. For the object a prop is created, the object
% is filled and written at a suitable time. For this we use a command that setup suitable
% setters and push commands.
%    \begin{macrocode}
%<*package>
\cs_new_protected:Npn \@@_value_dict_new:nnn #1 #2 #3
  %#1 prefix e.g. catalog
  %#2 key name, e.g. ViewerPreferences
  %#3 the command /code needed to write the value, e.g.
  %   \@@_backend_catalog_gput:nn, or a \pdf-setter
 {
  \prop_new:c { g_@@_value_#1_#2_prop }
  \cs_new_protected:cpn { pdf_#1_#2_gput:nn } ##1 ##2
   {
    %% add test for ##1 values that have their own setter ...
    \tl_if_empty:nTF { ##2 }
     {
      \msg_none:nnn { pdf }{ empty-value }{ #1_#2 }
     }
     {
      \prop_gput:cnn { g_@@_value_#1_#2_prop } {##1}{##2}
     }
   }
  \cs_generate_variant:cn{ pdf_#1_#2_gput:nn } {no,nx}
  \cs_new_protected:cpn{ @@_value_#1_#2_gpush: }
   {%\prop_show:c { g_@@_value_#1_#2_prop }
    \prop_if_empty:cF { g_@@_value_#1_#2_prop }
     {
      \@@_backend_object_new:nn   { g_@@_value_#1_#2_obj } { dict }
      \@@_backend_object_write:nx { g_@@_value_#1_#2_obj }
       {
        \prop_map_function:cN  { g_@@_value_#1_#2_prop } \@@_dict_item:nn
       }
      #3 { #2 }{ \@@_backend_object_ref:n { g_@@_value_#1_#2_obj } }
     }
   }
 }
%</package>
%    \end{macrocode}
% \paragraph{Values that are arrays}
% In a number of cases a value is an and users/packages must be able to
% \emph{append} entries to this dictionary. It makes sense to create an object for this
% and use the reference as value. For the object a seq is created, the object
% is filled and written at a suitable time. For this we use a command that setup suitable
% setters and push commands.
%    \begin{macrocode}
%<*package>
\cs_new_protected:Npn \@@_value_array_new:nnn #1 #2 #3
  %#1 prefix e.g. catalog
  %#2 key name, e.g. AF
  %#3 the command /code needed to write the value, e.g.
  %   \driver_pdf_catalog_gput:nn, or a \pdf-setter
 {
  \seq_new:c { g_@@_value_#1_#2_seq }
  \cs_new_protected:cpn { pdf_#1_#2_gput:n } ##1
   {
    \tl_if_empty:nTF { ##1 }
     {
      \msg_none:nnn { pdf }{ empty-value }{ #1_#2 }
     }
     {
      \seq_gput_right:cn { g_@@_value_#1_#2_seq } {##1}
     }
   }
  \cs_new_protected:cpn { pdf_#1_#2_gput_left:n } ##1
   {
    \tl_if_empty:nTF { ##1 }
     {
      \msg_none:nnn { pdf }{ empty-value }{ #1_#2 }
     }
     {
      \seq_gput_left:cn { g_@@_value_#1_#2_seq } {##1}
     }
   }
  \cs_generate_variant:cn{ pdf_#1_#2_gput:n } {o,x}
  \cs_generate_variant:cn{ pdf_#1_#2_gput_left:n } {o,x}
  \cs_new_protected:cpn{ @@_value_#1_#2_gpush: }
   {%\seq_show:c { g_@@_value_#1_#2_seq }
    \seq_if_empty:cF { g_@@_value_#1_#2_seq }
     {
      \@@_backend_object_new:nn   { g_@@_value_#1_#2_obj } { array }
      \exp_args:Nnx \@@_backend_object_write:nn { g_@@_value_#1_#2_obj }
       {
        \seq_use:cn { g_@@_value_#1_#2_seq } {~}
       }
      #3 { #2 }{ \@@_backend_object_ref:n { g_@@_value_#1_#2_obj } }
     }
   }
 }


%</package>
%    \end{macrocode}
% \subsection{The catalog}
% The catalog dictionary is filled by e.g. \cs{pdfcatalog}. Multiple appearances of
% \cs{pdfcatalog} are concatenated, so one could end with multiple entries.
% We is better to avoid this. We therefore setup a
% property which is filled and executed in one at a sensible (not yet found) place.
% \cs{pdfcatalog} has an option \texttt{openaction} to set the start view options.
% This is ignored here but set in a separate command (to be in sync with other drivers).
% The entries in the catalog have varying requirements regarding the
% pdf management. Some entries (like /Lang) are simple values where the last setting can
% simply win, other like /OutputIntents are dictionaries which can be filled from more than
% one source. /AF is even an array of dictionaries.
% There is probably no way to test what has already been added to the catalog,
% so doublettes can only be avoided with ``don't do it''.
% \subsubsection{Simple values}
% \enquote{Simple} values are values that can be sensibly set only once. When set a second time
% the new value overwrites the first value. The value itself can be something simple like
% a boolean but also a complicated dictionary.
% Simple values can be added with \cs{pdf_catalog_gput:nn}. This will add the value to
% a prop. The prop is then pushed to the catalog at the end of the document.
% Entries which can be added like this are
% \begin{description}
% \item[Version]  a version as name, e.g. \texttt{/1.7}
% \item[PageMode] (name: /UseNone, /UseOutlines, /UseThumbs, /FullScreen, /UseOC (PDF 1.5),
%   /UseAttachments (PDF 1.6)
% \item[MarkInfo] a dictionary with up to three entries, whose values are booleans (\texttt{true}
% or \texttt{false}). The default values of all always \texttt{false}. The dictionary should be set
% in one go by whatever package is handling tagging. Example\\
%  \verb+<</Marked true /UserProperties true /Suspects true>>+
%  \item[PageLayout] (name: one of /SinglePage, /OneColumn,
%  /TwoColumnLeft, /TwoColumnRight, /TwoPageLeft (PDF 1.5), /TwoPageRight (PDF 1.5)
%  \item[Outlines] a indirect reference (x 0 R) to an object.
%  \item[OpenAction] array (e.g. \verb+[page /Fit]+ or dictionary \verb+<</Type /Action /S /GoTo /D /somedest>>+)
%  \item[URI] dict, e.g. \verb+<</S/URI /URI (someurl)>>+
%  \item[StructTreeRoot] a dict (normally an indirect reference to a dict),
%   the package doing the tagging should create this.
%  \item[Lang] (string, e.g. (de-DE))
%  \item[NeedsRendering] (boolean, pdf 1.7)
%  \item[PageLabels] dictionary containing on /Nums + array entry describing the numbering system of the pages.
%  (done by hyperref).
%  \item[Collection] should be added by one package only (for an example see embedfile package).
%  \item[Metadata] only one package can add it (pdfx/hyperxmp clash here)
%  \item[Threads] this is an indirect reference pointing to an array of dictionaries. If threads are
%  added to a document it should be done by one package only.
% \end{description}
% \begin{function}[added = 2019-05-25]{\pdf_catalog_gput:nn}
%   \begin{syntax}
%     \cs{pdf_catalog_gput:nn} \meta{name} \meta{value}
%   \end{syntax}
%   Inserts \texttt{/name value} in the catalog.
% \end{function}
% \begin{macro}{\pdf_catalog_gput:nn}
%    \begin{macrocode}
%<*package>
\prop_new:N \g_@@_catalog_prop
\cs_new_protected:Npn \pdf_catalog_gput:nn #1 #2 %#1 name, #2 value
 {
  \tl_if_empty:nTF { #2 }
  {
   \msg_none:nnn { pdf }{ empty-value }{ #1 }
  }
  {% Add later: test for the names that should be handled specially
  \prop_gput:Nnn \g_@@_catalog_prop {#1}{#2}
  }
 }
%</package>
%    \end{macrocode}
% \end{macro}
%^^A open:  AcroForm, AA (dict, additional-actions),
%^^A open but unclear: Names. Is created automatically (for the Dests subdict), but no
%^^A other use found in the texmf tree. So perhaps later.
%^^A open not so important: Dests (only pdf 1.1, later subdict of Names), SpiderInfo (dict),
%^^A PieceInfo (dict), (dict, pdf 1.5, permissions), Legal (dict, pdf 1.5)
%^^A Requirements (array, pdf 1.7), Extensions (dict, pdf 2.0), DSS (dict, pdf 2.0),
%^^A DPartRoot, (dict, pdf 2.0)
%^^A resolved: OutputIntents, OCProperties, ViewerPreferences, AF (array of dictionaries, pdf 2.0,
%^^A associated files, important for accessibility)
% \subsubsection{catalog, special cases}
% \paragraph{AcroForm}
% AcroForm is a rather complicated case: It is a dictionary with a number of fields.
% \begin{itemize}
% \item the majorary are field which count as \enquote{simple}:
% /NeedAppearances (boolean), /SigFlags (integer), /DA (string), /Q (integer),
% /XFA (stream). From these only /NeedAppearances is actually in use. In pdf 2.0
% /NeedAppearances is deprecated, it is then required that every widget has
% an appearance streams.
% \item Two fields are arrays: /Fields and /CO. New values should be \emph{added}.
% \item /DR is a resource dictionary.
%^^A possible implementation: Prop for the general object, seq for /Fields, /CO
%^^A with \pdf_catalog_AcroForm_Fields_append, \pdf_catalog_AcroForm_Fields_append.
%^^A for /DR we perhaps need a general "resource dictionary" template, that can
%^^A be reused in other places (pageresources).
% \end{itemize}
% \paragraph{AF (Associated files, pdf 2.0)}
% This is simply an array of dictionaries / indirect references to file specification
% dictionaries. The implementation is similar to the OutputIntents later. We will
% decide later if tools to create the file specification dictionaries are needed.
% \begin{function}[added = 2019-05-25]{\pdf_catalog_AF_gput:n}
%   \begin{syntax}
%     \cs{pdf_catalog_AF_gput:n} \meta{indirect object reference}
%   \end{syntax}
%   Inserts the object reference in the AF entry of the catalog. The referenced
%   object must be created by the user.
% \end{function}
% \begin{macro}{\pdf_catalog_AF_gput:n}
%    \begin{macrocode}
%<*package>
% user command: \pdf_catalog_AF_gput:n, o, x
% push command: \@@_value_catalog_AF_gpush:
\@@_value_array_new:nnn { catalog } { AF }
                         {\@@_backend_catalog_gput:nn}
%</package>
%    \end{macrocode}
% \end{macro}
% \paragraph{ViewerPreferences}
% This is a dictionary with various entries. So we setup a prop that can be filled
% and is pushed to the catalog / an object later.
% \begin{function}[added = 2019-05-25]{\pdf_catalog_ViewerPreferences_gput:nn}
%   \begin{syntax}
%     \cs{pdf_catalog_ViewerPreferences_gput:n} \meta{name}\meta{value}
%   \end{syntax}
%   Inserts the /name value in the ViewerPreferences dictionary.
% \end{function}
% \begin{macro}{\pdf_catalog_ViewerPreferences_gput:nn}
%    \begin{macrocode}
%<*package>
% user command: \pdf_catalog_ViewerPreferences_gput:nn, no, nx
% push command: \@@_value_catalog_ViewerPreferences_gpush:

\@@_value_dict_new:nnn { catalog }{ ViewerPreferences }{ \@@_backend_catalog_gput:nn }
%</package>
%    \end{macrocode}
% \end{macro}
% \paragraph{OCProperties}
%  This is a dictionary with three entries:
%  \begin{description}
%  \item[/OCGs] (required) An array of indirect references, access needed for more than one package probably
%  \item[/D] (required)    a dict (at best as indirect reference) to the default configuration
%  \item[/Configs] (optional) an array of indirect references to more configurations.
%  \end{description}
%  The /D entry is also a config, so it can be the first from a seq.
%  The overall structure is nested: a dict with arrays.
%    \begin{macrocode}
%<*package>
% user command: \pdf_catalog_OCproperties_gput:nn, no, nx /should not be used hide it???
% push command: \@@_value_catalog_OCproperties_gpush:

%%% not finished ...............
%%%\@@_value_dict_new:nnn { catalog }{ OCproperties }{ \@@_backend_catalog_gput:nn }

\seq_new:N \g_@@_catalog_OCProperties_OCGs_seq
\seq_new:N \g_@@_catalog_OCProperties_Configs_seq

\cs_new_protected:Npn\pdf_catalog_OCProperties_OCGs_gput:n #1
 {
  \tl_if_empty:nTF { #1 }
  {
   \msg_none:nnn { pdf }{ empty-value }{ OCGs }
  }
  {
   \seq_gput_right:Nn \g_@@_catalog_OCProperties_OCGs_seq { #1 }
  }
 }

\cs_new_protected:Npn\pdf_catalog_OCProperties_Configs_gput:n #1
 {
  \tl_if_empty:nTF { #1 }
  {
   \msg_none:nnn { pdf }{ empty-value }{ OCProperties/Configs }
  }
  {
   \seq_gput_right:Nn \g_@@_catalog_OCProperties_Configs_seq { #1 }
  }
 }

\cs_new_protected:Npn\pdf_catalog_OCProperties_Configs_default_gput:n #1
 {
  \tl_if_empty:nTF { #1 }
  {
   \msg_none:nnn { pdf }{ empty-value }{ OCProperties/Configs }
  }
  {
   \seq_gput_left:Nn \g_@@_catalog_OCProperties_Configs_seq {#1}
  }
 }

\cs_new_protected:Npn\@@_catalog_OCProperties_gpush:
 {
  \int_compare:nNnT
  {
    (\seq_count:N \g_@@_catalog_OCProperties_OCGs_seq)*
    (\seq_count:N \g_@@_catalog_OCProperties_Configs_seq)
  } > {0}
  {
   \@@_backend_object_new:nn   {g_@@_catalog_OCProperties_obj} {dict}
   \seq_gpop_left:NN \g_@@_catalog_OCProperties_Configs_seq \g_tmpa_tl
   \exp_args:Nnx
    \@@_backend_object_write:nn {g_@@_catalog_OCProperties_obj}
    {
     /OCGs~[\seq_use:Nn \g_@@_catalog_OCProperties_OCGs_seq {~}]
     /D~\g_tmpa_tl~
     \seq_if_empty:NF \g_@@_catalog_OCProperties_Configs_seq
     {
     /Configs~[\seq_use:Nn \g_@@_catalog_OCProperties_Configs_seq {~}]
     }
    }
   \@@_backend_catalog_gput:nn {OCProperties}{\@@_backend_object_ref:n {g_@@_catalog_OCProperties_obj}}
  } %----------not finished
 }
%</package>
%    \end{macrocode}
% \paragraph{OutputIntents}
% This is an array of dict/indirect references. So we need a seq to hold the items
% and some code to put it in the catalog. The user is responsable that the indirect
% reference points to sensible objects.
% \begin{function}[added = 2019-05-25]{\pdf_catalog_OutputIntents_gput:nn}
%   \begin{syntax}
%     \cs{pdf_catalog_OutputIntents_gput:nn} \meta{name}\meta{indirect object reference}
%   \end{syntax}
%   Inserts \texttt{/name reference} in the OutputIntents dictionay of the catalog.
%   The referenced object must be created by the user.
% \end{function}
%    \begin{macrocode}
%<*package>
% user command: \pdf_catalog_OutputIntents_gput:nn, no, nx
% push command: \@@_value_catalog_OutputIntents_gpush:

\@@_value_array_new:nnn { catalog } { OutputIntents }
                         {\@@_backend_catalog_gput:nn}

%</package>
%    \end{macrocode}
% \subsubsection{catalog, output}
%    \begin{macrocode}
%<*package>
%\AfterEndPreamble %need to be decided ...
\AtEndDocument
 {
  \@@_value_catalog_OutputIntents_gpush:    %OutputIntents
  \@@_value_catalog_AF_gpush:               %AF
  \@@_catalog_OCProperties_gpush:           %OCProperties
  \@@_value_catalog_ViewerPreferences_gpush:
  \prop_map_function:NN  \g_@@_catalog_prop \@@_backend_catalog_gput:nn
 }
%</package>
%    \end{macrocode}
%
% \subsubsection{Doc View}
% This commands set Doc View options. This is rather crude /needs review. For now we
% assume that only the equivalent of \verb+openaction~goto~page\@pdfstartpage{\@pdfstartview}+ in
% hyperref is needed. The format of the second argument is quite unclear (slash, casing).
%    \begin{macrocode}
%<*package>
\cs_new_protected:Npn \pdf_docview:nn #1 #2
 {
  \@@_backend_docview:nn {#1}{#2}
 }

%</package>
%    \end{macrocode}

% \subsection{page resources}
% This mostly makes the driver commands available under the pdf module name.
% But adds a test for empty values
% !!!!!!!!!!!!!!!!!!!!!!
%    \begin{macrocode}
%<*package>
\cs_new_protected:Npn \@@_pageresources_gput:nnn #1 #2 #3
 {
  \tl_if_empty:nTF { #3 }
  {
   \msg_none:nnn { pdf }{ empty-value }{ Resources/#2 }
  }
  {
    \@@_backend_pageresources_gput:nnn { #1 } { #2 } { #3 }
  }
 }

\cs_new_protected:Npn \@@_pageresources_gput:nnnn #1 #2 #3 #4
 {
   \tl_if_empty:nTF { #4 }
  {
   \msg_none:nnn { pdf }{ empty-value }{ Resources/#3 }
  }
  {
    \@@_backend_pageresources_gput:nnnn { #1 } { #2 } { #3 } { #4}
  }
 }

\cs_generate_variant:Nn \@@_pageresources_gput:nnnn {nnnx}
\cs_generate_variant:Nn \@@_pageresources_gput:nnn {nnx}
%</package>
%    \end{macrocode}


% \subsection{Setting / comparing pdf versions}
% The code assumes that the versions are two integers separated by a period.
% The pdf version should be set rather early, before any object has been written.
% So we define a \cs{documentsetup} commmand which should go before \cs{documentclass}
% \begin{macro}{\documentsetup}
%    \begin{macrocode}
%<*package>

\NewDocumentCommand\documentsetup { m }
 {
  \cs_if_eq:NNTF \documentclass \@twoclasseserror
   {\msg_error:nn {pdf}{setup-after-documentclass }}
   {\keys_set:nn { pdf / setup } { #1 }}
 }

\keys_define:nn { pdf / setup }
 {
  pdfversion .code:n =
   {
    \pdf_version_gset:n { #1 }
    \@@_version_checks:
   }
 }
\cs_new_protected:Npn \@@_version_checks:
 {
  \pdf_version_compare:NnT < { 1.5 }
   {
    \@@_backend_compress_objects:n {0}
    \msg_info:nnx {pdf}{object-compression-disabled}
    { \@@_backend_version_major:.\@@_backend_version_minor:}
   }
 }

%</package>
%    \end{macrocode}
% \end{macro}

% \subsection{Higher-level link management}
% \subsubsection{Startlink}
% 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 \texttt{attr} argument through hooks.
%    \begin{macrocode}
%<*package>
\cs_new:Nn \@@_get_key_value:nn { #1~#2~ } %name?????
%</package>
%    \end{macrocode}
% Attributes are stored in a property list. Packages can add attributes through
% dedicated command. We assume that there will be different link types
% (url, file, run, link, is a cite type needed??\ldots)
% and that they should have their own attribute list.
% Probably we will need some commands to fill more than one prop ...
%
%    \begin{macrocode}
%<*package>
\prop_new:N\l_@@_hook_link_begin_url_attr_prop  %\hyper@linkurl
\prop_new:N\l_@@_hook_link_begin_file_attr_prop %\hyper@linkfile
\prop_new:N\l_@@_hook_link_begin_run_attr_prop  %\@hyper@launch run
\prop_new:N\l_@@_hook_link_begin_link_attr_prop %\hyper@link, \find@pdflink
\prop_new:N\l_@@_hook_link_begin_menu_attr_prop %\Acrobatmenu
%</package>
%    \end{macrocode}
%
% High-level startlink commands that uses the stored attributes:
% At first one with the \texttt{user} argument:
% A link command that grabs the content as argument and inserts both
% startlink and endlink directly (driver command is already in l3driver).
%    \begin{macrocode}
%<*package>
\cs_new_protected:Nn \pdf_link_user:nnn %#1 type (url, file etc, #2 action spec, #3 link text
 {
   \seq_if_exist:cT { l_@@_hook_link_begin_#1_seq }
   {
    \seq_use:cn { l_@@_hook_link_begin_#1_seq }{}
   }
   \mode_leave_vertical:
   %\driver_pdf_link_user:nnn
   \@@_backend_link_begin_user:nnw
    {
     \prop_if_exist:cT { l_@@_hook_link_begin_#1_attr_prop }
     {
      \prop_map_function:cN
       { l_@@_hook_link_begin_#1_attr_prop }
       \@@_get_key_value:nn
      }
    }
    {
      #2
    }
    #3
   \@@_backend_link_end:
   \seq_if_exist:cT { l_@@_hook_link_end_#1_seq }
    {
     \seq_use:cn { l_@@_hook_link_end_#1_seq }{}
    }
 }
%</package>
%    \end{macrocode}
%    \begin{macrocode}
%<*package>
\cs_new_protected:Npn \pdf_link_begin_user:nnw #1 #2 %#1 type, #2 action spec
{
 \seq_if_exist:cT { l_@@_hook_link_begin_#1_seq }
   {
    \seq_use:cn { l_@@_hook_link_begin_#1_seq }{}
   }
 \@@_backend_link_begin_user:nnw
  {
   \prop_if_exist:cT { l_@@_hook_link_begin_#1_attr_prop }
    {
     \prop_map_function:cN
      { l_@@_hook_link_begin_#1_attr_prop }
      \@@_get_key_value:nn
     }
  }
  { #2 }
}

% At second one with the \texttt{goto name} argument:
\cs_new_protected:Npn \pdf_link_begin_goto:nnw #1 #2 %#1 type, #2 destination
{
 \seq_if_exist:cT { l_@@_hook_link_begin_#1_seq }
   {
    \seq_use:cn { l_@@_hook_link_begin_#1_seq }{}
   }
 \@@_backend_link_begin_goto:nnw
  {
   \prop_if_exist:cT { l_@@_hook_link_begin_#1_attr_prop }
     {
      \prop_map_function:cN
      { l_@@_hook_link_begin_#1_attr_prop }
      \@@_get_key_value:nn
     }
  }
  { #2 }
}
%</package>
%    \end{macrocode}
% \subsection{Destinations}
% The command expects a lower case argument, it is up to the package to
% ensure this.
%
%    \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 }
   {
    \@@_backend_destination:nn { #1 } {  #2  }
   }
   {
    % should we assume that it is a zoom value then??
    % or should there be a third argument for this case and for other coordinates?
   }
 }
\cs_generate_variant:Nn\pdf_destination:nn {no,nf}
%</package>
%    \end{macrocode}
% \subsubsection{Endlink}
% tagpdf needs to execute code at the end of the link to store the object reference etc.
% So we need a hook. For now the hook is a seq: This will perhaps allows a system to
% add and remove hooks by index. The hook depends on the type.
%    \begin{macrocode}
%<*package>
\seq_new:N \l_@@_hook_link_end_url_seq
\seq_new:N \l_@@_hook_link_end_run_seq
\seq_new:N \l_@@_hook_link_end_file_seq
\seq_new:N \l_@@_hook_link_end_link_seq
\seq_new:N \l_@@_hook_link_end_menu_seq

\cs_new_protected:Nn \pdf_link_end:n %#1 type, e.g. url
 {
  \@@_backend_link_end:
  \seq_if_exist:cT {l_@@_hook_link_end_#1_seq}
   {
    \seq_use:cn { l_@@_hook_link_end_#1_seq }{}
   }
 }

%</package>
%    \end{macrocode}
% \subsection{Before the links}
% Both hyperref and tagpdf wants to insert code before the \cs{pdfstartlink} so lets
% setup hooks for this too:
%    \begin{macrocode}
%<*package>
\seq_new:N \l_@@_hook_link_begin_url_seq
\seq_new:N \l_@@_hook_link_begin_run_seq
\seq_new:N \l_@@_hook_link_begin_file_seq
\seq_new:N \l_@@_hook_link_begin_link_seq
%</package>
%    \end{macrocode}
%
% \section{Hook management}
% hooks are commands that allow users and other packages to inject code.
%
% \subsection{hooks with token lists}
%  Hook code can be stored in a simple token list variable (tl). An example is e.g.
% \cs{@begindocumenthook}. In this case possible operations are
% \begin{itemize}
% \item \emph{appending} to the hook
% \item \emph{prepending} to the hook
% \item and perhaps some more or less complicated \emph{patching} to remove/replace parts
% \end{itemize}
%
% Such a hook can be \emph{used} by using the variable.
%
% \subsection{hooks with sequences}
% Hook code can also be stored in a sequence (seq). In this data structure every user adding
% something to the hook can get an index back.
% In this case possible operations are
% \begin{itemize}
% \item \emph{appending} to the hook (\cs{seq_put_right}),
% \item \emph{prepending} to the hook (need to keep track of the \enquote{zero pointer} if the user
% should get an index back)
% \item \emph{changing} (e.g emptying) a hook item through the index. But as this
% involves mapping through the sequence to find the right item, it is perhaps too slow.
% \end{itemize}
%
% Such a hook can be \emph{used} by mapping over the sequence. It is possible to filter or
% exclude items. It is also possible to insert code while processing the individual items.
% It is not quite clear if the additional features of such sequence hooks are really needed
% but the overhead is not so large, so it should be ok to use is. Probably if the type
% is used at all, it would be sensible to drop the tl-type so that one doesn't have to define
% \cs{hook_put_right_tl:nnn} and \cs{hook_put_right_seq:nnn} functions.
%
% \subsection{hooks with properties}
% Hook code can also be stored in a property (prop). Here possible operations are
% \begin{itemize}
% \item \emph{adding} a new key and its value. It is possible to write the interface so
% that only a specific set of keys are allowed.
% \item \emph{changing} the value of an existing key, either by overwriting the
% current value or by appending more code to the value -- the second could e.g. be used
% to extend the /ExtGState or /ColorSpace values.
% \item \emph{removing} a key
% \end{itemize}
%
% A hook stored like this can be used by mapping over the properties, but selective
% use and filtering is possible too.
%
% Such a hook is useful if -- like in the case of dictionary values in a pdf -- various
% packages need to be able to manipulate the same key.
%
% \subsection{Naming hooks and access functions}
% hooks are module specific. So set functions should probably do be something like
%
% \cs{hook_put_right:nnn}\verb+{<module>}{<hook-name>}{value}+ (seq- or tl-type)
% or in the case of  properties
% \cs{hook_put:nnnn} {<module>}{<hook-name>}{<key>}{<value>}
%
% hooks should be manipulated only through such access functions. So their
% name should be an internal command of the module. E.g.
% \cs{l__<module>_hook_<hook-name>_prop}
%
%    \begin{macrocode}
%<*package>
\cs_new:Nn \hook_put_right:nnn
 {
  \seq_put_right:cn { l__#1_hook_#2_seq } { #3 }
 }

\cs_new:Nn \hook_put_left:nnn
 {
  \seq_put_left:cn { l__#1_hook_#2_seq } { #3 }
 }

\cs_new:Nn \hook_put:nnnn
 {
  \prop_put:cnn { l__#1_hook_#2_prop } { #3 }{ #4 }
 }

\cs_new:Nn \hook_gput:nnnn
 {
  \prop_gput:cnn { g__#1_hook_#2_prop } { #3 }{ #4 }
 }

\cs_new:Nn \hook_remove:nnn
 {
  \prop_remove:cn { l__#1_hook_#2_prop } { #3 }
 }

\cs_new:Nn \hook_gremove:nnn
 {
  \prop_gremove:cn { g__#1_hook_#2_prop } { #3 }
 }
%</package>
%    \end{macrocode}
% \subsection{Passing external information to hooks}
% hooks sometimes wants to know something about the arguments of the surrounding command.
% E.g. a hook in \cs{@startsection} perhaps needs the current section level or
% if it is a run-in or display sectioning. Using \#-arguments in the hook is possible
% but rather fragile. It is probably better if the surrounding command offers a
% documentated interface through e.g. tl-variables. It should be also clear which
% variables are read-only and which can be changed by the hook code.
%
%
% \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{pgf}
% For the pageresources 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>
\bool_if:nT { !\g_@@_patches_bool || \sys_if_output_dvi_p:  }
 {
  \file_input_stop:
 }
\msg_info:nn{pdf}{patches}
\RequirePackage{etoolbox}
% 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_generate_variant:Nn \pdf_pageresources_gput:nnnn {nnoo}
\cs_new_protected:Npn \pdf_pageresources_split_gput:nnn  #1 #2 #3 %#1 page, #2 resources
 {
   \@@_split_dict_entry_aux:NNw \l_@@_name_tmp_tl \l_@@_value_tmp_tl #3 \q_stop
   \pdf_pageresources_gput:nnoo {#1}{#2}{\l_@@_name_tmp_tl}{\l_@@_value_tmp_tl}
 }

\cs_generate_variant:Nn \pdf_pageresources_gput:nnn {noo}
\cs_new_protected:Npn \pdf_pageresources_split_gput:nn  #1 #2  %#1  resources
 {
   \@@_split_dict_entry_aux:NNw \l_@@_name_tmp_tl \l_@@_value_tmp_tl #2 \q_stop
   \pdf_pageresources_gput:noo {#1}{#2}{\l_@@_name_tmp_tl}{\l_@@_value_tmp_tl}
 }


  %Trying to patch pgf ..
\AtBeginDocument
 {
  % extgstate
  \cs_new:Npn \@@_patch_pgfextgs:w  #1/#2<<#3>>#4\q_stop
   {
    \@@_backend_pageresources_gput:nnn {ExtGState}{#2}{<<#3>>}
   }

  \def\pgf@sys@addpdfresource@extgs@plain#1
   {
    \exp_after:wN %for transparent which passes a command
    \@@_patch_pgfextgs:w #1\q_stop
   }

  % patterns
  \cs_new:Npn \@@_patch_pgfpatterns:w  #1/#2\space#3\q_stop
   {
    \exp_args:Nnnx \@@_backend_pageresources_gput:nnn {Pattern}{#2}{#3}
   }
  \def\pgf@sys@addpdfresource@patterns@plain#1
   {
    \@@_patch_pgfpatterns:w #1\q_stop
   }

  %colorspace is already set when tikz is loaded:
  \cs_new:Npn \@@_patch_pgfcolorspace:w  #1/#2[#3]#4\q_stop
   {
    \@@_backend_pageresources_gput:nnn {ColorSpace}{#2}{[#3]}
   }
  \tl_if_exist:NT \pgf@sys@pgf@resource@list@colorspaces
  {
   \exp_last_unbraced:NV
    \@@_patch_pgfcolorspace:w  \pgf@sys@pgf@resource@list@colorspaces\q_stop
   \pgfutil@everybye{}
  }
 }
% transparent, we assume that pdfresource is loaded first.

\AtEndPreamble
 {
  \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}
    }
  }
 }

%colorspace.sty
% rather difficult as no real places to inject patches
% at first a try to avoid that it's 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.
\AtEndPreamble
{
 \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}
  \pdf_pageresources_gput:nnn
   {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}%
  \pdf_pageresources_gput:nnn
   {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}%
  \pdf_pageresources_gput:nnn
   {ExtGState}
   {SPCop}
   {\@@_backend_object_ref:n {__spc_extgstate_op_true1}}
 \def\spc@Pageresources#1{}
 }
}

%</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.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_PageN_gput (page,name,value)
 @@.Page[page] = @@.Page[page] or {}
 @@.Page[page][name]=value
end

local function @@_backend_PageN_gpush (page)
 local token=""
 local t = {}
 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
 for name,value in pairs(t) do
   token = token .. "/"..name.." "..value
 end
 return token
end

function l3kernel.@@.backend_PageN_gput (page,name,value) -- tex.count["g_@@_abspage_int"]
 @@_backend_PageN_gput (page,name,value)
end

function l3kernel.@@.backend_PageN_gpush (page)
  pdf.setpageattributes(@@_backend_PageN_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 function @@_backend_PageN_Resources_gpush (page)
 local token=""
 if Properties[page] then
  for name,value in pairs(Properties[page]) do
   token = token .. "/"..name.." "..value
  end
  token = "/Properties <<"..token..">>"
 end
 -- add ExtGstate etc here ....
 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_@@_abspage_int"]
 Properties[page] = Properties[page] or {}
 Properties[page][name]=value
 pdf.setpageresources(@@_backend_PageN_Resources_gpush (page))
end
%</lua>
%    \end{macrocode}
% \PrintIndex