[latex3-commits] [git/LaTeX3-latex3-pdfresources] testlinkstuff: merged drivers, with some corrections (315d5ae)
Ulrike Fischer
fischer at troubleshooting-tex.de
Tue Apr 9 14:34:07 CEST 2019
Repository : https://github.com/latex3/pdfresources
On branch : testlinkstuff
Link : https://github.com/latex3/pdfresources/commit/315d5ae3d457854ea6082ff8478182cec2b20c13
>---------------------------------------------------------------
commit 315d5ae3d457854ea6082ff8478182cec2b20c13
Merge: 93b519f d223ad9
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date: Tue Apr 9 14:34:07 2019 +0200
merged drivers, with some corrections
>---------------------------------------------------------------
315d5ae3d457854ea6082ff8478182cec2b20c13
pdfresources.dtx | 185 +++++++++++++++++++++++++++++++++---------------------
pdfresources.ins | 6 ++
2 files changed, 120 insertions(+), 71 deletions(-)
diff --cc pdfresources.dtx
index 1998e31,3b84f76..e4c3433
--- a/pdfresources.dtx
+++ b/pdfresources.dtx
@@@ -72,284 -68,107 +75,324 @@@
%
% \subsection{\pkg{media9}}
%
- % \section{Managing Links}
- % \subsection{new experimental l3driver commands}
- % pdftex and luatex the startlink commands can use different \enquote{action spec}
-% \subsection{Driver implementation}
++% \section{New driver Code}
++% \subsection{already revisited }
+ %
+ % \begin{macrocode}
+ %<*drivers>
+ % \end{macrocode}
+ %
+ % \begin{macrocode}
+ %<@@=driver>
+ % \end{macrocode}
+ %
+ % \subsubsection{\texttt{pdfmode} driver}
+ %
+ % \begin{macrocode}
+ %<*pdfmode>
+ % \end{macrocode}
+ %
+ % \begin{macro}{\driver_pdf_startlink_goto:nn, \driver_pdf_startlink_user:nn}
+ % \begin{macro}{\@@_pdf_startlink:nnn}
+ % \begin{macrocode}
+ \cs_new_protected:Npn \driver_pdf_startlink_goto:nn #1#2
+ { \@@_pdf_startlink:nnn {#1} { goto~name } {#3} }
+ \cs_new_protected:Npn \driver_pdf_startlink_user:nn #1#2
+ { \@@_pdf_startlink:nnn {#1} { user } {#3} }
+ \cs_new_protected:Npx \@@_pdf_startlink:nn #1#2#3
+ {
+ \cs_if_exist:NTF \tex_pdfextension:D
+ { \tex_pdfextension:D startlink ~ }
+ { \tex_pdfstartlink:D }
+ attr {#1}
+ \exp_not:N \tl_if_blank:nF {#2}
+ { ~ #2 {#3} }
+ }
+ % \end{macrocode}
+ % \end{macro}
+ % \end{macro}
+ %
+ % \begin{macro}{\driver_pdf_endlink:}
+ % \begin{macrocode}
-\cs_new_protected:Npx \@@_pdf_endline:
++\cs_new_protected:Npx \@@_pdf_endlink:
+ {
+ \cs_if_exist:NTF \tex_pdfextension:D
+ { \tex_pdfextension:D endlink }
+ { \tex_pdfendlink:D }
+ }
+ % \end{macrocode}
+ % \end{macro}
+ %
+ % \begin{macrocode}
+ %</pdfmode>
+ % \end{macrocode}
+ %
+ % \subsubsection{\texttt{(x)dvipdfmx} driver}
+ %
+ % \begin{macrocode}
+ %<*dvipdfmx|dvixpdfmx>
+ % \end{macrocode}
+ %
+ % \begin{macro}{\@@_pdf:n}
+ % \begin{macrocode}
+ \cs_new_protected:Npx \@@_pdf:n #1
+ { \@@_literal:n { pdf: #1 } }
+ % \end{macrocode}
+ % \end{macro}
+ %
+ % \begin{macro}{\driver_pdf_startlink_goto:nn, \driver_pdf_startlink_user:nn}
+ % \begin{macro}{\@@_pdf_startlink:nnn}
+ % \begin{macrocode}
+ \cs_new_protected:Npn \driver_pdf_startlink_goto:nn #1#2
+ { \@@_pdf_startlink:nnn {#1} { /GoTo } {#3} }
+ \cs_new_protected:Npn \driver_pdf_startlink_user:nn #1#2
+ { \@@_pdf_startlink:nnn {#1} { } {#3} }
+ \cs_new_protected:Npn \@@_pdf_startlink:nn #1#2#3
+ {
+ \@@_pdf:n
+ {
+ bann
+ <<
+ /Type /Annot
+ #1 ~ #2 ~ #3
+ >>
+ }
+ }
+ % \end{macrocode}
+ % \end{macro}
+ % \end{macro}
+ %
+ % \begin{macro}{\driver_pdf_endlink:}
+ % \begin{macrocode}
-\cs_new_protected:Npx \@@_pdf_endline:
++\cs_new_protected:Npx \@@_pdf_endlink:
+ { \@@_pdf:n { eann } }
+ % \end{macrocode}
+ % \end{macro}
+ %
+ % \begin{macrocode}
+ %</dvipdfmx|dvixpdfmx>
+ % \end{macrocode}
+ %
+ % \begin{macrocode}
+ %</drivers>
+ % \end{macrocode}
+ %
-% \maketitle
++%
++% \subsection{driver commands / experimental}
++% Notes: pdftex and luatex the startlink commands can use different \enquote{action spec}
+% \texttt{user}, \texttt{goto} and \texttt{thread}. To be able to translate this to
- % other drivers, three startlink variant are defined.
++% other drivers, startlink variants are defined.
+% Variants which allow also to set the rule spec are perhaps needed too.
+% Currently only pdftex, luatex and xetex are setup. Some commands can probably not be
+% implemented in all drivers.
+% \begin{macrocode}
+
+\sys_if_engine_pdftex:T
+{
- \cs_new_protected:Nn \driver_pdf_startlink_user:nn
- {
- \pdfstartlink
- attr { #1 }
- ~
- user { #2 }
- \relax %?needed, hyperref seems to think so
- }
-
- \cs_new_protected:Nn \driver_pdf_startlink_goto_name:nn
- {
- \pdfstartlink
- attr { #1 }
- ~
- goto~name { #2 }
- \relax %?needed, hyperref seems to think so
- }
-
- \cs_new_protected:Nn \driver_pdf_endlink:
- {
- \pdfendlink
- }
-
+ \cs_new_protected:Nn \driver_pdf_lastlink:
+ {
+ \pdflastlink
+ }
+
+ \cs_new_protected:Nn \driver_pdf_catalog:n
+ {
+ \pdfcatalog { #1 }
+ }
-
+}
+
+\sys_if_engine_luatex:T
+{
- \cs_new_protected:Nn \driver_pdf_startlink_user:nn
- {
- \pdfextension startlink
- attr { #1 }
- ~
- user { #2 }
- \relax %?needed, hyperref seems to think so
- }
-
- \cs_new_protected:Nn \driver_pdf_startlink_goto_name:nn
- {
- \pdfextension startlink
- attr { #1 }
- ~
- goto~name { #2 }
- \relax %?needed, hyperref seems to think so
- }
-
- \cs_new_protected:Nn \driver_pdf_endlink:
- {
- \pdfextension endlink
- }
-
+ \cs_new_protected:Nn \driver_pdf_lastlink:
+ {
+ \numexpr\pdffeedback lastlink\relax
+ }
+
+ \cs_new_protected:Nn \driver_pdf_catalog:n
+ {
+ \pdfextension catalog { #1 }
+ }
+
+}
+
+\sys_if_engine_xetex:T
+{
- \cs_new_protected:Nn \driver_pdf_startlink_user:nn
- {
- \special
- {
- pdf:bann
- <<
- /Type/Annot
- #1~#2
- >>
- }
- }
+ %% \cs_new_protected:Nn \driver_pdf_startlink_goto_name:nn %????
- \cs_new_protected:Nn \driver_pdf_endlink:
- {
- \special{pdf:eann}
- }
+ %% \cs_new_protected:Nn \driver_pdf_catalog:n ????
+}
+% \end{macrocode}
- %
++% \section{Management code}
+% \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}
+\cs_new:Nn \__pdf_get_key_value:nn { #1~#2~ } %name?????
+% \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}
+\prop_new:N\l__pdf_hook_startlink_url_attr_prop %\hyper at linkurl
+\prop_new:N\l__pdf_hook_startlink_file_attr_prop %\hyper at linkfile
+\prop_new:N\l__pdf_hook_startlink_run_attr_prop %\@hyper at launch run
+\prop_new:N\l__pdf_hook_startlink_link_attr_prop %\hyper at link, \find at pdflink
+% \end{macrocode}
+%
+% High-level startlink commands that uses the stored attributes:
+% At first one with the \texttt{user} argument:
+% \begin{macrocode}
+\cs_new_protected:Nn \pdf_startlink_user:nn %#1 type, #2 action spec
+{
+ \seq_use:cn { l__pdf_hook_startlink_#1_seq }{}
+ \driver_pdf_startlink_user:nn
+ {
+ \prop_map_function:cN
+ { l__pdf_hook_startlink_#1_attr_prop }
+ \__pdf_get_key_value:nn
+ }
+ { #2 }
+}
+
+% At second one with the \texttt{goto name} argument:
+\cs_new_protected:Nn \pdf_startlink_goto_name:nn %#1 type, #2 destination
+{
+ \seq_use:cn { l__pdf_hook_startlink_#1_seq }{}
- \driver_pdf_startlink_goto_name:nn
++ \driver_pdf_startlink_goto:nn
+ {
+ \prop_map_function:cN
+ { l__pdf_hook_startlink_#1_attr_prop }
+ \__pdf_get_key_value:nn
+ }
+ { #2 }
+}
+% \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__pdf_hook_endlink_url_seq
+\seq_new:N \l__pdf_hook_endlink_run_seq
+\seq_new:N \l__pdf_hook_endlink_file_seq
+\seq_new:N \l__pdf_hook_endlink_link_seq
+
+\cs_new_protected:Nn \pdf_endlink:n %#1 type, e.g. url
+ {
+ \driver_pdf_endlink:
+ \seq_use:cn { l__pdf_hook_endlink_#1_seq }{}
+ }
+
+
+% \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}
+\seq_new:N \l__pdf_hook_startlink_url_seq
+\seq_new:N \l__pdf_hook_startlink_run_seq
+\seq_new:N \l__pdf_hook_startlink_file_seq
+\seq_new:N \l__pdf_hook_startlink_link_seq
+% \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>}
++% \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}
+\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 }
+ }
+
+% \end{macrocode}
+%
+%
%
% \PrintIndex
More information about the latex3-commits
mailing list