l3pdffile.dtx

% \iffalse meta-comment
%
%% File: l3pdffile.dtx
%
% Copyright (C) 2018-2020 The LaTeX3 Project
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
% license or (at your option) any later version.  The latest version
% of this license is in the file
%
%    http://www.latex-project.org/lppl.txt
%
% This file is part of the "(experimental) pdfresources bundle" (The Work in LPPL)
% and all files in that bundle must be distributed together.
%
% -----------------------------------------------------------------------
%
% The development version of the bundle can be found at
%
%    https://github.com/latex3/pdfresources
%
% for those people who are interested.
%
%<*driver>
\RequirePackage{expl3}
\documentclass[full]{l3doc}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \title{^^A
%   The \pkg{l3pdffile} package\\ Embedding and referencing files in a PDF ^^A
% }
%
% \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 XXXX-XX-XX}
%
% \maketitle
% \begin{documentation}
%
% \section{\pkg{l3pdffile} documentation}
% External files can be referenced from a PDF in three ways:
% \begin{enumerate}
% \item through an annotation of type Link,
% \item by referencing a local file in the file system,
% \item by embedding the file directly into the PDF
% \end{enumerate}
%
% Case 1 (Links) are created with the \cs{pdfannot} commands.
%
% This module handles the two other cases. Actually from the view
% of the PDF format they are quite similar: Case 2 is case 3 without the stream
% object and without the /EF entry in the /FileSpec dictionary (this points to the
% stream object of the file). Not embedding the file makes the PDF smaller. But it is
% also less portable: the files can only be found if there are is the right location
% relative to the PDF. The normal case is to embed the file. So this is handled first.
%
% The tasks to embed and reference such file are
% \begin{enumerate}
% \item Embed the file in a stream.
% \item Create a FileSpec dictionary which references the stream object in the /EF
% dictionary
% \begin{verbatim}
% <<
% /Type /Filespec
% /F (l3pdffile.dtx)
% /UF (l3pdffile.dtx)
% /AFRelationship /Source
% /EF <</F 21 0 R /UF 21 0 R>>   %case 3, embedded file
% >>
% \end{verbatim}
% The file names in the /UF and /F value don't need to be identical to the
% file name of the embedded file. It is quite possible to embed a \texttt{zzz.tex}
% and name it \texttt{blub.tex}. The second name is then what the user will see
% in the attachment list or in the properties of an annotation.
%
%\item Reference the FileSpec dictionary so that the user can access the file.
%       This can be done in various way:
%       \begin{enumerate}
%       \item With an annotation (/Subtype/FileAttachment). This is done by
%       attachfile, attachfile2 and intopdf. Typical entries of such an annotation
%       are:
%
%             \begin{tabular}{lll}
%             FS       & object reference &(FileSpec dictionary)\\
%             Name     & name           & Graph, PushPin, Paperclip, Tag\\
%             Contents & text string & optional but recommended\\
%             F        & integer     & Flags\\
%             AP       & dictionary  & Appearance (required if rectangle >0) \\
%             AS       & name\\
%             \end{tabular}
%
%             The AP takes precedence over Border and similar keys.
%       \item Through an entry in the /EmbeddedFiles name tree. This is what embedfiles does.
%       \begin{verbatim}
%       20 0 obj %Document Name tree
%        <</EmbeddedFiles 21 0 R>>
%           endobj
%         21 0 obj %Embedded Files Name dictionary
%        <</Names [(AcmeCustomCrypto Protected PDF.pdf) 17 0 R]>>
%        endobj
%       \end{verbatim}
%       The strings (keys) in the /Names dictionary must be sorted lexically. But they
%       don't have to be the file name or anything related to the file name. So the code will
%       use l3emb0001, l3emb0002. The key  used for it is perhaps needed once:
%       to identify the start file in a collection, so there must be a way to retrieve it.
%
%       \item Through the /AF key in various objects (pdf 2.0). The value is normally an array of object
%       references, but it can also be a name which is mapped to an array in /Properties:
%        \begin{verbatim}
%        /AF /NamedAF BDC
%        /Properties <</NamedAF [12 0 R]
%        \end{verbatim}
%        The related FileSpec dictionary should contain an /AFRelationship key in this case:
%
%       \begin{tabular}{lp{6cm}}
%       Source  & shall be used if this file specification is the original
%                source material for the associated content.\\
%       Data    & shall be used if this file specification represents information used to
%                derive a visual presentation – such as for a table or a graph.\\
%       Alternative & shall be used if this file specification is an
%               alternative representation of content, for example audio.\\
%       Supplement & shall be used if this file specification represents
%       a supplemental representation of the original source or data
%       that may be more easily consumable
%       (e.g., A MathML version of an equation).\\
%       EncryptedPayload & shall be used if this file specification
%       is an encrypted payload document that should be displayed to the user
%       if the PDF processor has the cryptographic filter
%       needed to decrypt the document.\\
%       FormData & shall be used if this file specification
%       is the data associated with the AcroForm
%       (see 12.7.3, \enquote{Interactive form dictionary}) of this PDF.\\
%       Schema & shall be used if this file specification is a schema
%       definition for the associated object
%       (e.g. an XML schema associated with a metadata stream).\\
%       Unspecified &(default value) shall be used when the
%       relationship is not known
%       or cannot be described using one of the other values.\\
%       Other names & Second-class names (see Annex E,
%       \enquote{(normative) PDF Name Registry}) should be used to
%       represent other types of relationships.
%       \end{tabular}
%      \end{enumerate}
% \end{enumerate}
%
%
%\subsection{Embedding a file}
% Embedding an existing file is in most cases quite straightforward. It can be done with
% \cs{pdf_object_now:nn} or \cs{pdf_object_new:nn}/\cs{pdf_object_write:nn}.
% In the first variant one should then store the object number for the reference
% in the /FileSpec dictionary.
%
% \begin{verbatim}
% \pdf_object_now:nx {fstream}
%   {
%     {
%       /Type /EmbeddedFile
%       /Subtype /application\c_hash_str2Fpostscript
%       /Params
%         <<
%           /ModDate  ~ (\file_timestamp:n{example-image.eps})
%           /Size     ~  \file_size:n {example-image.eps}
%           /CheckSum ~ (\file_mdfive_hash:n {example-image.eps})
%          >>
%     }
%     {example-image.eps}
%   }
% \tl_set:Nx \l_my_fileobj_tl {\pdf_object_last:}
% \end{verbatim}
%
% Remarks:
% \begin{itemize}
% \item The /Params dictionary is not always required, but as the basic data
% are easily accessed it makes sense to add it automatically. Users will
% perhaps want to add also CreationDate here.
% \item The mimetype (in the /Subtype) can not always be detected automatically but
% it should be possible to store and use a list of common extensions. Other
% can be added manually.
% \item The dictionary can contain additional keys (/Filter, /DecodeParms)
% \item The filespec dictionary can actually refer to an external file (in which case the
% stream is ignored.

% \end{itemize}
%
% \begin{function}{file, file/Params, file/FileSpec}
% These are three local dictionaries which are used by the \cs{pdffile_embed} command
% to fill the dictionaries of the file and the filespec object. The following values
% are preset in the dictionary:
%
% \begin{tabular}{lll}
% dictionary & key      & value\\\hline
% file       & Type     & /EmbeddedFile\\
% file/Params& Size     & \cs{file_size:n}\\
% file/Params& ModDate  & (\cs{file_timestamp:n})\\
% file/Params& CheckSum & (\cs{file_mdfive_hash:n})\\
% file/FileSpec & Type  & /FileSpec\\
% file/FileSpec & AFRelationship &Unspecified
%
% \end{tabular}
% \end{function}
%
% \begin{function}{\pdffile_embed_file:nnn}
%   \begin{syntax}
%     \cs{pdffile_embed_file:nnn} \Arg{source filename} \Arg{target filename} \Arg{object name }
%   \end{syntax}
%   This commands embeds the file \Arg{source filename} in the PDF,
%   creates a /FileSpec dictionary object named \Arg { object name }.
%   The object name must be unique.
%   It uses the content of the local
%   dictionaries \texttt{file}, \texttt{file/Params} \texttt{file/FileSpec} to setup
%   the dictionary entries of the stream object and the  /FileSpec dictionary. The
%   /F and /UF entry are filled with \Arg{target filename}. If \Arg{target filename}
%   is empty \Arg{source filename} is used instead. If the file dictionary doesn't
%   contain a Subtype entry with the mimetype, the command tries to guess it
%   from the file extension.
% \end{function}
% \begin{function}{\pdffile_embed_stream:nnn}
%   \begin{syntax}
%     \cs{pdffile_embed_stream:nnN} \Arg{content} \Arg{target filename} \Arg{object name }
%   \end{syntax}
%   This commands embeds the \Arg{content} in the PDF in a stream objects,
%   creates a /FileSpec dictionary object named \Arg { object name }.
%   The object name must be unique. It uses the content of the local
%   dictionaries \texttt{file}, \texttt{file/Params} \texttt{file/FileSpec} to setup
%   the dictionary entries of the stream object and the /FileSpec dictionary. The
%   /F and /UF entry are filled with \Arg{target filename}. If \Arg{target filename}
%   is empty an automatically created name is used instead.
% \end{function}
% \end{documentation}
%
% \begin{implementation}
%
% \section{\pkg{l3pdffile} implementation}
%
%    \begin{macrocode}
%<*package>
\ProvidesExplPackage {l3pdffile} {2020-04-21} {0.1}
  {embedding and referencing files in PDF}
\RequirePackage{new-pdfescape}  %temporarly!!
%    \end{macrocode}
%
%    \begin{macrocode}
%<@@=pdffile>
\cs_set_eq:NN \@@_file_filename_convert_to_print:nN \pdftool_textstringhex_print:nN
%    \end{macrocode}
% \subsection{Messages}
%    \begin{macrocode}
\msg_new:nnn { pdffile } { file-not-found }
  {
    File~'\tl_to_str:n{#1}'~not~found
  }

\msg_new:nnn { pdffile } { mimetype-missing }
  {
    Mime~type~not~set~for~file~'\tl_to_str:n{#1}'
  }

\msg_new:nnn { pdffile } { file-object-no-found }
  {
    file~object~'\tl_to_str:n{#1}'~is~not~declared
  }

\msg_new:nnn { pdffile } { target-name-missing }
  {
    a~target~name~for~the~/FileSpec~dictionary~is~missing.
  }

\msg_new:nnn { pdffile } { object-exists }
  {
    object~name~'#1'~is~already~used.
  }

\msg_new:nnn { pdffile } { no-file-embedded }
  {
    No~file~has~been~embedded~with~object~name~'#1'\\
    Attaching~command~ignored.
  }
%    \end{macrocode}
% \begin{variable}
%   {
%     \l_@@_file_tmpa_tl,
%     \l_@@_file_tmpb_tl,
%     \l_@@_file_tmpa_str,
%     \l_@@_file_tmpb_str,
%     \l_@@_file_ext_str,
%     \l_@@_file_automimetype_tl
%   }
% temporary variables: generic, for extension, subtype
% \end{variable}
%    \begin{macrocode}
\tl_new:N  \l_@@_file_tmpa_tl
\str_new:N \l_@@_file_tmpa_str

\str_new:N \l_@@_file_ext_str
\tl_new:N  \l_@@_file_automimetype_tl

%    \end{macrocode}
% \begin{variable} {\g_pdffile_mimetypes_prop}
% This variable holds common mimetypes. The key is an extension with (one) period, the
% value the description, e.g. \texttt{text/csv}.
% \end{variable}
%    \begin{macrocode}
\prop_new:N \g_pdffile_mimetypes_prop
\prop_set_from_keyval:Nn \g_pdffile_mimetypes_prop
  {
    ,.csv = text/csv
    ,.html= text/html
    ,.dtx = text/plain %or application/x-tex, not in iana.org list
    ,.eps = application/postscript
    ,.jpg = image/jpeg
    ,.mp4 = video/mp4
    ,.pdf = application/pdf
    ,.png = image/png
    ,.tex = text/plain %or application/x-tex, not in iana.org list
    ,.txt = text/plain
    ,.sty = text/plain
  }
%    \end{macrocode}
% \begin{variable}
%  {
%   \l_pdffile_source_full_name_str,
%  }
% \cs{l_pdffile_source_full_name_str} will be set at the begin of the command and
% contains the full file name and can be used e.g. with \cs{file_timestamp:n}.
% \end{variable}
%    \begin{macrocode}
\str_new:N  \l_pdffile_source_full_name_str
\str_new:N  \l_pdffile_full_name_convert_str %???
%    \end{macrocode}
% Here we define and setup the local dictionaries. We also define constants.
%    \begin{macrocode}
\pdfdict_new:n   { file }
\pdfdict_put:nnn { file }{Type}{/EmbeddedFile}
\pdfdict_new:n   { file/Params }
\pdfdict_put:nnn { file/Params }
  {ModDate}  { (\file_timestamp:n { \l_pdffile_source_full_name_str }) }
\pdfdict_put:nnn { file/Params }
  {Size}     { \file_size:n { \l_pdffile_source_full_name_str } }
\pdfdict_put:nnn { file/Params }
  {CheckSum} { (\file_mdfive_hash:n { \l_pdffile_source_full_name_str }) }

\pdfdict_new:n   { file/FileSpec }
\pdfdict_put:nnn { file/FileSpec }
  {Type} { /FileSpec }
\pdfdict_put:nnn { file/FileSpec }
  {AFRelationship} { /Unspecified }

%    \end{macrocode}
%
% \begin{macro}{\pdffile_embed_file:nnn, \pdffile_embed_stream:nnn}
% At first a command to set the mimetype. It either uses the current value
% in the file dictionary, or tries to guess it from the extension.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_file_mimetype_set:nN #1 #2 %#1 file name, #2 tl for guessed mimetype
  {
    \file_parse_full_name:nNNN
          {#1}
          \l_@@_file_tmpa_str %unneeded
          \l_@@_file_tmpb_str %unneeded
          \l_@@_file_ext_str
        %check if Subtype has been set
        \pdfdict_get:nnN {file}{Subtype}\l_@@_file_tmpa_tl
        %if not look up in the prop:
        \quark_if_no_value:NT \l_@@_file_tmpa_tl
          {
            \prop_get:NVNTF \g_pdffile_mimetypes_prop \l_@@_file_ext_str \l_@@_file_tmpb_tl
              {
                \tl_set:Nx #2 {/Subtype~\pdftool_name_print:V \l_@@_file_tmpb_tl}
              }
              {
                \msg_warning:nnx { pdffile }{ mimetype-missing} {#1}
                \tl_clear:N #2
              }
          }
    }

\cs_generate_variant:Nn \@@_file_mimetype_set:nN {VN}

\cs_new_protected:Npn \@@_file_fstream_write:nN #1 #2
                                   %#1 file name,
                                   %#2 tl, should be empty or contain /Subtype /mimtype
                                   %   e.g. result from \@@_file_mimetype_set:NN

  {
    \pdf_object_now:nx { fstream }
      {
        {
          #2
          \pdfdict_map:n {file}
          \pdfdict_if_empty:nF {file/Params}
            {
              /Params
                <<
                  \pdfdict_map:n {file/Params}
                >>
            }
        }
        { #1 }
      }
     \tl_clear:N \l_@@_file_automimetype_tl
   }

\cs_generate_variant:Nn \@@_file_fstream_write:nN {VN}

\cs_new_protected:Npn \@@_file_filespec_write:nnn #1 #2 #3 %#1 name of dict object,
                                                           %#2 target file name,
                                                           %#3 object ref
  {
    \tl_if_blank:nT { #2 }
      {
        \msg_error:nn {pdffile}{target-name-missing}
      }
      {
        \pdf_object_new:nn   { #1 } {dict}
        \group_begin:
            \@@_file_filename_convert_to_print:nN  { #2 } \l_@@_file_tmpa_str
            %\str_show:N\l_@@_file_tmpa_str
            \pdfdict_put:nnx {file/FileSpec}{F} { \l_@@_file_tmpa_str }
            \pdfdict_put:nnx {file/FileSpec}{UF}{ \l_@@_file_tmpa_str }
            \pdf_object_write:nx { #1 }
              {
                \pdfdict_map:n {file/FileSpec}
                \tl_if_empty:nF { #3 }
                  {
                    /EF <</F~#3 /UF~#3>>
                  }
              }
        \group_end:
       }
  }
%% separate file name to embed and file name to display!
% we record here the source file. This allows also to test if an object name
% has an embedded file or is only a filespec
%
\prop_new:N \g_@@_file_embed_sources_prop

\cs_new_protected:Npn \pdffile_embed_file:nnn #1 #2 #3
   %\Arg{source filename} \Arg{target filename} \Arg{ file object name }
  { %               if #1 empty => only filespec
    %               if #2 empty => = #1
    \pdf_object_if_exist:nTF { @@_#3 }
      {
        \msg_error:nnn { pdffile }{ object-exists } { #3 }
      }
      {
        \tl_if_blank:nTF { #1 }
          {
            \tl_set:Nn \l_@@_file_embed_ref_tl {}
          }
          {
            \file_get_full_name:nNTF {#1} \l_pdffile_source_full_name_str
              {
                \prop_gput:NnV
                  \g_@@_file_embed_sources_prop
                  { #3 }
                  \l_pdffile_source_full_name_str
                \@@_file_mimetype_set:VN
                  \l_pdffile_source_full_name_str
                  \l_@@_file_automimetype_tl
                \@@_file_fstream_write:VN
                  \l_pdffile_source_full_name_str
                  \l_@@_file_automimetype_tl
                \tl_set:Nx \l_@@_file_embed_ref_tl { \pdf_object_last: }
              }
              {
                \msg_error:nnn { pdffile }{ file-not-found }{ #1 }
              }

           }
        \tl_if_blank:nTF { #2 }
          {
            \exp_args:Nnnx
              \@@_file_filespec_write:nnn
                %#1 dict, #2 target file name, #3 object ref
                { @@_#3 }
                { #1 }
                {\l_@@_file_embed_ref_tl}
          }
          {
            \exp_args:Nnnx
              \@@_file_filespec_write:nnn
                %#1 dict, #2 target file name, #3 object ref
                { @@_#3 }
                { #2 }
                {\l_@@_file_embed_ref_tl}
          }
      }
  }


\cs_new_protected:Npn \pdffile_embed_stream:nnn #1 #2 #3
   %\Arg{source filename} \Arg{target filename} \Arg{ file object name }
  { %               if #1 empty => only filespec
    %               if #2 empty => = #1
    \pdf_object_if_exist:nTF { @@_#3 }
      {
        \msg_error:nnn { pdffile }{ object-exists } { #3 }
      }
      {
        \tl_if_blank:nTF { #1 }
          {
            \tl_set:Nn \l_@@_file_embed_ref_tl {}
          }
          {
            \file_get_full_name:nNTF {#1} \l_pdffile_source_full_name_str
              {
                \prop_gput:NnV
                  \g_@@_file_embed_sources_prop
                  { #3 }
                  \l_pdffile_source_full_name_str
                \@@_file_mimetype_set:NN
                  \l_pdffile_source_full_name_str
                  \l_@@_file_automimetype_tl
                \@@_file_fstream_write:NN
                  \l_pdffile_source_full_name_str
                  \l_@@_file_automimetype_tl
                \tl_set:Nx \l_@@_file_embed_ref_tl { \pdf_object_last: }
              }
              {
                \msg_error:nnn { pdffile }{ file-not-found }{ #1 }
              }

           }
        \tl_if_blank:nTF { #2 }
          {
            \exp_args:Nnnx
              \@@_file_filespec_write:nnn
                %#1 dict, #2 target file name, #3 object ref
                { @@_#3 }
                { #1 }
                {\l_@@_file_embed_ref_tl}
          }
          {
            \exp_args:Nnnx
              \@@_file_filespec_write:nnn
                %#1 dict, #2 target file name, #3 object ref
                { @@_#3 }
                { #2 }
                {\l_@@_file_embed_ref_tl}
          }
      }
  }

\cs_new:Npn \pdffile_embed_ref:n #1 % #1 is the symbolic name used above
  {
    \pdf_object_ref:n {@@_#1}
  }
%    \end{macrocode}
% \end{macro}

% \subsection{backend commands to add the file to the /EmbeddedFiles name tree}
% For pdflatex, lualatex and xelatex, the name and object reference is stored in a sequence.
% The pdfresources code for the catalog output this and add a reference to /Names,
% if the sequence is not empty.
% dvips wants code for every file and then sorts this itself.
%    \begin{macrocode}
%    \end{macrocode}
% \begin{function}[added = 2020-04-24]
%   {\pdffile_attach:n, \pdffile_attach:nN,}
%   \begin{syntax}
%     \cs{pdffile_attach:n}  \Arg{name} \\
%     \cs{pdffile_attach:nN}  \Arg{name} \meta{tl var}
%   \end{syntax}
%   This attaches the file with name \Arg{name} which has been embedded
%   with \cs{pdffile_embed:nnn} to the attachments panel
%   of the pdf reader. \meta{tl var} stores the name used in the name tree, in
%   case it is needed to setup up for example a collection.
%\end{function}
%    \begin{macrocode}
\cs_new_protected:Npn \@@_file_check_attach_aux:nN #1  #2
  {
    \prop_get:NnNTF \g_@@_file_embed_sources_prop { #1 } \l_tmpa_str
      {
        \exp_args:Nx
          \@@_backend_NamesEmbeddedFiles_add:nN {\pdf_object_ref:n{#1}} #2
      }
      {
        \msg_warning:nnn { pdffile } { no-file-embedded } { #1 }
      }
  }

\cs_new_protected:Npn \pdffile_attach:nN #1 #2 % #1 name of filespec object, #2 in case the name must be retourned
 {
   \@@_backend_object_if_exist:nTF { #1 }
     {
       \@@_file_check_attach_aux:nN { #1 } #2
     }
     {
       \msg_error:nnn { pdffile } { file-object-no-found } { #1 }
     }
 }

\cs_new_protected:Npn \pdffile_attach:n #1 % name of filespec object
 {
   \@@_backend_object_if_exist:nTF { #1}
     {
       \@@_file_check_attach_aux:nN { #1 } \l_@@_file_tmpa_tl
     }
     {
       \msg_error:nnn { pdffile } { file-object-no-found } { #1 }
     }
 }

% for anonymous objects. This allows to use the interface with objects not
% created with l3 commands / naming. Testing if there is a file is not possible here
\cs_new_protected:Npn \pdffile_attach_last:N #1 % #1 in case the name must be retourned
 {
   \tl_set:Nx \l_@@_file_tmpa_tl {\pdf_object_last:}
   \exp_args:Nx
     \@@_backend_NamesEmbeddedFiles_add:nN { \l_@@_file_tmpa_tl } #1
 }

\cs_new_protected:Npn \pdffile_attach_last:
 {
   \tl_set:Nx \l_@@_file_tmpa_tl {\pdf_object_last:}
   \exp_args:Nx
     \@@_backend_NamesEmbeddedFiles_add:nN { \l_@@_file_tmpa_tl } \l_@@_file_tmpa_tl
 }


%    \end{macrocode}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex