Debian Codegraph @

texmf-dist/source/latex/pdfoverlay/pdfoverlay.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (c) 2018-2022 David Purton <[email protected]>
4 %
5 % This work may be distributed and/or modified under the conditions of
6 % the LaTeX Project Public License, either version 1.3c of this license
7 % or (at your option) any later version. The latest version of this
8 % license is in
9 % http://www.latex-project.org/lppl.txt
10 % and version 1.3c or later is part of all distributions of LaTeX
11 % version 2005/12/01 or later.
12 %
13 %<*driver>
14 \documentclass[a4paper]{l3doc}
15 \begin{document}
16 \DocInput{\jobname.dtx}
17 \end{document}
18 %</driver>
19 % \fi
20 %
21 % \changes{v1.0}{2018/05/08}{First public release}
22 % \changes{v1.1}{2019/11/03}{Fix deprecated macros}
23 % \changes{v1.2}{2020/10/29}{Update to use \pkg{l3hooks}}
24 % \changes{v1.2a}{2021/02/25}{Ensure backend loaded before counting pages}
25 % \changes{v1.2b}{2021/11/01}{Protect unexpandable macros}
26 % \changes{v1.3}{2022/08/27}{Allow PDF file name to be passed in as macro}
27 %
28 % \title{The \pkg{pdfoverlay} package}
29 % \author{David Purton\thanks{Email: \url{[email protected]}}}
30 % \date{2022/08/27 v1.3}
31 %
32 % \maketitle
33 %
34 % \begin{abstract}
35 % This \pkg{pdfoverlay} package provides a simple interface to overlay text
36 % on to an existing PDF. The text to be overlaid is typeset and positioned
37 % normally as you would any other \LaTeX{} document. Some or all of the
38 % pages of the PDF can be included and not all pages of the PDF need have
39 % overlaid text. It's also possible to include text between pages of the
40 % PDF.
41 % \end{abstract}
42 %
43 % \tableofcontents
44 %
45 % \begin{documentation}
46 %
47 % \section{Introduction}
48 %
49 % It's often desirable to take an existing PDF and easily add annotations or
50 % text overlaying the PDF. This might arise if you wish to add comments to a
51 % PDF, fill in a PDF form, or add text to a PDF where space has been left for
52 % notes.
53 %
54 % This package provides a simple interface to do this without having to resort
55 % to inserting one page at a time. Some or all of the pages of the PDF can be
56 % included and not all pages of the PDF need have overlaid text. It's also
57 % possible to include text between pages of the PDF.
58 %
59 % Another advantage of this package is that the overlaid text can be set as
60 % normal flowing from one page to another or with manual page breaks if you
61 % wish. It's also possible to use any standard method to position text at
62 % arbitrary places on a given page.
63 %
64 % \section{Bug Reports and Feature Requests}
65 %
66 % Bug reports and feature requests can be made at the \pkg{pdfoverlay} package
67 % GitHub repository. See \url{https://github.com/dcpurton/pdfoverlay}.
68 %
69 % \section{Documentation}
70 %
71 % \subsection{Basic Usage}
72 %
73 % At it's simplest, the only thing required is to specify the PDF to overlay
74 % with text and then begin typing your document. The pages of the PDF will be
75 % inserted as you go automatically. If your text takes up more pages than the
76 % PDF then any remaining text is inserted on blank pages.
77 % \begin{verbatim}
78 % \documentclass{article}
79 % \usepackage{pdfoverlay}
80 % \pdfoverlaySetPDF{filename.pdf}
81 % \begin{document}
82 % ...
83 % \end{document}
84 % \end{verbatim}
85 % The PDF will be centered on and scaled to fit the document page size while
86 % keeping a fixed aspect ratio.
87 %
88 % \subsection{Main Interface}
89 %
90 % \begin{function}{\pdfoverlaySetPDF, \pdfoverlay_set_pdf:n}
91 % \begin{syntax}
92 % \cs{pdfoverlaySetPDF} \Arg{PDF filename}
93 % \end{syntax}
94 % Specify the \meta{PDF filename} to overlay text on to. This function must
95 % be called first. It can be used either in the preamble or at any point in
96 % the document body. It is possible to call this more than once to include
97 % multiple PDF files. If the specified \meta{PDF filename} cannot be found an
98 % error is generated.
99 % \end{function}
100 %
101 % \begin{function}{\pdfoverlaySetGraphicsOptions,
102 % \pdfoverlay_set_graphics_options:n}
103 % \begin{syntax}
104 % \cs{pdfoverlaySetGraphicsOptions} \Arg{Options}
105 % \end{syntax}
106 % Set the \meta{Options} to be passed to \cs{includegraphics} when each page
107 % of the PDF is output. See the \pkg{graphicx} package documentation for
108 % valid options.
109 %
110 % \textbf{Note} that it is not necessary to specify the \texttt{page} option
111 % as this is appended automatically in the right format. The default
112 % options are: \texttt{keepaspectratio, width=}\cs{paperwidth}\texttt{,
113 % height=}\cs{paperheight}.
114 % \end{function}
115 %
116 % \begin{function}{\pdfoverlayIncludeToPage, \pdfoverlay_include_to_page:n}
117 % \begin{syntax}
118 % \cs{pdfoverlayIncludeToPage} \Arg{page number}
119 % \end{syntax}
120 % Output all pages in the PDF file up until the specified \meta{page number}.
121 % If the specified \meta{page number} does not evaluate to an integer or does
122 % not exist in the PDF an error is generated.
123 % \end{function}
124 %
125 % \begin{function}{\pdfoverlayIncludeToLastPage, \pdfoverlay_include_to_last_page:}
126 % \begin{syntax}
127 % \cs{pdfoverlayIncludeToLastPage}
128 % \end{syntax}
129 % Output all remaining pages in the PDF file.
130 % \end{function}
131 %
132 % \begin{function}{\pdfoverlaySkipToPage, \pdfoverlay_skip_to_page:n}
133 % \begin{syntax}
134 % \cs{pdfoverlaySkipToPage} \Arg{page number}
135 % \end{syntax}
136 % Skip to the specified \meta{page number}. This can be before or after the
137 % current page in the PDF file. If the specified \meta{page number} does not
138 % evaluate to an integer or does not exist in the PDF an error is generated.
139 % \end{function}
140 %
141 % \begin{function}{\pdfoverlayPauseOutput, \pdfoverlay_pause_output:}
142 % \begin{syntax}
143 % \cs{pdfoverlayPauseOutput}
144 % \end{syntax}
145 % Pause outputting pages from the PDF file. Any subsequent text will by
146 % output on blank pages.
147 % \end{function}
148 %
149 % \begin{function}{\pdfoverlayResumeOutput, \pdfoverlay_resume_output:}
150 % \begin{syntax}
151 % \cs{pdfoverlayResumeOutput}
152 % \end{syntax}
153 % Resume outputting pages from the PDF file.
154 % \end{function}
155 %
156 % \end{documentation}
157 %
158 % \begin{implementation}
159 %
160 % \section{Implementation}
161 %
162 % \begin{macrocode}
163 %<*package>
164 %<@@=pdfoverlay>
165 % \end{macrocode}
166 %
167 % \begin{macrocode}
168 \NeedsTeXFormat{LaTeX2e}[2020-10-01]
169 \ProvidesExplPackage{pdfoverlay}{2022/08/27}{1.3}
170 {Overlay text on an existing PDF document (DCP)}
171 % \end{macrocode}
172 %
173 % \noindent The \pkg{graphicx} package is required.
174 %
175 % \begin{macrocode}
176 \RequirePackage{graphicx}
177 % \end{macrocode}
178 %
179 % \noindent Call \cs{@@_output_pdf_page:} on every page.
180 % \begin{macrocode}
181 \hook_gput_code:nnn { shipout/background } { pdfoverlay } { \@@_output_pdf_page: }
182 % \end{macrocode}
183 %
184 % \noindent Add an empty \cs{hbox:n} to the end of the document if an action
185 % is pending. This is required to ensure that the last requested page from the
186 % PDF file is output even if there isn't any other content on the page.
187 % \begin{macrocode}
188 \hook_gput_code:nnn { enddocument } { pdfoverlay } {
189 \bool_if:NT \g_@@_action_pending_bool
190 {
191 \hbox:n { }
192 }
193 }
194 % \end{macrocode}
195 %
196 % \subsection{Messages}
197 %
198 % Error message when specified PDF file cannot be found. \\
199 % |#|1: PDF file name
200 % \begin{macrocode}
201 \msg_new:nnnn { pdfoverlay } { file-not-found }
202 { PDF~file~`#1'~not~found. }
203 { Unable~to~find~the~file~`#1'. \\
204 Check~that~the~file~exists~and~you~have~spelt~it~correctly. }
205 % \end{macrocode}
206 %
207 % \noindent Error message when no PDF file has been set.
208 % \begin{macrocode}
209 \msg_new:nnnn { pdfoverlay } { file-not-set }
210 { PDF~file~not~set. }
211 { You~have~not~specified~a~PDF~file. \\
212 Set~a~PDF~file~using~\pdfoverlaySetPDF. }
213 % \end{macrocode}
214 %
215 % \noindent Error message when the requested page number cannot be found in the
216 % PDF file. \\
217 % |#1|: PDF file name \\
218 % |#2|: Requested page number \\
219 % |#3|: Total number of pages in PDF
220 % \begin{macrocode}
221 \msg_new:nnnn { pdfoverlay } { page-not-found }
222 { Page~not~found~in~PDF. }
223 { PDF~file~`#1'~does~not~contain~page~#2. \\
224 Specify~a~page~between~1~and~#3. }
225 % \end{macrocode}
226 %
227 % \noindent Error message when the requested page number to include to is less
228 % than the current page number being output from the PDF file. \\
229 % |#1|: Requested page number \\
230 % |#2|: Current page number in PDF \\
231 % |#3|: Total number of pages in PDF
232 % \begin{macrocode}
233 \msg_new:nnnn { pdfoverlay } { page-too-low }
234 { Requested~page~less~than~current~page~in~PDF. }
235 { You~have~requested~to~include~to~page~#1, \\
236 but~the~current~page~is~already~at~page~#2. \\
237 Specify~a~page~between~#2~and~#3. }
238 % \end{macrocode}
239 %
240 % \noindent Error message when running in DVI mode. The \pkg{pdfoverlay}
241 % package does not support DVI mode for either \texttt{pdflatex} or
242 % \texttt{lualatex}.
243 % \begin{macrocode}
244 \msg_new:nnnn { pdfoverlay } { dvi-mode }
245 { DVI~mode~not~supported. }
246 { DVI~mode~of~#1~is~not~supported. \\
247 You~must~use~PDF~mode. }
248 % \end{macrocode}
249 %
250 % \noindent Error message for unsupported engine. Only \texttt{pdftex},
251 % \texttt{luatex}, and \texttt{xetex} are supported.
252 % \begin{macrocode}
253 \msg_new:nnnn { pdfoverlay } { unsupported-engine }
254 { #1~not~supported. }
255 { The~#1~engine~is~not~supported. \\
256 Use~one~of~pdftex,~luatex,~or~xetex. }
257 % \end{macrocode}
258 %
259 %
260 % \subsection{Private Variables and Helper Functions}
261 %
262 % \begin{macro}{\g_@@_pdf_file_name_tl}
263 % Store the PDF file name.
264 % \begin{macrocode}
265 \tl_new:N \g_@@_pdf_file_name_tl
266 % \end{macrocode}
267 % \end{macro}
268 %
269 % \begin{macro}{\g_@@_page_count_int}
270 % Store the total number of pages in the PDF file.
271 % \begin{macrocode}
272 \int_new:N \g_@@_page_count_int
273 % \end{macrocode}
274 % \end{macro}
275 %
276 % \begin{macro}{\g_@@_page_int}
277 % Keep track of the current page in the PDF file.
278 % \begin{macrocode}
279 \int_new:N \g_@@_page_int
280 % \end{macrocode}
281 % \end{macro}
282 %
283 % \begin{macro}{\g_@@_output_active_bool}
284 % Flag to store whether to output pages from the PDF file or not.
285 % \begin{macrocode}
286 \bool_new:N \g_@@_output_active_bool
287 % \end{macrocode}
288 % \end{macro}
289 %
290 % \begin{macro}{\g_@@_action_pending_bool}
291 % Flag to store whether an action (\cs{pdfoverlay_include_to_page:n} or
292 % \cs{pdfoverlay_set_page:n}) is pending. If an action is pending, these
293 % functions will start a new page.
294 % \begin{macrocode}
295 \bool_new:N \g_@@_action_pending_bool
296 % \end{macrocode}
297 % \end{macro}
298 %
299 % \begin{macro}{\g_@@_graphics_options_clist}
300 % Hold the options passed to \cs{includegraphics} when including a page from
301 % the PDF. The default options scale the PDF page to fit the document page
302 % while keeping the original PDF page aspect ratio.
303 % \begin{macrocode}
304 \clist_new:N \g_@@_graphics_options_clist
305 \clist_set:Nn \g_@@_graphics_options_clist
306 {
307 keepaspectratio ,
308 width = \paperwidth ,
309 height = \paperheight ,
310 page = \int_use:N \g_@@_page_int
311 }
312 % \end{macrocode}
313 % \end{macro}
314 %
315 % \begin{macro}{\g_@@_pdf_page_coffin}
316 % The current PDF page is set in this coffin which can then be positioned on
317 % the page.
318 % \begin{macrocode}
319 \coffin_new:N \g_@@_pdf_page_coffin
320 % \end{macrocode}
321 % \end{macro}
322 %
323 % \begin{macro}{\@@_output_pdf_page:}
324 % Main function to output the current page of the PDF file. This is called
325 % before every page is shipped using the \texttt{shipout/background} hook.
326 % \begin{macrocode}
327 \cs_new_protected:Nn \@@_output_pdf_page:
328 {
329 % \end{macrocode}
330 % Check if we are currently outputting pages, a PDF file has been set, and
331 % the requested page exists in the PDF file.
332 % \begin{macrocode}
333 \bool_lazy_all:nT
334 {
335 { \bool_if_p:N \g_@@_output_active_bool }
336 { \bool_not_p:n
337 { \tl_if_empty_p:N \g_@@_pdf_file_name_tl } }
338 { \int_compare_p:n
339 { \c_zero_int <= \g_@@_page_int
340 < \g_@@_page_count_int } }
341 }
342 {
343 % \end{macrocode}
344 % Increment the current page counter.
345 % \begin{macrocode}
346 \int_gincr:N \g_@@_page_int
347 % \end{macrocode}
348 % Place requested page from the PDF file in the background of the
349 % document page with the specified format.
350 % \begin{macrocode}
351 \@@_format_pdf_page:
352 \@@_place_pdf_page:
353 % \end{macrocode}
354 % Set action pending flag to false.
355 % \begin{macrocode}
356 \bool_gset_false:N \g_@@_action_pending_bool
357 }
358 }
359 % \end{macrocode}
360 % \end{macro}
361 %
362 % \begin{macro}{\@@_format_pdf_page:}
363 % Format the PDF page with options from \cs{g_@@_graphics_options_clist} and
364 % place it in \cs{g_@@_pdf_page_coffin}.
365 % \begin{macrocode}
366 \cs_new_protected:Nn \@@_format_pdf_page:
367 {
368 \hcoffin_gset:Nn \g_@@_pdf_page_coffin
369 {
370 \use:x
371 {
372 \exp_not:N \includegraphics
373 [ \clist_use:Nn \g_@@_graphics_options_clist { , } ]
374 { \g_@@_pdf_file_name_tl }
375 }
376 }
377 }
378 % \end{macrocode}
379 % \end{macro}
380 %
381 % \begin{macro}{\@@_place_pdf_page:}
382 % Place the PDF page in the centre of the document page.
383 %
384 % Although marked as private, this function could be redefined to position
385 % the PDF page at a different location on the document page.
386 %
387 % This macro is called from within the \texttt{shipout\slash background}
388 % hook, which adds a picture environment into the background of the page
389 % with the (0, 0) coordinate in the top-left corner using a \cs{unitlength}
390 % of 1pt. It should therefore only receive \cs{put} commands or other
391 % commands suitable in a picture environment and the vertical coordinate
392 % values would normally be negative.
393 %
394 % The PDF page to be placed is available as the coffin
395 % \cs{g_@@_pdf_page_coffin}.
396 % \begin{macrocode}
397 \cs_new_protected:Nn \@@_place_pdf_page:
398 {
399 \put ( 0.5 \paperwidth, -0.5 \paperheight )
400 {
401 \coffin_typeset:Nnnnn \g_@@_pdf_page_coffin
402 { hc } { vc } { 0pt } { 0pt }
403 }
404 }
405 % \end{macrocode}
406 % \end{macro}
407 %
408 % \begin{macro}{\@@_count_pdf_pages:}
409 % Count the number of pages in the current \cs{g_@@_pdf_file_name_tl} and
410 % store the result in \cs{g_@@_pdf_page_count_int}. If no PDF has been set
411 % with \cs{pdfoverlay_set_pdf} then \cs{g_@@_pdf_page_count_int} is set to
412 % zero.
413 % \begin{macrocode}
414 \cs_new_protected:Nn \@@_count_pdf_pages:
415 {
416 \int_gzero:N \g_@@_page_count_int
417 \tl_if_empty:NTF \g_@@_pdf_file_name_tl
418 {
419 \msg_error:nn { pdfoverlay } { file-not-set }
420 }
421 {
422 \sys_if_engine_xetex:TF
423 {
424 \int_gset:Nn \g_@@_page_count_int
425 {
426 \XeTeXpdfpagecount " \g_@@_pdf_file_name_tl "
427 }
428 }
429 {
430 \str_if_exist:NF \c_sys_backend_str
431 {
432 \sys_load_backend:n { }
433 }
434 \sys_if_output_pdf:TF
435 {
436 \sys_if_engine_pdftex:TF
437 {
438 \pdfximage { \g_@@_pdf_file_name_tl }
439 \int_gset_eq:NN
440 \g_@@_page_count_int
441 \pdflastximagepages
442 }
443 {
444 \sys_if_engine_luatex:TF
445 {
446 \saveimageresource
447 { \g_@@_pdf_file_name_tl }
448 \int_gset_eq:NN
449 \g_@@_page_count_int
450 \lastsavedimageresourcepages
451 }
452 {
453 \msg_error:nnx { pdfoverlay } { unsupported-engine }
454 { \c_sys_engine_str }
455 }
456 }
457 }
458 {
459 \msg_error:nnx { pdfoverlay } { dvi-mode }
460 { \c_sys_engine_str }
461 }
462 }
463 }
464 }
465 % \end{macrocode}
466 % \end{macro}
467 %
468 % \begin{macro}[pTF]{\@@_check_page:n}
469 % Check if a PDF file has been set and the requested page is valid. If not,
470 % generate suitable error messages.
471 % \begin{macrocode}
472 \prg_new_conditional:Nnn \@@_if_page_exists:n { p, T, F, TF }
473 {
474 \tl_if_empty:NTF \g_@@_pdf_file_name_tl
475 {
476 \msg_error:nn { pdfoverlay } { file-not-set }
477 \prg_return_false:
478 }
479 {
480 \int_compare:nTF
481 {
482 \c_one_int <= #1 <= \g_@@_page_count_int
483 }
484 {
485 \prg_return_true:
486 }
487 {
488 \msg_error:nnxxx { pdfoverlay } { page-not-found }
489 { \g_@@_pdf_file_name_tl }
490 { \int_eval:n { #1 } }
491 { \int_use:N \g_@@_page_count_int }
492 \prg_return_false:
493 }
494 }
495 }
496 % \end{macrocode}
497 % \end{macro}
498 %
499 %
500 % \subsection{Public Expl3 Functions}
501 %
502 % \begin{macro}{\pdfoverlay_set_pdf:n}
503 % Specify a PDF file to overlay text on to.
504 % \begin{macrocode}
505 \cs_new_protected:Nn \pdfoverlay_set_pdf:n
506 {
507 % \end{macrocode}
508 % Test if the file exists and generate a suitable error if it doesn't.
509 % \begin{macrocode}
510 \file_if_exist:nTF { #1 }
511 {
512 \tl_gset:Nn \g_@@_pdf_file_name_tl { #1 }
513 % \end{macrocode}
514 % Find the number of pages in the PDF file.
515 % \begin{macrocode}
516 \@@_count_pdf_pages:
517 % \end{macrocode}
518 % Initialise variables.
519 % \begin{macrocode}
520 \int_gzero:N \g_@@_page_int
521 \bool_gset_true:N \g_@@_output_active_bool
522 \bool_gset_false:N \g_@@_action_pending_bool
523 }
524 {
525 \msg_error:nnx { pdfoverlay } { file-not-found } { #1 }
526 }
527 }
528 % \end{macrocode}
529 % \end{macro}
530 %
531 % \begin{macro}{\pdfoverlay_set_graphics_options:n}
532 % Set the options as a comma separated list to be passed to
533 % \cs{includegraphics} when outputting each page from the PDF file. The
534 % \texttt{page} option is appended automatically in the
535 % correct format.
536 % \begin{macrocode}
537 \cs_new_protected:Nn \pdfoverlay_set_graphics_options:n
538 {
539 \clist_gset:Nn \g_@@_graphics_options_clist { #1 }
540 \clist_gput_right:Nn \g_@@_graphics_options_clist
541 {
542 page = \int_use:N \g_@@_page_int
543 }
544 }
545 % \end{macrocode}
546 % \end{macro}
547 %
548 % \begin{macro}{\pdfoverlay_include_to_page:n}
549 % Output all pages in the PDF file up until the specified page. Since the
550 % actual PDF page is inserted by \cs{__pdfoverlay_output_pdf_page:} using the
551 % \texttt{shipout/background} hook, we just insert the required number of
552 % blank pages into the document.
553 % \begin{macrocode}
554 \cs_new_protected:Nn \pdfoverlay_include_to_page:n
555 {
556 % \end{macrocode}
557 % Check if a PDF file is set and the requested page exists.
558 % \begin{macrocode}
559 \@@_if_page_exists:nT { #1 }
560 {
561 % \end{macrocode}
562 % Check if the requested page is greater than the current page.
563 % \begin{macrocode}
564 \int_compare:nTF
565 {
566 #1 >= \g_@@_page_int + 1
567 }
568 {
569 % \end{macrocode}
570 % Check if an action is pending and start a new page if so.
571 % \begin{macrocode}
572 \bool_lazy_all:nT
573 {
574 { \bool_if_p:n { \g_@@_action_pending_bool } }
575 { \int_compare_p:n { \g_@@_page_int <
576 \g_@@_page_count_int - 1 } }
577 { \int_compare_p:n { #1 != \g_@@_page_int + 1 } }
578 }
579 {
580 \hbox:n { }
581 \clearpage
582 }
583 % \end{macrocode}
584 % Loop until the specified page, inserting blank pages.
585 % \begin{macrocode}
586 \int_while_do:nNnn { \g_@@_page_int } < { #1 - 1 }
587 {
588 \hbox:n { }
589 \clearpage
590 }
591 % \end{macrocode}
592 % Set the action pending flag, so final page is output even if no text is
593 % overlaid on it.
594 % \begin{macrocode}
595 \bool_gset_true:N \g_@@_action_pending_bool
596 }
597 {
598 \msg_error:nnxxx { pdfoverlay } { page-too-low }
599 { \int_eval:n { #1 } }
600 { \int_eval:n { \g_@@_page_int + 1 } }
601 { \int_use:N \g_@@_page_count_int }
602 }
603 }
604 }
605 % \end{macrocode}
606 % \end{macro}
607 %
608 % \begin{macro}{\pdfoverlay_include_to_last_page:}
609 % Output all remaining pages in the PDF file.
610 % \begin{macrocode}
611 \cs_new_protected:Nn \pdfoverlay_include_to_last_page:
612 {
613 \pdfoverlay_include_to_page:n { \g_@@_page_count_int }
614 }
615 % \end{macrocode}
616 % \end{macro}
617 %
618 % \begin{macro}{\pdfoverlay_skip_to_page:n}
619 % Skip to the specified page number in the PDF file.
620 % \begin{macrocode}
621 \cs_new_protected:Nn \pdfoverlay_skip_to_page:n
622 {
623 \@@_if_page_exists:nT { #1 }
624 {
625 % \end{macrocode}
626 % Check if an action is pending and start a new page if so.
627 % \begin{macrocode}
628 \bool_if:nT { \g_@@_action_pending_bool }
629 {
630 \hbox:n { }
631 \clearpage
632 }
633 % \end{macrocode}
634 % Set the page number for the next page to be output.
635 % \begin{macrocode}
636 \int_gset:Nn \g_@@_page_int { #1 - 1 }
637 % \end{macrocode}
638 % Set the action pending flag, so final page is output even if no text is
639 % overlaid on it.
640 % \begin{macrocode}
641 \bool_gset_true:N \g_@@_action_pending_bool
642 }
643 }
644 % \end{macrocode}
645 % \end{macro}
646 %
647 % \begin{macro}{\pdfoverlay_pause_output:}
648 % Pause outputting pages from the PDF file.
649 % \begin{macrocode}
650 \cs_new_protected:Nn \pdfoverlay_pause_output:
651 {
652 \bool_gset_false:N \g_@@_output_active_bool
653 }
654 % \end{macrocode}
655 % \end{macro}
656 %
657 % \begin{macro}{\pdfoverlay_resume_output:}
658 % Resume outputting pages from the PDF file.
659 % \begin{macrocode}
660 \cs_new_protected:Nn \pdfoverlay_resume_output:
661 {
662 \bool_gset_true:N \g_@@_output_active_bool
663 }
664 % \end{macrocode}
665 % \end{macro}
666 %
667 % \subsection{Public \LaTeX{} Interface}
668 %
669 % \begin{macro}{\pdfoverlaySetPDF}
670 % Specify a PDF file to overlay text on to.
671 % \begin{macrocode}
672 \NewDocumentCommand \pdfoverlaySetPDF { m }
673 {
674 \pdfoverlay_set_pdf:n { #1 }
675 }
676 % \end{macrocode}
677 % \end{macro}
678 %
679 % \begin{macro}{\pdfoverlaySetGraphicsOptions}
680 % Set the options as a comma separated list to be passed to
681 % \cs{includegraphics} when outputting each page from the PDF file. The
682 % \texttt{page} option is appended automatically in the right format.
683 % \begin{macrocode}
684 \NewDocumentCommand \pdfoverlaySetGraphicsOptions { m }
685 {
686 \pdfoverlay_set_graphics_options:n { #1 }
687 }
688 % \end{macrocode}
689 % \end{macro}
690 %
691 % \begin{macro}{\pdfoverlayIncludeToPage}
692 % Output all pages in the PDF file up until the specified page.
693 % \begin{macrocode}
694 \NewDocumentCommand \pdfoverlayIncludeToPage { m }
695 {
696 \pdfoverlay_include_to_page:n { #1 }
697 }
698 % \end{macrocode}
699 % \end{macro}
700 %
701 % \begin{macro}{\pdfoverlayIncludeToLastPage}
702 % Output all remaining pages in the PDF file.
703 % \begin{macrocode}
704 \NewDocumentCommand \pdfoverlayIncludeToLastPage { }
705 {
706 \pdfoverlay_include_to_last_page:
707 }
708 % \end{macrocode}
709 % \end{macro}
710 %
711 % \begin{macro}{\pdfoverlaySkipToPage}
712 % Skip ahead to the specified page number in the PDF file.
713 % \begin{macrocode}
714 \NewDocumentCommand \pdfoverlaySkipToPage { m }
715 {
716 \pdfoverlay_skip_to_page:n { #1 }
717 }
718 % \end{macrocode}
719 % \end{macro}
720 %
721 % \begin{macro}{\pdfoverlayPauseOutput}
722 % Pause outputting pages from the PDF file.
723 % \begin{macrocode}
724 \NewDocumentCommand \pdfoverlayPauseOutput { }
725 {
726 \pdfoverlay_pause_output:
727 }
728 % \end{macrocode}
729 % \end{macro}
730 %
731 % \begin{macro}{\pdfoverlayResumeOutput}
732 % Resume outputting pages from the PDF file.
733 % \begin{macrocode}
734 \NewDocumentCommand \pdfoverlayResumeOutput { }
735 {
736 \pdfoverlay_resume_output:
737 }
738 % \end{macrocode}
739 % \end{macro}
740 %
741 % \begin{macrocode}
742 %</package>
743 % \end{macrocode}
744 %
745 % \end{implementation}
746 %
747 % \PrintChanges
748 %
749 % \PrintIndex