summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/pdfmanagement-testphase/ltdocinit.dtx
blob: 7688446417cd5df8ab9e648b343e72a2d50a6ce4 (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
% \iffalse meta-comment
%
%% File: ltdocinit.dtx
%
% Copyright (C) 2018-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
%
%    http://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[full]{l3doc}
\usepackage{array,booktabs}
\hypersetup{pdfauthor=The LaTeX Project,pdftitle=ltdocinit (LaTeX PDF management testphase bundle)}

\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \title{^^A
%   The \pkg{ltdocinit} module
% }
%
% \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.96d, released 2023-12-09}
%
% \maketitle
% \begin{documentation}
%
% \section{\pkg{ltdocinit} documentation}
% This small module defined \cs{DocumentMetadata} but the definition  
% has been moved to latex-lab. The documentation can be found in 
% \texttt{documentmetadata-support-doc-.pdf}
%
% \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}.
%
% 
% Here only a few newer keys are defined and the older \cs{DeclareDocumentMetadata}
% is provided.
%
% The module also defines commands to store document properties in a global container.
%
% This module will slowly disappear.
%
% \subsection{\cs{DocumentMetadata}/\cs{DeclareDocumentMetadata}}
%
% \begin{function}{\DeclareDocumentMetadata}
% \begin{syntax}
%  \cs{DeclareDocumentMetadata}\Arg{key-value list} (deprecated)
% \end{syntax}
% This is an older alias for \cs{DocumentMetadata}
% \end{function}
%
% Additionally to the keys described in \texttt{documentmetadata-support-doc-.pdf}
% the following keys/values are implemented
%
% \begin{description}
%
%    \item[\texttt{pdfstandard}] Choice key to set the pdf standard.
%    
%      Starting with version 0.95s it is also possible to use the values
%      |X-4|, |X-4p|, |X-5g|, |X-5n|, |X-5pg|, |X-6|, |X-6n|, |X-6p|, |UA-1|, for
%      a PDF/X and PDF/UA standard. These keys set \emph{only} the relevant
%      XMP-metadata. In version 0.95z support for |UA-2| has been added but
%      note that |UA-2| hasn't been released yet. It should be used only together
%      with pdf version 2.0.
%      
%      Beside this |A-1b|, |A-2a|, |A-2b|, |A-2u|, |A-3a|, |A-3b|, |A-3u| and |A-4|
%      are accepted as values for A-standards. The casing is irrelevant, |a-1b| works too.
%      Note that using these
%      key doesn't mean that the document actually follows the standard. \LaTeX{}
%      can neither ensure nor check all requirements of a standard, and not everything
%      it can do theoretically has already been implemented.
%      For A-standard a color profile is included and the
%      \texttt{/OutputIntent} is set and javascript action in hyperref are suppressed.
%      The |u| variants do not force unicode,
%      but they will pass the information to hyperref. 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}.
%
%      |pdfstandard| can be used more than once to set overlapping standards, e.g:\\
%      |pdfstandard=A-2b,pdfstandard=X-4,pdfstandard=UA-1|
%
%    \item[\texttt{xmp}] A boolean, if set to false no XMP metadata are added to the PDF.
%    The default is true. Details are described in the documentation of \pkg{l3pdfmeta}.
%
%    \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 or when the code is moved into the kernel. New value here are
%     \begin{description}
%    \item[\texttt{new-or-1}] This patches a few commands related
%    to the output routing. They are needed for the tagging
%    of paragraphs, for the tagging of header and footer and 
%    to allow the PDF management to insert code which avoids that
%    links happening at page breaks spills into the header and footer. 
%    This code is also loaded be the following values.
%    \item[\texttt{new-or}] This loads more changes to the output routine required for the 
%    tagging. It is not compatible with every class! The code is also loaded by the 
%    \texttt{phase-II} value.
%    \end{description}
%    The |testphase| key can only be used in the first \cs{DocumentMetadata}.
%
%    \item[\texttt{debug}] This key activates some debug options. It takes a list of key-values
%    as value. Currently the following keys are known:
%     \begin{description}
%     \item[\texttt{para}] with the default and only value |show|. It will activate the |paratagging-show|
%       option of \pkg{tagpdf},
%     \item[\texttt{log}]  with the values as described in the documentation \pkg{tagpdf},
%     \item[\texttt{uncompress}] which does the same as |uncompress| as main key
%     \item[\texttt{pdfmanagement}] a boolean which allows to deactivate the pdfmanagement.
%     This should only be done for debugging! 
%     \item[\texttt{firstaidoff}] This accepts a comma lists of keywords and disables the patches
%       related to them. More information can be found in the documentation of
%       \pkg{pdfmanagement-firstaid}.
%     \item[\texttt{xmp-export}] This will export the XMP-metadata to a file \verb+\jobname.xmpi+.
%     with \texttt{debug=\{xmp-export=filename\}} the file name can be changed. 
%     More information can be found in the documentation of \pkg{l3pdfmeta}.  
%    \end{description}
% \end{description}
%
% \subsection{Container for document properties}
%
% The module provides a container where classes, packages and users can store
% properties of the document which are perhaps of interest
% or use for other packages or the author.
%
% The properties are stored with a key |label/property|. The values can be
% retrieved expandably.
%
% \begin{function}{\AddToDocumentProperties}
% \begin{syntax}
%  \cs{AddToDocumentProperties}\oarg{label}\Arg{property}\Arg{value}
% \end{syntax}
% This stores \meta{value} under the key \meta{label}/\meta{property}.
% By default \meta{label} is the current package name |\@currname|. If another
% label is chosen, it should be one which avoids clashes with other packages
% using the container. The label |document| is reserved.
% \end{function}
%
% \begin{function}[updated=2022-10-09]{\GetDocumentProperties,\pdfmanagement_get_documentproperties:n}
% \begin{syntax}
%  \cs{GetDocumentProperties}\Arg{label/property}\\
%  \cs{pdfmanagement_get_documentproperties:n}\Arg{label/property}
% \end{syntax}
% Expands to the \meta{value} corresponding to \meta{label/property}
% in the container. If \meta{label/property} is missing,
% this has an empty expansion.
% The result is returned within \cs{exp_not:n}, which means
% that the \meta{value} does not expand further
% when appearing in an x-type argument expansion.
% \end{function}
%
% \begin{function}[added=2022-10-09,TF]{\pdfmanagement_get_documentproperties:nN}
% \begin{syntax}
%  \cs{pdfmanagement_get_documentproperties:nNTF}\Arg{label/property} \meta{token list variable}\\
%  ~~~~ \Arg{true code} \Arg{false code}
% \end{syntax}
%   If the \meta{label/property} is not present in the document properties
%   container, leaves the \meta{false code} in the input stream.
%   The value of the
%   \meta{token list variable} is not defined in this case and should
%   not be relied upon.  If the \meta{label/property} is present in the
%   container, stores the corresponding \meta{value} in the
%   \meta{token list variable} without removing it from the
%   container, then leaves the \meta{true code} in the input
%   stream.  The \meta{token list variable} is assigned locally.
% \end{function}
% 
% \begin{function}{\ShowDocumentProperties}
% \begin{syntax}
%  \cs{ShowDocumentProperties}
% \end{syntax}
% This show the current content of the container.
% \end{function}
%
% \begin{thebibliography}{9}
%
% \bibitem{blueprint} Frank Mittelbach and Chris Rowley:
%   \emph{\LaTeX{} Tagged PDF\,---\,A blueprint for a large project}.
%   \url{https://latex-project.org/publications/indexbyyear/2020/}
%
% \end{thebibliography}
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{\pkg{ltdocinit} implementation}
%    \begin{macrocode}
%<@@=pdfmanagement>
%<*header>
\ProvidesExplPackage{ltdocinit}{2023-12-09}{0.96d}
  {Initialize document metadata}
%</header>
%    \end{macrocode}
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
% \subsection{Variables}
% This variable definitions can be remove once latex-lab has been updated to
% provide them too.
%  \begin{variable}{\g_@@_firstaidoff_clist}
%  A list to store the firstaid code which should be disabled
%    \begin{macrocode}
\clist_if_exist:NF \g_@@_firstaidoff_clist
  { \clist_new:N \g_@@_firstaidoff_clist }
%    \end{macrocode} 
% \end{variable}
%  \begin{variable}{\g_@@_testphase_tl}
%  a tl to store the testphase loading code so that we can load them at
%  the end of the command.
%    \begin{macrocode}
\tl_if_exist:NF \g_@@_testphase_tl
 { \tl_new:N \g_@@_testphase_tl }
%    \end{macrocode}
% \end{variable}
% \subsection{\cs{DeclareDocumentMetadata}}
% \cs{DocumentMetadata} is defined by the kernel.
% We only define the older alias \cs{DeclareDocumentMetadata}
%
% \begin{macro}{\DeclareDocumentMetadata}
%    \begin{macrocode}
\NewCommandCopy\DeclareDocumentMetadata\DocumentMetadata
%    \end{macrocode}
% \end{macro}
%
% \subsection{Container for document Properties}
% The container for the document properties is a prop
% \begin{variable}{\g_@@_documentproperties_prop}
%    \begin{macrocode}
\prop_new:N \g_@@_documentproperties_prop %
%    \end{macrocode}
% \end{variable}
% \begin{macro}{\AddToDocumentProperties}
%    \begin{macrocode}
\NewDocumentCommand\AddToDocumentProperties{O{\@currname}mm}
  {
    \exp_args:NNe
      \prop_gput:Nnn \g_@@_documentproperties_prop
        {
          \tl_if_blank:eTF {#1}{top-level/}{#1/} #2
        }
        { #3}
  }
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\GetDocumentProperties}
%    \begin{macrocode}
\NewExpandableDocumentCommand\GetDocumentProperties{m}
  {
    \prop_item:Nn \g_@@_documentproperties_prop {#1}
  }
%    \end{macrocode}
% \end{macro}
% For uses in modules (e.g. l3pdfmeta)
% we provide an expl3 version without the xparse overhead:
%
% \begin{macro}[EXP]{\pdfmanagement_get_documentproperties:n}
%    \begin{macrocode}
\cs_new:Npn\pdfmanagement_get_documentproperties:n #1
  {
    \prop_item:Nn \g_@@_documentproperties_prop {#1}
  }
%    \end{macrocode}
% \end{macro}
% The following allows to retrieve the values with branching.
% \begin{macro}[added=2022-10-09]{\pdfmanagement_get_documentproperties:nNTF}
%    \begin{macrocode}
\prg_new_protected_conditional:Npnn
  \pdfmanagement_get_documentproperties:nN #1#2 { T , F , TF }
    {
     \prop_get:NnNTF \g_@@_documentproperties_prop  {#1} #2
       {
        \prg_return_true:
       }
       {
        \prg_return_false:
       }
    }
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\ShowDocumentProperties}
%    \begin{macrocode}
\msg_new:nnn  { pdfmanagement } { show-properties }
  {
    The~following~document~properties~have~been~stored:
    #1
  }
\NewDocumentCommand\ShowDocumentProperties {}
  {
    \msg_show:nne {pdfmanagement}{show-properties}
      {
        \prop_map_function:NN \g_@@_documentproperties_prop \msg_show_item:nn
      }
  }
%    \end{macrocode}
% \end{macro}
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex