% \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.0b} \def\documentmetadatasupportdate{2022-14-04} % \end{macrocode} % % %<*driver> \documentclass{l3doc} \EnableCrossrefs \CodelineIndex \begin{document} \DocInput{documentmetadata-support.dtx} \end{document} % % % \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|, |A-3u| and |A-4| 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. The |A-4| support is % currently incomplete. % 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,A-4} { \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 { \AddToDocumentProperties [document]{testphase/#1}{loaded} \file_if_exist_input:nF {#1-latex-lab-testphase.ltx} { \msg_warning:nnn{meta}{latex-lab-pkg-missing}{#1} \AddToDocumentProperties [document]{testphase/#1}{missing} } } } ,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} % % \end{macrocode} % % \end{implementation} % % \Finale %