diff options
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.dtx | 429 |
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 |