summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/pdfmanagement-testphase/pdfmanagement-testphase.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/pdfmanagement-testphase/pdfmanagement-testphase.dtx')
-rw-r--r--Master/texmf-dist/source/latex/pdfmanagement-testphase/pdfmanagement-testphase.dtx429
1 files changed, 429 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/pdfmanagement-testphase/pdfmanagement-testphase.dtx b/Master/texmf-dist/source/latex/pdfmanagement-testphase/pdfmanagement-testphase.dtx
new file mode 100644
index 00000000000..4b63544d179
--- /dev/null
+++ b/Master/texmf-dist/source/latex/pdfmanagement-testphase/pdfmanagement-testphase.dtx
@@ -0,0 +1,429 @@
+% \iffalse meta-comment
+%
+%% File: pdfmanagement-testphase.dtx
+%
+% Copyright (C) 2019-2021 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>
+\RequirePackage{pdfmanagement-testphase}
+\DeclareDocumentMetadata{pdfstandard=A-2b}
+\makeatletter
+\declare@file@substitution{doc.sty}{doc-v3beta.sty}
+\makeatother
+\documentclass{l3doc}
+\usepackage{tabularx,array,booktabs,hyperxmp}
+\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.95a, released 2021-02-22}
+%
+% \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
+%
+% \DeclareDocumentMetadata % 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}.
+%
+%
+%
+% \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 already done
+% with the \pkg{l3pdf} package which has now been integrated 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{DeclareDocumentMetadata} 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{DeclareDocumentMetadata}\marg{key-val}.
+% The options of \cs{DeclareDocumentMetadata} are described in the documentation of
+% \pkg{ltdocinit}.
+%
+% \begin{verbatim}
+% \RequirePackage{pdfmanagement-testphase} % load the package
+% \DeclareDocumentMetadata % activates the PDF management interface
+% {
+% %options
+% }
+% \documentclass {...}
+% \end{verbatim}
+%
+% The PDF management can be deactivated either setting the key
+% \texttt{pdfmanagement} to \texttt{false} or by commenting out
+% the whole \cs{DeclareDocumentMetadata} 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{DeclareDocumentMetadata} 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.
+%
+% \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. This
+% makes it incompatible, but adjusting this is even possible with external
+% patches. \pkg{hyperxmp} also relies on some \pkg{hyperref} internals, so
+% changes in \pkg{hyperref} must be coordinated.
+%
+% Some patch code is provided by the bundle and loaded automatically,
+% but it is not complete currently. Failures are e.g. possible with complicated
+% author or title settings. The handling of dates isn't correct either yet.
+% The patch code can be disabled by using |firstaidoff=hyperxmp| in \cs{DeclareDocumentMetadata}
+%
+% \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{pagemanagement} will load the patches automatically.
+% This can be disabled by using |firstaidoff=pgf| in \cs{DeclareDocumentMetadata}
+%
+% \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 |firstaidoff=transparent| in \cs{DeclareDocumentMetadata}
+% \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 |firstaidoff=pdflscape| in \cs{DeclareDocumentMetadata}
+%
+% \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 add 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} {2021-02-22} {0.95a}
+ {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]{}
+ \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}{2021-02-22}{0.95a}
+ {PDF~management~code~(testphase)}
+%</header>
+%<*package>
+%\RequirePackage{l3pdfdict} % needed by l3pdfmanagement
+%\RequirePackage{l3pdfmanagement} % loads the core code with the boolean
+%\RequirePackage{ltdocinit} % DeclareDocumentMetadata,
+%% can perhaps be combined or made optional ...
+%\RequirePackage{l3pdfannot}
+%\RequirePackage{l3pdfxform-beta}
+%\RequirePackage{l3pdfmeta} %
+%\RequirePackage{l3pdftools}
+%\RequirePackage{l3pdffile}
+\input{pdfmanagement-testphase.ltx}
+%</package>
+% \end{macrocode}
+% \end{implementation}
+% \newpage
+% \PrintIndex