summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/pdfmanagement-testphase/pdfmanagement-testphase.dtx
blob: 8cee17982e0d0c17f5cc00b575829a46884c32b2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
% \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.95c, released 2021-03-17}
%
% \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.
%
% \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. 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-03-17}{0.95c}
  {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-03-17}{0.95c}
  {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