-
Notifications
You must be signed in to change notification settings - Fork 8
/
Copy pathl3pdfmanagement.dtx
1667 lines (1622 loc) · 62.2 KB
/
l3pdfmanagement.dtx
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
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
% \iffalse meta-comment
%
%% File: l3pdfmanagement.dtx
%
% Copyright (C) 2018-2024 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{tabularx}
\usepackage{array,booktabs}
\hypersetup{pdfauthor=The LaTeX Project,pdftitle=l3pdfmanagement (LaTeX PDF management testphase bundle)}
\providecommand\potentialclash{\noindent\llap{\dbend\ }}
% Fixing footnotes in functions and variables: this should be in l3doc!
\newcommand\fixfootnote[2]{\footnotemark
\AddToHookNext{env/#1/after}{\footnotetext{#2}}}
\AddToHook{env/function/begin}{\def\footnote{\fixfootnote{function}}}
\AddToHook{env/variable/begin}{\def\footnote{\fixfootnote{variable}}}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \title{^^A
% The \pkg{l3pdfmanagement} module\\ Managing central PDF resources ^^A
% \\\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.96o, released 2024-12-20}
%
% \maketitle
% \begin{documentation}
%
% \section{\pkg{l3pdfmanagement} documentation}
% When creating a pdf a number of objects, dictionaries and entries to
% central \enquote{core} dictionaries must be created.
%
% The commands in this module offer interfaces to this core PDF dictionaries
% They unify a number of primitives like the pdftex
% registers and commands \cs{pdfcatalog}, \cs{pdfpageattr},
% \cs{pdfpagesattr}, \cs{pdfinfo}, \cs{pdfpageresources}
% and similar commands of the other backends in a backend independent way.
%
% The supported backends are pdflatex, lualatex, (x)dvipdfmx (latex, xelatex
% and---starting in texlive 2021--lualatex)
% and dvips with ps2pdf (not completely yet). dvips with distiller could work too
% but is untested.
%
% That the interfaces 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. Some backends create and
% manage resources automatically which must be managed manually by other backends.
%
% The dictionaries and resources handled by this module are inserted only
% once in a PDF or only once per page. Examples are the Catalog dictionary,
% the Info dictionary, the page resources. For these dictionaries and resources
% management by the \LaTeX{} kernel is necessary to avoid
% that packages overwrite settings from
% other packages which would lead to clashes and incompatibilities.
% It is therefore necessary that \emph{all} packages which want to add content to these
% dictionaries and resources use the interface provided by this module.
%
% As these dictionaries and resources are so central for the PDF format values to these
% dictionaries are always added globally. Through the interface values
% can be added (and in many cases also removed) by users and packages,
% but the actually writing of the
% dictionary entries and resources to the PDF is handled by
% the kernel code.
%
% The interface uses as main name to address the resources \emph{Paths}
% which follow the names and structure described in the PDF reference. This
% should make it easy to identify the names needed to insert a specific
% PDF resources with the new interfaces.
% All \emph{Paths} have names starting with an uppercase letter.
%
% The following tabular summarize the \emph{Paths} and which pdftex primitive they
% replace:
%
% \begin{tabular}{ll}
% Info & \cs{pdfinfo} \\
% Catalog \& various subdictionaries & \cs{pdfcatalog} \\
% Pages & \cs{pdfpagesattr} \\
% Page, ThisPage & \cs{pdfpageattr} \\
% Page/Resources/ExtGState & \cs{pdfpageresources} \\
% Page/Resources/Shading & \cs{pdfpageresources} \\
% Page/Resources/Pattern & \cs{pdfpageresources} \\
% Page/Resources/ColorSpace & \cs{pdfpageresources} \\%
% \end{tabular}
%
% There is no \texttt{Page/Resources/Properties} dictionary in the list,
% because this dictionary is not filled directly, but
% managed through side effects when setting BDC-marks.
%
% \subsection{User Commands}
% To avoid problems with older documents the resource management of this
% module is not activated unconditionally. The values are pushed out to the
% dictionaries only if a boolean has been set to true. The state can be tested
% with a conditional.
% \begin{function}[EXP,pTF,added=2020-07-04]
% {\pdfmanagement_if_active:}
% This conditional tests if the resource management code is active.
% \end{function}
% \begin{function}[added=2021-07-23]
% {\IfPDFManagementActiveTF}
% This is a LaTeX2e version of the conditional
% \end{function}
% \begin{function}[added = 2020-04-06,updated=2021-07-23]
% {\pdfmanagement_add:nnn,\pdfmanagement_add:nne,\pdfmanagement_add:nee,\pdfmanagement_add:eee,
% \PDFManagementAdd}
% \begin{syntax}
% \cs{pdfmanagement_add:nnn} \Arg{resource path} \Arg{name} \Arg{value}
% \end{syntax}
% This function puts \Arg{name} \Arg{value} in the PDF resource described by
% the symbolic name \Arg{resource path}. Technically it stores it globally in an internal
% property lists and writes it later into the right PDF dictionary\footnote{Currently all
% resources are PDF dictionaries, so resource and dictionary mean the same.}
% Which values for \Arg{resource path} exist is described in the following.
% \Arg{name} should be a PDF Name without the starting slash. Like with all
% keys used in PDF dictionaries (see the l3pdfdict module) the name is escaped
% with \cs{str_convert_pdfname:n} when stored.
% \Arg{value} should be a valid PDF value for this Name in the
% target dictionary. |\PDFManagementAdd| is a copy of |\pdfmanagement_add:eee|
% and so expands all its arguments.
%
%
% The code works with all major engines but not necessarily
% in the same way. Most importantly
% \begin{itemize}
% \item The expansion behaviour of the backends can differ. Some backends expand a
% value always fully when writing to the PDF, with other backends command names
% could end as strings in the PDF. So one should neither rely on \Arg{name}
% \Arg{value} to be expanded nor not expanded by the backend commands.
% \item The number of compilations needed can differ between the engines and
% backends. Some engines have to use labels and the aux-file to setup
% the dictionaries and so need at least two compilations to put everything
% in place.
% \item dvips doesn't support everything. It is for example not possible
% to add manually or through side effects
% a name tree like /AP or /JavaScript, pdfmark doesn't provide a handler
% here---at least I didn't find anything suitable.
% \end{itemize}
% \end{function}
%
% \begin{function}[added = 2020-04-08]
% {\pdfmanagement_show:n }
% \begin{syntax}
% \cs{pdfmanagement_show:n} \Arg{resource path}
% \end{syntax}
% This shows the content of the dictionary targeted by
% \Arg{resource path} in the log and on the terminal if possible.
%
% It is not reliable for page resources as these are filled at shipout.
%
% It also doesn't show necessarily all the content.
% For example most backends add automatically
% entries to the Info dictionary.
% \end{function}
%
% \begin{function}[added = 2020-04-07]
% {
% \pdfmanagement_remove:nn,
% }
% \begin{syntax}
% \cs{pdfmanagement_remove:nn} \Arg{resource path} \Arg{name}
% \end{syntax}
% Removes |/|\meta{name} and its associated \meta{value} from the
% dictionary described with \Arg{resource path}
% The removal is global.
% If \meta{name} is not found no change occurs,
% \emph{i.e}~there is no need to test for the existence of a name before
% trying to remove it.
% Values from the special Catalog entries where the values are collected in arrays
% can't be removed (but should ever a use case appear it could be added).
% \end{function}
%
% \subsection{Description of the resource paths}
% \subsubsection{Info: The Info dictionary}
% \begin{NOTE}{UF}
% path: Info
% The info dictionary is filled by e.g. \cs{pdfinfo}. Multiple appearances of
% \cs{pdfinfo} are concatenated, so one could end with multiple /Title or /Author entries.
% It is then viewer dependent which one is showed, so it is better to avoid this.
% We therefore setup a property which is filled and written to the info
% directory in one go. According to hyperref a few odd drivers (hvtex, dvipsone, dviwind)
% don't support arbitrary keys, but this should be handle elsewhere.
% As entries with empty content
% should be omitted we add a test. The string command should perhaps escape the argument,
% but for now we are assuming that the argument is pdf safe.
% hyperref writes to the info dictionary at the shipout of the first page --
% probably to catch the case that \cs{title} is issued after the begin of the document.
% We are outputting at the last page -- this needs a second compilation but
% this is needed anyway.
% \end{NOTE}
% \potentialclash If the primitive commands of the engines are used too there will
% be double entries in the pdf (at least with the backend pdftex and luatex).
% How pdf viewer handles this is unpredictable.
%
% \begin{function}
% {
% pdfmanagement: Info
% }
% \begin{syntax}
% \cs{pdfmanagement_add:nnn} \{Info\} \Arg{name} \Arg{value}
% \end{syntax}
% Adds |/|\meta{name} and the \meta{value} to the Info dictionary.
% \meta{name} should be a PDF name without the leading slash,
% Like with all
% keys used in PDF dictionaries (see the l3pdfdict module) the name is escaped
% with \cs{str_convert_pdfname:n} when stored.
% \meta{value} should be a valid pdf value. Any escaping or (re)encoding must be
% done explicitly.
% If a \meta{name} is used twice, only the last \meta{value}
% set will be used. The Info dictionary is written at the end of the compilation,
% so values can be set at any time.
% The Info dictionary expects utf16be in the strings, so a conversion like this is
% normally sensible:
% \begin{verbatim}
% \str_set_convert:Nnnn \l_tmpa_str { Grüße }{ default } {utf16/string}
% \pdfmanagement_add:nne {Info} {Title}{(\l_tmpa_str)}
% \end{verbatim}
% \end{function}
%
% The entries in Info dictionary are rather special as the engines/backends adds some
% core entries, and changing or removing these entries is not always possible.
%
% The special entries are
% \begin{description}
% \item[Producer] Added by all engines and backends. Removing the entry is only possible
% with luatex with |\pdfvariable suppressoptionalinfo 128|. Changing is possible
% with \cs{pdfmanagement_add:nnn} with the exception of dvips/pstopdf where the entry is
% always something like |GPL Ghostscript 9.53.3|.
% \item[Creator] Added by all engines and backends. Removal only possible in luatex by adding
% 16 to the bitset. Changing is possible with the management command.
% \item[CreationDate] Added by all engines and backends. With the exception of |dvips/ps2pdf|
% |SOURCE_DATE_EPOCH| is honored. With pdftex it is possible to suppress it with
% |\pdfinfoomitdate = 1|, and in luatex by adding 32 to the bitset.
% Changing is possible with the management command and will overwrite an epoch setting.
% \item[ModDate] Added by all engines and backends with the exception of xdvipdfmx.
% With the exception of |dvips/ps2pdf| |SOURCE_DATE_EPOCH| is honored.
% Suppressing it is possible in pdftex with
% |\pdfinfoomitdate = 1|, and in luatex by adding 64 to the bitset. Changing is possible with
% the management command.
% \item[Trapped] Added by pdftex and luatex. Removal only possible in
% luatex by adding 256 to the bitset. Changing (and adding in the other backends) is
% possible with the management command.
% \item[PTEX.Fullbanner] Added by pdftex and luatex. Removal possible in pdftex with
% |\pdfsuppressptexinfo-1|, in luatex by adding 512 to the bitset.
% Changing is not possible.
% \item[Title] Added by dvips/ps2pdf and set to |filename.dvi|. Removal is probably
% not possible, but it can be overwritten with the management command.%
% \end{description}
% \subsubsection{Pages: The \enquote{Pages} dictionary}
% \potentialclash As the content of this dictionary is written at the end it will
% in pdftex and luatex overwrite values added with the primitive commands (e.g.
% \cs{pdfpagesattr}.
% Package authors should use the management commands instead.
% By using this path with the pdfmanagement interface,
% values can be added to the /Pages object.
% This replaces for example \cs{pdfpagesattr}.
%
% \begin{function}{pdfmanagement: Pages}
% \begin{syntax}
% \cs{pdfmanagement_add:nnn} \{Pages\} \Arg{name} \Arg{value}
% \end{syntax}
%
% Adds |/|\meta{name} \meta{value} to the |/Pages| dictionary.
% It is always stored globally. The content is written to the pdf
% at the end of the compilation, so values can be added, changed or
% removed until then.
% \meta{name} should be a valid pdf name without the leading slash,
% \meta{value} should be a valid pdf value. Any escaping or (re)encoding must
% be done explicitly. Some backends expand the value but this should not be
% relied on. If a \meta{name} is used twice, only the last \meta{value}
% set will be used.
%
% \end{function}
%
% \subsubsection{\enquote{Page} and \enquote{ThisPage}}
% \begin{NOTE}{UF}
% Open is the question if one need a command to set attribute on a page by page number.
% Open is the setter for /AF (and perhaps /OutputIntents).
% See also https://tex.stackexchange.com/questions/479812/extension-of-rotating-package-to-set-pdf-rotation
% (should work now)
% \end{NOTE}
% \begin{function}[added = 2020-04-12]
% {pdfmanagement: Page}
% \begin{syntax}
% \cs{pdfmanagement_add:nnn} \{Page\} \Arg{name} \Arg{value}
% \end{syntax}
% Values added with the path \texttt{Page} are added to the page dictionary
% of the current page and the following pages. The current page means the page
% on which the command is \emph{executed}. \meta{name} should be a valid pdf name
% without the leading slash. Typical names used here are e.g.
% \texttt{Rotate} and \texttt{CropBox}.
% \meta{value} should be a valid pdf value.
% Any escaping or (re)encoding must be done explicitly. Some backends expand the
% value but this should not be relied on.
% To avoid problems with the asynchronous page breaking
% the command should be used after \cs{newpage} or in the header.
% It should not be used in a float, as it will then quite probably be executed
% on the wrong page.
% The value is assigned directly and is always stored globally.
% If a \meta{name} is used twice, only the last \meta{value}
% set will be used. Names set with \cs{pdfmanagement_add:nnn}|{ThisPage}| will overwrite
% names set with \cs{pdfmanagement_add:nnn}|{Page}| if there is a clash.
% Values can be removed again with \cs{pdfmanagement_remove:nn}.
% This replaces \cs{pdfpageattr}.
% \end{function}
% \begin{function}[added = 2020-04-12]
% { pdfmanagement: ThisPage}
% \begin{syntax}
% \cs{pdfmanagement_add:nnn} \{ThisPage\} \Arg{name} \Arg{value}
% \end{syntax}
% Adds |/|\meta{name} \meta{value} at \emph{shipout} to the page dictionary of the
% current page. Current page means here the \emph{shipout} page. \emph{shipout} means
% at the end of the \texttt{shipout/background} hook. Code that wants to set a value
% in a shipout hook should use the \texttt{shipout/background} hook too. Other hooks
% are either too early or too late.%
% It is always stored globally.
% If \Arg{name} has already a value set in the \texttt{Page}
% dictionary it will be overwritten for this page.
% \meta{name} should be a valid pdf name without the leading slash,
% \meta{value} should be a valid pdf value. Any escaping or (re)encoding must be
% done explicitly. If a \meta{name} is used twice, only the last \meta{value}
% set will be used.
% With the engine pdflatex (at least) a second compilation is needed.
% Values added to \texttt{ThisPage} can not be removed. It is not possible to
% show the content of this dictionary with \cs{pdfmanagement_show:n}.
% \end{function}
%
% \paragraph{Changing the \texttt{/MediaBox}}: It is possible to change
% the \texttt{/MediaBox} of one or more pages by setting it for the \texttt{Page}
% or \texttt{ThisPage} path (using \texttt{Pages} doesn't work, the engines
% overwrite this)---this works even with dvips and allows to create
% pages of different sizes. But you must be careful with the values.
% If you set e.g. with pdflatex \cs{pdfpageheight} to 300bp you get a mediabox of
% |0 0 595 300|, but pdflatex measure from the top and will also move
% the reference point up, so effectively
% you get the \emph{upper} third of the page. If you set the \texttt{/MediaBox}
% to |0 0 595 300| with \cs{pdfmanagement_add:nnn} you get the \emph{lower} third.
% In general it is better to use only the primitive commands to avoid confusing
% results.
%
% \subsubsection{\enquote{Page/Resources}: ExtGState, ColorSpace, Shading, Pattern}
% \begin{NOTE}{UF}
% Only for pdf/luatex and xdvipdfmx backend- and pdf-code is needed to add values
% to these resources.
% With dvips the resources are added through high-level code (e.g. transparency), so the
% backend/pdf commands are no-ops.
% For every resources there is only one object. References to these objects are added to
% all pages starting from the page where the first time something has been added to the
% resource and to all XObjects. For luatex and pdftex it must be done together
% with the /Properties, see above.
% I don't see a need to set e.g. /ColorSpace page wise: preflight handles this
% fine, see experiment colorspace-resources.
% As pgf does the same, there is a need to patch it for now. Ditto for package colorspace.
% \end{NOTE}
% \begin{function}[updated = 2020-04-10]
% {
% pdfmanagement: Page/Resources/ExtGState,
% pdfmanagement: Page/Resources/ColorSpace,
% pdfmanagement: Page/Resources/Shading,
% pdfmanagement: Page/Resources/Pattern,
% }
% \begin{syntax}
% \cs{pdfmanagement_add:nnn} \{Page/Resources/\meta{resource}\} \Arg{name} \Arg{value}
% \end{syntax}
% Adds |/|\meta{name} \meta{value} to the page resource \meta{resource}.
% \meta{resource} can be |ExtGState|, |ColorSpace|, |Pattern| or |Shading|.
% The values are always stored globally. The content is written to the pdf
% at the end of the compilation, so values can be added until then.
% \meta{name} should be a valid pdf name without the leading slash,
% \meta{value} should be a valid pdf value for the resource.
% Any escaping or (re)encoding must be done explicitly. If a \meta{name} is
% used twice, only the last \meta{value} set will be used.
%
% With the dvips backend the command does nothing: these resources are managed by
% ghostscript or the distiller if e.\,g. transparency is used.
%
% The resources are added to all pages starting with the first where something has
% been added to a resources. That means that for example
% all ExtGState resources are combined in one
% dictionary object and every page with a ExtGState resource refer to this object%
% \footnote{This is similar to how pgf handles this resources}.
%
% \potentialclash The primitive commands (e.g. \cs{pdfpageresources})
% to set the resources should not be used
% together with this code as the calls will overwrite each other and values
% will be lost. This means that currently there are clashes with the packages tikz,
% transparent and colorspace.
% \end{function}
% \subsubsection{\enquote{Catalog} \& subdirectories}
% \begin{NOTE}{UF}
% Perhaps some tools to create the AF-file specification dictionaries is useful.
% Open for now:
% /Extensions (dict, pdf 2.0)
% /Dests ? difference to subdict in Names?
% /DSS (dict, pdf 2.0)
% /Acroform/DR/ExtGState etc probably unneeded.
% \end{NOTE}
% The catalog is a central dictionary in a PDF with a number of subdictionaries.
% Entries to the top level of the catalog can be added with\\
% |\pdfmanagement_add:nnn {Catalog}|\Arg{Name}\Arg{Value}.
% Entries to subdictionaries by using in the first
% argument one of the paths described later.
% The entries in the catalog have varying requirements regarding the
% PDF management. Some entries (like \texttt{/Lang}) are simple values
% where new values should
% overwrite existing values, other like for example \texttt{/OutputIntents}
% can contain a number of values and can be filled from more than one source.
% In some cases the values that needs to be added are not at the top-level
% but in some subsubdictionary or are actually part of an array.
% To handle the pdf management uses a variety of internal, special handlers.
%
% \potentialclash In some cases entries are added implicitly.
% For example entries to the name
% tree of the \texttt{/EmbeddedFiles} key in the \texttt{/Names} directory are
% added with the commands of the \texttt{l3pdffile} module. This clashes with
% e.g. the embedfile package which should not be used!
%
%
% \paragraph{Entries at the top level of the catalog}
% The Names in the following tabular are entries that are added to the
% top level of the catalog.
%
% If \meta{Name} gets assigned a value more than once the last one wins.
% There is no check that the values have the correct type and format.
% It is up to the user to ensure that the value does what is intended.
%
% The required PDF version is only mentioned if it is larger than 1.5.
%
% Example: |\pdfmanagement_add:nnn {Catalog}{PageMode}{/UseNone}|
%
% \medskip
% \noindent
% \begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X}
% \bfseries Name & \bfseries Value & \bfseries Remark \\\midrule
% Collection & objref or dict & the content should be
% build by external packages (see eg embedfile) \\
% DPartRoot & objref or dict & PDF 2.0 \\
% Lang & string & e.g. \texttt{(de-DE)} \\
% Legal & objref or dict \\
% Metadata & objref or stream \\
% NeedsRendering & boolean & PDF 1.7\\
% OpenAction & array (dest) or dict (action) \\
% PageLabels & objref or dict & number tree \\
% PageLayout & name & one of /SinglePage, /OneColumn,
% /TwoColumnLeft, /TwoColumnRight,
% /TwoPageLeft,
% /TwoPageRight \\
% PageMode & name & one of /UseNone, /UseOutlines, /UseThumbs,
% /UseOC, /UseAttachments (PDF 1.6)\\
% Perms & objref or dict & permissions\\
% PieceInfo & objref or dict \\
% SpiderInfo & objref or dict \\
% StructTreeRoot & objref or dict \\
% Threads & objref to an array\\
% URI & objref or dict \\
% Version & name & eg. \texttt{/1.7} \\
% \meta{unknown} & & an unknown \meta{name} will be
% inserted without a warning.\\
% \end{tabularx}
% \par\medskip
%
% \paragraph{Simple entries in subdictionaries of the catalog}
% The following resource paths have been predeclared and allow to
% add values to the respective subdictionaries of the catalog. The
% names of the dictionaries follow the naming and location of the dictionaries
% in the PDF reference.
% If \meta{Name} gets assigned two values the last one wins.
%
% Example: |\pdfmanagement_add:nnn {Catalog/MarkInfo}{Marked}{true}|
%
% \medskip
% \noindent
% \begin{tabularx}{\linewidth}{lll>{\raggedright\arraybackslash}X}
% \bfseries Path/dictionary & \bfseries Names & \bfseries Value & \bfseries Remark
% \\\midrule
% Catalog/AA &WC, WS, DS, WP,DP& all dict \\
% Catalog/AcroForm & NeedAppearances& boolean & In pdf 2.0
% NeedAppearances
% is deprecated,
% it is then required
% that every widget has
% an appearance streams.\\
% & SigFlags & Integer\\
% & DA & String \\
% & Q & Integer\\
% & XFA & stream or array & pdf 1.5\\
% Catalog/AcroForm/DR & \meta{name} & & probably unneeded \\
% Catalog/AcroForm/DR/Font & \meta{name} & dict & \\
% Catalog/MarkInfo & Marked & boolean \\
% & UserProperties & boolean \\
% & Suspects & boolean \\
% Catalog/ViewerPreferences & HideToolbar & boolean \\
% & Direction & /R2L or /L2R \\
% & \ldots & & many more, see the reference \\
% \end{tabularx}
%
%
% \paragraph{Catalog entries with multiple values in arrays}
% The following entries are special: Their values are arrays and
% it must be possible to append to such arrays. This means that a new
% call to set this value doesn't replace the value but appends it.
% The value is an object reference. It is sensible to declare the object
% first. E.g.
% \begin{verbatim}
% \pdf_object_new:n {module/intent}
% \pdf_object_write:nnn {module/intent}{dict}{...}
% \pdfmanagement_add:nne {Catalog} {OutputIntents}{\pdf_object_ref:n {module/intent}}
% \end{verbatim}
%
% or
% \begin{verbatim}
% \pdf_object_unnamed_write:nn {dict} { ... }
% \pdfmanagement_add:nne {Catalog} {OutputIntents}{\pdf_object_ref_last:}
% \end{verbatim}
%
%
% \medskip
% \noindent
% \begin{tabularx}{\linewidth}{lll>{\raggedright\arraybackslash}X}
% \bfseries Path/dictionary &\bfseries Name & \bfseries Value & \bfseries Remark \\\midrule
% Catalog/AcroForm & Fields & object reference\\
% Catalog/AcroForm & CO & object reference\\
% Catalog & AF & object reference & PDF 2.0, associated files\\
% Catalog/OCProperties & OCGs & object reference &if there are OCProperties, OCGs and D are required.\\
% Catalog/OCProperties & Configs & object reference \\
% Catalog/OCProperties & D & object reference & This is actually a single value as
% there can be only one default.
% If the value is set twice, the
% second wins, and the first is
% added to OCProperties/Configs.\\
% Catalog & OutputIntents & object reference\\
% Catalog & Requirements & object reference & PDF 1.7 \\
% Catalog/Names & EmbeddedFiles & object reference & This should reference a filespec dictionary. It will
% attach the file to the file panel.
% \end{tabularx}
%
% \paragraph{Catalog entries for name trees}
%
% \emph{Not supported in the dvips backend, pdfmark doesn't have an interface here}.
%
% In various places the PDF format allows to reference objects by name instead
% of by object reference. The relationship between a name and the object reference
% are store in so-called \emph{name trees}, which are stored in the
% Catalog/Names dictionary. The |/Dests| and the |/EmbeddedFiles| name trees are
% handled implicitly if destinations or files are added. Names to the other
% name trees can be added with |\pdfmanagement_add:nnn|, e.g. to add an value to
% the AP names (for appearance streams) use
%
% \begin{verbatim}
% \pdfmanagement_add:nne { Catalog / Names / AP } {myAPname} {\pdf_object_ref_last:}
% \end{verbatim}
%
% Remarks:
% \begin{itemize}
% \item The name |myAPname| is processed through |\pdf_string_from_unicode:nnN{utf8/string}|
% and parentheses are added automatically. Ensure that the use of the name
% handles it in the same way.
% \item It is currently not possible to test if a name has already been used
% by another package or previous code,
% so use names where you can be confident that they are unique.
% (It would be possible to split up the first part and test, but it would slow
% down the compilation and I'm not sure if it is worth the trouble)
% \item The value is not preprocessed, it is up-to-you to ensure that it does the
% right thing.
% \item Currently the structure of the name tree is flat, it doesn't use
% Kids. But this can be changed if the need arise.
% \end{itemize}
%
% The following name trees can be filled with this method. Currently only the
% first three are activated. For the first, |EmbeddedFiles| there are two methods
% to add a value:\\
% |\pdfmanagement_add:nnn{Catalog/Names/EmbeddedFiles}{name}{reference}|
% and
% |\pdfmanagement_add:nnn{Catalog/Names}{EmbeddedFiles}{reference}|.
% This is intended, the second methods creates a name on the fly (with the prefix l3ef)
%
% \medskip
% \noindent
% \begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X}
% Catalog/Names/EmbeddedFiles & A name tree mapping name strings to file
% specifications for embedded file streams. The value should be a reference to a filespec
% dictionary\\
% Catalog/Names/AP & A name tree mapping name strings to annotation appearance streams\\
% Catalog/Names/JavaScript & A name tree mapping name strings to documentlevel ECMAScript actions\\
% (inactive) Catalog/Names/Pages & A name tree mapping name strings to visible pages for use in interactive forms\\
% (inactive) Catalog/Names/Templates & A name tree mapping name strings to invisible pages for use in interactive forms\\
% (inactive) Catalog/Names/IDS & A name tree mapping digital identifiers to Web.Capture content sets\\
% (inactive) Catalog/Names/URLS & A name tree mapping name strings to documentlevel ECMAScript actions\\
% (inactive) Catalog/Names/Renditions & A name tree mapping name strings (which shall have Unicode encoding) to rendition objects
% (it is not quite clear yet, what unicode encoding means here. Perhaps this string will need special handling)\\
% \end{tabularx}
% \end{documentation}
%
% \begin{implementation}
% \section{\pkg{l3pdfmanagement} implementation}
% \begin{macrocode}
%<@@=pdfmanagement>
%<*header>
%
\ProvidesExplPackage{l3pdfmanagement}{2024-12-20}{0.96o}
{Management of core PDF dictionaries (LaTeX PDF management testphase bundle)}
%</header>
% \end{macrocode}
% \subsection{Messages}
% \begin{macrocode}
%<*package>
\msg_new:nnn { pdfmanagement } { unknown-dict }
{ The~PDF~management~resource~'#1'~is~unknown. }
\msg_new:nnn { pdfmanagement } { empty-value }
{ The~value~for~#1~is~empty~and~will~be~ignored }
\msg_new:nnn { pdfmanagement } { no-removal }
{ It~is~not~possible~to~remove~values~from~'#1'.}
\msg_new:nnn { pdfmanagement } { no-show }
{ It~is~not~possible~to~show~the~content~of~'#1'.}
\msg_new:nnn { pdfmanagement } { name-exist }
{ The~name~'#1'~has~already~been~used~for~name~tree~'#2'.}
\msg_new:nnn { pdfmanagement } { show-dict }
{
The~PDF~resource~'#1'~
\tl_if_empty:nTF {#2}
{ is~empty \\>~ . }
{ contains~the~pairs~(without~outer~braces): #2 . }
}
\msg_new:nnn { pdfmanagement } { dict-already-defined }
{
The~path~'#1'~is~already~defined.
}
\msg_new:nnn { pdfmanagement } { inactive }
{
The~PDF~resources~management~is~not~active\\
command~'#1'~ignored.
}
% \end{macrocode}
%
% \begin{variable}{\l_@@_tmpa_tl,\l_@@_tmpb_tl,\l_@@_tmpa_seq}
% Some temp variables
% \begin{macrocode}
\tl_new:N \l_@@_tmpa_tl
\tl_new:N \l_@@_tmpb_tl
\seq_new:N \l_@@_tmpa_seq
% \end{macrocode}
% \end{variable}
% \begin{variable}{\g_@@_active_bool}
% This boolean will control the activation of the management code.
% It is used in the hooks, and in some backend files.
% % \cs{DocumentMetadata} should set it to true
% \begin{macrocode}
\bool_new:N \g_@@_active_bool
% \end{macrocode}
% \end{variable}
% A user predicate to test if the management code is active
% \begin{macrocode}
\prg_new_conditional:Npnn \@@_if_active: { p , T , F , TF }
{
\bool_if:NTF \g_@@_active_bool
{ \prg_return_true: }
{ \prg_return_false: }
}
\prg_set_eq_conditional:NNn
\pdfmanagement_if_active: \@@_if_active: { p , T , F , TF }
\cs_set_eq:NN \IfPDFManagementActiveTF\pdfmanagement_if_active:TF
% \end{macrocode}
% We use a hook, to collect value added before the backend is ready.
% \begin{macrocode}
\hook_new:n {pdfmanagement/add}
\cs_new_protected:Npn \pdfmanagement_add:nnn #1 #2 #3
{
\@@_if_active:TF
{
\pdfdict_if_exist:nTF { g__pdf_Core/#1 }
{
\hook_gput_code:nnn
{pdfmanagement/add}
{pdfmanagement}
{
\@@_handler_gput:nnn { #1 }{ #2 }{ #3 }
}
}
{
\msg_error:nnn{pdfmanagement}{unknown-dict}{#1}
}
}
{
\msg_warning:nne {pdfmanagement}{inactive}
{\tl_to_str:n {\pdfmanagement_add:nnn}}
}
}
\cs_generate_variant:Nn \pdfmanagement_add:nnn {nne,nee,eee,nnx,nxx,xxx}
\cs_set_eq:NN \PDFManagementAdd \pdfmanagement_add:eee
% \end{macrocode}
% \subsection{Hooks -- shipout and end of run code}
% Code is executed in three places: At shipout of every page,
% at shipout of the last page, at the end of the document
% (after the last clearpage). Due to backend differences the code in the
% three places (and the exact timing) can be different: pdflatex/lualatex
% can execute code after the last \cs{clearpage} which the dvi-based
% drivers have to add on a shipout page.
%
% \begin{variable}
% {
% \g__kernel_pdfmanagement_thispage_shipout_code_tl
% \g__kernel_pdfmanagement_lastpage_shipout_code_tl
% \g__kernel_pdfmanagement_end_run_code_tl
% }
% This variables contain the code run in the three places.
% \begin{macrocode}
\tl_new:N \g__kernel_pdfmanagement_thispage_shipout_code_tl
\tl_new:N \g__kernel_pdfmanagement_lastpage_shipout_code_tl
\tl_new:N \g__kernel_pdfmanagement_end_run_code_tl
% \end{macrocode}
% \end{variable}
% \begin{macrocode}
\tl_gset:Nn \g__kernel_pdfmanagement_thispage_shipout_code_tl
{
\bool_if:NT \g_@@_active_bool
{
\exp_args:NV \__pdf_backend_ThisPage_gpush:n { \g_shipout_readonly_int }
\exp_args:NV \__pdf_backend_PageResources_gpush:n { \g_shipout_readonly_int }
}
}
\tl_gset:Nn \g__kernel_pdfmanagement_end_run_code_tl
{
\bool_if:NT \g_@@_active_bool
{
\__pdf_backend_PageResources_obj_gpush: %ExtGState etc
\@@_Pages_gpush: %pagesattr
\@@_Info_gpush: %pdfinfo
\@@_Catalog_gpush:
}
}
% \end{macrocode}
% \subsection{Naming convention}
% Currently the following names are used: ^^A!!!!! check, compare with g_@@_gnames_seq
% All have internally additionally a \texttt{Core} before the slash, to
% hide the real name a bit.
% \begin{verbatim}
% /Info % (\pdfinfo)
% /Catalog % (\pdfcatalog)
% /Catalog/AA %
% /Catalog/AcroForm
% /Catalog/OCProperties
% /Catalog/OutputIntents
% /Catalog/AcroForm/DR
% /Catalog/AcroForm/DR/Font
% /Catalog/MarkInfo
% /Catalog/ViewerPreferences
% /Pages % (\pagesattr)
% /Page % (\pageattr)
% /ThisPage % (\pageattr)
% /backend_PageN/Resources/Properties % this is only internal.
% /Page/Resources/ExtGState
% /Page/Resources/ColorSpace
% /Page/Resources/Pattern
% /Page/Resources/Shading
% /Page/Resources/Properties
% /Xform/Resources/Properties
% \end{verbatim}
% \begin{macro}{
% \@@_handler_gput:nnn,
% \@@_get:nnN,
% \@@_gremove:nn,
% \@@_show:n
% }
% \cs{@@_handler_gput:nnn} is the main command to fill the dictionaries.
% In simple cases it directly fill the property list, but if a handler exists
% this is called. It is important to use it only in places where this make sense.
%
% \begin{macrocode}
%global
\cs_new_protected:Npn \@@_handler_gput:nnn #1 #2 #3 %#1 dict, #2 name, #3 value
{
\tl_if_empty:nTF { #3 }
{
\msg_none:nnn { pdfmanagement }{ empty-value }{ /#1/#2 }
}
{
\pdfdict_if_exist:nTF { g__pdf_Core/#1 }
{
\cs_if_exist:cTF
{ @@_handler/#1/?_gput:nn } %general, name independent handler
{ \use:c {@@_handler/#1/?_gput:nn} {#2} {#3} }
{
\cs_if_exist:cTF
{ @@_handler/#1/#2_gput:n }
{ \use:c {@@_handler/#1/#2_gput:n} {#3} } %special handler
{
\exp_args:Nne
\prop_gput:cnn
{ \__kernel_pdfdict_name:n { g__pdf_Core/#1 } }
{ \str_convert_pdfname:n { #2 } }
{ #3 }
}
}
}
{
\msg_error:nnn { pdfmanagement } { unknown-dict } { #1 }
}
}
}
\cs_generate_variant:Nn \@@_handler_gput:nnn {nee}
\cs_new_protected:Npn \@@_get:nnN #1 #2 #3 %path,key,macro
{
\exp_args:Nne
\prop_get:cnN
{ \__kernel_pdfdict_name:n { g__pdf_Core/#1 } }
{ \str_convert_pdfname:n {#2} } #3
}
\cs_new_protected:Npn \@@_handler_gremove:nn #1 #2 %path,key
{
\pdfdict_if_exist:nTF { g__pdf_Core/#1 }
{
\cs_if_exist:cTF
{ @@_handler/#1/?_gremove:n } %general, name independent handler
{ \use:c {@@_handler/#1/?_gremove:n} {#2} }
{
\cs_if_exist:cTF
{ @@_handler/#1/#2_gremove: }
{ \use:c {@@_handler/#1/#2_gremove:} } %special handler
{
\exp_args:Nne
\prop_gremove:cn
{ \__kernel_pdfdict_name:n { g__pdf_Core/#1 } }
{ \str_convert_pdfname:n {#2} }
}
}
}
{
\msg_error:nnn { pdfmanagement } { unknown-dict } { #1 }
}
}
\cs_new_protected:Npn \@@_gremove:nn #1 #2 %path,key
{
\pdfdict_if_exist:nTF { g__pdf_Core/#1 }
{
\exp_args:Nne
\prop_gremove:cn
{ \__kernel_pdfdict_name:n { g__pdf_Core/#1 } }
{ \str_convert_pdfname:n{#2} }
}
{
\msg_error:nnn { pdfmanagement } { unknown-dict } { #1 }
}
}
\cs_new_protected:Npn \@@_show:Nn #1#2
{
\cs_if_exist:cTF
{ @@_handler/#2/?_show: } %general, name independent handler
{ \use:c {@@_handler/#2/?_show:} }
{
\prop_if_exist:cTF { \__kernel_pdfdict_name:n { g__pdf_Core/#2 } }
{
#1
{ pdfmanagement } { show-dict }
{ \tl_to_str:n {#2} }
{
\prop_map_function:cN
{\__kernel_pdfdict_name:n { g__pdf_Core/#2 }}
\msg_show_item:nn
}
{ } { }
}
{
#1 { pdfmanagement } { unknown-dict } {#2}{}{}{}
}
}
}
\cs_new_protected:Npn \@@_show:n #1 %path
{
\prop_show:c { \__kernel_pdfdict_name:n { g__pdf_Core/#1 } }
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macrocode}
\cs_new_protected:Npn \pdfmanagement_show:n #1
{
\@@_show:Nn \msg_show:nneeee {#1}
}
% \end{macrocode}
% \begin{macrocode}
\cs_new_protected:Npn \pdfmanagement_remove:nn #1 #2
{
\pdfdict_if_exist:nTF { g__pdf_Core/#1 }
{
\@@_handler_gremove:nn { #1 }{ #2 }
}
{
\msg_error:nnn{pdfmanagement}{unknown-dict}{#1}
}
}
% \end{macrocode}
% \begin{macrocode}
\cs_new_protected:Npn \pdfmanagement_get:nnN #1 #2 #3
{
\pdfdict_if_exist:nTF { g__pdf_Core/#1 }
{
\@@_get:nnN { #1 }{ #2 } #3
}
{
\msg_error:nnn{pdfmanagement}{unknown-dict}{#1}
}
}
% \end{macrocode}
% \subsection{The Info dictionary}
% Initialization of the dictionary:
% \begin{macrocode}
\pdfdict_new:n { g__pdf_Core/Info}
% \end{macrocode}
%
% \begin{macro}{\@@_Info_gpush:}
% \cs{@@_Info_gpush:} is the command that outputs the info dictionary (currently
% in the end-of-run hooks).
% \begin{macrocode}
% push to the register command / issue the special
\cs_new_protected:Npn \@@_Info_gpush:
{
\prop_map_function:cN
{ \__kernel_pdfdict_name:n { g__pdf_Core/Info} }
\__pdf_backend_info_gput:nn
\prop_gclear:c { \__kernel_pdfdict_name:n { g__pdf_Core/Info} }
}
% \end{macrocode}
% \end{macro}
% \subsection{The Pages dictionary code}
% \begin{NOTE}{UF}
% The register is normally used only a few times in a document, so it would be
% okay to update the register/add the special at every change,
% but with dvips/dvipdfmx this would disable removing entries.
% So we issue the push code only at the end of the document.
% \end{NOTE}
% At first the initialisation
% \begin{macrocode}
\pdfdict_new:n { g__pdf_Core/Pages}
% \end{macrocode}
%
% \begin{macro}{\@@_Pages_gpush:}
% This is the command that outputs the Pages dictionary. It is used
% at the end of the document in \cs{g__pdf_backend_end_run_tl}
% \begin{macrocode}
% push to the register command / issue the special