path: root/macros/latex/contrib/pdfmanagement-testphase/pdfmanagement-testphase.dtx

% \iffalse meta-comment
%
%% File: pdfmanagement-testphase.dtx
%
% Copyright (C) 2019-2023 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
%
% This file is part of the "LaTeX PDF management testphase 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>
\DocumentMetadata{pdfstandard=A-2b}
\documentclass{l3doc}
\usepackage{tabularx,array,booktabs}
\hypersetup{pdfauthor=The LaTeX Project,pdftitle=LaTeX PDF management testphase bundle}
\newcommand\potentialclash{\noindent\llap{\dbend\ }}
\raggedbottom
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
%
% \title{The \LaTeX{} PDF management testphase bundle}
%
% \author{^^A
%  The \LaTeX{} Project\thanks
%    {^^A
%      E-mail:
%        \href{mailto:latex-team@latex-project.org}
%          {latex-team@latex-project.org}^^A
%    }^^A
% }
%
% \date{Version 0.95x, released 2023-03-09}
%
% \maketitle
% \begin{documentation}
% \section*{Abstract}
%  {\em This is a temporary package created to allow the manual
%   loading of the new \LaTeX{} PDF management code during a test phase.
%  It will disappear when the code is integrated into the \LaTeX{} format.}
%
%  \medskip
%  \noindent During the test phase the package should be used like this:
%
% \begin{verbatim}
% \RequirePackage{pdfmanagement-testphase}   % load the package
%
% \DocumentMetadata      % activate the PDF management (with options)
%     {
%       % options
%     }
%
%  \documentclass {...}
% \end{verbatim}
%  Note that the activation has to happen before the \cs{documentclass} declaration.
%  Because of this, the package needs loading with \cs{RequirePackage}.
%
% Starting with LaTeX 2022-06-01 (or a suitable latex-dev) it is no longer necessary to
% load pdfmanagement-testphase manually, using \cs{DocumentMetadata} is enough.
%
%
% \section*{Feedback wanted!}
%
% Bug reports and feedback are welcome. Please open an issue at
% \url{https://github.com/latex3/pdfresources}.
%
% While the code targets PDF as output format, feedback about the
% effect on other formats is needed too.
%
% \section{Introduction}
% The \LaTeX{} format currently contains nearly no code specific to the now quite
% central output format, PDF. It also offers nearly no interfaces to important PDF related
% primitive commands for package writers.
%
% Important tasks like supporting PDF standards,
% creating links, adding special colors, managing the content of
% central PDF-directories or even simple tasks like setting the PDF version
% are delegated to external packages which have to recourse to
% the primitive low-level commands in their code.
%
% This is problematic for three reasons:
% \begin{itemize}
%\item At first using primitives directly can lead to clashes and duplicate
% settings with conflicting values---nothing prevent packages to add for example
% the \texttt{/Title} twice to the Info dictionary, the \texttt{/Lang} entry
% twice to the Catalog, or to add two \texttt{/ExtGState}
% resources to a page. The PDF normally doesn't break in such
% cases---the format is quite robust---but it will ignore one of the duplicates and
% the output can be wrong.
%
% \item At second the primitives differ between the various engines and backends with
% which \LaTeX{} is used. To support the engines and backend
% packages have to write and maintain
% \enquote{driver} files which they did to a varying degree. This makes it
% difficult for users to assess if a package will work with their work-flow and
% is a strain for package writers as they have to keep track of engine and backend changes.
%
% \item And at last generic hooks and configuration points to various
% PDF related structures are missing and difficult to add.
% \end{itemize}
%
% Despite the potential problems, until now the number of conflicts were
% small and could be resolved in an ad-hoc fashion. But the future plans for
% \LaTeX{} regarding support for tagged PDF and
% PDF standards mean that much more PDF specific code will have to be
% written by the kernel directly and this can not be done without proper,
% well-defined and well-behaving interfaces and hooks.
%
% Some first steps for better support of PDF related commands have been done
% with the \pkg{l3pdf} package which has now been integrated as a module
% into \pkg{l3kernel}.
% It offers backend independent commands to create
% PDF objects and destination, to set the compress level and the PDF version.
%
% The PDF management bundle extends this to more PDF related areas
% and provides interfaces to them in a backend independent way.
%
% The new PDF management has three main objectives
% connected with the problems identified above:
% \begin{itemize}
% \item For commands with \enquote{clash potential} it implements commands to
% replace the primitives and so to resolve potential conflicts.
%
% \item It implements commands for a variety of PDF related tasks
% and supports a well-defined set of backends.
%
% \item If sensible this commands are enhanced by hooks from the new
% \LaTeX{} hook system. This has been e.g.\ done for annotations in the
% \pkg{l3pdfannot} bundle.
% \end{itemize}
%
% \section{\enquote{Change Strategy}: The integration into \LaTeX\label{sec:change}}
%
% The central module of this bundle, \pkg{l3pdfmanagement}, defines an interface
% for the (pdf\TeX) primitives \cs{pdfcatalog}, \cs{pdfinfo},
% \cs{pdfpagesattr}, \cs{pdfpagesattr} and \cs{pdfpageresources} and
% the analog commands from the other engines and backends.
%
% All these commands have a \enquote{clash potential}, this means that the new
% interface is incompatible with a parallel use of the primitive commands
% which it targets to replace and supersede.
% This doesn't affect many packages, but the list of package using such primitives
% contains central and important packages like \pkg{hyperref}, \pkg{tikz},
% \pkg{pdfx} and more.
%
% So while the goal is to integrate the code into the \LaTeX{} format directly,
% this can not be done immediately without conflicts with existing documents and packages.
%
% As an intermediary step the package \pkg{pdfmanagement-testphase} has been
% created which loads the code manually.
% With it package authors and users can test the new code, give feedback
% and packages can be adapted.
%
% Loading the package will only \emph{load} the modules,
% to \emph{activate} the core PDF management the trigger command
% \cs{DocumentMetadata} has to be used too.
% The loading and activation has to be done
% \emph{before} the \cs{documentclass} command.
%
%
% We hope that this setup will allow packages writers and users to test the
% PDF management code and adapt packages and documents safely.
%
%
% \section{Backend support}
% The supported backends are pdflatex, lualatex, (x)dvipdfmx (latex, xelatex,
% dvilualatex (in texlive 2021))
% and dvips with ps2pdf (not completely yet). dvips with distiller could work too
% but is untested.
%
% That the interfaces and commands are backend independent doesn't mean
% that the results and even the compilation behavior is identical.
% The backends are too different to allow this.
% Some backends expand arguments e.g. in a \cs{special} while other don't.
% Some backends can insert a resource at the first compilation, while another uses
% the aux-file and a label and so needs at least two compilation runs.
% Some backends manage some of the resources through side-effects,
% some manage them automatically.
% All this mean that package writers will still have to keep an eye on
% backend requirements and run tests for all variants. Also backend specific code
% will still be needed in some cases.
%
% \section{Use}\label{sec:use}
% The package should be loaded before \cs{documentclass}. To activate
% the resource management it should be followed by
% \cs{DocumentMetadata}\marg{key-val}.
% The options of \cs{DocumentMetadata} are described in the documentation of
% \pkg{ltdocinit}.
%
% \begin{verbatim}
% \RequirePackage{pdfmanagement-testphase} % load the package
%                                          % not needed with LaTeX 2022-06-01
% \DocumentMetadata % activates the PDF management interface
%     {
%        %options
%     }
% \documentclass {...}
% \end{verbatim}
%
% The PDF management can be deactivated either setting in the \texttt{debug} key
% the key
% \texttt{pdfmanagement} to \texttt{false} or by commenting out
% the whole \cs{DocumentMetadata} declaration.
%
% To test if the PDF management is active the predicate
% \cs{pdfmanagement_if_active:TF} can be used, see the documentation of \pkg{l3pdfmanagement}.
%
% \section{Requirements}
% The new PDF management requires a \LaTeX{} format from 2020/10/01 or later
% and an L3 programming layer of 2021-02-18 or later.
% It currently depends on the experimental packages \pkg{l3ref-tmp} and \pkg{l3bitset}.
% In some places, e.g. when writing strings to the pdf it assumes that
% the file is utf8 encoded -- ascii will naturally work too, but legacy 8bit encodings are
% not supported.
%
% \section{Modules}
% The bundle contains a number of modules. The majority of the modules don't
% have a stand alone \texttt{sty}, their code is combined
% in one file and loaded by the main package. The organization and naming is bound
% to change over time: For almost all modules the goal is to
% integrate them into the format and the individual files to disappear.
%
% The description items give the name of the documentation
% of the modules. There doesn't exist in all cases a related |.sty|.
%
% \begin{description}
% \item[l3pdfdict] This module provides commands for PDF dictionaries. Its main
% purpose is to create name spaces. The code used e.g. by \pkg{l3pdfmanagement} and
% \pkg{l3pdfannot}.
%
% \item[l3pdfannot] This module provides commands for annotations. Currently mainly
% link annotations, widget annotations will be added later. It doesn't require
% the PDF management to be active.
%
% \item[l3pdfmanagement] This is the core code of the PDF management.
%
% \item[ltdocinit] This module provides the \cs{DocumentMetadata} command.
%
% \item[hyperref-generic] This module provides a new generic hyperref driver.
% The driver will
% be loaded automatically by hyperref if the PDF management code is active.
%
% \item[l3backend-testphase] This module contains backend code needed by the
% PDF management. It will in due time be integrated into l3backend.
%
% \item[l3pdfmeta] This module contains code to handle PDF standards.
% Currently it handles pdf/A and colorprofiles/outputintents.
%
% \item[l3pdfxform]  Commands for form XObjects (xforms).
%
% \item[l3pdf\/tool] A number of commands like text conversion commands and
% bcd/emc.  The commands will at some time be moved into the \pkg{l3pdf}
% module of l3kernel.
%
% \item[l3pdf\/file] This module provides commands for to embed files.
%
% \item[pdfmanagement-firstaid] This module provides a number of patches
% for external incompatible packages. This patches will disappear as soon as
% the packages are natively compatible. It is loaded automatically.
%
% \item[l3pdffield]  Commands for form fields. Currently it only provides commands
% for checkboxes. It must be loaded explicitly as with
% |\usepackage{l3pdffield-testphase}|.
%
% \end{description}
% \section{Incompabilities}
%
% As described in section~\ref{sec:change}, if activated
% the new PDF management takes over the management of core PDF dictionaries.
% All packages
% that bypass the PDF management and access these dictionaries with primitives like
% \cs{pdfcatalog}, \cs{pdfinfo}, \cs{pdfpageresources}, \cs{pdfpagesattr}
% and \cs{pdfpageattr} or similar commands from other engines and backends are
% basically incompatible: values can get lost or will be wrong.
%
% The following describes known incompatible packages along with some suggestions
% how this should or will be handled in future. The list is not exhaustive.
%
% \subsection{hyperref}
% A generic driver that can
% be used as replacement has been developed and is provided by this bundle.
% It will be loaded automatically if the pdf management is active.
%
% The generic driver differs in some points from other \pkg{hyperref} drivers:
% \begin{itemize}
% \item The code for bookmarks has been removed from this driver, instead
% the \pkg{bookmarks} is loaded and used.
% \item The driver isn't yet fully integrated into hyperref. This means that
% it doesn't react to a number of package options. Instead \cs{hypersetup} should
% be used.
% \item Incomplete is the support for form fields. Quite probably form fields will
% be extracted in a dedicated package.
% \item The driver uses for the color handling the l3color package. While normally
% it should be able to use colors defined with color and xcolor, there could be
% edge cases where it fails.
% \item The colors have been changed (this counts probably as an improvement \ldots).
% \end{itemize}
%
% More details can be found in the documentation \pkg{hyperref-generic.pdf}.
%
% \subsection{pdfx}
% \pkg{pdfx} is not compatible. It uses the commands \cs{pdfpagesattr}, \cs{pdfpageattr},
% \cs{pdfinfo} and \cs{pdfcatalog}. The needed changes are not many, but can
% not be done by external patches.
%
% It is also one goal of the pdfmanagement project to
% offer support for standards natively. The code is under development,
% see the documentation of \pkg{l3pdfmeta}.
%
% \subsection{hyperxmp}
% \pkg{hyperxmp} uses \cs{pdfcatalog} to insert the \texttt{/MetaData} reference
% and also relies on some \pkg{hyperref} internals which are not present in the new
% generic driver used by \pkg{hyperref} when the pdfmanagement is active.
% This makes \pkg{hyperxmp} incompatible.
%
% For some time some patch code was provided by the bundle to keep \pkg{hyperxmp}
% working but starting with version  0.95s XMP-metadata are handled directly
% by the \pkg{pdfmanagement-testphase} bundle (see the documentation of \pkg{l3pdfmeta})
% and the patch code has been removed and the loading of
% \pkg{hyperxmp} has been disabled.
%
% \subsection{tikz/pgf}
% \pkg{pgf} writes to the page resources too and so is incompatible. The needed
% changes are rather small and will be done in coordination with the maintainer.
% Until this works, \pkg{pdfmanagement-testphase} will load the patches automatically.
% This can be disabled by using |debug={firstaidoff=pgf}| in \cs{DocumentMetadata}
%
% \subsection{transparent}
% The package \pkg{transparent} is incompatible. A replacement has been written
% (\pkg{transparent-ltx}) and is loaded automatically. It requires a very recent
% L3 programming layer!
% This can be disabled by using |debug={firstaidoff=transparent}| in \cs{DocumentMetadata}
% \subsection{pdflscape}
% The package \pkg{pdflscape} is incompatible. A replacement has been written
% (\pkg{pdflscape-ltx}) and is loaded automatically.
% This can be disabled by using |debug={firstaidoff=pdflscape}| in \cs{DocumentMetadata}
%
% \subsection{colorspace}
% The package is incompatible. Some patches
% have been added to \pkg{pdfmanagement-firstaid}.
% Alternative code for spot colors is
% in the \pkg{l3color} package which has now been added to \pkg{l3kernel}.
%
% \subsection{embedfile, attachfile, attachfile2}
% Tools needed to be able to write a replacement
% to replace these packages have been developed in the \pkg{l3pdffile} package.
% Full replacements for the packages don't exist yet.
%
% \subsection{tagpdf}
% The development code is compatible and will be uploaded in time.
%
% \subsection{ocgx2, animate, media9}
% These package all make use of low-level PDF command and will
% have to be reviewed.
%
% \subsection{acrotex}
% The \pkg{acrotex} makes heavy use of PDF commands and so must be reviewed and
% adapted, including the currently untested route dvips + distiller.
%
% \subsection{fancytooltips}
% This package uses \cs{pdfpageattr} and \pkg{acrotex} and so must be reviewed.
% \end{documentation}
%
%
% \begin{implementation}
%
% \section{Implementation}
%
%    \begin{macrocode}
%<@@=pdf>
%<*package>
\ProvidesExplPackage{pdfmanagement-testphase}{2023-03-09}{0.95x}
  {LaTeX PDF management testphase bundle}
\providecommand\IfFormatAtLeastTF{\@ifl@t@r\fmtversion}
\IfFormatAtLeastTF{2020-10-01}{}{
 \PackageWarning{pdfmanagement-testphase}
   {This~package~needs~LaTeX~2020-10-01~or~newer.
    \MessageBreak Loading~is~aborted.}{}
 \DeclareOption { debug }{}
 \newcommand\DeclareDocumentMetadata[1]{}
 \newcommand\DocumentMetadata[1]{}
 \ProcessOptions\relax
 }
\IfFormatAtLeastTF{2020-10-01}{}{\endinput}

\DeclareOption { debug }
  {
    \msg_redirect_module:nnn { pdf } { none } { warning }
  }

\ProcessOptions\relax
%</package>
%    \end{macrocode}
%
% \subsection{Loading the core files.}
% This loads the core files. The backend should not be loaded
% to allow to set it in the document.
%    \begin{macrocode}
%<*header>
\ProvidesExplFile{pdfmanagement-testphase.ltx}{2023-03-09}{0.95x}
  {PDF~management~code~(testphase)}
%</header>
%<*package>
%\RequirePackage{l3pdfdict}       % needed by l3pdfmanagement
%\RequirePackage{l3pdfmanagement} % loads the core code with the boolean
%\RequirePackage{ltdocinit}       % DocumentMetadata,
%can perhaps be combined or made optional ...
%\RequirePackage{l3pdfannot}
%\RequirePackage{l3pdfxform-beta}
%\RequirePackage{l3pdfmeta}       %
%\RequirePackage{l3pdftools}
%\RequirePackage{l3pdffile}
\IfFileExists{tagpdf-base.sty}
  {\RequirePackage{tagpdf-base}}{}
\input{pdfmanagement-testphase.ltx}
%</package>
%    \end{macrocode}
% \end{implementation}
% \newpage
% \PrintIndex