From 2ad4e5bb3dc803f2c4fc3623bc0e367cd7f2c691 Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Fri, 30 Oct 2020 03:00:58 +0000 Subject: CTAN sync 202010300300 --- macros/latex/contrib/pdfoverlay/README.md | 11 +- macros/latex/contrib/pdfoverlay/pdfoverlay.dtx | 232 +++++++++++++++++-------- macros/latex/contrib/pdfoverlay/pdfoverlay.ins | 4 +- macros/latex/contrib/pdfoverlay/pdfoverlay.pdf | Bin 543827 -> 547108 bytes 4 files changed, 171 insertions(+), 76 deletions(-) (limited to 'macros/latex/contrib/pdfoverlay') diff --git a/macros/latex/contrib/pdfoverlay/README.md b/macros/latex/contrib/pdfoverlay/README.md index 3abb0f4ef3..e08949050c 100644 --- a/macros/latex/contrib/pdfoverlay/README.md +++ b/macros/latex/contrib/pdfoverlay/README.md @@ -1,15 +1,15 @@ # pdfoverlay — A LaTeX style for overlaying text on a PDF The `pdfoverlay` package provides a simple interface to overlay text on to an -existing PDF. The text to be overlayed is typeset and positioned normally as +existing PDF. The text to be overlaid is typeset and positioned normally as you would any other LaTeX document. Some or all of the pages of the PDF can be -included and not all pages of the PDF need have overlayed text. It’s also +included and not all pages of the PDF need have overlaid text. It’s also possible to include text between pages of the PDF. ## Installation from TeXLive or MiKTeX `pdfoverlay` is in TeXLive and MiKTeX and can be installed in the usual way -through your distribution. e.g., in TeXLive by running: +through your distribution. E.g., in TeXLive by running: ``` tlmgr install pdfoverlay @@ -28,7 +28,8 @@ tex pdfoverlay.ins to generate `pdfoverlay.sty`. -Copy `pdfoverlay.sty` to `$TEXMFHOME/tex/latex/pdfoverlay/` and `pdfoverlay.pdf` to `$TEXMFHOME/doc/latex/pdfoverlay/`. +Copy `pdfoverlay.sty` to `$TEXMFHOME/tex/latex/pdfoverlay/` and +`pdfoverlay.pdf` to `$TEXMFHOME/doc/latex/pdfoverlay/`. You can find `$TEXMFHOME` by running: @@ -57,7 +58,7 @@ l3build install --full ## Licence ``` -Copyright (c) 2018-2019 David Purton +Copyright (c) 2018-2020 David Purton This work may be distributed and/or modified under the conditions of the LaTeX Project2 Public License, either version 1.3c of this license diff --git a/macros/latex/contrib/pdfoverlay/pdfoverlay.dtx b/macros/latex/contrib/pdfoverlay/pdfoverlay.dtx index 805ad91d63..1f7064be06 100644 --- a/macros/latex/contrib/pdfoverlay/pdfoverlay.dtx +++ b/macros/latex/contrib/pdfoverlay/pdfoverlay.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (c) 2018-2019 David Purton +% Copyright (c) 2018-2020 David Purton % % This work may be distributed and/or modified under the conditions of % the LaTeX Project Public License, either version 1.3c of this license @@ -19,20 +19,22 @@ % \fi % % \changes{v1.0}{2018/05/08}{First public release} -% \changes{v1.1}{2019/11/03}{Fix depracated macros} +% \changes{v1.1}{2019/11/03}{Fix deprecated macros} +% \changes{v1.2}{2020/10/29}{Update to use \pkg{l3hooks}} % % \title{The \pkg{pdfoverlay} package} % \author{David Purton\thanks{Email: \url{dcpurton@marshwiggle.net}}} -% \date{2019/11/03 v1.1} +% \date{2020/10/29 v1.2} % % \maketitle % % \begin{abstract} % This \pkg{pdfoverlay} package provides a simple interface to overlay text -% on to an existing PDF. The text to be overlayed is typeset and positioned -% normally as you would any other \LaTeX{} document. Some or all of the pages -% of the PDF can be included and not all pages of the PDF need have overlayed -% text. It's also possible to include text between pages of the PDF. +% on to an existing PDF. The text to be overlaid is typeset and positioned +% normally as you would any other \LaTeX{} document. Some or all of the +% pages of the PDF can be included and not all pages of the PDF need have +% overlaid text. It's also possible to include text between pages of the +% PDF. % \end{abstract} % % \tableofcontents @@ -41,32 +43,25 @@ % % \section{Introduction} % -% It's often desirable to take an exisiting PDF and easily add annotations or +% It's often desirable to take an existing PDF and easily add annotations or % text overlaying the PDF. This might arise if you wish to add comments to a % PDF, fill in a PDF form, or add text to a PDF where space has been left for % notes. % % This package provides a simple interface to do this without having to resort % to inserting one page at a time. Some or all of the pages of the PDF can be -% included and not all pages of the PDF need have overlayed text. It's also +% included and not all pages of the PDF need have overlaid text. It's also % possible to include text between pages of the PDF. % -% Another advantage of this package is that the overlayed text can be set as +% Another advantage of this package is that the overlaid text can be set as % normal flowing from one page to another or with manual page breaks if you % wish. It's also possible to use any standard method to position text at % arbitrary places on a given page. % -% \section{Acknowlegements} -% -% This package is particularly indebted to the \pkg{pdfpages} package to count -% the number of pages in the PDF file, the \pkg{eso-pic} package to output -% pages from the PDF file in the document background, and the \pkg{everypage} -% package to ensure that PDF pages are inserted at every page in the document. -% % \section{Bug Reports and Feature Requests} % % Bug reports and feature requests can be made at the \pkg{pdfoverlay} package -% GitHub respoitory. See \url{https://github.com/dcpurton/pdfoverlay}. +% GitHub repository. See \url{https://github.com/dcpurton/pdfoverlay}. % % \section{Documentation} % @@ -107,10 +102,12 @@ % \end{syntax} % Set the \meta{Options} to be passed to \cs{includegraphics} when each page % of the PDF is output. See the \pkg{graphicx} package documentation for -% valid options. \textbf{Note} that it is not necessary to specify the -% \texttt{page} option as this is appended automatically in the right format. -% The default options are: \texttt{keepaspectratio, -% width=}\cs{paperwidth}\texttt{, height=}\cs{paperheight}. +% valid options. +% +% \textbf{Note} that it is not necessary to specify the \texttt{page} option +% as this is appended automatically in the right format. The default +% options are: \texttt{keepaspectratio, width=}\cs{paperwidth}\texttt{, +% height=}\cs{paperheight}. % \end{function} % % \begin{function}{\pdfoverlayIncludeToPage, \pdfoverlay_include_to_page:n} @@ -165,34 +162,30 @@ % \end{macrocode} % % \begin{macrocode} -\RequirePackage{xparse} -% \end{macrocode} -% -% \begin{macrocode} -\ProvidesExplPackage{pdfoverlay}{2019/11/03}{1.1} +\NeedsTeXFormat{LaTeX2e}[2020-10-01] +\ProvidesExplPackage{pdfoverlay}{2020/10/18}{1.2} {Overlay text on an existing PDF document (DCP)} % \end{macrocode} % -% \noindent The \pkg{everypage} and \pkg{pdfpages} packages are required. +% \noindent The \pkg{graphicx} package is required. % % \begin{macrocode} -\RequirePackage{everypage,pdfpages} +\RequirePackage{graphicx} % \end{macrocode} % -% \noindent Call \cs{@@_output_pdf_page:} on every page using the -% \pkg{everypage} package. +% \noindent Call \cs{@@_output_pdf_page:} on every page. % \begin{macrocode} -\AddEverypageHook { \@@_output_pdf_page: } +\AddToHook { shipout/background } { \@@_output_pdf_page: } % \end{macrocode} % -% \noindent Add \cs{null} to the end of the document if an action is pending. -% This is required to ensure that the last requested page from the PDF file is -% output even if there isn't any other content on the page. +% \noindent Add an empty \cs{hbox:n} to the end of the document if an action +% is pending. This is required to ensure that the last requested page from the +% PDF file is output even if there isn't any other content on the page. % \begin{macrocode} \AtEndDocument { \bool_if:NT \g_@@_action_pending_bool { - \null + \hbox:n { } } } % \end{macrocode} @@ -241,6 +234,26 @@ Specify~a~page~between~#2~and~#3. } % \end{macrocode} % +% \noindent Error message when running in DVI mode. The \pkg{pdfoverlay} +% package does not support DVI mode for either \texttt{pdflatex} or +% \texttt{lualatex}. +% \begin{macrocode} +\msg_new:nnnn { pdfoverlay } { dvi-mode } + { DVI~mode~not~supported. } + { DVI~mode~of~#1~is~not~supported. \\ + You~must~use~PDF~mode. } +% \end{macrocode} +% +% \noindent Error message for unsupported engine. Only \texttt{pdftex}, +% \texttt{luatex}, and \texttt{xetex} are supported. +% \begin{macrocode} +\msg_new:nnnn { pdfoverlay } { unsupported-engine } + { #1~not~supported. } + { The~#1~engine~is~not~supported. \\ + Use~one~of~pdftex,~luatex,~or~xetex. } +% \end{macrocode} +% +% % \subsection{Private Variables and Helper Functions} % % \begin{macro}{\g_@@_pdf_file_name_str} @@ -296,9 +309,17 @@ % \end{macrocode} % \end{macro} % +% \begin{macro}{\g_@@_pdf_page_coffin} +% The current PDF page is set in this coffin which can then be positioned on +% the page. +% \begin{macrocode} +\coffin_new:N \g_@@_pdf_page_coffin +% \end{macrocode} +% \end{macro} +% % \begin{macro}{\@@_output_pdf_page:} % Main function to output the current page of the PDF file. This is called -% before every page is shipped using the \pkg{everypage} package. +% before every page is shipped using the \texttt{shipout/background} hook. % \begin{macrocode} \cs_new:Nn \@@_output_pdf_page: { @@ -317,18 +338,16 @@ } { % \end{macrocode} -% Place requested page from the PDF file in the background of the -% document page with the specified format. -% \begin{macrocode} - \AddToShipoutPictureBG* - { - \@@_format_pdf_page: - } -% \end{macrocode} % Increment the current page counter. % \begin{macrocode} \int_gincr:N \g_@@_page_int % \end{macrocode} +% Place requested page from the PDF file in the background of the +% document page with the specified format. +% \begin{macrocode} + \@@_format_pdf_page: + \@@_place_pdf_page: +% \end{macrocode} % Set action pending flag to false. % \begin{macrocode} \bool_gset_false:N \g_@@_action_pending_bool @@ -338,23 +357,100 @@ % \end{macro} % % \begin{macro}{\@@_format_pdf_page:} -% Format the PDF page in the centre of the document page with options from -% \cs{g_@@_graphics_options_clist}. Although marked as private, this function -% could be redifined to position the PDF page at a different location on the -% document page. See the \pkg{eso-pic} package documentation for hints on how -% to position the PDF page. +% Format the PDF page with options from \cs{g_@@_graphics_options_clist} and +% place it in \cs{g_@@_pdf_page_coffin}. % \begin{macrocode} \cs_new:Nn \@@_format_pdf_page: { - \AtPageCenter + \hcoffin_gset:Nn \g_@@_pdf_page_coffin + { + \use:x + { + \exp_not:N \includegraphics + [ \clist_use:Nn \g_@@_graphics_options_clist { , } ] + { \g_@@_pdf_file_name_str } + } + } + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\@@_place_pdf_page:} +% Place the PDF page in the centre of the document page. +% +% Although marked as private, this function could be redefined to position +% the PDF page at a different location on the document page. +% +% This macro is called from within the \texttt{shipout\slash background} +% hook, which adds a picture environment into the background of the page +% with the (0, 0) coordinate in the top-left corner using a \cs{unitlength} +% of 1pt. It should therefore only receive \cs{put} commands or other +% commands suitable in a picture environment and the vertical coordinate +% values would normally be negative. +% +% The PDF page to be placed is available as the coffin +% \cs{g_@@_pdf_page_coffin}. +% \begin{macrocode} +\cs_new:Nn \@@_place_pdf_page: + { + \put ( 0.5 \paperwidth, -0.5 \paperheight ) { - \makebox (0, 0) + \coffin_typeset:Nnnnn \g_@@_pdf_page_coffin + { hc } { vc } { 0pt } { 0pt } + } + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\@@_count_pdf_pages:} +% Count the number of pages in the current \cs{g_@@_pdf_file_name_str} and +% store the result in \cs{g_@@_pdf_page_count_int}. If no PDF has been set +% with \cs{pdfoverlay_set_pdf} then \cs{g_@@_pdf_page_count_int} is set to +% zero. +% \begin{macrocode} +\cs_new:Nn \@@_count_pdf_pages: + { + \int_gzero:N \g_@@_page_count_int + \str_if_empty:NTF \g_@@_pdf_file_name_str + { + \msg_error:nn { pdfoverlay } { file-not-set } + } + { + \sys_if_engine_xetex:TF { - \use:x + \int_gset:Nn \g_@@_page_count_int + { + \XeTeXpdfpagecount " \g_@@_pdf_file_name_str " + } + } + { + \sys_if_output_pdf:TF + { + \sys_if_engine_pdftex:TF + { + \pdfximage { \g_@@_pdf_file_name_str } + \int_gset_eq:NN + \g_@@_page_count_int + \pdflastximagepages + } + { + \sys_if_engine_luatex:TF + { + \saveimageresource + { \g_@@_pdf_file_name_str } + \int_gset_eq:NN + \g_@@_page_count_int + \lastsavedimageresourcepages + } + { + \msg_error:nnx { pdfoverlay } { unsupported-engine } + { \c_sys_engine_str } + } + } + } { - \exp_not:N \includegraphics - [ \clist_use:Nn \g_@@_graphics_options_clist { , } ] - { \g_@@_pdf_file_name_str } + \msg_error:nnx { pdfoverlay } { dvi-mode } + { \c_sys_engine_str } } } } @@ -408,15 +504,13 @@ { \str_gset:Nn \g_@@_pdf_file_name_str { #1 } % \end{macrocode} -% Use the \pkg{pdfpages} package to find the number of pages in the PDF file. +% Find the number of pages in the PDF file. % \begin{macrocode} - \edef \AM@currentdocname { #1 } - \AM@getpagecount + \@@_count_pdf_pages: % \end{macrocode} % Initialise variables. % \begin{macrocode} - \int_gset_eq:NN \g_@@_page_count_int \AM@pagecount - \int_gset_eq:NN \g_@@_page_int \c_zero_int + \int_gzero:N \g_@@_page_int \bool_gset_true:N \g_@@_output_active_bool \bool_gset_false:N \g_@@_action_pending_bool } @@ -447,8 +541,8 @@ % \begin{macro}{\pdfoverlay_include_to_page:n} % Output all pages in the PDF file up until the specified page. Since the % actual PDF page is inserted by \cs{__pdfoverlay_output_pdf_page:} using the -% \pkg{everypage} package before the page is shipped, we just insert the -% required number of blank pages into the document. +% \texttt{shipout/background} hook, we just insert the required number of +% blank pages into the document. % \begin{macrocode} \cs_new:Npn \pdfoverlay_include_to_page:n #1 { @@ -476,7 +570,7 @@ { \int_compare_p:n { #1 != \g_@@_page_int + 1 } } } { - \null + \hbox:n { } \clearpage } % \end{macrocode} @@ -484,12 +578,12 @@ % \begin{macrocode} \int_while_do:nNnn { \g_@@_page_int } < { #1 - 1 } { - \null + \hbox:n { } \clearpage } % \end{macrocode} % Set the action pending flag, so final page is output even if no text is -% overlayed on it. +% overlaid on it. % \begin{macrocode} \bool_gset_true:N \g_@@_action_pending_bool } @@ -526,16 +620,16 @@ % \begin{macrocode} \bool_if:nT { \g_@@_action_pending_bool } { - \null + \hbox:n { } \clearpage } % \end{macrocode} -% Set the page numer for the next page to be output. +% Set the page number for the next page to be output. % \begin{macrocode} \int_gset:Nn \g_@@_page_int { #1 - 1 } % \end{macrocode} % Set the action pending flag, so final page is output even if no text is -% overlayed on it. +% overlaid on it. % \begin{macrocode} \bool_gset_true:N \g_@@_action_pending_bool } diff --git a/macros/latex/contrib/pdfoverlay/pdfoverlay.ins b/macros/latex/contrib/pdfoverlay/pdfoverlay.ins index 7f2a4200f9..743dbdca59 100644 --- a/macros/latex/contrib/pdfoverlay/pdfoverlay.ins +++ b/macros/latex/contrib/pdfoverlay/pdfoverlay.ins @@ -1,6 +1,6 @@ \iffalse meta-comment -Copyright (c) 2018-2019 David Purton +Copyright (c) 2018-2020 David Purton This work may be distributed and/or modified under the conditions of the LaTeX Project Public License, either version 1.3c of this license @@ -19,7 +19,7 @@ version 2005/12/01 or later. This is a generated file. -Copyright (c) 2018-2019 David Purton +Copyright (c) 2018-2020 David Purton This work may be distributed and/or modified under the conditions of the LaTeX Project2 Public License, either version 1.3c of this license diff --git a/macros/latex/contrib/pdfoverlay/pdfoverlay.pdf b/macros/latex/contrib/pdfoverlay/pdfoverlay.pdf index d98a995913..276775c6e4 100644 Binary files a/macros/latex/contrib/pdfoverlay/pdfoverlay.pdf and b/macros/latex/contrib/pdfoverlay/pdfoverlay.pdf differ -- cgit v1.2.3