[latex3-commits] [git/LaTeX3-latex3-latex2e] metadata: WIP (f58cec49)

[Frank Mittelbach]

Repository : https://github.com/latex3/latex2e
On branch  : metadata
Link       : https://github.com/latex3/latex2e/commit/f58cec4978fc1d4a36fe2802528949b173397f34

>---------------------------------------------------------------

commit f58cec4978fc1d4a36fe2802528949b173397f34
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Fri Dec 10 15:43:16 2021 +0100

    WIP


>---------------------------------------------------------------

f58cec4978fc1d4a36fe2802528949b173397f34
 base/ltmeta.dtx | 111 +++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 105 insertions(+), 6 deletions(-)

diff --git a/base/ltmeta.dtx b/base/ltmeta.dtx
index 36ffa238..6cfcbd25 100644
--- a/base/ltmeta.dtx
+++ b/base/ltmeta.dtx
@@ -52,7 +52,7 @@
 %
 %
 % \begin{abstract}
-%    This code defines the \cs{DeclareDocumentMetadata} interface.
+%    This code defines the \cs{DocumentMetadata} interface.
 % \end{abstract}
 %
 % \tableofcontents
@@ -61,6 +61,94 @@
 % \section{Introduction}
 %
 %
+%    In the past there was no dedicated location to declare settings
+%    concerning a document as a whole. Settings are placed somewhere
+%    in the preamble or with the class options or even with some
+%    package options.  For some settings this can be too late, for
+%    example the pdf version can no longer be changed if a package has
+%    used code which already opened the PDF.
+%
+%    \cs{DocumentMetadata} as a new command unifies such settings in
+%    one place.  It must be used before \cs{documentclass} but can be
+%    issued more than once there.
+%
+%    At the moment most of the code run by \cs{DocumentMetadata} is
+%    external to the format and subject to change. This includes the
+%    supported key/values.
+%
+% \subsection{\cs{DocumentMetadata}}
+%
+% \begin{function}{\DocumentMetadata}
+% \begin{syntax}
+%  \cs{DocumentMetadata}\Arg{key-value list}
+% \end{syntax}
+% \end{function}
+%
+%
+%
+%    The keys defined for \cs{DocumentMetadata}
+%    currently allow to set the PDF version, to set the PDF \texttt{/Lang},
+%    to uncompress a PDF, to set the language and to declare a few PDF standards
+%    and some color profiles.
+%
+%    \cs{DocumentMetadata} is also used to
+%    activate the new PDF management code and it loads
+%    a number of required files for the PDF management code.
+%    As this forces the loading of the backend files, a backend
+%    which can't be detected automatically like |dvipdfmx|,
+%    must be set in the first \cs{DocumentMetadata} call (if there is more than one).
+%
+%    Currently the following keys are implemented:
+%
+%    \begin{description}
+%       \item[\texttt{backend}] to specify the backend to use; this is
+%           usually determined automatically.
+%^^C       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}. The initial value 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 incomplete, but a color profile is included and the
+%         /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{pdfmanagement}] Boolean. This activates/deactivates
+%         the core management code. By default the value is true.
+%
+%       \item[\texttt{firstaidoff}] This accepts a comma lists of keysword and disable the patches
+%       related to them. More information can be found in the documentation of
+%       \pkg{pdfmanagement-firstaid}.
+%
+%       \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 when the code is moved into the kernel. Currently the accepted values are
+%       \texttt{tagpdf}, this load the tagpdf package, \texttt{headings}, this loads
+%       code which reimplements heading commands, and \texttt{ptagging} this loads code
+%       to allow paragraph tagging to work with engine other than luatex.
+%       \item[\texttt{activate}] This key is used to enable some document wide functions. It is
+%       currently in an experimental state. The values and their behaviour are subject to change.
+%       Currently the only value is |tagging|,
+%       which will do |\tagpdfsetup{activate,paratagging,interwordspace}|. It requires that
+%       \pkg{tagpdf} has been loaded first with the |testphase| key.
+%       \item[\texttt{debug}] This key activates some debug options. Currently only the
+%       keys |para| (with the default and only value |show|),
+%       and |log| (with the values of \pkg{tagpdf}) and |uncompress| (which does the same
+%       as |uncompress| as main key)  are known.
+%    \end{description}
 %
 %
 %
@@ -70,9 +158,6 @@
 %
 % \section{The Implementation}
 %
-%    \begin{macrocode}
-%<@@=tag>
-%    \end{macrocode}
 %
 %
 %    \begin{macrocode}
@@ -82,9 +167,23 @@
 %<latexrelease>                 {Document~Metadata~handling}
 %    \end{macrocode}
 %
+%    \begin{macrocode}
+\newcommand\DocumentMetadata{
+  \IfFileExists{pdfmanagement-testphase}
+     {
+      \RequirePackage{pdfmanagement-testphase}
+      \let\DocumentMetadata\DeclareDocumentMetadata
+      \DeclareDocumentMetadata
+     }
+     {
+       \ErrorNecessarySupportFilesMissing
+       \@gobble
+     }
+}     
+%    \end{macrocode}
+%
 %
 %
-% \subsection{}
 %
 %
 %    \begin{macrocode}
@@ -99,7 +198,7 @@
 %</2ekernel|latexrelease>
 %    \end{macrocode}
 %
-%    Restore module prefix:
+%    Restore module prefix (if any):
 %    \begin{macrocode}
 %<@@=>
 %    \end{macrocode}