ltdocinit.dtx

% \iffalse meta-comment
%
%% File: ltdocinit.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) pdfmanagement bundle" (The Work in LPPL)
% and all files in that bundle must be distributed together.
%
% -----------------------------------------------------------------------
%
% The development version of the bundle can be found at
%
%    https://github.com/latex3/pdfresources
%
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \title{^^A
%   The \pkg{ltdocinit} package
% }
%
% \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{ltdocinit} documentation}
% This small package defines \cs{DeclareDocumentMetadata} and the related keys.
% \cs{DeclareDocumentMetadata} loads the new PDF management code.
% This forces the loading of the backend files the backend.
% So it needs at least a key to set the backend is needed.
%
% Currently the following keys are implemented
%
% \begin{description}
%    \item[\texttt{backend}] passes the backend name to expl3.
%    This will probably be extended to  pass the value also to packages.
%    \item[\texttt{pdfversion}] e.g. \texttt{pdfversion=1.7}
%    \item[\texttt{uncompress}] no value. Forces an uncompressed pdf.
%    \item[\texttt{lang}] to set the Lang entry in the Catalog. E.g. \texttt{lang=de-DE}.
%    \item[\texttt{standard}] Choice key to set the pdf standard.
%      Currently A-1b, A-2b and A-3b are accepted as
%      values, but the underlying code to ensure the requirements (as far as it
%      can be ensured) is incomplete.
%^^A     disabled for now.
%^^A    \item[\texttt{xmpmeta}] Boolean. This includes a skeleton XMP-metadata in the pdf. This clashes
%^^A     with e.g. hyperxmp, and the code to extend the metadata isn't finished yet.
%    \item[\texttt{pdfmanagement}] Boolean. This activates/deactivates
%      the core management code. By default the value is true.
% \end{description}
% \end{documentation}
%
% \begin{implementation}
%
% \section{\pkg{ltdocinit} implementation}
%
%    \begin{macrocode}
%<*package>
\ProvidesExplPackage {ltdocinit} {2020-11-27} {0.2}
  {Set document metadata}
%    \end{macrocode}
% \section{Document metadata}
% Currently there is no dedicated location to declare settings concerning
% a document as a whole. Settings are placed somewhere in the preamble or
% with the class options. For some settings this can be too late,
% for example the pdf version can no longer be changed if a
% package has already opened the PDF. \cs{DeclareDocumentMetadata} as a new command
% should unify such settings in one place. It should always be the first command
% in a document.
% Beside loading the PDF management code \cs{DeclareDocumentMetadata}
% currently allows to set the PDF version, to set the PDF \texttt{/Lang} and
% to uncompress a pdf.
% and set the language.
% ^^A We also add a key to activate the metadata stream and to set a standard.
%%
%    \begin{macrocode}
%<@@=document>
%<*package>
%    \end{macrocode}
% \begin{function}[updated=2020-11-27]{\DeclareDocumentMetadata}
%    \begin{macrocode}
\msg_new:nnn  { document } { setup-after-documentclass }
              {
                \token_to_str:N \DeclareDocumentMetadata \c_space_tl
                should~be~used~only~before~\token_to_str:N\documentclass
              }


\NewDocumentCommand\DeclareDocumentMetadata { m }
  {
    \cs_if_eq:NNTF \documentclass \@twoclasseserror
      { \msg_error:nn { document }{ setup-after-documentclass } }
      {
        \keys_set_groups:nnn { pdf / setup} {init}{ #1 }
        \RequirePackage{l3pdf}   %should be loaded after the backend is set.
         % %load backend driver
        \ExplSyntaxOn\makeatletter
          \file_input:n {l3\g__sys_backend_tl-pdf.def} %should be inside the normal backend
        \ExplSyntaxOff\makeatother
        \RequirePackage{l3pdfutils}
        \RequirePackage{l3pdfannot}
        \bool_gset_true:N \g__pdfmanagement_active_bool
        \keys_set_filter:nnn  { pdf / setup } { init } { #1 }
        \bool_if:NT \g__pdfmanagement_active_bool
          {
            \PassOptionsToPackage{customdriver=hgeneric-experimental}{hyperref}
          }
        \RenewDocumentCommand\DeclareDocumentMetadata { m }
          {
            \keys_set_filter:nnn  { pdf / setup } { init } { ##1 }
            \bool_if:NTF \g__pdfmanagement_active_bool
             {
               \str_remove_all:cn {opt@hyperref.sty}{customdriver=hgeneric-experimental}
               \PassOptionsToPackage{customdriver=hgeneric-experimental}{hyperref}
             }
             {
               \str_remove_all:cn {opt@hyperref.sty}{customdriver=hgeneric-experimental}
             }
          }
      }
  }


\keys_define:nn { pdf / setup }
  {
    backend .code:n = { \PassOptionsToPackage { driver=#1 } {expl3} },
    backend .groups:n = { init } ,
  }

%perhaps it should be a seq?
\keys_define:nn { pdf / setup }
  {
    ,pdfversion .code:n =
      {
        \pdf_version_gset:n { #1 }
      }
    ,uncompress .code:n =
      {
        \pdf_uncompress:
      }
    ,lang .code:n =
      {
        \pdfmanagement_add:nnn {Catalog} {Lang}{(#1)}
      }
    ,xmpmeta .bool_gset:N = \g_pdfmeta_xmp_bool %see pdfmeta undocumentated for now!
    ,standard .choices:nn =
      {A-1b,A-2b,A-3b}
      {
        \prop_if_exist:cT { g_pdfmeta_standard_pdf/#1_prop }
          {
            \prop_gset_eq:Nc \g_pdfmeta_standard_prop { g_pdfmeta_standard_pdf/#1 _prop }
          }

      }
    ,standard / unknown .code:n =
      {
        \msg_warning:nnn{pdf}{unknown-standard}{#1}
      }
    ,pdfmanagement .bool_gset:N = \g__pdfmanagement_active_bool
    ,pdfmanagement .initial:n =  {true}
  }
%    \end{macrocode}
% \end{function}
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex