[latex3-commits] [git/LaTeX3-latex3-pdfresources] master: storted link commands, tests failing with new l3build (2eb5b9e)
Ulrike Fischer
fischer at troubleshooting-tex.de
Thu Mar 12 19:20:32 CET 2020
Repository : https://github.com/latex3/pdfresources
On branch : master
Link : https://github.com/latex3/pdfresources/commit/2eb5b9e32a7b565116481172935aa4368fed3a70
>---------------------------------------------------------------
commit 2eb5b9e32a7b565116481172935aa4368fed3a70
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date: Thu Mar 12 19:20:32 2020 +0100
storted link commands, tests failing with new l3build
>---------------------------------------------------------------
2eb5b9e32a7b565116481172935aa4368fed3a70
pdfresources.dtx | 285 +++++++++++++++++++++++++++++++++++--------------------
1 file changed, 181 insertions(+), 104 deletions(-)
diff --git a/pdfresources.dtx b/pdfresources.dtx
index 1262ed3..5d161d0 100644
--- a/pdfresources.dtx
+++ b/pdfresources.dtx
@@ -1506,7 +1506,7 @@
% \pdf_xform_new:nnn
% }
% \begin{syntax}
-% \cs{pdf_xform_new:nnnn} \Arg{name} \Arg{attributes} \Arg {content}
+% \cs{pdf_xform_new:nnnn} \Arg{name} \Arg{attributes} \Arg{content}
% \end{syntax}
% This command create a new form XObject that can be used as appearance or
% directly later.
@@ -2058,7 +2058,7 @@
% \begin{function}[added = 2019-08-18]
% {\pdf_catalog_gput:nn, \pdf_catalog_gput:no , \pdf_catalog_gput:nx }
% \begin{syntax}
-% \cs{pdf_catalog_gput:nn} \Arg{key} \Arg {value}
+% \cs{pdf_catalog_gput:nn} \Arg{key} \Arg{value}
% \end{syntax}
% This adds an entry to the catalog. \Arg{key} is either a valid pdf
% \meta{name} (without preceding slash) or one of the special keys described
@@ -2581,7 +2581,7 @@
% \begin{function}[added = 2019-08-18]
% {\pdf_docview:nn}
% \begin{syntax}
-% \cs{pdf_docview:nn} \Arg{page} \Arg {view}
+% \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
@@ -2606,7 +2606,7 @@
% \begin{function}[added = 2019-09-05]
% {\pdf_annotation:nnnn}
% \begin{syntax}
-% \cs{pdf_annotation:nnnn} \Arg{width} \Arg {height} \Arg{depth} \Arg {annot spec}
+% \cs{pdf_annotation:nnnn} \Arg{width} \Arg{height} \Arg{depth} \Arg{annot spec}
% \end{syntax}
% This creates an /Type/Annot object.
% \end{function}
@@ -2631,115 +2631,184 @@
% \end{macrocode}
%
% \subsection{Higher-level link management}
-% \subsubsection{Startlink}
% Packages like hyperref, ocgx2 and tagpdf all wants to add code
-% to links/annotation. So we need a generic command to start a link which allows
-% packages to add their code to the \texttt{attr} argument through hooks.
-%
-% 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 ...
+% to links/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 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.
+% Probably we will need some commands to add an attribute to all link types
+% at once.
+% hyperref commands for the various type:
+% url |\hyper at linkurl|,
+% file |\hyper at linkfile|,
+% run |\@hyper at launch run|,
+% link |\hyper at link|, |\find at pdflink|
+% menu |\Acrobatmenu|
+% \end{NOTE}
+% \begin{variable}[added = 2020-03-12]{ \c_pdf_link_types_seq }
+% This constand sequence contains the list of currently supported link types
+% for which hooks exist.
+% \end{variable}
%
% \begin{macrocode}
-\prop_new:N\l_@@_hook_link_begin_url_attr_prop %\hyper at linkurl
-\prop_new:N\l_@@_hook_link_begin_file_attr_prop %\hyper at linkfile
-\prop_new:N\l_@@_hook_link_begin_run_attr_prop %\@hyper at launch run
-\prop_new:N\l_@@_hook_link_begin_link_attr_prop %\hyper at link, \find at pdflink
-\prop_new:N\l_@@_hook_link_begin_menu_attr_prop %\Acrobatmenu
+
+\seq_const_from_clist:Nn \c_pdf_link_types_seq { url , file , run , link, menu }
+
+\seq_map_inline:Nn \c_pdf_link_types_seq
+ {
+ \prop_new:c { l_@@_hook_link_begin_#1_attr_prop }
+ \seq_new:c { l_@@_hook_link_begin_#1_seq }
+ \seq_new:c { l_@@_hook_link_end_#1_seq
+ }
+
% \end{macrocode}
+
+
+% \subsubsection{Startlink}
+% \begin{function}[added = 2020-03-12]{ \pdf_link_user:nnn }
+% \begin{syntax}
+% \cs{pdf_link_user: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}.
+% If the type is one of the known types the attributes stored in the attribute
+% hook 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}
+% \pdf_link_user:nnn { url }
+% {
+% /Subtype /Link
+% /A<<
+% /Type/Action
+% /S/URI
+% /URI(https://www.latex-project.org)
+% >>
+% }
+% { link text }
+% \end{verbatim}
+% \end{function}
%
-% 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}
-\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
- \exp_args:Nxx %xetex needs expansion
- \@@_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 }
- \@@_dict_item:nn
+\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:
+ \exp_args:Nxx %xetex needs expansion
+ \@@_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 }
+ \@@_dict_item:nn
+ }
+ }
+ {
+ #2
}
- }
- {
- #2
- }
#3
- \@@_backend_link_end:
- \seq_if_exist:cT { l_@@_hook_link_end_#1_seq }
- {
- \seq_use:cn { l_@@_hook_link_end_#1_seq }{}
- }
- }
+ \@@_backend_link_end:
+ \seq_if_exist:cT { l_@@_hook_link_end_#1_seq }
+ {
+ \seq_use:cn { l_@@_hook_link_end_#1_seq }{}
+ }
+ }
% \end{macrocode}
+% \begin{function}[added = 2020-03-12]{ \pdf_link_begin_user:nnw, \pdf_link_begin_goto:nnw, \pdf_link_end:n }
+% \begin{syntax}
+% \cs{pdf_link_begin_user:nnw} \Arg{type} \Arg{user action spec} \meta{content}
+% \cs{pdf_link_end:n} \Arg{type}
+%
+% \cs{pdf_link_begin_goto:nnw} \Arg{type} \Arg{destination} \meta{content}
+% \cs{pdf_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}).
+% In contrast to \cs{pdf_link_user: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 the type is one of the known types the attributes stored in the attribute
+% hook of type \meta{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}
+% \pdf_link_begin_user:nnw { url }
+% {
+% /Subtype /Link
+% /A<<
+% /Type/Action
+% /S/URI
+% /URI(https://www.latex-project.org)
+% >>
+% }
+% link text
+% \pdf_link_end:n { url }
+% \end{verbatim}
+% \end{function}
% \begin{macrocode}
\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 }{}
- }
- \exp_args:Nxx %xetex needs expansion
- \@@_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 }
- \@@_dict_item:nn
- }
+ \seq_if_exist:cT { l_@@_hook_link_begin_#1_seq }
+ {
+ \seq_use:cn { l_@@_hook_link_begin_#1_seq }{}
}
- { #2 }
+ \exp_args:Nxx %xetex needs expansion
+ \@@_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 }
+ \@@_dict_item: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 }{}
- }
- \exp_args:Nxx %xetex needs expansion
- \@@_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 }
- \@@_dict_item:nn
- }
- }
- { #2 }
+ \seq_if_exist:cT { l_@@_hook_link_begin_#1_seq }
+ {
+ \seq_use:cn { l_@@_hook_link_begin_#1_seq }{}
+ }
+ \exp_args:Nxx %xetex needs expansion
+ \@@_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 }
+ \@@_dict_item:nn
+ }
+ }
+ { #2 }
}
-% \end{macrocode}
-% \begin{macrocode}
-\cs_set_eq:NN \pdf_link_margin:n \@@_backend_link_margin:n
-\cs_set_eq:NN \pdf_link_last: \@@_backend_link_last:
-% \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}
-\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
{
@@ -2751,16 +2820,24 @@
}
% \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{function}[added = 2020-03-12]{ \pdf_link_last: }
+% This retrieves the object reference a previously link created with the commands
+% above
+% \end{function}
% \begin{macrocode}
-\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
+\cs_set_eq:NN \pdf_link_last: \@@_backend_link_last:
% \end{macrocode}
%
+% \begin{function}[added = 2020-03-12]{ \pdf_link_margin:n }
+% \begin{syntax}
+% \cs{pdf_link_margin:n} \Arg{dimen}
+% \end{syntax}
+% This sets the dimension of the link margin.
+% \end{function}
+% \begin{macrocode}
+\cs_set_eq:NN \pdf_link_margin:n \@@_backend_link_margin:n
+% \end{macrocode}
+
% \subsection{Destinations}
% \begin{NOTE}{UF}
% I'm unsure about the backend code of the rectangle (FitR) variant. Should it
@@ -2794,16 +2871,16 @@
% \begin{function}[added = 2020-03-10]
% {\pdf_destination:nn}
% \begin{syntax}
-% \cs{pdf_destination:nn} \Arg{name} \Arg {type or integer}
+% \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|,
+% 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}
+% \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.
More information about the latex3-commits
mailing list.