latex-lab-dev (16jan22)

git-svn-id: svn://tug.org/texlive/trunk@61624 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 415 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/latex-dev/latex-lab/documentmetadata-support.dtx b/Master/texmf-dist/source/latex-dev/latex-lab/documentmetadata-support.dtx
new file mode 100644
index 00000000000..0c7a1d9d80a
--- /dev/null
+++ b/Master/texmf-dist/source/latex-dev/latex-lab/documentmetadata-support.dtx
@@ -0,0 +1,415 @@
+% \iffalse meta-comment
+%
+%% File: documentmetadata-support.dtx
+% Copyright (C) 2021-2022 The LaTeX 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
+%
+%
+% The development version of the bundle can be found below
+%
+%    https://github.com/latex3/latex2e
+%
+% for those people who are interested or want to report an issue.
+%
+%    \begin{macrocode}
+\def\documentmetadatasupportversion{1.0a}
+\def\documentmetadatasupportdate{2022-01-12}
+%    \end{macrocode}
+%
+%
+%<*driver>
+\documentclass{l3doc}
+\EnableCrossrefs
+\CodelineIndex
+\begin{document}
+  \DocInput{documentmetadata-support.dtx}
+\end{document}
+%</driver>
+%
+% \fi
+%
+%
+%\NewDocElement[macrolike = false ,
+%		 toplevel  = true,
+%                idxtype   =  key  ,
+%                noprint   = true  ,
+%                idxgroup  = metadata keys ,
+%                printtype = \textit{key}
+%               ]{Mkey}{mkey}
+%
+%
+% \title{The \texttt{documentmetadata-support} code\thanks{This file
+%      has version \documentmetadatasupportversion\ dated
+%      \documentmetadatasupportdate,  \copyright\ \LaTeX\
+%    Project.}}
+% \author{Frank Mittelbach, Ulrike Fischer, \LaTeX{} Project}
+%
+% \maketitle
+%
+%
+% \section{Introduction}
+%
+%    The kernel command \cs{DocumentMetadata}, which can be used as
+%    the very first declaration in a document (i.e., before
+%    \cs{documentclass}), defines metadata and other configuration
+%    data that applies to the document as a whole (using a key/value
+%    syntax).
+%
+%    While the underlying functionality is still under
+%    development (e.g., further keys will be added over time and keys
+%    marked temporary may vanish again) the code for
+%    \cs{DocumentMetadata} is place in a separate bundle, so that it
+%    is easier to update it without the need to build a full \LaTeX{}
+%    release. Over time the functionality will move fully into the
+%    kernel.
+%
+%    From a process perspective \cs{DocumentMetadata} loads the
+%    \pkg{pdfmanagement} code the first time it is called and then
+%    redefines itself to only manage key/value pairs in case it is
+%    called more than once. In particular, this means that a document
+%    without a \cs{DocumentMetadata} declaration has no code available
+%    for extended management of PDF output as needed for various
+%    features developed as part of the multi-year ``Tagged PDF''
+%    project~\cite{blueprint}.
+%
+%
+%
+% \section{Currently supported key/values}
+%
+%
+% Currently the following keys are implemented for \cs{DocumentMetadata}:
+% \DescribeMkey{colorprofiles}
+% \DescribeMkey{debug}
+% \DescribeMkey{lang}
+% \DescribeMkey{pdfstandard}
+% \DescribeMkey{pdfversion}
+% \DescribeMkey{testphase}
+% \DescribeMkey{uncompress}
+%
+% \begin{description}
+%    \item[\texttt{backend}] Passes the backend name to expl3. This is
+%      needed only if the needed backend can't be automatically
+%      determined or if the workflow used requires a special backend.
+%
+%^^A    This will probably be extended to  pass the value also to
+%^^A      packages.
+%
+%    \item[\texttt{pdfversion}] Sets the PDF version explicitly, e.g., \texttt{pdfversion=1.7}
+%    \item[\texttt{uncompress}] (no value) Forces an uncompressed pdf
+%      --- mainly for debugging purposes.
+%
+%    \item[\texttt{lang}] Explicitly sets the Lang entry in the Catalog,
+%     e.g., \texttt{lang=de-DE}. If not given the default value used is |en-US|.
+%
+%    \item[\texttt{pdfstandard}] Choice key to set the pdf standard.
+%      Currently |A-1b|, |A-2a|, |A-2b|, |A-2u|, |A-3a|, |A-3b| and |A-3u| are accepted as
+%      values. The casing is irrelevant, |a-1b| works too.
+%      The underlying code to ensure the requirements (as far as they
+%      can be ensured) is still incomplete, but a color profile is included and the
+%      \texttt{/OutputIntent} is set. The |u| variants for example do not force unicode,
+%      but they will pass the information to hyperref and hyperxmp. The |a| variants
+%      do \emph{not} enforce (or even test) a tagged pdf yet.
+%      More information can be found in the documentation
+%      of \pkg{l3pdfmeta}.
+%
+%    \item[\texttt{colorprofiles}] This allows to load icc-colorprofiles. Details
+%       are described in the documentation of \pkg{l3pdfmeta}.
+%
+%    \item[\texttt{testphase}] This key is used to load testphase code. The values it accepts
+%    and their effect will change over time, when testphase packages are added or
+%    removed or when the code is moved into the kernel.
+%     \begin{description}
+%    \item[\texttt{phase-I}]
+%       This value loads code implementing the first phase of the project~\cite{blueprint}, i.e., it 
+%       will load the tagpdf package. It will also activate tagging by issuing
+%       |\tagpdfsetup{activate,interwordspace}|. This phase
+%       is frozen.
+%    \item[\texttt{phase-II}]
+%       This is the current development phase.
+%       Currently it differs from \texttt{phase-I} only in one point: It will
+%       additionally activate tagging of paragraphs with
+%       |\tagpdfsetup{paratagging}|. In the upcoming months it will
+%       also enable automatic tagging of other basic document elements.
+%    \end{description}
+%    The |testphase| key can only be used in the first \cs{DocumentMetadata}.
+%
+%    \item[\texttt{debug}] This key activates some debug options. It takes a list of key-values
+%    as value. Currently the following keys are known:
+%     \begin{description}
+%     \item[\texttt{para}] with the default and only value |show|. It will activate the |paratagging-show|
+%       option of \pkg{tagpdf},
+%     \item[\texttt{log}]  with the values as described in the documentation \pkg{tagpdf},
+%     \item[\texttt{uncompress}] which does the same as |uncompress| as main key
+%     \item[\texttt{pdfmanagement}] a boolean which allows to deactivate the pdfmanagement.
+%     \item[\texttt{firstaidoff}] This accepts a comma lists of keywords and disables the patches
+%       related to them. More information can be found in the documentation of
+%       \pkg{pdfmanagement-firstaid}.
+%    \end{description}
+% \end{description}
+%
+% \bibliographystyle{plain}
+%
+% \begin{thebibliography}{9}
+%
+% \bibitem{blueprint} Frank Mittelbach and Chris Rowley:
+%   \emph{\LaTeX{} Tagged PDF\,---\,A blueprint for a large project}.
+%   \url{https://latex-project.org/publications/indexbyyear/2020/}
+%
+% \end{thebibliography}
+%
+%
+%
+% \MaybeStop{\setlength\IndexMin{200pt}  \PrintIndex  }
+%
+% \begin{implementation}
+%
+% \section{The Implementation}
+%
+%
+%    \begin{macrocode}
+%<@@=pdfmanagement>
+%<*code>
+%    \end{macrocode}
+%
+%    \begin{macrocode}
+
+\RequirePackage{pdfmanagement-testphase}
+%    \end{macrocode}
+%
+%    \begin{macrocode}
+\ExplSyntaxOn\makeatletter
+%    \end{macrocode}
+
+
+
+%  \begin{macro}{\DocumentMetadata}
+%
+%    \cs{DocumentMetadata} should not be used after
+%    \cs{documentclass} so we error in this case.
+%    It can be used more than once
+%     but follow-up calls should not do the initialization code.
+%    \begin{macrocode}
+\cs_set_protected:Npn \DocumentMetadata #1
+  {
+    \cs_if_eq:NNTF \documentclass \@twoclasseserror
+      { \msg_error:nn { meta } { after-class } }
+      {
+%    \end{macrocode}
+%
+%    The wanted backend must be detected first, we read the init
+%    key and then force the loading of the backend.
+%    The backend can contain management commands, so the boolean should
+%    be set to true first.
+%    \begin{macrocode}
+        \bool_gset_true:N \g_@@_active_bool
+        \keys_set_groups:nnn { document / metadata} {init}{ #1 }
+        %if no backend has been loaded force it now:
+        \str_if_exist:NF \c_sys_backend_str
+          {
+            \sys_load_backend:n {}
+          }
+%    \end{macrocode}
+%    Now we load the extra backend code:
+%    \begin{macrocode}
+        \ExplSyntaxOn\makeatletter
+          \file_input:n {l3backend-testphase-\c_sys_backend_str.def}
+        \ExplSyntaxOff\makeatother
+%    \end{macrocode}
+%    Set the default language (this requires that the backend has been loaded),
+%    process the rest of the keys,
+%    and setup the generic driver.
+%    \begin{macrocode}
+        \keys_set_filter:nnn  { document / metadata } { init } { lang=en-US, #1 }
+        \bool_if:NT \g_@@_active_bool
+          {
+            \PassOptionsToPackage{customdriver=hgeneric-testphase}{hyperref}
+          }
+%    \end{macrocode}
+%    \cs{pdfmanagement_add:nnn} has collected values in this hook.
+%    \begin{macrocode}
+        \hook_use_once:n {pdfmanagement/add}
+%    \end{macrocode}
+%    Now we redefine \cs{DocumentMetadata} so that it only process the
+%    keys on any further calls.
+%
+%     We need to update the hyperref option if the active status changes.
+%    \begin{macrocode}
+        \cs_set_protected:Npn \DocumentMetadata ##1
+          {
+            \keys_set_filter:nnn  { document / metadata } { init } { ##1 }
+            \str_remove_all:cn {opt@hyperref.sty}{customdriver=hgeneric-testphase}
+            \bool_if:NT \g__pdfmanagement_active_bool
+             {
+               \PassOptionsToPackage{customdriver=hgeneric-testphase}{hyperref}
+             }
+          }
+%    \end{macrocode}
+% Load more modules, the testphase code and the firstaid code. The code is only
+% loaded in the first \cs{DocumentMetadata} call!
+%    \begin{macrocode}
+        \g_@@_testphase_tl
+        \RequirePackage{pdfmanagement-firstaid}
+      }
+  }
+%    \end{macrocode}
+%  \end{macro}
+
+
+
+
+%    \begin{macrocode}
+%FMi defined elsewhere
+%FMi
+%FMi \clist_new:N \g_@@_firstaidoff_clist
+%FMi \tl_new:N \g_@@_testphase_tl
+% UFi should the definition move to here?
+\keys_define:nn { document / metadata }
+  {
+    backend .choices:nn =
+      { dvipdfmx , dvips , dvisvgm , luatex , pdftex , pdfmode , xdvipdfmx , xetex }
+      {
+        \sys_load_backend:n {#1}
+      },
+    backend .groups:n = { init } ,
+  }
+
+\keys_define:nn { document / metadata }
+  {
+    ,pdfversion .code:n =
+      {
+        \pdf_version_gset:n { #1 }
+        \AddToDocumentProperties[document]{pdfversion}{#1}
+      }
+    ,uncompress .code:n =
+      {
+        \pdf_uncompress:
+      }
+    ,uncompress .value_forbidden:n = true
+    ,lang .code:n =
+      {
+        \pdfmanagement_add:nnn {Catalog} {Lang}{(#1)}
+        \AddToDocumentProperties[document]{lang}{#1}
+      }
+    %,xmpmeta .bool_gset:N = \g_pdfmeta_xmp_bool %see pdfmeta unused and undefined for now!
+    % this uses internal command from pdfmeta, it should probably move there ...
+    ,pdfstandard .code:n =
+      {
+        \exp_args:Nnx
+        \keys_set:nn {document / metadata} {_pdfstandard=\str_uppercase:n{#1}}
+      }
+    ,_pdfstandard .choices:nn =
+      {A-1B,A-2A,A-2B,A-2U,A-3A,A-3B,A-3U}
+      {
+        \prop_if_exist:cT { g__pdfmeta_standard_pdf/#1_prop }
+          {
+            \prop_gset_eq:Nc \g__pdfmeta_standard_prop { g__pdfmeta_standard_pdf/#1 _prop }
+          }
+        \AddToDocumentProperties [document]{pdfstandard}{#1}
+      }
+    ,_pdfstandard / unknown .code:n =
+      {
+        \msg_warning:nnn{pdf}{unknown-standard}{#1}
+      }
+    ,testphase .multichoice:
+    ,testphase / tagpdf .code:n =
+      {
+        \tl_gput_right:Nn\g_@@_testphase_tl
+          {
+            \file_if_exist_input:nF {tagpdf-latex-lab-testphase.ltx}
+              {
+                \RequirePackage{tagpdf}
+                \AddToDocumentProperties [document]{testphase/tagpdf}{loaded}
+                \tagpdfsetup{activate,paratagging,interwordspace}
+                \AddToDocumentProperties [document]{tagging}{active}
+                \AddToDocumentProperties [document]{tagging/para}{active}
+                \AddToDocumentProperties [document]{tagging/interwordspace}{active}
+              }
+          }
+      }
+    ,testphase / unknown .code:n =
+      {
+        \tl_gput_right:Nn\g_@@_testphase_tl
+           {
+             \file_if_exist_input:nF {#1-latex-lab-testphase.ltx}
+              {
+                 \msg_warning:nnn{meta}{latex-lab-pkg-missing}{#1}
+              }
+           }
+      }
+    ,activate .multichoice:
+    ,activate / tagging .code:n =
+      {
+        \PackageWarning{pdfmanagement-testphase}
+         {The~activate~key~is~deprecated.\MessageBreak
+          Tagging~is~activated~with~'testphase=tagpdf'~directly}{}
+      }
+    ,debug .code:n =
+      {
+        \keys_set:nn { document / metadata / debug } {#1}
+      }
+    ,debug / para .code:n =
+      {
+        \AddToHook
+          {
+            package/tagpdf/after
+          }
+          {
+             \tagpdfsetup{paratagging-show}
+          }
+      }
+    ,debug / log .code:n =
+      {
+        \AddToHook
+          {
+           package/tagpdf/after
+          }
+          {
+             \tagpdfsetup{log=#1}
+          }
+      }
+    ,debug / uncompress .code:n =
+      {
+        \pdf_uncompress:
+      }
+    ,debug / pdfmanagement .bool_gset:N = \g_@@_active_bool
+    ,debug / firstaidoff .clist_gset:N = \g_@@_firstaidoff_clist
+  }
+
+
+%    \end{macrocode}
+% \subsection{Messages}
+%    \begin{macrocode}
+%UFi is meta the right module name here?
+\prop_gput:Nnn \g_msg_module_type_prop { meta } { LaTeX }
+\prop_gput:Nnn \g_msg_module_name_prop { meta } { DocumentMetadata }
+
+\msg_new:nnn { meta } { after-class }
+             {
+                \token_to_str:N \DocumentMetadata \c_space_tl
+                should~be~used~only~before~\token_to_str:N\documentclass
+             }
+\msg_new:nnn { meta } { latex-lab-pkg-missing }
+             {
+               LaTeX-lab~package~'#1'~not~found.
+              }
+%    \end{macrocode}
+%
+%    \begin{macrocode}
+\ExplSyntaxOff\makeatother
+%    \end{macrocode}
+%
+%
+%    \begin{macrocode}
+%</code>
+%    \end{macrocode}
+%
+% \end{implementation}
+%
+% \Finale
+%