pdfoverlay (29oct20)

git-svn-id: svn://tug.org/texlive/trunk@56803 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 165 insertions, 71 deletions

diff --git a/Master/texmf-dist/source/latex/pdfoverlay/pdfoverlay.dtx b/Master/texmf-dist/source/latex/pdfoverlay/pdfoverlay.dtx
index 805ad91d63c..1f7064be067 100644
--- a/Master/texmf-dist/source/latex/pdfoverlay/pdfoverlay.dtx
+++ b/Master/texmf-dist/source/latex/pdfoverlay/pdfoverlay.dtx
@@ -1,6 +1,6 @@
 % \iffalse meta-comment
 %
-% Copyright (c) 2018-2019 David Purton <dcpurton@marshwiggle.net>
+% Copyright (c) 2018-2020 David Purton <dcpurton@marshwiggle.net>
 %
 % 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/Master/texmf-dist/source/latex/pdfoverlay/pdfoverlay.ins b/Master/texmf-dist/source/latex/pdfoverlay/pdfoverlay.ins
index 7f2a4200f95..743dbdca593 100644
--- a/Master/texmf-dist/source/latex/pdfoverlay/pdfoverlay.ins
+++ b/Master/texmf-dist/source/latex/pdfoverlay/pdfoverlay.ins
@@ -1,6 +1,6 @@
 \iffalse meta-comment
 
-Copyright (c) 2018-2019 David Purton <dcpurton@marshwiggle.net>
+Copyright (c) 2018-2020 David Purton <dcpurton@marshwiggle.net>
 
 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 <dcpurton@marshwiggle.net>
+Copyright (c) 2018-2020 David Purton <dcpurton@marshwiggle.net>
 
 This work may be distributed and/or modified under the conditions of
 the LaTeX Project2 Public License, either version 1.3c of this license